DOCUMENTATION.md

# Particri (بارتيكري) - Complete Technical Documentation & API Reference
## التوثيق التقني الشامل والمرجع الكامل لجميع دوال ومكونات المكتبة

Welcome to the definitive reference manual for **Particri**, the state-of-the-art C++20 and Python particle simulation and procedural rendering engine.

---

# 📑 Table of Contents (فهرس المحتويات)

1. [Architectural Overview (نظرة عامة على البنية البرمجية)](#1-architectural-overview)
2. [Class: ParticleEngine (محرك الجزيئات الأساسي)](#2-class-particleengine)
3. [Enums (الثوابت والتصنيفات)](#3-enums)
   - [ParticleShape (أشكال الجزيئات)](#particleshape)
   - [BlendMode (أوضاع دمج الألوان)](#blendmode)
   - [EmitterShape (أشكال البواعث)](#emittershape)
4. [Math Primitives: Vec2 & Color4 (بُنى الرياضيات والألوان)](#4-math-primitives)
5. [Class: Presets (الأنماط الجاهزة فائقة الواقعية)](#5-class-presets)
6. [Class: StyleGenerator (مولد الستايلات اللانهائية)](#6-class-stylegenerator)
7. [Class: StockFactory (مصنع أصول الستوك الضخم لـ Shutterstock)](#7-class-stockfactory)
8. [Class: Exporter (نظام التصدير للصور والفيديو والمتحركات)](#8-class-exporter)
9. [Class: Studio (الأستوديو التفاعلي المباشر 60 FPS)](#9-class-studio)
10. [End-to-End Tutorials (أمثلة برمجية شاملة)](#10-end-to-end-tutorials)

---

# 1. Architectural Overview

Particri is architected in a high-performance two-tier hybrid model:
- **Tier 1: High-Performance C++20 Core (`_particri_core`)**:
  - Implements SIMD vector math, force fields, and multithreaded rasterization.
  - Integrates **`FastNoiseLite`** to compute divergence-free **Curl Noise** ($\nabla \cdot \vec{v} = 0$), producing smooth fluid-like particle turbulence.
  - Generates mathematical light sprites on-the-fly (`Star4`, `Star8`, `Bokeh`, `Halo`, `Streak`, `Glitter`).
  - High Dynamic Range (HDR) accumulation pipeline with multi-pass Gaussian Optical Bloom and Reinhard tone mapping.
  - Exposes zero-copy NumPy memory views via **`pybind11`**.
- **Tier 2: Python High-Level API (`particri`)**:
  - Intuitive, declarative class hierarchy with chaining support.
  - Infinite procedural style synthesis engine.
  - Automated Shutterstock batch production and SEO metadata generator.
  - Real-time interactive studio with live 60 FPS Pygame viewport.

---

# 2. Class: ParticleEngine

The primary coordinator managing particles, emitters, forces, and rendering.

```python
import particri
engine = particri.ParticleEngine(max_particles=30000, width=1920, height=1080)
```

### Constructor: `__init__`
```python
ParticleEngine(max_particles: int = 25000, width: int = 1920, height: int = 1080)
```
- **`max_particles`** *(int)*: Maximum number of particles allocated in the pre-allocated C++ memory pool.
- **`width`** *(int)*: Frame buffer horizontal resolution in pixels.
- **`height`** *(int)*: Frame buffer vertical resolution in pixels.

---

### Emitter Management: `add_emitter`
Configures and attaches a new procedural particle emitter to the system.

```python
engine.add_emitter(
    shape=particri.EmitterShape.Point,
    position=(960.0, 540.0),
    size=(100.0, 100.0),
    rate=200.0,
    speed_range=(20.0, 120.0),
    angle_range=(0.0, 6.283185),
    lifetime_range=(1.5, 3.5),
    size_start_range=(6.0, 18.0),
    size_end_range=(0.0, 2.0),
    color_start=(1.0, 0.85, 0.35, 1.0),
    color_variance=(0.1, 0.1, 0.05, 0.0),
    color_end=(1.0, 0.5, 0.1, 0.0),
    particle_shape=particri.ParticleShape.Star4,
    twinkle_speed_range=(3.0, 12.0),
    rotation_speed_range=(-2.0, 2.0),
    drag=0.15,
    radial_velocity=True,
    seed=42
) -> int
```
#### Parameters:
- **`shape`** (`EmitterShape`): Geometry from which particles originate (`Point`, `Circle`, `Ring`, `Box`, `Line`).
- **`position`** (`Tuple[float, float]`): Center `(x, y)` coordinate of the emitter in pixels.
- **`size`** (`Tuple[float, float]`): Emitter dimensions:
  - For `Box`: `(width, height)`.
  - For `Circle`: `(inner_radius, outer_radius)` (inner radius is 0 for solid disc).
  - For `Ring`: `(inner_radius, outer_radius)`.
- **`rate`** (`float`): Emission rate in particles spawned per second.
- **`speed_range`** (`Tuple[float, float]`): Min and max initial ejection velocity in pixels/second.
- **`angle_range`** (`Tuple[float, float]`): Min and max ejection angle in radians `[0, 2π]`.
- **`lifetime_range`** (`Tuple[float, float]`): Min and max lifespan of each particle in seconds.
- **`size_start_range`** (`Tuple[float, float]`): Min and max initial particle diameter in pixels.
- **`size_end_range`** (`Tuple[float, float]`): Min and max diameter at the end of particle lifetime.
- **`color_start`** (`Tuple[float, float, float, float]`): Initial RGBA color in normalized float `[0.0, 1.0+]` (supports HDR values > 1.0).
- **`color_variance`** (`Tuple[float, float, float, float]`): Random jitter added to `color_start` per particle.
- **`color_end`** (`Tuple[float, float, float, float]`): Target RGBA color at the end of particle lifetime.
- **`particle_shape`** (`ParticleShape`): Visual sprite shape (`Bokeh`, `Star4`, `Star8`, `Halo`, `Streak`, `Glitter`).
- **`twinkle_speed_range`** (`Tuple[float, float]`): Frequency of specular twinkle oscillation.
- **`rotation_speed_range`** (`Tuple[float, float]`): Angular rotation speed in radians/second.
- **`drag`** (`float`): Particle specific air resistance coefficient.
- **`radial_velocity`** (`bool`): If `True`, velocity points radially outward from the emitter center.
- **`seed`** (`int`): PRNG seed for reproducible particle distribution.
- **Returns**: `int` - Index of the newly created emitter.

---

### Physics & Force Fields

#### `add_curl_noise`
Adds divergence-free 2D/3D turbulence field computed via finite differences over OpenSimplex2 noise. Guarantees $\nabla \cdot \vec{v} = 0$, giving fluid-like swirling motion without clumping.
```python
engine.add_curl_noise(seed: int = 1337, strength: float = 120.0, frequency: float = 0.003, speed: float = 0.3) -> ParticleEngine
```
- **`seed`**: FastNoiseLite PRNG seed.
- **`strength`**: Force magnitude scaling the curl velocity vectors.
- **`frequency`**: Spatial scale of noise vortices (lower = larger swirling eddies).
- **`speed`**: Temporal rate of evolution of the noise field over time.

#### `add_vortex`
Adds an orbital rotational vortex force around a specified coordinate.
```python
engine.add_vortex(center: Tuple[float, float], strength: float = 150.0, radial_pull: float = 20.0, radius: float = 800.0) -> ParticleEngine
```
- **`center`**: `(x, y)` coordinate of the vortex core.
- **`strength`**: Tangential rotational speed.
- **`radial_pull`**: Inward (positive) or outward (negative) suction force.
- **`radius`**: Maximum effective radius of the vortex field.

#### `add_gravity`
Adds constant directional acceleration (gravity, wind, or diagonal draft).
```python
engine.add_gravity(gx: float = 0.0, gy: float = 98.0) -> ParticleEngine
```

#### `add_drag`
Adds global fluid damping resistance proportional to velocity ($F = -k \cdot v$).
```python
engine.add_drag(coeff: float = 0.5) -> ParticleEngine
```

#### `add_attractor`
Attracts (positive strength) or repels (negative strength) particles towards a point.
```python
engine.add_attractor(target: Tuple[float, float], strength: float = 200.0, min_distance: float = 20.0, max_distance: float = 800.0) -> ParticleEngine
```

#### `add_brownian`
Adds chaotic microscopic Brownian motion jitter (critical for floating dust and pollen).
```python
engine.add_brownian(strength: float = 30.0, seed: int = 42) -> ParticleEngine
```

---

### Trapcode Particular Iconic VFX Systems

#### 1. Auxiliary System (`enable_aux_system` / `disable_aux_system`)
Recreates Trapcode Particular's famous **Aux System** where primary parent particles emit secondary child particles (sparkle trails, smoke dust, or explosive death bursts):
```python
engine.enable_aux_system(
    rate: float = 15.0,                  # Aux particles emitted per parent per second
    lifetime: float = 1.2,               # Lifespan of child particles in seconds
    size_range: Tuple[float, float] = (4.0, 0.5), # (start_size, end_size)
    color_start: Tuple[float, float, float, float] = (1.0, 0.9, 0.4, 0.9),
    color_end: Tuple[float, float, float, float] = (1.0, 0.4, 0.1, 0.0),
    inherit_color: bool = True,          # If True, inherits current parent color
    velocity_inheritance: float = 0.15,  # Percentage of parent velocity inherited
    spread: float = 25.0,                # Random velocity dispersion jitter
    particle_shape: ParticleShape = ParticleShape.Glitter,
    size_curve: CurveType = CurveType.Bell,
    opacity_curve: CurveType = CurveType.GrowAndFade,
    emit_at_death: int = 0               # Burst count when parent particle dies
) -> ParticleEngine

engine.disable_aux_system() -> ParticleEngine
```

#### 2. Layer / Mask Image Emitter (`add_layer_emitter`)
Recreates Trapcode Particular's **Layer Grid Emitter**. Particles are born exclusively from non-empty pixels of an image, logo, or text mask, with optional **automatic pixel color inheritance**:
```python
engine.add_layer_emitter(
    image: Union[str, Path, np.ndarray],  # Filepath or (H, W, 4) NumPy array
    rate: float = 500.0,
    threshold: float = 0.05,              # Alpha / luminance cutoff
    inherit_layer_color: bool = True,     # Particles born with the exact colors of the logo
    speed_range: Tuple[float, float] = (5.0, 30.0),
    lifetime_range: Tuple[float, float] = (1.0, 2.5),
    size_start_range: Tuple[float, float] = (4.0, 10.0),
    size_end_range: Tuple[float, float] = (0.0, 1.0),
    particle_shape: ParticleShape = ParticleShape.Star8,
    size_curve: CurveType = CurveType.Bell,
    opacity_curve: CurveType = CurveType.GrowAndFade,
    drag: float = 0.2,
    seed: int = 42
) -> int
```

#### 3. Floor & Bounce Collision Physics (`add_bounce_plane`)
Recreates Trapcode Particular's **Bounce Physics**. Adds collision planes (floors, ceilings, walls) that particles bounce against with elasticity (restitution) and surface friction:
```python
engine.add_bounce_plane(
    coord: float = 900.0,      # Floor coordinate (y) or wall coordinate (x)
    bounce: float = 0.65,      # Elasticity restitution [0.0 = clay stop, 1.0 = superball]
    friction: float = 0.85,    # Tangential friction factor [0.0 = full stop, 1.0 = frictionless]
    is_horizontal: bool = True,# True for Floor/Ceiling (Y), False for Walls (X)
    is_max: bool = True        # True for Floor / Right Wall (>= coord), False for Ceiling / Left Wall (<= coord)
) -> ParticleEngine
```

#### 4. Curves Over Life (`CurveType`)
Advanced mathematical curves for evaluating size and opacity dynamically across particle lifespan:
- `CurveType.Linear`: Linear ramp from start to end.
- `CurveType.Bell`: $\sin(\pi t)$, peaks at mid-life and fades gracefully at birth and death.
- `CurveType.GrowAndFade`: Grows during first 15% of life, sustains until 75%, then fades out.
- `CurveType.Pulse`: Oscillating shimmer wave.
- `CurveType.Decay`: Exponential decay $e^{-3.5t}$.
- `CurveType.EaseIn`: Quadratic ease in ($t^2$).
- `CurveType.EaseOut`: Quadratic ease out ($1 - (1-t)^2$).

---

### Simulation & Lifecycle Methods

#### `burst`
Instantly spawns $N$ particles in a single frame from the specified emitter.
```python
engine.burst(emitter_idx: int = 0, count: int = 100) -> ParticleEngine
```

#### `update`
Advances physics simulation, force application, lifecycles, and particle emission by `dt` seconds.
```python
engine.update(dt: float) -> ParticleEngine
```

#### `warmup`
Fast-forwards the simulation by `duration` seconds in steps of `step` to achieve steady-state visual dispersion before rendering.
```python
engine.warmup(duration: float = 2.0, step: float = 1.0 / 60.0) -> ParticleEngine
```

#### `clear` / `reset_forces` / `reset_emitters`
```python
engine.clear()          # Deactivates all active particles
engine.reset_forces()   # Removes all registered force fields
engine.reset_emitters() # Removes all registered emitters
```

---

### Rendering Methods

#### `render`
Renders the current frame to an **(H, W, 4) uint8 RGBA** NumPy array with tone mapping.
```python
engine.render(
    blend_mode: BlendMode = BlendMode.Additive,
    bloom: bool = True,
    bloom_threshold: float = 0.35,
    bloom_intensity: float = 0.8,
    bloom_radius: int = 8
) -> np.ndarray
```
- **`blend_mode`**: Blending mode applied during sprite accumulation.
- **`bloom`**: Whether to apply the multi-pass optical Gaussian glow filter.
- **`bloom_threshold`**: Luminance cutoff for bright pixels feeding into the bloom pyramid.
- **`bloom_intensity`**: Multiplier for the composited glow aura.
- **`bloom_radius`**: Kernel radius in pixels for the separable Gaussian blur.
- **Returns**: `np.ndarray` of shape `(H, W, 4)` and type `uint8`.

#### `render_hdr`
Renders to an **(H, W, 4) float32 HDR RGBA** NumPy array without 8-bit clamping.

---

# 3. Enums

### `ParticleShape`
Procedural mathematical light sprites:
- **`ParticleShape.Bokeh`** (0): Soft circular out-of-focus optical disc with smooth edge falloff and subtle rim brightening.
- **`ParticleShape.Star4`** (1): 4-point diamond cross flare with razor-sharp horizontal/vertical diffraction spikes and glowing core.
- **`ParticleShape.Star8`** (2): 8-point cinematic Hollywood starburst with major cross rays and diagonal accent spikes.
- **`ParticleShape.Halo`** (3): Concentric ethereal shockwave ring.
- **`ParticleShape.Streak`** (4): Directional motion-blur spark automatically oriented and stretched along the particle's velocity vector.
- **`ParticleShape.Glitter`** (5): Microscopic faceted crystal facet with high-contrast pinpoint specular sparkle.
- **`ParticleShape.Custom`** (6): Custom RGBA user-provided sprite texture.

### `BlendMode`
- **`BlendMode.Additive`** (0): Adds color values ($C_{dst} += C_{src} \cdot \alpha$). Essential for stars, fire, and glowing light.
- **`BlendMode.Screen`** (1): Soft brightening formula without blowing out into pure white ($1 - (1 - dst)(1 - src)$).
- **`BlendMode.Alpha`** (2): Standard Porter-Duff alpha over blending ($src \cdot \alpha + dst \cdot (1 - \alpha)$). Ideal for smoke, dust, and dark particles.
- **`BlendMode.ColorDodge`** (3): Hyper-luminous magical color dodge ($dst / (1 - src)$).

### `EmitterShape`
- **`EmitterShape.Point`** (0): Emits from a single coordinate.
- **`EmitterShape.Circle`** (1): Emits inside a circular disc.
- **`EmitterShape.Ring`** (2): Emits in a concentric ring between inner and outer radii.
- **`EmitterShape.Box`** (3): Emits uniformly within a rectangular boundary.
- **`EmitterShape.Line`** (4): Emits along a line segment.

---

# 4. Math Primitives

### `Vec2`
2D vector class supporting full vector arithmetic:
```python
from particri import Vec2
v = Vec2(10.0, 20.0)
v.x += 5.0
```

### `Color4`
HDR RGBA color structure:
```python
from particri import Color4
c = Color4(1.0, 0.85, 0.35, 1.0)
c_hex = Color4.from_hex(0xFFD700, alpha=1.0) # Gold
```

---

# 5. Class: Presets

Curated VFX presets that faithfully reproduce every style from luxury stock photography:

```python
import particri
```

### 1. `Presets.golden_sparkles`
Replicates Reference Panel 2: Golden diamond stars, soft glowing bokeh dust, and fine glitter.
```python
engine = particri.Presets.golden_sparkles(width=1920, height=1080, density=1.0, seed=42)
```

### 2. `Presets.starburst_cluster`
Replicates Reference Panel 3: Dense central explosive golden star cluster radiating sparkling dust.
```python
engine = particri.Presets.starburst_cluster(width=1920, height=1080, density=1.0, seed=101)
```

### 3. `Presets.cosmic_nebula`
Replicates Reference Panel 4: Swirling purple/indigo stardust cloud driven by Curl Noise fluid turbulence.
```python
engine = particri.Presets.cosmic_nebula(width=1920, height=1080, density=1.0, seed=202)
```

### 4. `Presets.light_streaks`
Replicates Reference Panel 1: High-velocity directional cyan/emerald light streaks and anamorphic rays.
```python
engine = particri.Presets.light_streaks(width=1920, height=1080, density=1.0, seed=303)
```

### 5. `Presets.glitter_field`
Replicates Reference Bottom Panel: Dense luxury gold glitter texture with high-frequency specular twinkle.
```python
engine = particri.Presets.glitter_field(width=1920, height=1080, density=1.0, seed=404)
```

### 6. `Presets.circle_wreath`
Sparkling circular ring / wreath frame for luxury logos, monograms, and invitation headers.
```python
engine = particri.Presets.circle_wreath(width=1920, height=1080, radius=340.0, density=1.0, seed=505)
```

### 7. `Presets.heart_burst`
Romantic heart-shaped particle constellation for Valentine's Day, weddings, and greeting cards.
```python
engine = particri.Presets.heart_burst(width=1920, height=1080, scale=18.0, density=1.0, seed=606)
```

### 8. `Presets.golden_rain`
Vertical cascading waterfall / rain curtain of twinkling gold dust and soft bokeh drops.
```python
engine = particri.Presets.golden_rain(width=1920, height=1080, density=1.0, seed=707)
```

---

# 6. Class: StyleGenerator (The Infinite Styles Engine)

Procedural synthesis engine capable of producing thousands of unique, non-repeating particle styles.

```python
engine = particri.StyleGenerator.create(
    seed=1234,
    width=1920,
    height=1080,
    palette_name="gold",  # 'gold', 'cosmic', 'solar', 'emerald', 'rose', 'cyberpunk', 'diamond', or None (procedural)
    motion_type="swirl"   # 'swirl', 'burst', 'drift', 'rain', 'vortex', 'cosmic'
)
```
- **`palette_name=None`**: Automatically derives harmonious complementary or split-complementary color palettes using golden ratio hue shifts.
- **`motion_type=None`**: Automatically curates physics parameters, drag coefficients, turbulence frequencies, and Brownian factors.

---

# 7. Class: StockFactory (Shutterstock Mass-Production)

Specialized bulk generator engineered to produce thousands of commercial stock assets for **Shutterstock**, **Adobe Stock**, **Freepik**, and **Envato**.

```python
from particri import StockFactory
```

### `StockFactory.create_asset`
Creates a single commercial asset archetype and its associated SEO metadata.
```python
engine, metadata = StockFactory.create_asset(
    category="frame",     # 'overlay', 'frame', 'burst', 'wave', 'corner', 'glitter'
    theme="gold",         # 'gold', 'silver', 'rose_gold', 'cosmic', 'emerald', 'solar'
    resolution="4K",      # '4K' (3840x2160), '1080p', 'Square' (3000x3000), 'Vertical' (2160x3840)
    seed=100
)
```

### `StockFactory.generate_batch`
Mass-produces an entire collection of assets and writes a ready-to-upload `shutterstock_bulk_upload_manifest.csv` with optimized titles, descriptions, and 35+ SEO keywords per item!
```python
records = StockFactory.generate_batch(
    output_dir="shutterstock_gold_pack",
    count=100,
    resolution="4K",
    export_black_preview=True # Saves transparent PNG + pure black composite for video editors
)
```

---

# 8. Class: Exporter

High-fidelity export pipeline:

```python
from particri import Exporter
```

- **`Exporter.save_image(image_array, filepath, quality=95)`**: Saves to 32-bit RGBA PNG, WebP (lossless), or JPG.
- **`Exporter.save_sequence(engine, output_dir, frames=120, fps=60, warmup=1.5)`**: Exports a numbered sequence of transparent PNG frames.
- **`Exporter.save_video(engine, filepath, duration=4.0, fps=60, warmup=1.5)`**: Exports smooth 60 FPS MP4 video.
- **`Exporter.save_gif(engine, filepath, duration=2.5, fps=30, warmup=1.5)`**: Exports an animated GIF.

---

# 9. Class: Studio

Real-time interactive GUI viewport running at 60 FPS via Pygame:

```python
from particri import Studio
Studio.launch()
```

### Keyboard & Mouse Controls:
- **`[1 - 5]`**: Switch between reference presets (Sparkles, Burst, Nebula, Streaks, Glitter).
- **`[6]`**: Generate a completely new infinite procedural style on-the-fly!
- **`[SPACE]`**: Trigger particle explosion / burst.
- **`[B]`**: Toggle Optical Bloom on / off.
- **`[S]`**: Save high-resolution PNG screenshot to disk.
- **`Mouse Click & Drag`**: Emit particles interactively at cursor location.

---

# 10. End-to-End Tutorials

### Tutorial 1: Generate 1,000 Shutterstock 4K Assets with Metadata
```python
import particri

# Produce 1,000 unique 4K stock assets
particri.StockFactory.generate_batch(
    output_dir="my_shutterstock_collection_4k",
    count=1000,
    resolution="4K",
    export_black_preview=True
)
print("Complete! Upload the generated PNGs and the manifest CSV directly to Shutterstock.")
```

### Tutorial 2: Creating a Custom Swirling Golden Spell Circle
```python
import particri

engine = particri.ParticleEngine(max_particles=35000, width=1920, height=1080)
cx, cy = 960.0, 540.0

# 1. Add physics forces
engine.add_vortex(center=(cx, cy), strength=160.0, radial_pull=15.0, radius=600.0)
engine.add_curl_noise(seed=42, strength=80.0, frequency=0.003, speed=0.25)
engine.add_drag(0.15)

# 2. Add sparkling ring emitter
engine.add_emitter(
    shape=particri.EmitterShape.Ring,
    position=(cx, cy),
    size=(250.0, 320.0),
    rate=450.0,
    speed_range=(10.0, 40.0),
    lifetime_range=(2.0, 4.5),
    size_start_range=(16.0, 48.0),
    color_start=(1.0, 0.9, 0.45, 1.0),
    color_end=(1.0, 0.5, 0.1, 0.0),
    particle_shape=particri.ParticleShape.Star4,
    twinkle_speed_range=(6.0, 18.0)
)

# 3. Simulate and save
engine.warmup(2.5)
frame = engine.render(bloom=True, bloom_intensity=0.9)
particri.Exporter.save_image(frame, "golden_spell_vortex.png")
```