Metadata-Version: 2.5
Name: animora
Version: 0.1.0
Summary: High-level, declarative animation framework built on top of Manim for educational, technical, and algorithmic visualization.
Project-URL: Homepage, https://github.com/himanshu-jadhav108/Animora
Project-URL: Documentation, https://github.com/himanshu-jadhav108/Animora#readme
Project-URL: Repository, https://github.com/himanshu-jadhav108/Animora.git
Project-URL: Issues, https://github.com/himanshu-jadhav108/Animora/issues
Author-email: Himanshu Jadhav <himanshujadhav40@gmail.com>
License: MIT
License-File: LICENSE
Keywords: algorithms,animation,data-structures,education,manim,math,visualization
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: manim<1.0.0,>=0.18.0
Requires-Dist: networkx<4.0,>=3.0
Requires-Dist: numpy<3.0.0,>=1.24.0
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Requires-Dist: rich>=13.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: click>=8.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rich>=13.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Description-Content-Type: text/markdown

<div align="center">

# 🎬 Animora

### *Declarative, High-Level Animation Framework for Python*

[![PyPI Version](https://img.shields.io/pypi/v/animora.svg?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/animora/)
[![CI Status](https://github.com/himanshu-jadhav108/Animora/actions/workflows/ci.yml/badge.svg)](https://github.com/himanshu-jadhav108/Animora/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-00B4D8.svg?logo=materialformkdocs&logoColor=white)](https://himanshu-jadhav108.github.io/Animora/)
[![Python Version](https://img.shields.io/pypi/pyversions/animora.svg?logo=python&logoColor=white)](https://pypi.org/project/animora/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://img.shields.io/badge/mypy-checked-1f425f.svg)](https://mypy-lang.org/)

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-why-animora">Why Animora?</a> •
  <a href="#-features--examples">Features & Examples</a> •
  <a href="#-cli-tooling">CLI Tooling</a> •
  <a href="#-architecture">Architecture</a> •
  <a href="https://himanshu-jadhav108.github.io/Animora/">Documentation</a>
</p>

</div>

---

## 🌟 Overview

**Animora** is to [Manim](https://www.manim.community/) what **Seaborn** is to **Matplotlib**.

Instead of manually calculating pixel coordinates, managing low-level point arrays, and choreographing dozens of vector mobjects, Animora enables you to write **clean, declarative, and composable animations** for educational videos, computer science lectures, technical presentations, and data stories.

```python
from animora.core import Scene
from animora.datastructures import BST
from animora.theme import ModernDark, use_theme

class BinarySearchTreeDemo(Scene):
    def construct(self) -> None:
        with use_theme(ModernDark):
            # 1. Declaratively initialize a Binary Search Tree
            bst = BST([50, 30, 70, 20, 40])
            self.play(bst.animate_create())

            # 2. Insert key with animated comparison path: 50 -> 30 -> 40 -> 35
            self.play(bst.animate_insert(35))

            # 3. Search target key with instant visual highlight
            self.play(bst.animate_search(35))
```

---

## 💡 Why Animora?

| Capability | Raw Manim | With Animora |
|:---|:---|:---|
| **Programming Model** | Imperative, low-level coordinate positioning | Declarative, component-based composition |
| **Layouts** | Manual `.next_to()`, `.shift()`, and math calculations | Automatic solvers (`Grid`, `Circular`, `Tree`, `Graph`, `Flow`) |
| **Theming & Styling** | Hardcoded hex strings scattered in scripts | Centralized design tokens (`ModernDark`, `PaperLight`, `Cyberpunk`) |
| **Data Structures** | Manual construction of circles, arrows, and text | Stateful `Array`, `BST`, `Graph`, `Heap`, `Stack`, `Queue`, `HashTable` |
| **Algorithm Animations** | Ad-hoc animation choreography | Traced execution (`quick_sort`, `dijkstra`, `a_star`, `binary_search`) |
| **Extensibility** | Fixed to Manim APIs | First-class **Escape Hatch** (`.manim_object`) on all components |

---

## 🚀 Quick Start

### 1. Installation

Install Animora from PyPI:

```bash
pip install animora
```

*(Optional: Install with development dependencies)*
```bash
pip install "animora[dev]"
```

### 2. Verify Your Environment

Animora includes a built-in doctor to verify Python, Manim, and FFmpeg installations:

```bash
animora doctor
```

```text
============================================================
 Animora System & Environment Diagnostics
============================================================
[PASS]   Python       : Python 3.11.8 (>= 3.10 supported)
[PASS]   Animora      : Animora 0.1.0 installed
[PASS]   Manim        : Manim Community 0.18.1 (compatible)
[PASS]   NumPy        : NumPy 1.26.4 installed
[PASS]   NetworkX     : NetworkX 3.2.1 installed
[PASS]   FFmpeg       : FFmpeg binary found at /usr/bin/ffmpeg
============================================================
Status: Environment is fully ready for Animora visualizations.
```

---

## 🛠️ CLI Tooling

Animora comes with a dedicated CLI for rapid prototyping and production export:

```bash
# 1. Scaffold a starter scene from template
animora new my_scene.py

# 2. Fast low-quality preview (instant rendering for iterative design)
animora preview my_scene.py --open

# 3. Full production quality render (1080p 60fps or 4K)
animora render my_scene.py --quality high
```

---

## 📦 Features & Examples

### 1. Visual Primitives & Container Panels
Compose shapes, text, arrows, and containers with semantic state animations:

```python
from animora.core import Scene
from animora.components import Text, Shape, Panel, Arrow
from animora.theme import ModernDark, use_theme

class PrimitivesScene(Scene):
    def construct(self) -> None:
        with use_theme(ModernDark):
            title = Text("Visual Primitives", font_size=36)
            circle = Shape.circle(radius=0.6, fill_color="#38BDF8")
            rect = Shape.rounded_rectangle(width=2.0, height=1.2, corner_radius=0.15)
            card = Panel(circle, rect, title="Component Container")

            self.play(title.animate_fade_in())
            self.play(card.animate_create())
            self.play(circle.animate_highlight())
```

### 2. Automatic Layout Solvers
Pure geometric layout engines that automatically arrange collections of components:

```python
from animora.components import Group, Shape
from animora.layout import GridLayout, CircularLayout

nodes = [Shape.circle(radius=0.3) for _ in range(8)]
group = Group(*nodes)

# Arrange in a 2x4 Grid
group.arrange(GridLayout(columns=4, col_spacing=0.5, row_spacing=0.5))

# Rearrange into a Circle
group.arrange(CircularLayout(radius=2.0))
```

### 3. Data Visualization
Mathematically rigorous chart components featuring dual-correctness:

```python
from animora.core import Scene
from animora.dataviz import BarChart, Table

class ChartScene(Scene):
    def construct(self) -> None:
        chart = BarChart(
            data=[("MergeSort", 45), ("QuickSort", 30), ("BubbleSort", 120)],
            bar_width=0.7,
        )
        self.play(chart.animate_grow())
        self.play(chart.animate_highlight_bar(1, color="#10B981"))
```

### 4. Algorithm Visualizations & Tracing
Generate step-by-step algorithm animations directly from real execution traces:

```python
from animora.core import Scene
from animora.datastructures import Array
from animora.algorithms import quick_sort

class SortingScene(Scene):
    def construct(self) -> None:
        arr = Array([45, 12, 89, 33, 7, 56])
        self.play(arr.animate_create())

        # Returns a sequence of step-by-step animations (compares, swaps, highlights)
        self.play(*quick_sort(arr))
```

### 5. Multi-Theme Scoping
Dynamically switch between built-in design systems (`ModernDark`, `PaperLight`, `Cyberpunk`, `Monokai`):

```python
from animora.components import Text, Shape, Panel
from animora.theme import Cyberpunk, PaperLight, use_theme

with use_theme(Cyberpunk):
    neon_box = Panel(Shape.circle(), title=Text("Cyberpunk"))

with use_theme(PaperLight):
    clean_box = Panel(Shape.circle(), title=Text("Paper Light"))
```

---

## 🏗️ Architecture & Escape Hatch

Animora follows a strict 4-layer decoupled architecture:

```text
┌────────────────────────────────────────────────────────┐
│ Layer 4: Algorithms & Data Visualization               │
│          (Sorting, Pathfinding, Charts, Trees, Tables) │
├────────────────────────────────────────────────────────┤
│ Layer 3: Layout Engines & Theme System                 │
│          (Grid, TreeLayout, ModernDark, Cyberpunk)     │
├────────────────────────────────────────────────────────┤
│ Layer 2: Visual Primitives & Containers                │
│          (Text, Shape, Connector, Arrow, Group, Panel) │
├────────────────────────────────────────────────────────┤
│ Layer 1: Core Abstractions & Manim Bridge              │
│          (Component, Scene, Animation, .manim_object)  │
└────────────────────────────────────────────────────────┘
```

### The Native Manim Escape Hatch
You are never locked into Animora's abstractions. Every single component exposes its underlying Manim vector entity through `.manim_object`:

```python
import manim
from animora.components import Shape

circle = Shape.circle(radius=1.0)
native_mobject = circle.manim_object  # Access raw Manim VMobject

# Use raw Manim shaders, gradients, or updaters freely
native_mobject.set_color_by_gradient(manim.BLUE, manim.PINK)
```

---

## 🎨 Example Gallery

Check out runnable examples located in the [`examples/`](examples/) directory:

- [`01_basics_and_shapes.py`](examples/01_basics_and_shapes.py) — Visual primitives & container panels.
- [`02_layout_and_grouping.py`](examples/02_layout_and_grouping.py) — Automatic layout solvers.
- [`03_themes_and_styling.py`](examples/03_themes_and_styling.py) — Multi-theme scoping.
- [`04_dataviz_charts.py`](examples/04_dataviz_charts.py) — Bar charts & data visualization.
- [`05_datastructures_bst.py`](examples/05_datastructures_bst.py) — Binary Search Tree with path tracing.
- [`06_algorithms_sorting.py`](examples/06_algorithms_sorting.py) — Quick Sort animation.
- [`07_pathfinding_dijkstra.py`](examples/07_pathfinding_dijkstra.py) — Dijkstra graph shortest path.

---

## 🤝 Contributing

We welcome community contributions! Please read our [Contributing Guide](CONTRIBUTING.md) and review our [Code of Conduct](CODE_OF_CONDUCT.md) before submitting pull requests.

### Development Setup

```bash
git clone https://github.com/himanshu-jadhav108/Animora.git
cd Animora
pip install -e ".[dev]"
pytest
ruff check src/
mypy src/
```

---

## 📄 License

Animora is open-source software licensed under the **[MIT License](LICENSE)**.
