Metadata-Version: 2.3
Name: handanim
Version: 0.1.0
Summary: A Python library to create whiteboard-style, hand-drawn animations for educational videos, tutorials or data storytelling.
License: MIT
Keywords: animation,hand-drawn,manim,math,whiteboard,education
Author: Subhrajyoty Roy
Author-email: subhrajyotyroy@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Provides-Extra: ai
Requires-Dist: cairocffi (>=1.7.1,<2.0.0)
Requires-Dist: fonttools (>=4.47.0,<5.0.0)
Requires-Dist: hershey-fonts (>=2.1.0,<3.0.0)
Requires-Dist: matplotlib (>=3.7.0,<4.0.0)
Requires-Dist: moviepy (>=2.1.2,<3.0.0)
Requires-Dist: numpy (>=2.2.4,<3.0.0)
Requires-Dist: pycairo (>=1.27.0,<2.0.0)
Requires-Dist: svgelements (>=1.9.6)
Requires-Dist: urllib3 (>=2.6.3,<3.0.0)
Project-URL: Changelog, https://github.com/subroy13/handanim/blob/master/CHANGELOG.md
Project-URL: Documentation, https://subroy13.github.io/handanim/
Project-URL: Homepage, https://github.com/subroy13/handanim
Project-URL: Issues, https://github.com/subroy13/handanim/issues
Project-URL: Repository, https://github.com/subroy13/handanim.git
Description-Content-Type: text/markdown

# ✍️ handanim

[![Build and Deploy Docs](https://github.com/subroy13/handanim/actions/workflows/docs.yml/badge.svg)](https://github.com/subroy13/handanim/actions/workflows/docs.yml)

> A Python library to create whiteboard-style, hand-drawn animations for educational videos, tutorials or data storytelling.

**handanim** lets you programmatically animate hand-drawn diagrams, geometric shapes, handwritten text, and visual explanations — ideal for online teaching, explainer videos, and mathematical illustrations.

> ⭐️ If you like this project, please consider starring it on [GitHub](https://github.com/subroy13/handanim)! Your support helps the project grow.

## ✨ Features

- Draw and animate shapes (lines, ellipses, polygons) with a hand-drawn feel
- Fill objects with sketch-style strokes (hatching, scribbles)
- Animate handwritten text using custom fonts
- Export vector images (SVG) or videos (MP4).
- Intuitive Python API for creating scenes and timelines

## 📷 Example Output

### Example 1: Pythagoras Theorem

<p align="center">
  <img src="https://raw.githubusercontent.com/subroy13/handanim/master/examples/output/pythagoras.gif" width="500">
</p>

_(Example animation of a Pythagoras Theorem — see `examples/pythagoras.py`)_


### Example 2: Square formula

<p align="center">
  <img src="https://raw.githubusercontent.com/subroy13/handanim/master/examples/output/a_plus_b_square.gif" width="500">
</p>

_(Example animation of proof of a plus b whole square — see `examples/a_plus_b_square.py`)_



## 🚀 Quickstart

### 📦 Installation using Poetry

The easiest way to install all the dependencies is to use [Poetry](https://python-poetry.org/).

```bash
# Install dependencies (requires Python 3.11+)
poetry install

# Run example animation
poetry run python examples/pythagoras.py
```

### ✏️ Basic Usage

```python
from handanim.core import Scene
from handanim.animations import SketchAnimation
from handanim.primitives import NGon

scene = Scene(width = 800, height = 608)
triangle = NGon(
    center = (400, 304),
    radius = 100,
    n = 3
)
scene.add(SketchAnimation(start_time = 0, end_time = 5), drawable = triangle)
scene.render("triangle_anim.mp4", fps = 30)
```

## 📦 Installation using pip

If you prefer using `pip` instead of Poetry, you can install the main dependencies directly from the `requirements.txt` file. This method works well for lightweight setups or deployment environments.

```bash
# Create and activate a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install core dependencies
pip install -r requirements.txt

# (Optional) Install development dependencies
pip install -r dev-requirements.txt

# Run example animation
python examples/pythagoras.py
```

Make sure you're using Python 3.11+ (as specified in the project). 

## 📦 Installation using conda

If you prefer conda for environment management:

```bash
# Create a new environment
conda create -n handanim python=3.11
conda activate handanim

# Install system dependencies via conda-forge
conda install -c conda-forge cairo pycairo ffmpeg

# Install handanim and remaining Python dependencies
pip install -r requirements.txt

# Run example animation
python examples/pythagoras.py
```

> **Note:** The `requirements.txt` may need updating for your platform. If you encounter issues, the Poetry-based installation is the most tested path.

## Installing Cairo 

Your system must have the Cairo graphics library installed for `pycairo` or `cairocffi` to work correctly. This is a native C library and needs to be installed separately depending on your OS.

#### ✅ On Ubuntu/Debian

```bash
sudo apt update
sudo apt install libcairo2 libcairo2-dev
```

#### ✅ On macOS (using Homebrew)

```bash
brew install cairo
```

#### ✅ On Windows
Use the precompiled binaries:

1. Download the [GTK 3 Runtime](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases) (which includes Cairo).
2. Install it and add its bin/ folder to your system PATH.
3. Then install Python packages as usual:

```bash
pip install -r requirements.txt
```

Or use the cairocffi + pycairo + pip combo with wheels from [Gohlke's unofficial site](https://www.cgohlke.com/#pycairo) if needed.


## 🎬 Installing FFmpeg (Required for Video Rendering)

`moviepy` uses FFmpeg to write video files (e.g., .mp4). You must have FFmpeg installed and accessible in your system PATH.

#### ✅ On Ubuntu/Debian

```bash
sudo apt update
sudo apt install ffmpeg
```

#### ✅ On macOS (using Homebrew)

```bash
brew install ffmpeg
```

#### ✅ On Windows

1. Download FFmpeg from the [official site](https://ffmpeg.org/download.html) or a reliable Windows build like [gyan.dev](https://www.gyan.dev/ffmpeg/builds/).
2. Extract the archive, and add the bin/ folder to your system PATH.
3. Verify installation:

```bash
ffmpeg -version
```


## 📄 License

This project is licensed under the MIT License.

## 🤝 Contributing

We welcome contributions!

You can help by:

- Adding new animation primitives (e.g., Bezier curves, arrows)
- Improving rendering quality and styles, caching and optimization.
- Writing example scripts or tutorials.
- Reporting bugs and suggesting features

Please see `CONTRIBUTING.md` (coming soon) for guidelines.

## ❤️ Inspiration

Inspired by:

- [3Blue1Brown's manim](https://github.com/3b1b/manim)
- [RoughJS](https://github.com/rough-stuff/rough)
- Whiteboard animation videos
- Interactive teaching tools

⭐️ **Support handanim!**

If you find this project useful, please give it a star on [GitHub](https://github.com/subroy13/handanim).

It motivates me to keep improving it and helps others discover it!

> ✨ Made with love by Subhrajyoty Roy



