Metadata-Version: 2.4
Name: naramotion
Version: 0.26.1
Summary: High-Performance 2D Vector Graphics, Spatial GIS, Motion & Cinematic Rendering Engine for Python powered by Blend2D.
Author: Islam Arifi, NaraMotion Developers
Maintainer: Islam Arifi
License: Proprietary
Project-URL: Homepage, https://pypi.org/project/naramotion/
Project-URL: Repository, https://pypi.org/project/naramotion/
Project-URL: Documentation, https://pypi.org/project/naramotion/
Keywords: naramotion,blend2d,graphics,2d,vector,rasterizer,jit,simd,motion,gis,geopandas,shapely,video,render,vfx,aftereffects
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: numpy
Requires-Dist: numpy>=1.20; extra == "numpy"
Provides-Extra: pil
Requires-Dist: Pillow>=8.0; extra == "pil"
Provides-Extra: all
Requires-Dist: numpy>=1.20; extra == "all"
Requires-Dist: Pillow>=8.0; extra == "all"
Requires-Dist: geopandas>=0.10.0; extra == "all"
Requires-Dist: shapely>=1.8.0; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Dynamic: requires-python

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

**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)
```

---

### 4. High-Performance Geospatial Engine & Shockwave Waves (v0.26.0)

For processing 50,000+ city blocks/parcels at 4K 60FPS:
- **Direct Native Parquet WKB Reader** (`read_parquet_native`) bypassing Python/Shapely object allocations.
- **Structure of Arrays (`NativeGeoLayerSoA`) & Path Arena**: Keeps distances, bounding boxes, and centroids in contiguous CPU cache lines.
- **Dual-Buffer Polygon Pipeline**: Flushes fills and strokes in separate SIMD batches.
- **Centroid Spring Pop-In**: Elastic spring back-out scale expansion ($\text{Scale}(t) = \text{Easing::back\_out}(t)$) per polygon.

```python
from naramotion.shapgeo import GeoCanvas, read_parquet_native
from naramotion.video import VideoWriter

WIDTH, HEIGHT = 3840, 2160
# 1. Pure C++ zero-copy ingest directly into SoA memory arena (< 0.8s for 50k blocks)
layer = read_parquet_native("city_blocks.parquet", return_native_soa=True)

# 2. Precompute radial shockwave wavefront in CPU cache
layer.compute_propagation(epicenters=[(-74.0060, 40.7128)], duration_frames=180.0)

# 3. Stream 4K frames zero-copy
with VideoWriter("shockwave_4k.mp4", width=WIDTH, height=HEIGHT, fps=60) as vw:
    with GeoCanvas(width=WIDTH, height=HEIGHT, bg_color="#050811") as canvas:
        for frame in range(180):
            canvas.clear("#050811")
            # Dual-buffer batch render with spring pop-in physics
            layer.render_popin(canvas, current_frame=frame, fill_color="#00F0FF", stroke_color="#FFFFFF", stroke_width=1.2)
            vw.write_frame(canvas.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)
