# Pixie-Anim
<p align="center">
<img src="docs/logo_wordmark.png" width="400" alt="Pixie-Anim Logo">
</p>
<p align="center">
<a href="https://crates.io/crates/pixie-anim"><img src="https://img.shields.io/crates/v/pixie-anim.svg" alt="Crates.io"></a>
<a href="https://docs.rs/pixie-anim"><img src="https://docs.rs/pixie-anim/badge.svg" alt="Docs.rs"></a>
<a href="https://github.com/ghchinoy/pixie-anim/actions/workflows/deploy.yml"><img src="https://github.com/ghchinoy/pixie-anim/actions/workflows/deploy.yml/badge.svg" alt="Build Status"></a>
<img src="https://img.shields.io/crates/l/pixie-anim.svg" alt="License">
</p>
A high-performance, zero-dependency short-form animation optimizer written in Rust and WebAssembly.
Inspired by Lee Robinson's [pixo](https://github.com/leerob/pixo), Pixie-Anim follows a similar philosophy: building mission-critical codecs from scratch without heavy runtime dependencies, optimized for both native CLI performance and zero-latency in-browser execution.
- **📖 Read more**: [Optimizing GIFs with Pixo: Extending Lessons Learned](https://ghc.wtf/writing/optimizing-gifs-with-pixo-extending-lessons-learned/) - A technical writeup on the architecture and philosophy behind Pixie-Anim.
## 🚀 Key Features
- **Zero-Dependency Core**: From-scratch implementation of GIF89a and LZW.
- **Superior Compression**: Achieves **30-50% smaller** files than Gifsicle -O3 through advanced heuristics.
- **Perceptual Quantization**: Uses CIELAB color space and K-Means++ for superior color fidelity.
- **Temporal Denoising**: Index-reuse logic that treats temporal noise as negligible, dramatically reducing size for real-world video.
- **Stable Dithering**: Choice of **Ordered (Bayer)** or **Blue Noise** dithering to eliminate spatial "shimmer."
- **Parallelized & SIMD**: Multi-threaded quantization via Rayon and Planar AVX2/NEON kernels for nearest-color search.
- **WASM Playground**: Fully functional, client-side optimizer with direct MP4-to-GIF support.
- **Subjective LLM Judge**: Automated quality evaluation via Gemini 3 Flash.
## 📊 Performance Matrix (Space Waves - 720p)
| **Gifsicle -O3** | Standard | 19,034 | 6 |
| **FFmpeg** | 2-Pass HQ | 19,290 | 6 |
| **Pixie-Anim** | **Quality/Lossy**| **9,821** | **7** |
*Benchmarked on the high-complexity "Space Waves" sequence (Veo 3.1). Pixie-Anim provides a massive size advantage while improving visual stability through Ordered Dithering.*
## 🧠 Algorithms
### Zeng Palette Reordering
By ordering the 256-color palette by visual similarity, we maximize the length of LZW strings, gaining "free" compression with negligible compute cost.
### Lossy LZW (Fuzzy Neighbor Matching)
A unique optimization where the encoder can match visually similar "neighbor" indices in the Zeng-ordered palette to continue an LZW sequence, further collapsing file size.
### Planar SIMD Search
We discovered that standard interleaved RGB SIMD is often slower than scalar for small palettes. Pixie-Anim uses a **Planar** data layout to unlock the true potential of AVX2/NEON for nearest-color search.
## 🛠 Usage
### CLI
Build the native binary:
```bash
cargo build --release --features="cli"
```
The binary will be available at `target/release/pixie-anim`.
Optimize an image sequence:
```bash
./target/release/pixie-anim frames/*.png --output optimized.gif --fps 15 --lossy 8 --fuzz 10
```
### Web Playground
The web UI is a Lit-based application that leverages the Rust core via WASM.
1. `cd web`
2. `pnpm install`
3. `pnpm run dev` (This automatically triggers `build-wasm` to generate bindings)
4. Drop an MP4 or GIF into the browser to optimize locally.
*Note: To prevent browser memory exhaustion, the web playground currently scales video to 640px and caps extraction at 300 frames. Use the CLI for unlimited high-resolution processing.*
### 📊 Benchmarking & Evaluation
Pixie-Anim includes a unified benchmarking tool to compare performance and visual quality against `Gifsicle`, `FFmpeg`, and `gifski`.
See [tests/README.md](tests/README.md) for detailed instructions on the **Hill-Climbing** workflow and iterative performance tuning.
**Quick Benchmark:**
```bash
./target/release/pixie-bench --input video.mp4 --name my_test --lossy 8 --report tests/benchmarks.md
```
This tool automatically:
1. Extracts frames via `ffmpeg`.
2. Runs the optimization suite across all four engines.
3. Invokes the **Gemini Subjective Judge** for quality scoring.
4. Generates a detailed Markdown report with size, speed, and visual critique.
## 👁️ Automated Evaluation
Pixie-Anim includes a `judge` tool that uses **Gemini 3 Flash** to perform a comparative analysis of the output, identifying artifacts like banding or temporal jitter that traditional metrics (PSNR/SSIM) might miss.
## 📋 Prerequisites
### Core Development
- **Rust** (1.70+)
- **Node.js & npm/pnpm** (For Web Playground)
- **wasm-bindgen-cli** (`cargo install wasm-bindgen-cli`)
### Benchmarking & Evaluation
To run the comparative benchmarks and the subjective judge, you'll need:
- **FFmpeg**: For frame extraction and judge frame analysis.
- **Gifsicle**: For baseline compression comparison.
- **gifski**: For high-quality comparison.
- **bc**: For benchmark timing calculations.
- **Gemini API Key**: Set as `GEMINI_API_KEY` in your environment or `.env` file for the `judge` tool.
Install on macOS via Homebrew:
```bash
brew install ffmpeg gifsicle gifski bc
```
---
Part of the **Pixie** family of high-performance media tools