NaraMotion 🎨🚀

Author & Creator: Islam Arifi
Official PyPI Package: naramotion (v0.27.0)

NaraMotion is an ultra-fast 2D/2.5D vector graphics, GIS, motion graphics, and cinematic video engine for Python powered by Blend2D (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:

import naramotion

# Activate official license (removes all evaluation watermarks)
naramotion.set_license("YOUR_COMMERCIAL_KEY")

Or set the environment variable:

export NARAMOTION_LICENSE_KEY="YOUR_COMMERCIAL_KEY"  # Linux/macOS
set NARAMOTION_LICENSE_KEY="YOUR_COMMERCIAL_KEY"     # Windows

📦 Official Installation

1. From PyPI:

pip install naramotion

2. Optional Speed & Ecosystem Extensions:

pip install "naramotion[numpy,pil]"     # For Zero-Copy NumPy & Pillow integration
pip install "naramotion[all]"           # For GeoPandas, Shapely & full testing

✅ Quick Verification:

import naramotion
print(f"✨ NaraMotion Version: {naramotion.__version__} by {naramotion.__author__}")

🚀 Quickstart

⭐ 1. The 5-Line Magic: GeoScene & Cinematic Camera (v0.28.0)

The fastest, most elegant way to build geospatial motion videos in Python:

import naramotion as nm

# 1. Create scene (auto-detects bounds, projections & buffers)
scene = nm.GeoScene(width=3840, height=2160, bg_color="#04060B")

# 2. Add layers with lenient kwargs (supports Parquet, GeoJSON, Shapefile, GeoPandas)
scene.add("buildings.parquet", color="#38BDF8", border="#FFFFFF", reveal="wave")
scene.add("roads.parquet", color="#F43F5E", width=3.0)

# 3. Dynamic cinematic camera with smooth easing
scene.camera.zoom_in(factor=1.6, duration=150, easing="cubic_out")

# 4. Export universal 4K MP4 in one line (100% Native C++ engine)
scene.export("city_cinematic_4k.mp4", duration=10.0, fps=30)

👉 See COOKBOOK.md for 5-minute practical recipes!

2. Basic Drawing & Context Manager

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

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)

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.

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)

5. What's New in v0.27.0 ⚡

• Ultra-Fast 4K Integer Fixed-Point Bloom: Post-processing bloom screen blend optimized in native C++ using integer arithmetic (255 - (((255 - a) * (255 - b) * 257 + 257) >> 16)), reducing 4K bloom latency to 28ms (>35 FPS).
• Native Ramer-Douglas-Peucker (RDP) Simplification: simplify_coords() and simplify_geometry() eliminate 80-90% of redundant vertices on camera zoom-out, preventing sub-pixel moiré and rasterizer choke.
• Native Ear-Clipping Polygon Triangulation: triangulate_polygon() decomposes arbitrary complex polygons into SIMD triangle arrays for direct rendering via GeoCanvas.fill_triangles().
• Zero-Allocation Fast Frame Clear: GeoCanvas.clear_frame(bg_color) reuses existing 3840x2160 pixel allocations in 0.4ms across video loops.
• Resilient Video Streaming: VideoWriter.write_frame() seamlessly accepts GeoCanvas, Image, numpy.ndarray, or raw buffer bytes with automatic MP4 +faststart web streaming.

📚 Master Documentation & Architectural Guides

For technical specifications, unified styling, and AI guidelines, see:

• COOKBOOK.md — 5-Minute Practical Recipes & Ready-to-Run Blueprints
• STYLE_GUIDE.md — Master Unified Design System & Developer Ergonomics
• API_REFERENCE.md — Strict Technical Signatures & Canonical Blueprints
• DOCUMENTATION.md — Comprehensive API Documentation
• AI_RULES.md — Master Coding Rules for AI Assistants