Release NaraMotion v0.26.0: Structure of Arrays (SoA), Path Arena Allocator, Uniform Grid Indexing, Dual-Buffer Rendering & Centroid Spring Pop-in

-

@@ -0,0 +1,73 @@
+# 1 "C:/Users/islam/OneDrive/Desktop/PyBlend/cmake-bin/cmake-3.31.5-windows-x86_64/share/cmake-3.31/Modules/CXX-DetectStdlib.h"
+# 1 "<built-in>" 1
+# 1 "<built-in>" 3
+# 452 "<built-in>" 3
+# 1 "<command line>" 1
+# 1 "<built-in>" 2
+# 1 "C:/Users/islam/OneDrive/Desktop/PyBlend/cmake-bin/cmake-3.31.5-windows-x86_64/share/cmake-3.31/Modules/CXX-DetectStdlib.h" 2
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/version" 1 3
+# 247 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/version" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assert" 1 3
+# 13 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assert" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assertion_handler" 1 3
+# 13 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assertion_handler" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__config" 1 3
+# 17 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__config" 3
+# 517 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__config" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 1 3
+# 407 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features-time64.h" 1 3
+# 20 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features-time64.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/bits/wordsize.h" 1 3
+# 21 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features-time64.h" 2 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/bits/timesize.h" 1 3
+# 19 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/bits/timesize.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/bits/wordsize.h" 1 3
+# 20 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/bits/timesize.h" 2 3
+# 22 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features-time64.h" 2 3
+# 408 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 2 3
+# 505 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/stdc-predef.h" 1 3
+# 506 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 2 3
+# 519 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/sys/cdefs.h" 1 3
+# 576 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/sys/cdefs.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/bits/wordsize.h" 1 3
+# 577 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/sys/cdefs.h" 2 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/bits/long-double.h" 1 3
+# 578 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/sys/cdefs.h" 2 3
+# 520 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 2 3
+# 543 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/gnu/stubs.h" 1 3
+# 10 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/gnu/stubs.h" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/gnu/stubs-64.h" 1 3
+# 11 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\x86_64-linux-gnu/gnu/stubs.h" 2 3
+# 544 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libc\\include\\generic-glibc/features.h" 2 3
+# 518 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__config" 2 3
+# 14 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assertion_handler" 2 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__verbose_abort" 1 3
+# 13 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__verbose_abort" 3
+# 1 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__availability" 1 3
+# 17 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__availability" 3
+# 14 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__verbose_abort" 2 3
+# 18 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__verbose_abort" 3
+
+
+namespace std { inline namespace __1 {
+
+
+
+[[noreturn]]
+    __attribute__((__format__(__printf__, 1, 2))) void __libcpp_verbose_abort(const char* __format, ...);
+# 51 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__verbose_abort" 3
+}}
+# 15 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assertion_handler" 2 3
+# 18 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assertion_handler" 3
+# 14 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assert" 2 3
+# 18 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/__assert" 3
+# 248 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/version" 2 3
+# 253 "zig-bin\\zig-windows-x86_64-0.13.0\\lib\\libcxx\\include/version" 3
+# 2 "C:/Users/islam/OneDrive/Desktop/PyBlend/cmake-bin/cmake-3.31.5-windows-x86_64/share/cmake-3.31/Modules/CXX-DetectStdlib.h" 2
+
+
+CMAKE-STDLIB-DETECT: libc++

.gitattributes

@@ -33,3 +33,52 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_fx.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_fx.pdb filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_fx.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_geo.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_geo.pdb filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_geo.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_motion.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_motion.pdb filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_motion.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_perspective.pdb filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_video.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_video.pdb filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libblend2d_video.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_fx.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_fx.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_geo.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_geo.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_motion.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_motion.so filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_video.dll filter=lfs diff=lfs merge=lfs -text
+blend2d/_bin/libnaramotion_video.so filter=lfs diff=lfs merge=lfs -text
+dist/naramotion-0.26.0-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_fx.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_fx.pdb filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_fx.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_geo.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_geo.pdb filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_geo.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_motion.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_motion.pdb filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_motion.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_perspective.pdb filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_video.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_video.pdb filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libblend2d_video.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_fx.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_fx.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_geo.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_geo.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_motion.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_motion.so filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_video.dll filter=lfs diff=lfs merge=lfs -text
+naramotion/_bin/libnaramotion_video.so filter=lfs diff=lfs merge=lfs -text
+test_winhttp.dll filter=lfs diff=lfs merge=lfs -text
+test_winhttp.pdb filter=lfs diff=lfs merge=lfs -text

AI_RULES.md

@@ -0,0 +1,189 @@
+# 🤖 AI_RULES.md: Master System Prompt & Engineering Guidelines for NaraMotion
+
+> **NOTE FOR AI CODING ASSISTANTS (ChatGPT, Claude, Gemini, DeepSeek, Cursor, Copilot, Kaggle)**:
+> This document defines the strict architectural rules, API standards, and execution patterns for writing code using **NaraMotion** (`import naramotion as nm` or `from naramotion import ...`).
+
+---
+
+## 🛑 1. The Cardinal Rule: 100% Native & Self-Contained Engine
+
+**NaraMotion is an All-in-One Super Engine** combining JIT-accelerated vector drawing, cinematic visual FX, motion graphics, 2.5D perspective camera, particle physics, GIS mapping, multi-threaded Parquet ingestion, and hardware video encoding into a single native C++ pipeline.
+
+### ⛔ BANNED EXTERNAL LIBRARIES (DO NOT USE):
+| Prohibited Library | Reason | Native NaraMotion Replacement |
+| :--- | :--- | :--- |
+| `import cv2` (OpenCV) | Redundant & slow memory copies | `from naramotion.fx import bloom, neon_glow, gaussian_blur, box_blur_integral, chromatic_aberration, color_grade, tone_map_aces` |
+| `import moviepy` / `imageio` | Inefficient Python video wrappers | `from naramotion.video import VideoWriter` or direct `img.buffer` pipe |
+| `from PIL import Image` | Unnecessary wrapper overhead | `from naramotion import Image, Context` (includes `to_pil()` / `from_pil()`) |
+| `import matplotlib.pyplot` | Slow vector rendering | `from naramotion.shapgeo import GeoCanvas` or `ctx.stroke_line_array` |
+| `import scipy.ndimage` | External filter dependency | `from naramotion.fx import FXPipeline, gaussian_blur, box_blur, box_blur_integral` |
+| `import pyproj` | Heavy external projection dependency | `from naramotion.shapgeo import Transformer, reproject_gdf` (Native C++ Proj Engine) |
+
+---
+
+## 🔑 2. Mandatory Commercial License Activation
+
+Every standalone script or notebook cell must begin by activating the license:
+
+```python
+import naramotion as nm
+
+# 1. Activate License (Bypasses evaluation watermark)
+nm.set_license("08032008is")
+```
+
+---
+
+## 🗺️ 3. Native Module Directory & Import Map
+
+```python
+# 1. Core Vector & Context Engine
+from naramotion import (
+    Image, Context, Path, Font, FontFace, Matrix2D,
+    Format, CompOp, StrokeCap, StrokeJoin, FillRule, ExtendMode,
+    Color, Rgba32, Rgba, set_license, is_licensed, Palette
+)
+
+# 2. Cinematic Post-Processing & Visual FX Engine
+from naramotion.fx import (
+    bloom, neon_glow, gaussian_blur, box_blur, box_blur_integral,
+    chromatic_aberration, vignette, film_grain,
+    color_grade, grayscale, invert, sepia,
+    scanlines, glitch_displacement, drop_shadow,
+    tone_map_aces, tone_map_reinhard, FXPipeline
+)
+
+# 3. Motion Graphics, Particles, Timeline & 2.5D Camera
+from naramotion.motion import (
+    Timeline, Easing, Spring, CubicBezier,
+    Action, DrawReveal, Create, ShowCreation, Uncreate, Typewriter, Stagger,
+    interpolate, Extrapolate, chaikin_smooth, chaikin_smooth_points,
+    Sequence, Composition, delay_render,
+    ParticleSystem, trim_path, PathFollower, PathMorph,
+    Scene, Node, Camera2D, PerspectiveCamera, render_globe
+)
+
+# 4. Geospatial & GIS Big Data Engine
+from naramotion.shapgeo import (
+    GeoCanvas, GeoTransform, auto_bounds, compute_center,
+    read_file, read_parquet, read_parquet_native, read_geojson, read_shapefile,
+    Transformer, to_web_mercator, to_wgs84, reproject_gdf,
+    RetainedGeoLayer, NativeGeoLayerSoA, UniformGridIndex, clip_polygon_bbox
+)
+
+# 5. Zero-Copy Hardware Video Encoder & Reader
+from naramotion.video import VideoWriter, VideoReader, record_animation
+```
+
+---
+
+## 🎬 4. Core Motion & Declarative Kinetic Suite
+
+### Declarative Reveal Actions (`Create`, `ShowCreation`, `Uncreate`):
+```python
+from naramotion.motion import Create, ShowCreation, Uncreate, Timeline
+
+timeline = Timeline(fps=60)
+timeline.add_action(Create(road_path, duration=2.5, easing=Easing.cubic_out), start_time=0.0)
+```
+
+### Chaikin's Corner Smoothing (Native C++ Curve Curvature Continuous):
+```python
+from naramotion.motion import chaikin_smooth
+
+# Smooth raw polygon/linestring/coords in C++ in 0.01ms
+smooth_geometry = chaikin_smooth(raw_road_geometry, iterations=2)
+```
+
+### Interpolation & Extrapolation Remapping:
+```python
+from naramotion.motion import interpolate, Extrapolate
+
+# Piecewise remapping with clamping or bounce
+val = interpolate(progress, [0.0, 0.5, 1.0], [0.0, 100.0, 50.0], extrapolate=Extrapolate.CLAMP)
+```
+
+### Distributed Temporal Composition (`Sequence`, `delay_render`):
+```python
+from naramotion.motion import Sequence, Composition, delay_render
+
+seq = Sequence(from_frame=60, duration_frames=180)
+```
+
+---
+
+## 🗺️ 5. Geospatial Super-Engine (Structure of Arrays, Dual-Buffer, Spring Pop-in)
+
+### 1. Structure of Arrays (SoA) & Path Memory Arena (`NativeGeoLayerSoA`):
+Pre-allocates city blocks in contiguous C++ cache lines (`distances`, `bboxes`, `paths`, `centroids`, `start_frames`), eliminating heap jitter:
+```python
+from naramotion import NativeGeoLayerSoA
+
+layer = NativeGeoLayerSoA(capacity=50000)
+layer.from_wkb_batch(wkb_list, transform=canvas.transform)
+layer.compute_propagation(epicenters=[(-74.0060, 40.7128)], duration_frames=300.0)
+```
+
+### 2. Dual-Buffer Polygon Rendering & Centroid Spring Pop-in:
+> **PERFORMANCE RULE**: Group fills into Pass 1 and strokes into Pass 2 to keep Blend2D JIT pipelines 100% hot (2.5x faster). Animate expansion via `popin=True` ($Scale(t) = \text{Easing::back\_out}(t)$) centered on feature centroids:
+```python
+with GeoCanvas(width=3840, height=2160, bg_color="#030408") as canvas:
+    canvas.crop_and_fit(min_lon, min_lat, max_lon, max_lat, aspect_ratio=16/9)
+    
+    with VideoWriter("output_4k.mp4", 3840, 2160, fps=60) as vw:
+        for frame in range(300):
+            canvas.clear_frame("#030408")  # Fast memset clear in 0.4ms
+            
+            # Dual-buffer batch render with elastic spring pop-in
+            layer.render_popin(
+                canvas, current_frame=frame,
+                fill_color="#00F0FF", stroke_color="#FFFFFF", stroke_width=1.0
+            )
+            
+            # Zero-copy pipe stream directly to FFmpeg stdin
+            vw.write_frame(canvas.image)
+```
+
+### 3. Flat Uniform Grid Spatial Indexing (`UniformGridIndex`):
+```python
+from naramotion import UniformGridIndex
+
+grid = UniformGridIndex(bounds=(-74.1, 40.6, -73.8, 40.9), grid_w=64, grid_h=64)
+grid.build_from_bboxes(bboxes)
+visible_ids = grid.query_bbox(-74.01, 40.70, -73.98, 40.75) # < 1 microsecond!
+```
+
+### 4. Zero-Object Native Parquet / WKB Ingestion:
+```python
+import naramotion as nm
+
+# Streams WKB directly into C++ SoA layers bypassing Python/Shapely completely
+layer = nm.read_parquet_native("nyc_blocks.parquet", return_native_soa=True)
+```
+
+### 5. Fast Built-in Metric Projection (Proj Engine):
+```python
+# C++ SIMD transformations for EPSG:4326, 3857, 2263, 5070, and UTM
+projected = nm.reproject_gdf(gdf, target_crs="EPSG:2263")
+```
+
+### 6. 4K Ultra-Fast Hierarchical Downsampled Bloom:
+```python
+from naramotion.fx import bloom
+
+# Multi-threaded pyramid downsampling runs in < 60ms on full 4K frames
+bloom(canvas.image, threshold=0.4, intensity=1.5, radius=16.0)
+```
+
+---
+
+## 🎯 6. AI Code Validation Checklist
+
+Before presenting NaraMotion code to the user, ensure:
+1. `naramotion.set_license("08032008is")` is present.
+2. NO `cv2`, `PIL`, `pyproj`, or `moviepy` are imported.
+3. For video loops, instantiate `GeoCanvas` ONCE outside the loop and reuse via `canvas.clear_frame(...)`.
+4. For polygon blocks/roads in animations, pre-compile with `canvas.create_retained_layer(...)` or `NativeGeoLayerSoA(...)`.
+5. For animated building reveals, utilize `layer.render_popin(...)` or `dual_buffer=True`.
+6. Visual FX use `naramotion.fx.*` or `FXPipeline`.
+7. Video export uses `naramotion.video.VideoWriter` or direct `img.buffer` pipe.

DOCUMENTATION.md

@@ -0,0 +1,889 @@
+# NaraMotion Complete API Documentation & Reference Guide 📚✨
+
+**Author & Creator**: Islam Arifi  
+**Official PyPI Package**: [`naramotion`](https://pypi.org/project/naramotion/) (v0.26.0)  
+**Core Engine**: Powered by Blend2D (Native C++ JIT Compiler & SIMD Hardware Acceleration)  
+**License**: Proprietary Commercial License (with Evaluation Mode)
+
+
+---
+
+## 📑 Table of Contents
+
+1. [Official Installation](#1-official-installation)
+2. [Commercial License & Evaluation Watermark Removal](#2-commercial-license--evaluation-watermark-removal)
+3. [Architectural Overview: C++ vs. Python](#3-architectural-overview-c-vs-python)
+4. [C++ to Python Translation Cheat Sheet](#4-c-to-python-translation-cheat-sheet)
+5. [Strict Color Input Specifications & Restrictions](#5-strict-color-input-specifications--restrictions)
+6. [Image Handling (`naramotion.Image`)](#6-image-handling-blend2dimage)
+7. [2D Rendering Context (`naramotion.Context`)](#7-2d-rendering-context-blend2dcontext)
+8. [Vector Path Builder (`naramotion.Path`)](#8-vector-path-builder-blend2dpath)
+9. [Typography & Fonts (`naramotion.Font`, `naramotion.FontFace`)](#9-typography--fonts-blend2dfont-blend2dfontface)
+10. [Gradients & Patterns (`naramotion.style`)](#10-gradients--patterns-blend2dstyle)
+11. [Geometric Primitives (`naramotion.geometry`)](#11-geometric-primitives-blend2dgeometry)
+12. [Affine Transformations (`naramotion.Matrix2D`)](#12-affine-transformations-blend2dmatrix2d)
+13. [Bulk & Batch Operations for Big Data](#13-bulk--batch-operations-for-big-data)
+14. [Zero-Copy NumPy & FFmpeg Video Streaming](#14-zero-copy-numpy--ffmpeg-video-streaming)
+15. [Hardware-Accelerated Video Engine (`naramotion.video`)](#15-hardware-accelerated-video-engine-blend2dvideo)
+16. [Geospatial & Big Data Engine (`naramotion.shapgeo` / `naramotion.geo`)](#16-geospatial--big-data-engine-blend2dshapgeo--blend2dgeo)
+17. [Motion Graphics & Animation (`naramotion.motion`)](#17-motion-graphics--animation-blend2dmotion)
+    - [17.1 Easing Curves Reference Table & Physics Springs](#171-easing-curves-reference-table--physics-springs)
+    - [17.2 Vector Path Animations & Trimming](#172-vector-path-animations--trimming)
+    - [17.3 Particle Simulation & VFX Engine](#173-particle-simulation--vfx-engine)
+    - [17.4 Scene Graph, Layers & Camera2D](#174-scene-graph-layers--camera2d)
+    - [17.5 Multi-Track Timeline & Direct Video Export](#175-multi-track-timeline--direct-video-export)
+18. [Kinetic Perspective & 3D Globe (`naramotion.motion.PerspectiveCamera`)](#18-kinetic-perspective--3d-globe-blend2dmotionperspectivecamera)
+19. [Cinematic Visual FX & Post-Processing (`naramotion.fx`)](#19-cinematic-visual-fx--post-processing-blend2dfx)
+20. [Enumerations Reference](#20-enumerations-reference)
+21. [Performance & Best Practices Guide](#21-performance--best-practices-guide)
+22. [Comprehensive Error Catalog, Exceptions & Troubleshooting Guide](#22-comprehensive-error-catalog-exceptions--troubleshooting-guide)
+
+---
+
+## 1. Official Installation
+
+NaraMotion is published officially on **PyPI** (`naramotion`) with pre-compiled native C++ binaries for maximum performance:
+
+### 📦 Standard PyPI Installation:
+```bash
+pip install naramotion
+```
+
+### 🛠️ Optional Ecosystem Dependencies:
+```bash
+# NumPy & Pillow integration (Zero-Copy views)
+pip install "naramotion[numpy,pil]"
+
+# Full GIS & Testing Suite (GeoPandas, Shapely, Pytest)
+pip install "naramotion[all]"
+```
+
+### ✅ Quick Verification & Sanity Check:
+```python
+import naramotion
+
+print(f"✨ NaraMotion Version: {naramotion.__version__} by {naramotion.__author__}")
+
+# Render test surface
+img = naramotion.Image(400, 400)
+with naramotion.Context(img) as ctx:
+    ctx.fill_all("#090D16")
+    ctx.fill_circle(200, 200, 80, "#38BDF8")
+
+img.save("test_render.png")
+print("🚀 NaraMotion is installed and rendering with 100% hardware acceleration!")
+```
+
+---
+
+## 2. Commercial License & Evaluation Watermark Removal
+
+NaraMotion is distributed under a **Proprietary Commercial License** with an Evaluation Mode.
+
+### Evaluation Mode Behavior:
+- When unlicensed, rendered images saved to disk or encoded to bytes contain a semi-transparent `"Auras"` watermark in the center.
+- Full API functionality, SIMD acceleration, GIS, and video features remain active during evaluation.
+
+### Activating the Commercial License:
+Call `naramotion.set_license()` with your commercial activation key at script startup:
+
+```python
+import naramotion
+
+# Activate commercial license (replaces 'YOUR_COMMERCIAL_KEY' with your purchased key)
+naramotion.set_license("YOUR_COMMERCIAL_KEY")
+
+print(f"🔑 License Activated: {naramotion.is_licensed()}")
+```
+
+Or set the environment variable on your system/server:
+```bash
+export NARAMOTION_LICENSE_KEY="YOUR_COMMERCIAL_KEY"  # Linux / macOS
+set NARAMOTION_LICENSE_KEY="YOUR_COMMERCIAL_KEY"     # Windows
+```
+
+---
+
+## 3. Architectural Overview: C++ vs. Python
+
+NaraMotion exposes the full power of Blend2D's native JIT engine while adapting all APIs into clean, idiomatic Python:
+
+| Concept | C++ (Blend2D) | Python (NaraMotion) |
+| :--- | :--- | :--- |
+| **Naming Convention** | CamelCase (`fillCircle`, `setStrokeWidth`) | snake_case (`fill_circle`, `stroke_width = ...`) |
+| **Context Lifecycle** | `BLContext ctx(img); ... ctx.end();` | `with Context(img) as ctx:` (Auto end/flush) |
+| **Colors** | `BLRgba32(0xFF0000FF)` | String (`"#FF0000"`), Tuple `(255, 0, 0)`, or `0xFFFF0000` |
+| **Properties** | `ctx.setCompOp(...)`, `ctx.getCompOp()` | `ctx.comp_op = CompOp.SRC_OVER` |
+| **Matrix Math** | `m.postTranslate(x, y)` | `m.translate(x, y)` or `m1 * m2` |
+| **NumPy Access** | `BLImageData::pixelData` | `img.to_numpy(copy=False)` (Zero-copy ndarray) |
+| **Video Streaming** | Manual pointer copy | `img.buffer` (Zero-copy Python `memoryview`) |
+
+---
+
+## 4. C++ to Python Translation Cheat Sheet
+
+### Creating an Image and Context
+**C++:**
+```cpp
+BLImage img(800, 600, BL_FORMAT_PRGB32);
+BLContext ctx(img);
+ctx.fillAll(BLRgba32(0xFF000000));
+ctx.fillCircle(BLCircle(400, 300, 100), BLRgba32(0xFFFF3366));
+ctx.end();
+img.writeToFile("output.png");
+```
+
+**Python:**
+```python
+from naramotion import Image, Context, Format
+
+img = Image(800, 600, Format.PRGB32)
+with Context(img) as ctx:
+    ctx.fill_all("black")
+    ctx.fill_circle(400, 300, 100, "#FF3366")
+
+img.save("output.png")
+```
+
+---
+
+## 5. Strict Color Input Specifications & Restrictions
+
+> [!WARNING]
+> **Strict C++ Parser Rule**:
+> The Blend2D parser does **NOT** accept CSS functional syntax like `"rgba(255, 0, 0, 0.5)"` or `"rgb(0, 255, 0)"`.
+> Colors must strictly be provided in one of the 5 formats below:
+
+| Format Type | Syntax Example | Technical Notes |
+| :--- | :--- | :--- |
+| **1. Hex String (RGB)** | `"#38BDF8"` or `"#F00"` | 6 or 3 hex characters prefixed with `#` |
+| **2. Hex String with Alpha (RGBA)** | `"#38BDF888"` or `"#F008"` | 8 or 4 hex characters (`AA` at end) |
+| **3. Named SVG / CSS Colors** | `"crimson"`, `"deepskyblue"`, `"black"` | Standard keyword identifiers |
+| **4. Numeric Tuple (RGB / RGBA)** | `(56, 189, 248)` or `(56, 189, 248, 128)` | Integers strictly between `[0, 255]` |
+| **5. 32-bit Packed Integer (ARGB)** | `0x8838BDF8` | Memory layout: `0xAARRGGBB` |
+| **6. Class Instances** | `Rgba32(56, 189, 248, 255)` or `Rgba(0.22, 0.74, 0.97, 1.0)` | Native C struct wrappers |
+
+---
+
+## 6. Image Handling (`naramotion.Image`)
+
+```python
+# Constructor Signature:
+Image(width: int = 0, height: int = 0, format: Format = Format.PRGB32)
+```
+
+```python
+# 3-Line MWE:
+from naramotion import Image, Format
+img = Image(1920, 1080, Format.PRGB32)
+img.save("frame.png")
+```
+
+### Supported Pixel Formats:
+- `Format.PRGB32`: 32-bit Premultiplied ARGB (Default, fastest SIMD execution and highest quality).
+- `Format.XRGB32`: 32-bit RGB with ignored alpha.
+- `Format.A8`: 8-bit Alpha mask only (ideal for glyph caches and matte compositing).
+
+### Complete Method Signatures:
+- `img.create(width: int, height: int, format: Format = Format.PRGB32)`: Reallocate image buffer.
+- `img.reset()`: Free underlying native image memory.
+- `img.copy() -> Image` / `img.clone() -> Image`: Create a deep copy of the image.
+- `img.convert(format: Format)`: In-place format conversion.
+- `img.read_from_file(path: str)`: Load PNG, JPEG, BMP from disk.
+- `img.write_to_file(path: str, codec: str = "PNG")`: Write to disk.
+- `img.save(path: str)`: Alias for `write_to_file`.
+- `img.to_data(codec: str = "PNG") -> bytes`: Encode directly to in-memory bytes.
+- `Image.from_file(path: str) -> Image`: Classmethod to load an image.
+- `Image.from_data(data: bytes) -> Image`: Classmethod to decode bytes.
+- `img.to_numpy(copy: bool = False) -> np.ndarray`: Return `(H, W, 4)` uint8 BGRA view.
+- `Image.from_numpy(arr: np.ndarray) -> Image`: Wrap or copy NumPy ndarray into Blend2D Image.
+- `img.to_pil() -> PIL.Image`: Convert to Pillow Image.
+- `Image.from_pil(pil_img) -> Image`: Convert Pillow Image to Blend2D Image.
+- `img.buffer -> memoryview`: Zero-copy `memoryview` for high-throughput streaming.
+
+---
+
+## 7. 2D Rendering Context (`naramotion.Context`)
+
+```python
+# Context Manager Usage:
+with Context(image: Image) as ctx:
+    ...
+```
+
+```python
+# 3-Line MWE:
+from naramotion import Image, Context
+img = Image(800, 600)
+with Context(img) as ctx:
+    ctx.fill_all("#0B0F19")
+    ctx.fill_circle(400, 300, 120, "#38BDF8")
+```
+
+### Complete Rendering API Signatures:
+
+#### 1. Canvas Clearing & Rectangles:
+- `ctx.fill_all(style)`: Fill entire surface with color, gradient, or pattern.
+- `ctx.clear_all()`: Clear surface to fully transparent black `(0x00000000)`.
+- `ctx.fill_rect(x: float, y: float, w: float, h: float, style)`
+- `ctx.stroke_rect(x: float, y: float, w: float, h: float, style)`
+- `ctx.fill_round_rect(x: float, y: float, w: float, h: float, rx: float, ry: Optional[float] = None, style)`
+- `ctx.stroke_round_rect(x: float, y: float, w: float, h: float, rx: float, ry: Optional[float] = None, style)`
+
+#### 2. Circles, Ellipses & Arcs:
+- `ctx.fill_circle(cx: float, cy: float, r: float, style)`
+- `ctx.stroke_circle(cx: float, cy: float, r: float, style)`
+- `ctx.fill_ellipse(cx: float, cy: float, rx: float, ry: float, style)`
+- `ctx.stroke_ellipse(cx: float, cy: float, rx: float, ry: float, style)`
+- `ctx.fill_arc(cx: float, cy: float, rx: float, ry: float, start: float, sweep: float, style)`
+- `ctx.stroke_arc(cx: float, cy: float, rx: float, ry: float, start: float, sweep: float, style)`
+- `ctx.fill_chord(cx: float, cy: float, rx: float, ry: float, start: float, sweep: float, style)`
+- `ctx.fill_pie(cx: float, cy: float, rx: float, ry: float, start: float, sweep: float, style)`
+
+#### 3. Lines & Polygons:
+- `ctx.stroke_line(x0: float, y0: float, x1: float, y1: float, style)`
+- `ctx.fill_polygon(points: Sequence[Tuple[float, float]], style)`
+- `ctx.stroke_polygon(points: Sequence[Tuple[float, float]], style)`
+- `ctx.fill_polyline(points: Sequence[Tuple[float, float]], style)`
+- `ctx.stroke_polyline(points: Sequence[Tuple[float, float]], style)`
+
+#### 4. Vector Paths:
+- `ctx.fill_path(path: Path, style)`
+- `ctx.stroke_path(path: Path, style)`
+
+#### 5. Image Blitting:
+- `ctx.blit_image(pt_or_x, y_or_img, image=None, src_rect=None)`: Blit an image at specified coordinates.
+
+#### 6. State Stack & Clipping:
+- `ctx.save() -> int`: Push context state (matrix, clip, styles) and return cookie ID.
+- `ctx.restore(cookie: Optional[int] = None)`: Pop state back to cookie ID.
+- `ctx.clip_to_rect(x: float, y: float, w: float, h: float)`
+- `ctx.clip_to_path(path: Path)`
+- `ctx.restore_clipping()`
+
+#### 7. Context Properties:
+- `ctx.comp_op = CompOp.SRC_OVER`: Composite operation mode.
+- `ctx.global_alpha = 0.75`: Global opacity multiplier `[0.0, 1.0]`.
+- `ctx.stroke_width = 3.5`: Stroke line width in pixels.
+- `ctx.stroke_cap = StrokeCap.ROUND`: Stroke end caps (`BUTT`, `SQUARE`, `ROUND`).
+- `ctx.stroke_join = StrokeJoin.ROUND`: Corner joins (`MITER_CLIP`, `BEVEL`, `ROUND`).
+- `ctx.stroke_miter_limit = 4.0`: Miter limit ratio.
+- `ctx.stroke_dash_offset = 0.0`: Dash pattern offset.
+- `ctx.set_stroke_dash_array(dashes: Sequence[float])`: e.g. `[10.0, 5.0]`.
+
+---
+
+## 8. Vector Path Builder (`naramotion.Path`)
+
+```python
+# Constructor Signature:
+Path()
+```
+
+```python
+# 3-Line MWE:
+from naramotion import Path
+p = Path()
+p.move_to(100, 100).line_to(200, 100).cubic_to(250, 150, 250, 250, 100, 200).close()
+```
+
+### Path Verbs & Signatures:
+- `p.move_to(x: float, y: float) -> Path`
+- `p.line_to(x: float, y: float) -> Path`
+- `p.quad_to(x1: float, y1: float, x2: float, y2: float) -> Path`
+- `p.cubic_to(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) -> Path`
+- `p.arc_to(cx: float, cy: float, rx: float, ry: float, start: float, sweep: float) -> Path`
+- `p.close() -> Path`
+- `p.clear() -> Path`
+- `p.add_circle(cx: float, cy: float, r: float) -> Path`
+- `p.add_rect(x: float, y: float, w: float, h: float) -> Path`
+- `p.add_round_rect(x: float, y: float, w: float, h: float, rx: float, ry: Optional[float] = None) -> Path`
+- `p.add_path(other: Path, matrix: Optional[Matrix2D] = None) -> Path`
+- `p.hit_test(x: float, y: float, fill_rule: FillRule = FillRule.NON_ZERO) -> HitTest`
+- `p.get_length() -> float`: Calculate total arc length in pixels.
+- `p.get_vertices() -> List[Tuple[int, float, float]]`: Extract raw control points and verb tags.
+- `p.to_svg_d() -> str`: Export path as standard SVG `d="..."` string.
+
+---
+
+## 9. Typography & Fonts (`naramotion.Font`, `naramotion.FontFace`)
+
+```python
+# Signatures:
+FontFace.from_file(filepath: str) -> FontFace
+Font(face: FontFace, size: float = 12.0)
+```
+
+```python
+# 3-Line MWE:
+from naramotion import FontFace, Font, Context
+face = FontFace.from_file("C:/Windows/Fonts/arial.ttf")
+font = Font(face, size=32.0)
+ctx.fill_text(100, 100, font, "NaraMotion Engine", style="#FFFFFF")
+```
+
+### Metrics & Text Measurement:
+- `font.metrics`: Returns ascent, descent, line gap, x-height, cap-height.
+- `font.get_text_metrics(text: str)`: Returns text advance vector `(advance.x, advance.y)` and bounding box.
+- `ctx.fill_text(x: float, y: float, font: Font, text: str, style)`
+- `ctx.stroke_text(x: float, y: float, font: Font, text: str, style)`
+
+---
+
+## 10. Gradients & Patterns (`naramotion.style`)
+
+### 1. Linear Gradient:
+```python
+LinearGradient(x0: float, y0: float, x1: float, y1: float, extend_mode: ExtendMode = ExtendMode.PAD)
+```
+```python
+from naramotion.style import LinearGradient
+grad = LinearGradient(0, 0, 800, 0)
+grad.add_stop(0.0, "#38BDF8").add_stop(1.0, "#F43F5E")
+ctx.fill_rect(0, 0, 800, 600, style=grad)
+```
+
+### 2. Radial Gradient:
+```python
+RadialGradient(x0: float, y0: float, x1: float, y1: float, r0: float, extend_mode: ExtendMode = ExtendMode.PAD)
+```
+```python
+from naramotion.style import RadialGradient
+rad = RadialGradient(400, 300, 400, 300, 200)
+rad.add_stop(0.0, "#FFFFFF").add_stop(1.0, "#090D16")
+ctx.fill_circle(400, 300, 200, style=rad)
+```
+
+### 3. Conic Gradient:
+```python
+ConicGradient(cx: float, cy: float, angle_rad: float = 0.0)
+```
+```python
+from naramotion.style import ConicGradient
+conic = ConicGradient(400, 300, 0.0)
+conic.add_stop(0.0, "red").add_stop(0.5, "blue").add_stop(1.0, "red")
+ctx.fill_circle(400, 300, 150, style=conic)
+```
+
+### 4. Image Pattern:
+```python
+Pattern(image: Image, extend_mode: ExtendMode = ExtendMode.REPEAT)
+```
+
+---
+
+## 11. Geometric Primitives (`naramotion.geometry`)
+
+NaraMotion provides direct C-struct wrappers for 2D primitives:
+- `Point(x, y)` / `PointI(x, y)`
+- `Size(w, h)` / `SizeI(w, h)`
+- `Rect(x, y, w, h)` / `RectI(x, y, w, h)`
+- `Circle(cx, cy, r)`
+- `Ellipse(cx, cy, rx, ry)`
+- `RoundRect(x, y, w, h, rx, ry)`
+- `Line(x0, y0, x1, y1)`
+- `Arc(cx, cy, rx, ry, start, sweep)`
+- `Chord(cx, cy, rx, ry, start, sweep)`
+- `Pie(cx, cy, rx, ry, start, sweep)`
+
+---
+
+## 12. Affine Transformations (`naramotion.Matrix2D`)
+
+```python
+# Constructor Signature:
+Matrix2D(m00: float = 1.0, m01: float = 0.0, m10: float = 0.0, m11: float = 1.0, m20: float = 0.0, m21: float = 0.0)
+```
+
+```python
+# 3-Line MWE:
+from naramotion import Matrix2D
+m = Matrix2D.make_translation(100, 50).scale(2.0, 2.0).rotate_deg(45.0)
+ctx.transform(m)
+```
+
+### Transformation Methods:
+- `Matrix2D.identity()`
+- `Matrix2D.make_translation(x, y)`
+- `Matrix2D.make_scaling(sx, sy)`
+- `Matrix2D.make_rotation(angle_rad)` / `Matrix2D.make_rotation_deg(angle_deg)`
+- `m.translate(x, y)` / `m.scale(sx, sy)` / `m.rotate(rad)` / `m.rotate_deg(deg)`
+- `m.invert() -> Matrix2D`
+- `m1 * m2`: Matrix multiplication operator.
+- `m.map_point(x, y) -> Tuple[float, float]`
+
+---
+
+## 13. Bulk & Batch Operations for Big Data
+
+Render millions of shapes in a single SIMD call with zero Python interpreter overhead:
+
+```python
+# 1. Batch Circles:
+ctx.fill_circle_array(circles_array, style="#38BDF8")
+
+# 2. Batch Rectangles:
+ctx.fill_rect_array(rects_array, style="#10B981")
+
+# 3. Batch Lines:
+ctx.stroke_line_array(lines_array, style="#F59E0B")
+```
+
+---
+
+## 14. Zero-Copy NumPy & FFmpeg Video Streaming
+
+```python
+import naramotion
+import numpy as np
+
+# Zero-copy NumPy view (changes in ndarray reflect instantly in Blend2D image)
+img = naramotion.Image(1920, 1080)
+arr = img.to_numpy(copy=False)
+arr[:, :, 0] = 255 # Fill blue channel directly in memory
+
+# Direct pipe to FFmpeg process
+import subprocess
+ffmpeg = subprocess.Popen([
+    "ffmpeg", "-y", "-f", "rawvideo", "-pix_fmt", "bgra",
+    "-s", "1920x1080", "-r", "60", "-i", "-",
+    "-c:v", "libx264", "-pix_fmt", "yuv420p", "output.mp4"
+], stdin=subprocess.PIPE)
+
+# Zero copy write from memoryview
+ffmpeg.stdin.write(img.buffer)
+```
+
+---
+
+## 15. Hardware-Accelerated Video Engine (`naramotion.video`)
+
+```python
+# Constructor Signature:
+VideoWriter(
+    output_path: str,
+    width: int,
+    height: int,
+    fps: int = 60,
+    bitrate: str = "12M",
+    codec: Optional[str] = None, # "h264_nvenc", "h264_qsv", "h264_amf", "libx264", "prores"
+    preset: str = "fast",
+    crf: Optional[int] = None,
+    pixel_format: str = "yuv420p"
+)
+```
+
+```python
+# 3-Line MWE:
+from naramotion.video import VideoWriter
+with VideoWriter("render.mp4", width=3840, height=2160, fps=60, codec="h264_nvenc") as vw:
+    with vw.render_frame_context() as ctx:
+        ctx.fill_all("#090D16")
+```
+
+---
+
+## 16. Geospatial & Big Data Engine (`naramotion.shapgeo` / `naramotion.geo`)
+
+NaraMotion natively streams and renders massive GIS datasets (e.g. `secondary_roads.parquet`, `roads.parquet`, `03_secondary_roads.geojson`, Shapefiles) directly with zero memory bloat.
+
+### `GeoCanvas` Signature:
+```python
+GeoCanvas(
+    width: int = 1920,
+    height: int = 1080,
+    bounds: Optional[Tuple[float, float, float, float]] = None,
+    bg_color: Union[str, Rgba32] = "#050811",
+    padding: float = 0.05
+)
+```
+
+```python
+# 3-Line MWE (Multi-Layer Parquet & GeoJSON Map):
+from naramotion.shapgeo import GeoCanvas
+
+with GeoCanvas(width=3840, height=2160, bg_color="#050811") as canvas:
+    # 1. Add massive Parquet vector layer (e.g. roads, secondary roads)
+    canvas.add_parquet("secondary_roads.parquet", stroke_color="#00F0FF", stroke_width=2.5)
+    
+    # 2. Add GeoJSON overlay layer
+    canvas.add_geojson("03_secondary_roads.geojson", stroke_color="#FF007F", stroke_width=1.5)
+    
+    canvas.save("world_roads_4k.png")
+```
+
+### Dynamic Stroke & Scale-Aware Level of Detail (LOD):
+Avoid map clutter and ink bleed when zooming out to country or continental level:
+```python
+# dynamic_stroke=True automatically scales line width proportionally to zoom bounds!
+canvas.add_parquet("secondary_roads.parquet", stroke_color="#00F0FF", stroke_width=2.0, dynamic_stroke=True)
+canvas.add_geojson("03_secondary_roads.geojson", stroke_color="#FF007F", stroke_width=1.5, dynamic_stroke=True)
+```
+
+### Center, Centroid & Auto-Focusing Viewport:
+```python
+from naramotion import compute_center, get_centroid
+
+# Compute center of GeoDataFrame, Shapefile, Path, or Bounding Box:
+cx, cy = compute_center(gdf_roads)
+print(f"Road network center: lon={cx:.4f}, lat={cy:.4f}")
+
+# Dynamically focus canvas camera onto a specific city or country with zoom factor:
+canvas.focus_on(gdf_city, zoom=2.5)
+```
+
+### High-Speed GIS Readers (`read_parquet`, `read_parquet_native`, `read_geojson`, `read_file`):
+```python
+from naramotion.shapgeo import read_parquet, read_parquet_native, read_geojson, read_file
+
+# 1. Read directly into GeoDataFrame or native GeoDataset
+gdf_roads = read_parquet("secondary_roads.parquet")
+gdf_json  = read_geojson("03_secondary_roads.geojson")
+gdf_auto  = read_file("boundaries.shp")
+
+# 2. Pure Native C++ WKB Parsing directly to SoA (bypasses Shapely/Python completely):
+soa_layer = read_parquet_native("census_blocks.parquet", return_native_soa=True)
+```
+
+### Structure of Arrays (SoA) & Path Memory Arena (`NativeGeoLayerSoA`):
+For massive cityscapes (30,000+ building blocks / parcels), SoA layout keeps all data in contiguous cache lines (`distances`, `bboxes`, `paths`, `centroids`, `start_frames`), eliminating Python object overhead:
+```python
+from naramotion import NativeGeoLayerSoA, GeoCanvas
+
+layer = NativeGeoLayerSoA(capacity=50000)
+# Parse WKB directly in C++ into BLPathCore
+layer.from_wkb_batch(wkb_buffers, transform=canvas.transform)
+
+# Compute shockwave timeline in L1/L2 cache
+layer.compute_propagation(epicenters=[(-74.0060, 40.7128)], duration_frames=300.0)
+
+# Vectorized BBox clipping and frame activation
+vis_count = layer.cull_and_update(viewport_bbox=(0, 0, 3840, 2160), current_frame=frame)
+```
+
+### Dual-Buffer Polygon Render Pipeline & Centroid Spring Pop-In:
+Alternating fill and stroke flushes the JIT pipeline. Dual-Buffer batch rendering separates all fills (Pass 1) from all strokes (Pass 2) for maximum speed. `render_popin` applies an elastic spring back-out scale expansion around each polygon's centroid:
+```python
+with GeoCanvas(3840, 2160) as canvas:
+    # 1. Dual-Buffer Batch Render
+    layer.render_dual_buffer(canvas, fill_color="#00F0FF", stroke_color="#FFFFFF", stroke_width=1.0)
+    
+    # 2. Spring Pop-In Animation (Scale(t) = Easing::back_out(t))
+    layer.render_popin(canvas, current_frame=frame, fill_color="#00F0FF", stroke_color="#FFFFFF", stroke_width=1.0)
+```
+
+### Flat Uniform Grid Spatial Index (`UniformGridIndex`):
+```python
+from naramotion import UniformGridIndex
+
+grid = UniformGridIndex(bounds=(-74.1, 40.6, -73.8, 40.9), grid_w=64, grid_h=64)
+grid.build_from_bboxes(bboxes)
+visible_ids = grid.query_bbox(-74.01, 40.70, -73.98, 40.75) # < 1 microsecond!
+```
+
+### Curated Palettes & Color Harmony Engine (`naramotion.Palette`):
+```python
+from naramotion import Palette
+
+# 1. Designer Pre-built Palettes:
+cyberpunk = Palette.CYBERPUNK       # Cyan, Hot Pink, Electric Purple, Neon Green, Acid Yellow
+tokyo     = Palette.TOKYO_NIGHT     # Soft Blue, Lavender, Sky, Crimson, Gold
+solar     = Palette.SOLAR_HEAT      # Red Orange, Solar Gold, Deep Pink, Plum
+nordic    = Palette.NORDIC_FROST    # Ice Blue, Glacier, Deep Ocean, Frost Mauve
+midnight  = Palette.MIDNIGHT_BLUE   # Electric Cyan, Indigo, Purple, Rose, Emerald
+
+# 2. Golden-Ratio Harmonic Generator (Guaranteed zero color clash for N layers):
+layer_colors = Palette.generate(8, base_color="#00F0FF", mode="golden_ratio")
+```
+
+### Anti-Burnout ACES Filmic Tone Mapping (`naramotion.fx.tone_map_aces`):
+```python
+from naramotion.fx import tone_map_aces, bloom
+
+# Render 10,000 glowing intersecting lines without clipping to solid white!
+tone_map_aces(canvas.img, exposure=1.1)
+```
+
+---
+
+## 17. Motion Graphics & Animation (`naramotion.motion`)
+
+### 17.1 Declarative Action Chaining & Kinetic Animations
+```python
+from naramotion.motion import DrawReveal, Typewriter, Stagger, Spring
+
+# Progressive line drawing reveal (0% to 100%):
+reveal_action = DrawReveal(target_path, duration=2.0, color="#00F0FF", width=2.5)
+
+# Kinetic Typewriter with glowing blinking cursor:
+typewriter_action = Typewriter("NARAMOTION V0.23", x=100, y=200, duration=1.5, font_size=36)
+
+# Stagger actions sequentially:
+staggered_actions = Stagger.create([reveal_action, typewriter_action], delay_step=0.4)
+```
+
+### 17.2 Easing Curves Reference Table & Physics Springs
+
+All easing functions accept progress $t \in [0.0, 1.0]$:
+
+| Family | In (`_in`) | Out (`_out`) | In-Out (`_in_out`) |
+| :--- | :--- | :--- | :--- |
+| **Linear** | `Easing.linear(t)` | `Easing.linear(t)` | `Easing.linear(t)` |
+| **Quadratic** | `Easing.quad_in(t)` | `Easing.quad_out(t)` | `Easing.quad_in_out(t)` |
+| **Cubic** | `Easing.cubic_in(t)` | `Easing.cubic_out(t)` | `Easing.cubic_in_out(t)` |
+| **Quartic** | `Easing.quart_in(t)` | `Easing.quart_out(t)` | `Easing.quart_in_out(t)` |
+| **Quintic** | `Easing.quint_in(t)` | `Easing.quint_out(t)` | `Easing.quint_in_out(t)` |
+| **Sine** | `Easing.sine_in(t)` | `Easing.sine_out(t)` | `Easing.sine_in_out(t)` |
+| **Exponential** | `Easing.expo_in(t)` | `Easing.expo_out(t)` | `Easing.expo_in_out(t)` |
+| **Circular** | `Easing.circ_in(t)` | `Easing.circ_out(t)` | `Easing.circ_in_out(t)` |
+| **Elastic** | `Easing.elastic_in(t)` | `Easing.elastic_out(t)` | `Easing.elastic_in_out(t)` |
+| **Back (Overshoot)** | `Easing.back_in(t)` | `Easing.back_out(t)` | `Easing.back_in_out(t)` |
+| **Bounce** | `Easing.bounce_in(t)` | `Easing.bounce_out(t)` | `Easing.bounce_in_out(t)` |
+
+#### Spring Physics Dynamics:
+```python
+from naramotion.motion import Spring
+spring = Spring(stiffness=170.0, damping=26.0, mass=1.0)
+pos = spring.evaluate(t=0.35)
+```
+
+#### Cubic Bezier Curves:
+```python
+from naramotion.motion import CubicBezier
+bezier = CubicBezier(0.25, 0.1, 0.25, 1.0)
+val = bezier.evaluate(t=0.5)
+```
+
+---
+
+### 17.2 Vector Path Animations & Trimming
+
+```python
+# Trim path line-drawing reveal:
+from naramotion.motion import trim_path, PathFollower, path_morph
+revealed = trim_path(full_path, start=0.0, end=0.8)
+
+# Follow tangent and position along path:
+follower = PathFollower(full_path)
+x, y, angle_rad = follower.point_at(t=0.5)
+
+# Morph between two paths:
+morphed_path = path_morph(path_a, path_b, progress=0.5)
+```
+
+---
+
+### 17.3 Particle Simulation & VFX Engine
+
+```python
+from naramotion.motion import ParticleSystem
+ps = ParticleSystem(max_particles=20000).add_gravity(0, 500)
+ps.preset_fireworks(x=960, y=540, count=250)
+ps.update(1.0 / 60.0)
+ps.render(ctx)
+```
+
+---
+
+### 17.4 Scene Graph, Layers & Camera2D
+
+```python
+from naramotion.motion import Scene, Node, Camera2D
+scene = Scene(1920, 1080)
+scene.camera.look_at(500, 500)
+scene.camera.shake(intensity=15.0, duration=0.6)
+scene.render(ctx)
+```
+
+---
+
+### 17.5 Multi-Track Timeline & Direct Video Export
+
+```python
+from naramotion.motion import Timeline
+tl = Timeline(duration=5.0, fps=60)
+tl.animate(cam, "pitch", start_val=0.0, end_val=70.0, duration=3.0, easing="easeInOutCubic")
+tl.render_video("cinematic.mp4", width=3840, height=2160, fps=60, draw_fn=render_callback)
+```
+
+---
+
+## 18. Kinetic Perspective & 3D Globe (`naramotion.motion.PerspectiveCamera`)
+
+```python
+# Constructor Signature:
+PerspectiveCamera(
+    width: int = 1920,
+    height: int = 1080,
+    fov: float = 60.0,
+    pitch: float = 0.0,      # Tilt (0 = top-down 2D, 75 = horizon perspective)
+    yaw: float = 0.0,        # Heading rotation
+    roll: float = 0.0,       # Banking angle
+    distance: float = 1000.0,# Altitude / zoom
+    target_x: float = 0.0,   # Focus point X
+    target_y: float = 0.0,   # Focus point Y
+    near_clip: float = 10.0  # Near-plane clipping
+)
+```
+
+```python
+# 3-Line MWE:
+from naramotion.motion import PerspectiveCamera
+cam = PerspectiveCamera(width=3840, height=2160, pitch=72.0, distance=900.0)
+proj_lines, scales, valid = cam.transform_lines(street_lines_nx4)
+cam.render_fog(ctx, fog_color="#050811", horizon_y_ratio=0.3)
+```
+
+### 3D Globe Renderer:
+```python
+from naramotion.motion import render_globe
+render_globe(
+    dst_image=canvas_img,
+    texture_image=world_texture_img,
+    cx=960, cy=540, radius=400,
+    rot_lon=45.0, rot_lat=15.0,
+    glow_color="#38BDF8FF"
+)
+```
+
+---
+
+## 19. Cinematic Visual FX & Post-Processing (`naramotion.fx`)
+
+```python
+# Signatures for All Filters:
+gaussian_blur(image: Image, sigma: float = 3.0, in_place: bool = True) -> Image
+bloom(image: Image, threshold: float = 0.6, intensity: float = 1.2, radius: float = 10.0, tint: str = "#FFFFFFFF") -> Image
+neon_glow(image: Image, color: str = "#38BDF8FF", intensity: float = 1.8, radius: float = 14.0) -> Image
+chromatic_aberration(image: Image, shift_x: float = 6.0, shift_y: float = 0.0) -> Image
+vignette(image: Image, intensity: float = 0.6, radius: float = 0.4, smoothness: float = 0.45) -> Image
+film_grain(image: Image, amount: float = 0.08, seed: int = 0) -> Image
+color_grade(image: Image, brightness: float = 0.0, contrast: float = 1.0, saturation: float = 1.0, gamma: float = 1.0) -> Image
+drop_shadow(image: Image, dx: float = 12.0, dy: float = 12.0, blur: float = 15.0, shadow_color: str = "#000000AA") -> Image
+scanlines(image: Image, spacing: int = 4, intensity: float = 0.35) -> Image
+glitch_displacement(image: Image, num_slices: int = 12, max_displacement: int = 30) -> Image
+```
+
+### Fluent Chaining Pipeline:
+```python
+from naramotion.fx import FXPipeline
+pipe = (
+    FXPipeline()
+    .bloom(threshold=0.5, intensity=1.4, radius=12.0)
+    .chromatic_aberration(shift_x=5.0)
+    .vignette(intensity=0.55)
+    .film_grain(amount=0.06)
+)
+pipe.apply(img)
+```
+
+---
+
+## 20. Enumerations Reference
+
+### `CompOp` (Composite Modes):
+`SRC_OVER`, `SRC_COPY`, `SRC_IN`, `SRC_OUT`, `SRC_ATOP`, `DST_OVER`, `DST_IN`, `DST_OUT`, `DST_ATOP`, `XOR`, `CLEAR`, `PLUS`, `MINUS`, `MULTIPLY`, `SCREEN`, `OVERLAY`, `DARKEN`, `LIGHTEN`, `COLOR_DODGE`, `COLOR_BURN`, `HARD_LIGHT`, `SOFT_LIGHT`, `DIFFERENCE`, `EXCLUSION`.
+
+### `StrokeCap`:
+`BUTT`, `SQUARE`, `ROUND`, `ROUND_REV`, `TRIANGLE`, `TRIANGLE_REV`.
+
+### `StrokeJoin`:
+`MITER_CLIP`, `MITER_BEVEL`, `MITER_ROUND`, `BEVEL`, `ROUND`.
+
+### `FillRule`:
+`NON_ZERO`, `EVEN_ODD`.
+
+### `Format`:
+`PRGB32` (Premultiplied 32-bit ARGB), `XRGB32` (Opaque 32-bit RGB), `A8` (8-bit Alpha mask).
+
+### `ExtendMode`:
+`PAD`, `REPEAT`, `REFLECT`, `PAD_X_PAD_Y`, `REPEAT_X_REPEAT_Y`.
+
+---
+
+## 21. Performance & Best Practices Guide
+
+1. **Always Use the Context Manager (`with Context(img) as ctx:`)**:
+   - Ensures automatic native flushing and exception safety.
+2. **Prefer In-Place Batch Arrays for Big Data**:
+   - Use `ctx.fill_circle_array()` and `cam.transform_lines()` instead of looping in Python.
+3. **Prefer `PRGB32` Format**:
+   - Blend2D's JIT compiler generates AVX2 / AVX-512 vector pipelines specifically optimized for premultiplied 32-bit pixel buffers.
+4. **Use Zero-Copy `img.buffer` for Video Encoding**:
+   - Stream directly into `VideoWriter` or FFmpeg without memory allocation overhead.
+
+---
+
+## 22. Comprehensive Error Catalog, Exceptions & Troubleshooting Guide
+
+NaraMotion wraps all native C++ engine errors into standard Python exceptions. Below is the complete catalog of errors, their root causes, and step-by-step resolution.
+
+### 22.1 Native Engine Errors (`naramotion.Blend2DError`)
+
+| Error Code | Exception Output | Root Cause | Resolution |
+| :--- | :--- | :--- | :--- |
+| **`BL_ERROR_INVALID_VALUE` (1)** | `Blend2DError: Invalid value` | Passing invalid image width/height ($\le 0$), negative radius, NaN, or Inf coordinates. | Ensure dimensions are integers $> 0$ and coordinates are valid finite numbers (`math.isfinite(x)`). |
+| **`BL_ERROR_INVALID_STATE` (2)** | `Blend2DError: Invalid state` | Calling drawing methods on a context after `ctx.end()`, or before `ctx.begin()`. | Always use the context manager `with Context(img) as ctx:` which guarantees safe lifecycle. |
+| **`BL_ERROR_INVALID_HANDLE` (3)** | `Blend2DError: Invalid handle` | Calling methods on a destroyed image/path resource (e.g. after `img.reset()`). | Do not access an image after calling `img.reset()`. Create a new image if needed. |
+| **`BL_ERROR_NO_MATCHING_VERTEX` (4)** | `Blend2DError: No matching vertex` | Attempting to trim or query path tangent on an empty `Path()`. | Ensure the path contains at least one `move_to` and `line_to` before calling `trim_path()` or `PathFollower`. |
+| **`BL_ERROR_OUT_OF_MEMORY` (6)** | `Blend2DError: Out of memory` | Requesting an image allocation larger than available RAM (e.g. $100000 \times 100000$). | Verify image dimensions before creating canvas. For large maps, render in tiles or at 4K/8K. |
+| **`BL_ERROR_FONT_NOT_MATCHED` (14)** | `Blend2DError: Font not matched` | Passing a corrupted font file or unsupported font format. | Provide a standard OpenType (`.otf`) or TrueType (`.ttf` / `.ttc`) font file. |
+
+---
+
+### 22.2 Common Python Exceptions in NaraMotion
+
+#### 1. `ValueError: Unsupported color format`
+- **When it happens**: Passing CSS functional strings like `"rgba(255, 0, 0, 0.5)"` or `"rgb(0, 255, 0)"`.
+- **Fix**: Convert to hex string or numeric tuple:
+  ```python
+  # ❌ Incorrect:
+  ctx.fill_circle(100, 100, 50, "rgba(56, 189, 248, 0.5)")
+
+  # ✅ Correct:
+  ctx.fill_circle(100, 100, 50, "#38BDF880")               # Hex with 50% alpha
+  ctx.fill_circle(100, 100, 50, (56, 189, 248, 128))        # Tuple with alpha
+  ```
+
+#### 2. `RuntimeError: FFmpeg executable not found`
+- **When it happens**: Using `VideoWriter` or `VideoReader` when FFmpeg is not installed or not in system `PATH`.
+- **Fix**:
+  - **Windows**: `winget install Gyan.FFmpeg`
+  - **Ubuntu / Debian**: `sudo apt update && sudo apt install -y ffmpeg`
+  - **macOS**: `brew install ffmpeg`
+
+#### 3. `TypeError: Array must be C-contiguous and uint8`
+- **When it happens**: Passing a non-contiguous slice or float array to `Image.from_numpy()`.
+- **Fix**: Ensure array is C-contiguous with `uint8` dtype:
+  ```python
+  import numpy as np
+  arr = np.ascontiguousarray(arr, dtype=np.uint8)
+  img = Image.from_numpy(arr)
+  ```
+
+#### 4. `FileNotFoundError: Font file not found`
+- **When it happens**: Calling `FontFace.from_file("arial.ttf")` when the file does not exist at that path.
+- **Fix**: Use absolute paths:
+  ```python
+  # Windows:
+  face = FontFace.from_file("C:/Windows/Fonts/segoeui.ttf")
+  # Linux:
+  face = FontFace.from_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf")
+  ```
+
+#### 5. `ImportError: DLL load failed while importing _bin`
+- **When it happens**: Missing Visual C++ runtime on Windows.
+- **Fix**: Install the official [Microsoft Visual C++ 2015-2022 Redistributable (x64)](https://aka.ms/vs/17/release/vc_redist.x64.exe) or reinstall with:
+  ```bash
+  pip install --force-reinstall naramotion
+  ```
+
+---
+
+### 22.3 Environment Conflicts & Compatibility Solutions
+
+| Environment Issue | Cause | Solution |
+| :--- | :--- | :--- |
+| **GeoPandas / Shapely version mismatch** | Old versions missing `__geo_interface__` | `pip install --upgrade geopandas shapely` |
+| **Virtualenv DLL isolation** | Custom sandbox blocking `.dll` search | NaraMotion auto-adds `blend2d/_bin` with `os.add_dll_directory()`. |
+| **Multithreading OpenMP / Context Sharing** | Two threads drawing to the same `Context` simultaneously | Create one `Context` per image per thread. Images can be rendered in parallel across threads. |

README.md

@@ -0,0 +1,128 @@
+# NaraMotion 🎨🚀
+
+[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Proprietary-red.svg)](https://pypi.org/project/naramotion/)
+[![JIT Accelerated](https://img.shields.io/badge/JIT-AsmJit%20Hardware%20Accelerated-orange.svg)](https://blend2d.com)
+
+**Author & Creator**: Islam Arifi  
+**Official PyPI Package**: [`naramotion`](https://pypi.org/project/naramotion/) (v0.22.0)  
+
+**NaraMotion** is an ultra-fast 2D/2.5D vector graphics, GIS, motion graphics, and cinematic video engine for Python powered by **[Blend2D](https://blend2d.com)** (embedded JIT compiler and SIMD hardware acceleration).
+
+---
+
+## 🔑 License Activation & Evaluation Mode
+
+NaraMotion is distributed under a **Proprietary Commercial License** with an Evaluation Mode.
+Unlicensed evaluation renders include a subtle semi-transparent `"Auras"` watermark in the center.
+
+### To Activate Full Commercial Version:
+Call `naramotion.set_license()` at the beginning of your program with your commercial key:
+
+```python
+import naramotion
+
+# Activate official license (removes all evaluation watermarks)
+naramotion.set_license("YOUR_COMMERCIAL_KEY")
+```
+
+Or set the environment variable:
+```bash
+export NARAMOTION_LICENSE_KEY="YOUR_COMMERCIAL_KEY"  # Linux/macOS
+set NARAMOTION_LICENSE_KEY="YOUR_COMMERCIAL_KEY"     # Windows
+```
+
+---
+
+## 📦 Official Installation
+
+### 1. From PyPI:
+```bash
+pip install naramotion
+```
+
+### 2. Optional Speed & Ecosystem Extensions:
+```bash
+pip install "naramotion[numpy,pil]"     # For Zero-Copy NumPy & Pillow integration
+pip install "naramotion[all]"           # For GeoPandas, Shapely & full testing
+```
+
+### ✅ Quick Verification:
+```python
+import naramotion
+print(f"✨ NaraMotion Version: {naramotion.__version__} by {naramotion.__author__}")
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Basic Drawing & Context Manager
+
+```python
+from naramotion import Image, Context, Format
+
+# Create 800x600 surface in PRGB32 format
+img = Image(800, 600, Format.PRGB32)
+
+with Context(img) as ctx:
+    # 1. Fill dark cyberpunk canvas background
+    ctx.fill_all("#090D16")
+    
+    # 2. Draw soft glowing circle
+    ctx.fill_circle(400, 300, 140, "#38BDF8")
+    
+    # 3. Add stylish thick border with rounded corners
+    ctx.stroke_width = 8.0
+    ctx.stroke_round_rect(100, 100, 600, 400, 24.0, style="#F43F5E")
+
+# Save directly to disk
+img.save("quickstart_naramotion.png")
+```
+
+---
+
+### 2. Cinematic Post-Processing FX & Post-Pipeline
+
+```python
+from naramotion import Image, Context, fx
+
+img = Image(1280, 720)
+with Context(img) as ctx:
+    ctx.fill_all("#060810")
+    ctx.fill_circle(640, 360, 180, "#38BDF8")
+
+# Apply chained visual FX (Bloom + Vignette + Film Grain)
+fx.FXPipeline().bloom(threshold=0.5, intensity=1.5, radius=12.0).vignette(0.5).film_grain(0.05).apply(img)
+img.save("cinematic_naramotion.png")
+```
+
+---
+
+### 3. Kinetic Perspective Camera (2.5D 4K Video Flythrough)
+
+```python
+from naramotion import Image, Context, Format, CompOp
+from naramotion.motion import PerspectiveCamera
+from naramotion.video import VideoWriter
+
+WIDTH, HEIGHT = 1920, 1080
+img = Image(WIDTH, HEIGHT, Format.PRGB32)
+cam = PerspectiveCamera(width=WIDTH, height=HEIGHT, pitch=65.0, distance=900.0)
+
+with VideoWriter("flythrough.mp4", width=WIDTH, height=HEIGHT, fps=60) as vw:
+    for frame in range(120):
+        cam.target_y = (frame / 119.0) * 1200.0
+        with Context(img) as ctx:
+            ctx.fill_all("#050811")
+            cam.render_fog(ctx, fog_color="#050811", horizon_y_ratio=0.35)
+        vw.write_frame(img)
+```
+
+---
+
+## 📚 Complete API Documentation
+
+For the complete 22-section master documentation and AI guidelines, see:
+- [`DOCUMENTATION.md`](DOCUMENTATION.md)
+- [`AI_RULES.md`](AI_RULES.md)

blend2d/__init__.py

@@ -0,0 +1,343 @@
+"""
+NaraMotion: High-Performance 2D Vector Graphics Engine for Python powered by Blend2D.
+"""
+
+from naramotion.enums import (
+    Format,
+    CompOp,
+    FillRule,
+    GeometryType,
+    ExtendMode,
+    GradientType,
+    StrokeCap,
+    StrokeCapPosition,
+    StrokeJoin,
+    StrokeTransformOrder,
+    TransformOp,
+    ClipOp,
+    FlattenMode,
+    RenderingEngine,
+    ResultCode,
+    ContextHint,
+    RenderingQuality,
+    GradientQuality,
+    PatternQuality,
+    RuntimeInfoType,
+    RuntimeCpuArch,
+    RuntimeCpuFeatures,
+)
+from naramotion.ffi import Blend2DError
+from naramotion.geometry import (
+    Point,
+    PointI,
+    Size,
+    SizeI,
+    Rect,
+    RectI,
+    Box,
+    BoxI,
+    Circle,
+    Ellipse,
+    RoundRect,
+    Triangle,
+    Arc,
+    Line,
+)
+from naramotion.matrix import Matrix2D
+from naramotion.color import (
+    Color,
+    Rgba32,
+    Rgba,
+    parse_color,
+    NAMED_COLORS,
+)
+from naramotion.image import Image
+from naramotion.path import Path
+from naramotion.style import (
+    Gradient,
+    LinearGradient,
+    RadialGradient,
+    ConicGradient,
+    Pattern,
+)
+from naramotion.font import (
+    FontFace,
+    Font,
+    FontMetrics,
+    TextMetrics,
+)
+from naramotion.context import Context
+from naramotion.diagnostics import (
+    diagnose_environment,
+    print_diagnostic_report,
+    get_error_details,
+    get_runtime_info,
+)
+from naramotion import svg
+from naramotion.svg import SvgContext, export_svg
+from naramotion import video
+from naramotion.video import (
+    VideoWriter,
+    VideoReader,
+    record_animation,
+    detect_hardware_encoders,
+    VideoError,
+    CodecNotFoundError,
+    FrameFormatError,
+)
+from naramotion import shapgeo
+from naramotion.shapgeo import (
+    GeoCanvas,
+    GeoTransform,
+    from_shapely,
+    from_geojson,
+    from_wkt,
+    render_gdf,
+    auto_bounds,
+    compute_center,
+    get_center,
+    get_centroid,
+    read_file,
+    read_parquet,
+    read_parquet_native,
+    read_shapefile,
+    read_geojson,
+    proj,
+    Transformer,
+    to_web_mercator,
+    to_wgs84,
+    reproject_gdf,
+    RetainedGeoLayer,
+    NativeGeoLayerSoA,
+    UniformGridIndex,
+    clip_polygon_bbox,
+)
+from naramotion.palette import Palette
+from naramotion import motion
+from naramotion.motion import (
+    Timeline,
+    Easing,
+    Spring,
+    Action,
+    DrawReveal,
+    Create,
+    ShowCreation,
+    Uncreate,
+    Typewriter,
+    Stagger,
+    interpolate,
+    Extrapolate,
+    chaikin_smooth,
+    chaikin_smooth_points,
+    Sequence,
+    Composition,
+    delay_render,
+    CubicBezier,
+    trim_path,
+    PathFollower,
+    PathMorph,
+    ParticleSystem,
+    Camera2D,
+    PerspectiveCamera,
+    render_globe,
+    Node,
+    Layer,
+    Scene,
+)
+from naramotion import fx
+from naramotion.fx import (
+    FXPipeline,
+    gaussian_blur,
+    box_blur,
+    box_blur_integral,
+    bloom,
+    neon_glow,
+    drop_shadow,
+    chromatic_aberration,
+    vignette,
+    film_grain,
+    color_grade,
+    grayscale,
+    invert,
+    sepia,
+    tone_map_aces,
+    tone_map_reinhard,
+    scanlines,
+    glitch_displacement,
+)
+from naramotion.license import (
+    set_license,
+    is_licensed,
+)
+
+# Alias geo -> shapgeo for developer convenience
+geo = shapgeo
+
+__version__ = "0.26.0"
+
+__author__ = "Islam Arifi, NaraMotion Team, Blend2D Authors"
+
+# Backward compatibility alias
+import sys
+sys.modules["blend2d"] = sys.modules[__name__]
+
+__all__ = [
+    # Core
+    "Image",
+    "Context",
+    "Path",
+    "Blend2DError",
+    "set_license",
+    "is_licensed",
+    # Post-Processing FX Engine
+    "fx",
+    "FXPipeline",
+    "gaussian_blur",
+    "box_blur",
+    "bloom",
+    "neon_glow",
+    "drop_shadow",
+    "chromatic_aberration",
+    "vignette",
+    "film_grain",
+    "color_grade",
+    "grayscale",
+    "invert",
+    "sepia",
+    "scanlines",
+    "glitch_displacement",
+    # Motion Graphics & Animation Engine
+    "motion",
+    "Timeline",
+    "Easing",
+    "Spring",
+    "Action",
+    "DrawReveal",
+    "Create",
+    "ShowCreation",
+    "Uncreate",
+    "Typewriter",
+    "Stagger",
+    "interpolate",
+    "Extrapolate",
+    "chaikin_smooth",
+    "chaikin_smooth_points",
+    "Sequence",
+    "Composition",
+    "delay_render",
+    "CubicBezier",
+    "trim_path",
+    "PathFollower",
+    "PathMorph",
+    "ParticleSystem",
+    "Camera2D",
+    "PerspectiveCamera",
+    "render_globe",
+    "Node",
+    "Layer",
+    "Scene",
+    # Geospatial (GeoPandas & Shapely C++ Engine)
+    "shapgeo",
+    "geo",
+    "GeoCanvas",
+    "GeoTransform",
+    "from_shapely",
+    "from_geojson",
+    "from_wkt",
+    "render_gdf",
+    "auto_bounds",
+    "compute_center",
+    "get_center",
+    "get_centroid",
+    "read_file",
+    "read_parquet",
+    "read_shapefile",
+    "read_geojson",
+    "proj",
+    "Transformer",
+    "to_web_mercator",
+    "to_wgs84",
+    "reproject_gdf",
+    "RetainedGeoLayer",
+    "clip_polygon_bbox",
+    # Palette & Color Harmony
+    "Palette",
+    # Video & Native FFmpeg Engine
+    "video",
+    "VideoWriter",
+    "VideoReader",
+    "record_animation",
+    "detect_hardware_encoders",
+    "VideoError",
+    "CodecNotFoundError",
+    "FrameFormatError",
+    # SVG Vector Export
+    "svg",
+    "SvgContext",
+    "export_svg",
+    # Diagnostics & Troubleshooting
+    "diagnose_environment",
+    "print_diagnostic_report",
+    "get_error_details",
+    "get_runtime_info",
+    # Styles
+    "Gradient",
+    "LinearGradient",
+    "RadialGradient",
+    "ConicGradient",
+    "Pattern",
+    # Colors
+    "Rgba32",
+    "Rgba",
+    "parse_color",
+    "NAMED_COLORS",
+    # Typography
+    "FontFace",
+    "Font",
+    "FontMetrics",
+    "TextMetrics",
+    # Geometry
+    "Point",
+    "PointI",
+    "Size",
+    "SizeI",
+    "Rect",
+    "RectI",
+    "Box",
+    "BoxI",
+    "Circle",
+    "Ellipse",
+    "RoundRect",
+    "Triangle",
+    "Arc",
+    "Line",
+    "Matrix2D",
+    # Colors
+    "Color",
+    "Rgba32",
+    "Rgba",
+    "parse_color",
+    # Enums
+    "Format",
+    "CompOp",
+    "FillRule",
+    "GeometryType",
+    "ExtendMode",
+    "GradientType",
+    "StrokeCap",
+    "StrokeCapPosition",
+    "StrokeJoin",
+    "StrokeTransformOrder",
+    "TransformOp",
+    "ClipOp",
+    "FlattenMode",
+    "RenderingEngine",
+    "ResultCode",
+    "ContextHint",
+    "RenderingQuality",
+    "GradientQuality",
+    "PatternQuality",
+    "RuntimeInfoType",
+    "RuntimeCpuArch",
+    "RuntimeCpuFeatures",
+]

blend2d/_bin/libblend2d.dll

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:032b420c9360a7a735207cd91258b27ff1041553b63c028695c2c5266b1b0f57
+size 2626560

blend2d/_bin/libblend2d.so

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ff8935b2a8b28b17f87268c0c131a6118bf76d81f17733dc02449f8daa50a139
+size 22254800

blend2d/_bin/libblend2d_fx.dll

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b463e7dbefed6cee153c73de9df99c23f933d36b5b75c9b50ea7387a11f143de
+size 263680

blend2d/_bin/libblend2d_fx.pdb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:02dc6afeed6a2a66dd8c59d8b6d996269125027d92a3d1bbb9608f8d68879570
+size 2179072

blend2d/_bin/libblend2d_fx.so

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:880923072fd29be23a5d9a861a8aaeeb402e60c44042e52e5ea4f10d19e79457
+size 280744

blend2d/_bin/libblend2d_geo.dll

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2a712fb15f6d9b6ad6b92639a52eca852aff2e2e93a5ca06b58ffb3e30274915
+size 232960

blend2d/_bin/libblend2d_geo.pdb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:847f5a8524710583c57702b09a2c25dd51166911f6a9bc28515792de32e14fd2
+size 2367488

blend2d/_bin/libblend2d_geo.so

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dc040879f510da62a88ba22190ec7c5465a4e6d19b68227024f77779bb1e0669
+size 278632

blend2d/_bin/libblend2d_motion.dll

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a2d336469f8afb6a2fa8fced6747dba0f8d969eb6fd337010d68ce01af27baf4
+size 198656

blend2d/_bin/libblend2d_motion.pdb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b9a412c18ecd1a385f43fef6cf5cc900e0fcbc14f1bde22d465823f5c4d82ca9
+size 2281472

blend2d/_bin/libblend2d_motion.so

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fe128e202a83727182e5d006aed573cebc7b957859b0855c7a8fef3748f0a94e
+size 246704

blend2d/_bin/libblend2d_perspective.pdb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a4f9c4f44cba88ac0756df2f9cbb513e2a3ec89d16557314f816b43b0bc0cb16
+size 925696

blend2d/_bin/libblend2d_video.dll

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e34618c350a965062bab6db603921328e8671d4a7f006a9ac0d1a5fc66b669c
+size 179712

blend2d/_bin/libblend2d_video.pdb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7f28c87b5171dde1ab40a29df17d28f41ff5c9218b2098eff5aeac9982929bc9
+size 2129920

blend2d/_bin/libblend2d_video.so

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:668090817b4c23d2c35a78bad9d05f8509857ed5748c13561d70f23f6d8992d8
+size 229824