Sprite Extractor

Sprite Extractor is a professional-grade command-line tool designed to intelligently analyze and extract sprites from complex sprite sheets. Built for game developers and archivists, it leverages advanced computer vision to handle everything from modern transparent PNGs to legacy grids and noisy screenshots.

---

🚀 Key Features

• Intelligent Segmentation:
  • Contour Mode: Automatically detects distinct objects using hierarchical contour analysis.
  • FloodFill Background Removal: New in v0.2.0! Robustly extracts pale or low-contrast subjects from solid backgrounds (e.g., white), preventing fragmentation of facial features.
• Aggressive Deduplication:
  • Uses Perceptual Hashing (pHash) and Histogram Analysis to identify identical sprites.
  • Spatial Awareness: Smartly distinguishes between identical sprites in different positions (e.g., animation frames) vs. true duplicates.
• Grid Mode: specialized extraction for fixed-size tilemaps and legacy sprite sheets.
• Production Ready:
  • Rich CLI: Beautiful, informative terminal output with real-time progress bars.
  • Type Safe: Fully typed codebase for reliability.
  • Modular Architecture: Clean, extensible package structure.

📦 Installation

This project is managed with Poetry.

# Clone the repository
git clone https://github.com/ericsonwillians/sprite-extractor.git
cd sprite-extractor

# Install dependencies
poetry install

🛠️ Usage

Quick Start

Extract sprites from a standard transparent PNG:

poetry run sprite-extractor input.png output_dir/ --auto-crop

🌟 New: Handling Light Backgrounds (Invert Mode)

If your image has a solid white or light background (not transparent), use the --invert flag. This uses our new FloodFill segmentation to correctly isolate objects like faces without losing internal details (eyes/mouth).

poetry run sprite-extractor faces.jpg output_faces/ \
    --invert \       # Activates FloodFill for light backgrounds
    --auto-crop \    # Trims empty space around the extracted sprite
    --min-size 50    # Filters out small noise

Grid Mode (Tilemaps)

For sheets with fixed-size grids:

poetry run sprite-extractor tileset.png output_tiles/ \
    --grid-mode \
    --grid-size 32 32

Advanced Configuration

Fine-tune the extraction process:

poetry run sprite-extractor input.png output/ \
    --threshold 15 \      # Adjust binary threshold sensitivity
    --padding 2 \         # Add safety padding around extracted sprites
    --format webp \       # Output format (png, jpg, webp)
    --metadata \          # Generate a JSON file with extraction stats
    --debug               # Enable verbose logging

🏗️ Architecture

The project is structured as a modular Python package:

src/sprite_extractor/
├── analysis.py      # Deduplication logic (pHash, spatial overlap, similarity metrics)
├── cli.py           # Command-line interface and Rich integration
├── detectors.py     # Core algorithms (Contour & Grid detection)
├── image_ops.py     # Image processing (FloodFill, Otsu thresholding, Preprocessing)
├── io.py            # File I/O and metadata serialization
└── models.py        # Data classes and configuration types

🤝 Contributing

Contributions are welcome! Please run the test suite before submitting a PR:

1. Test: poetry run pytest
2. Lint: Ensure code follows PEP 8.

📄 License

MIT © Ericson Willians