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 (نظرة عامة على البنية البرمجية)
2. Class: ParticleEngine (محرك الجزيئات الأساسي)
3. Enums (الثوابت والتصنيفات)
   • ParticleShape (أشكال الجزيئات)
   • BlendMode (أوضاع دمج الألوان)
   • EmitterShape (أشكال البواعث)
4. Math Primitives: Vec2 & Color4 (بُنى الرياضيات والألوان)
5. Class: Presets (الأنماط الجاهزة فائقة الواقعية)
6. Class: StyleGenerator (مولد الستايلات اللانهائية)
7. Class: StockFactory (مصنع أصول الستوك الضخم لـ Shutterstock)
8. Class: Exporter (نظام التصدير للصور والفيديو والمتحركات)
9. Class: Studio (الأستوديو التفاعلي المباشر 60 FPS)
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.

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

Constructor: __init__

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.

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.

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.

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).

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$).

engine.add_drag(coeff: float = 0.5) -> ParticleEngine

add_attractor

Attracts (positive strength) or repels (negative strength) particles towards a point.

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).

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):

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:

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:

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.

engine.burst(emitter_idx: int = 0, count: int = 100) -> ParticleEngine

update

Advances physics simulation, force application, lifecycles, and particle emission by dt seconds.

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.

engine.warmup(duration: float = 2.0, step: float = 1.0 / 60.0) -> ParticleEngine

clear / reset_forces / reset_emitters

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.

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:

from particri import Vec2
v = Vec2(10.0, 20.0)
v.x += 5.0

Color4

HDR RGBA color structure:

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:

import particri

1. Presets.golden_sparkles

Replicates Reference Panel 2: Golden diamond stars, soft glowing bokeh dust, and fine glitter.

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.

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.

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.

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.

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.

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.

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.

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.

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.

from particri import StockFactory

StockFactory.create_asset

Creates a single commercial asset archetype and its associated SEO metadata.

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!

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:

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:

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

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

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")