Metadata-Version: 2.4
Name: sanana
Version: 0.1.0
Summary: Local cartoon-style image editor powered by MNN-Sana-Edit-V2
Author: sanana contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/vra/sanana
Project-URL: Repository, https://github.com/vra/sanana
Project-URL: Issues, https://github.com/vra/sanana/issues
Keywords: mnn,sana,diffusion,image-editing,cartoon,ghibli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
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: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: modelscope>=1.30.0
Provides-Extra: dev
Requires-Dist: pybind11>=2.10.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Dynamic: license-file

<div align="center">

# 🎨 sanana

**Turn your photos into Ghibli-style illustrations in one command**

*Local · Private · CPU-only · No GPU needed*

<p>
  <a href="https://pypi.org/project/sanana"><img src="https://img.shields.io/pypi/v/sanana?style=flat-square&color=blue" alt="PyPI"></a>
  <a href="https://pypi.org/project/sanana"><img src="https://img.shields.io/pypi/pyversions/sanana?style=flat-square&color=green" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square" alt="License"></a>
  <a href="https://github.com/vra/sanana/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/vra/sanana/ci.yml?style=flat-square&label=CI" alt="CI"></a>
</p>

<p>
  <img src="examples/flower_cartoon.jpg" width="180" />
  <img src="examples/landscape_cartoon.jpg" width="180" />
  <img src="examples/portrait_cartoon.jpg" width="180" />
  <img src="examples/dog_cartoon.jpg" width="180" />
</p>

English | <a href="README_ZH.md">🌐 中文文档</a>

</div>

---

## ✨ Showcase

<table>
  <tr>
    <td align="center"><b>Original</b></td>
    <td align="center"><b>🪄 sanana Magic</b></td>
  </tr>
  <tr>
    <td><img src="examples/portrait.jpg" width="400"/></td>
    <td><img src="examples/portrait_cartoon.jpg" width="400"/></td>
  </tr>
  <tr>
    <td><img src="examples/landscape.jpg" width="400"/></td>
    <td><img src="examples/landscape_cartoon.jpg" width="400"/></td>
  </tr>
  <tr>
    <td><img src="examples/dog.jpg" width="400"/></td>
    <td><img src="examples/dog_cartoon.jpg" width="400"/></td>
  </tr>
  <tr>
    <td><img src="examples/flower.jpg" width="400"/></td>
    <td><img src="examples/flower_cartoon.jpg" width="400"/></td>
  </tr>
</table>

---

## 🚀 One-Liner Start

```bash
# Install once
pip install sanana
sanana photo.jpg

# Or run without installing (requires uv)
uvx sanana photo.jpg
```

The model (~1.2GB) will be downloaded automatically on first run.

---

## 🔥 Highlights

| 🎨 | **Cartoon Style Transfer** | Photos → Ghibli/anime illustrations |
|:---:|:---|:---|
| 🏠 | **Fully Local** | No internet, no cloud upload, absolute privacy |
| 🐍 | **Python Native** | pybind11 C++ extension, inference inside Python process |
| 💻 | **CPU-only** | MNN high-performance engine, runs on ordinary machines |
| ⚡ | **10 Steps** | Knowledge-distilled model, high quality with few steps |
| 📦 | **Truly Ready-to-Use** | `pip install` handles all dependencies automatically |

---

## 📦 Installation

### Option 1: pip (Recommended)

```bash
pip install sanana
```

This automatically clones and builds [MNN](https://github.com/alibaba/MNN) (requires `git`, `cmake`, C++ compiler).

### Option 2: From Source

```bash
git clone https://github.com/vra/sanana.git
cd sanana
uv pip install -e ".[dev]"
```

---

## 🎮 Usage

### CLI

```bash
# Minimal
sanana photo.jpg

# Custom output
sanana photo.jpg -o output.jpg

# Custom prompt
sanana photo.jpg --prompt "Ghibli style"

# Full args
sanana photo.jpg \
  -o out.jpg \
  --prompt "Convert to Ghibli style" \
  --steps 10 \
  --seed 42 \
  --width 512 \
  --height 512
```

| Argument | Description | Default |
|:---|:---|:---|
| `input` | Input image path | **Required** |
| `-o, --output` | Output path | `input_stem_cartoon.jpg` |
| `--prompt` | Style prompt | `Convert to a cartoon-style illustration` |
| `--steps` | Inference steps | `10` |
| `--seed` | Random seed | `42` |
| `--width/--height` | Output size | `512x512` |

### Python API

```python
from sanana import edit_image

# One-shot
edit_image("./photo.jpg", steps=10, seed=42)
```

```python
from sanana import SanaEditor

# Advanced: reuse model for batch processing
editor = SanaEditor(backend="cpu", memory_mode=2)
editor.load()

for img in ["a.jpg", "b.jpg", "c.jpg"]:
    editor.run(
        input_image=img,
        output_image=img.replace(".jpg", "_cartoon.jpg"),
        steps=10,
    )
```

---

## ⚙️ Architecture

```
┌────────────────────────────────────────────┐
│  🐍 Python Layer                            │
│     sanana (CLI / API)                      │
│            ↓ import                         │
│     sanana._sana_diffusion                  │
│     (pybind11 C++ Extension)                │
└────────────────────┬───────────────────────┘
                     │
┌────────────────────▼───────────────────────┐
│  🔧 C++ Layer (MNN)                         │
│     SanaLlm ──→ SanaDiffusion ──→ Image     │
│     (Text Encode) (Flow Matching Denoise)   │
└────────────────────────────────────────────┘
```

- **Text Encoding**: Qwen3-0.6B LLM processes the prompt
- **Feature Bridging**: Connector → Projector maps to DiT space
- **VAE Encode**: Input image → Latent (img2img)
- **DiT Denoise**: Euler sampling + Flow Shift, 10 steps
- **VAE Decode**: Latent → Final image

---

## 🖥️ Performance

Apple MacBook Pro M3 (CPU, 512×512, 10 steps):

| Stage | Time |
|:---|:---|
| LLM Text Encoding | ~1.5 s |
| VAE Encode | ~3 s |
| DiT Denoise (10 steps) | ~22 s |
| VAE Decode | ~5 s |
| **Total** | **~32 s** |

---

## 🧩 Requirements

| Platform | Status | Notes |
|:---|:---:|:---|
| macOS (Apple Silicon / Intel) | ✅ Supported | Best performance on M1/M2/M3 |
| Linux (x86_64 / ARM64) | ✅ Supported | Tested on Ubuntu 22.04+ |
| Windows (x86_64) | ⚠️ Experimental | Requires Visual Studio + OpenCV, CI unstable |

- **Python**: 3.10+
- **Compiler**: Clang/GCC/MSVC (C++17)
- **Tools**: git, cmake

---

## ❓ FAQ

**Q: MNN not found during install?**  
A: `setup.py` auto-clones and builds MNN. Just ensure `git`, `cmake`, and a C++ compiler are installed.

**Q: First run is slow?**  
A: The model (~1.2GB) is downloaded on first use. Subsequent runs are fast.

**Q: GPU support?**  
A: CPU by default. Use `backend="metal"` for Metal (macOS), requires MNN built with GPU flags.

**Q: Commercial use?**  
A: Code is Apache-2.0. Model files follow the original publisher's license.

---

## 🤝 Contributing

Issues and PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

## 📜 Changelog

See [CHANGELOG.md](CHANGELOG.md).

## 📄 License

Code: [Apache-2.0](LICENSE).  
Model: [MNN-Sana-Edit-V2](https://modelscope.cn/models/MNN/MNN-Sana-Edit-V2) belongs to its original publisher.

---

<div align="center">

If this project helps you, please give it a ⭐ **Star**!

</div>
