particri

Particri (بارتيكري) 🌟

Ultra-High-Performance C++ & Python Procedural Particle Engine

Particri is a professional particle simulation and procedural rendering library designed to generate photorealistic and stylized visual particle effects with infinite styles. It combines a blazing fast C++20 physics and rasterization core (integrated with FastNoiseLite) with a clean, expressive Python API.

---

📸 Reference Styles & Visual Capabilities

The engine is engineered from the ground up to synthesize every visual aesthetic shown below:

• Golden Diamond Stars & Sparkles (البريق والنجوم الماسية): 4-point & 8-point diffraction spikes with glowing cores.
• Soft Floating Bokeh (دوائر البوكيه العائمة): Optical out-of-focus discs with smooth chromatic falloff.
• Starburst Nova Clusters (العناقيد والانفجارات النجمية): Dense concentrated bursts of sparkling energy.
• Cosmic Nebula Stardust (السدم والغبار الكوني): Organic fluid-like turbulence powered by divergence-free Curl Noise.
• Anamorphic Light Streaks (خطوط الضوء والسرعة): Directional velocity-aligned motion trails and lens flares.
• Luxury Glitter Texture (نسيج الجليتر المتلألئ): Microscopic faceted crystals with high-frequency specular twinkle.

---

⚡ Key Architectural Features

1. C++20 High-Performance Core:
   • Vectorized math engine with SIMD operations.
   • Header-only integration with FastNoiseLite for 3D OpenSimplex2 and Fractal Brown Noise.
   • True 2D Curl Noise computation: guarantees $\nabla \cdot \vec{v} = 0$ (incompressible fluid motion) so particles swirl naturally without clumping.
2. Procedural Light Sprite Synthesis:
   • Mathematical sprites generated on-the-fly: Star4, Star8, Bokeh, Halo, Streak, Glitter.
   • No external image dependencies required for sprites.
3. Multi-Pass Optical Bloom & HDR Pipeline:
   • HDR floating-point accumulation buffer.
   • Multi-scale separable Gaussian bloom for dreamy, cinematic halos.
   • Reinhard tone mapping preserving rich warm hues at peak luminance.
4. Infinite Styles Generator:
   • Procedural color harmony synthesis (Golden Ratio, Complementary, Triadic).
   • Random seedable configurations allowing generation of thousands of unique particle styles.
5. Zero-Copy NumPy Interoperability:
   • Direct memory view buffer exchange with Python.
   • Instant export to transparent PNG, WebP, animated GIF, and MP4 video.
6. Real-Time Interactive Studio:
   • 60 FPS live viewer with interactive emitter controls and instant preset switching.
7. Trapcode Particular VFX Systems:
   • Auxiliary (Aux) System: Parent particles emit trailing child sparkles and death bursts.
   • Layer Mask Emitter: Emits particles from image masks and logos with pixel color inheritance.
   • Floor/Wall Bounce Physics: Realistic elastic rebound and surface friction against boundary planes.
   • Curves Over Life: Dynamic mathematical graphs (Bell curve, GrowAndFade, Pulse, Decay, EaseInOut).

---

🚀 Quick Start & Usage

1. Generating Golden Sparkles (Reference Panel 2)

import particri

# Initialize golden sparkles preset
engine = particri.Presets.golden_sparkles(width=1920, height=1080, density=1.2)

# Warmup simulation for natural dispersal
engine.warmup(duration=2.0)

# Render with optical bloom
frame = engine.render(bloom=True, bloom_intensity=0.85)

# Save as transparent 32-bit RGBA PNG
particri.Exporter.save_image(frame, "golden_sparkles.png")

2. Generating Infinite Procedural Styles

import particri

# Generate a unique style from any random seed
engine = particri.StyleGenerator.create(
    seed=777,
    width=1920,
    height=1080,
    palette_name="emerald",  # Options: 'gold', 'cosmic', 'solar', 'emerald', 'rose', 'cyberpunk', 'diamond', or None (procedural)
    motion_type="swirl",     # Options: 'swirl', 'burst', 'drift', 'vortex', 'rain', 'cosmic'
)

engine.warmup(2.0)
frame = engine.render()
particri.Exporter.save_image(frame, "unique_style_777.png")

3. Exporting 60 FPS Video (MP4) or Animated GIF

import particri

engine = particri.Presets.starburst_cluster(width=1280, height=720)

# Export MP4 video
particri.Exporter.save_video(engine, "starburst.mp4", duration=3.0, fps=60)

# Export animated GIF
particri.Exporter.save_gif(engine, "starburst.gif", duration=2.0, fps=25)

4. Real-Time Interactive Studio

from particri import Studio

# Launch real-time studio
# Controls: [1-5] Presets | [6] New Infinite Style | [SPACE] Burst | [B] Bloom | [S] Screenshot
Studio.launch()

---

📁 Project Structure

particri/
├── include/
│   ├── FastNoiseLite.h         # FastNoiseLite C++ noise library
│   └── particri/
│       ├── math.hpp            # Vec2, Vec3, Color4, Random
│       ├── particle.hpp        # Particle struct, shapes, blend modes
│       ├── forces.hpp          # CurlNoise, Vortex, Gravity, Drag, Attractor
│       ├── emitter.hpp         # Point, Circle, Ring, Box, Line emitters
│       ├── shapes.hpp          # Procedural mathematical sprite generator
│       ├── rasterizer.hpp      # HDR rasterizer & blend modes
│       ├── bloom.hpp           # Multi-pass optical bloom filter
│       └── system.hpp          # ParticleSystem coordinator
├── src/
│   └── bindings.cpp            # Pybind11 C++ module bindings
├── particri/                   # Python package
│   ├── __init__.py             # Top-level module exports
│   ├── core.py                 # ParticleEngine Python API
│   ├── presets.py              # Reference image & luxury presets
│   ├── styles.py               # Infinite procedural style generator
│   ├── exporter.py             # PNG, WebP, MP4, GIF exporters
│   └── studio.py               # Interactive real-time Pygame viewer
├── examples/                   # Standalone runnable scripts
│   ├── 01_golden_sparkles.py
│   ├── 02_starburst_nova.py
│   ├── 03_cosmic_nebula.py
│   ├── 04_light_streaks.py
│   ├── 05_glitter_field.py
│   ├── 06_infinite_styles_demo.py
│   ├── 07_export_video.py
│   └── 08_reference_replica_grid.py
├── tests/
│   └── test_particri.py        # Complete pytest suite
├── CMakeLists.txt
├── setup.py
└── pyproject.toml

---

🧪 Testing

Run the automated test suite:

pytest tests/ -v

All tests verify physics simulation, emitters, force fields, blend modes, presets, procedural style synthesis, and image exports.