swallow/SpriteTool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
981fae16933a229e821bdbbd8b129864b0d47c6e
SpriteTool/README_EN.md

11 KiB
Raw Blame History

SpriteTool - Game Developer Tool Suite

A powerful suite of game development tools providing a complete solution for Sprite and image editing.

🎯 Feature Overview

SpriteTool is an integrated web application that combines four professional-grade tools into one:

📏 Grid Tool

Used to define regular grid areas on an image and perform batch selections.

Key Features:

  • Automatically generate grids based on rows and columns (e.g., 64x95 cells).
  • Supports drag-to-pan and scroll-to-zoom.
  • Cmd+Click to select any rectangular area.
  • Real-time calculation of total selected cells.
  • Export or edit area definitions in JSON format.
  • Supports undo and clear operations.
  • Batch export as a single PNG image.

Use Cases: Tilemap creation, Sprite Sheet splitting, map editing.

🎯 Sprite Picker

Quickly select and extract individual sprites from complex Sprite Sheets.

Key Features:

  • Free-hand selection box (supports any size and position).
  • Unified Sprite dimension settings (width/height).
  • Set column count for export with automatic layout.
  • Real-time preview of selected Sprites.
  • Click preview images to remove unwanted Sprites.
  • Export as optimized PNG images.

Use Cases: Character animation decomposition, prop extraction, UI asset organization.

✨ Shiny Monster Maker

Professional-grade "shiny" variant adjustment using HSV color space.

Key Features:

  • Hue Shift - 0~180° color wheel rotation.
  • Saturation - 0~2x multiplier adjustment.
  • Brightness - 0~2x multiplier adjustment.
  • Saturation Mask - Protects gray/black pixels.
  • Real-time effect preview.
  • Supports multiple image input formats.
  • One-click download of the result.

Use Cases: Shiny variant creation, character skin adjustment, thematic color swapping.

🔄 Sprite Flipper

Quickly perform horizontal flipping (mirroring) for each animation cell in a Sprite Sheet.

Key Features:

  • Precisely split cells based on configured row and column counts.
  • Batch horizontal flip for all cells.
  • Real-time preview of both original and result images.
  • Preserves Alpha transparency channel.
  • One-click download of the complete flipped Sprite Sheet.

Use Cases: Creating mirrored animations, symmetrical Tilemap variants, character action adjustments.

🧩 Sprite Merger

Precisely merge source Sprite into the target cell of a main Sprite Sheet.

Key Features:

  • Upload main image and source sprite.
  • Set main image row/column counts with automatic cell size calculation.
  • Specify target cell coordinates (Column / Row).
  • Automatic alignment and merge of source sprite to target position.
  • Preserves transparency and color information.
  • Real-time preview of merge result.
  • One-click download of completed image.

Use Cases: Character variant assembly, Tilemap element composition, Sprite Sheet content updates.

✂️ Inset Crop Tool

Remove Chroma Key background and perform intelligent inset cropping and enlargement on Sprite Sheets.

Key Features:

  • Color Removal - Custom chroma key (default #ff00ff pink) and threshold adjustment.
  • Real-time Preview - Instantly view background removal effects while adjusting threshold.
  • Preview Background Customization - Change preview background color to check edge precision (inspection only, does not affect export).
  • Inset Guide Lines - Display dashed lines showing each cell's inset boundary (pink dashed outline) for visual verification of inset effects.
  • Smart Cropping - Precisely divide cells based on rows/columns and inset distance.
  • Enlarge After Crop - Automatically enlarge back to original cell size after inset cropping.
  • Batch Export - Export individual cell PNGs + combined full image.
  • ZIP Archive - Download all results in a single ZIP package.

Use Cases: Sprite Sheet background removal, pixel art standardization, animation frame sequence optimization.

🚀 Quick Start

Prerequisites

  • Python 3.8+
  • FastAPI
  • Pillow (PIL)
  • OpenCV (cv2)
  • Uvicorn
  • Starlette

Install Dependencies

pip install fastapi uvicorn pillow opencv-python starlette

Run Application

python tool.py

The application will start at http://localhost:8000

Visit the home page to see all available tools, or access them directly:

  • Grid Tool: http://localhost:8000/grid/
  • Sprite Picker: http://localhost:8000/picker/
  • Shiny Maker: http://localhost:8000/shiny/
  • Sprite Flipper: http://localhost:8000/flipper/
  • Sprite Merger: http://localhost:8000/merger/
  • Inset Crop Tool: http://localhost:8000/inset/

📂 Project Structure

SpriteTool/
├── tool.py                          # Main entry point (FastAPI aggregation)
├── sprite_tool_fullstack.py         # Grid Tool sub-app
├── sprite_webtool.py                # Sprite Picker sub-app
├── shiny_maker.py                   # Shiny Monster Maker sub-app
├── rotate_webtool.py                # Sprite Flipper sub-app
├── rotate.py                        # Flipper core processing logic
├── sprite_merger.py                 # Sprite Merger sub-app
├── inset_crop_tool.py               # Inset Crop Tool sub-app
├── remove_pink_background.py        # Color removal tool (standalone use)
├── output/                          # Grid Tool export directory
├── shiny_output/                    # Shiny Maker export directory
└── README.md                        # This file

🎮 User Guide

Grid Tool Workflow

  1. Upload Image - Select the Sprite Sheet to cut.
  2. Set Grid - Enter row and column counts (e.g., 64x95).
  3. Select Areas
    • Drag to pan the image.
    • Cmd+Click to select rectangular areas.
    • Or modify coordinates directly in the JSON editor below.
  4. Export - Set output columns and name, then click Export.

Sprite Picker Workflow

  1. Upload Sheet - Select an image containing multiple Sprites.
  2. Adjust Settings
    • Set uniform Sprite width and height.
    • Set the number of columns for the exported row.
  3. Select Sprites - Draw boxes on the canvas to select Sprites to extract.
  4. Check Preview - View thumbnail previews on the left.
  5. Remove Errors - Click a preview image to remove unwanted Sprites.
  6. Export - Enter a filename and click Export Image.

Shiny Maker Workflow

  1. Upload Original Image - Select the image to recolor.
  2. Adjust Parameters
    • Drag Hue Shift slider to change tone.
    • Adjust Saturation multiplier.
    • Adjust Brightness multiplier.
    • Set Saturation Mask to protect neutral colors.
  3. Real-time Preview - View the effect instantly on the right.
  4. Download - Click "Download" once satisfied.

Sprite Flipper Workflow

  1. Upload Image - Select the Sprite Sheet to flip.
  2. Set Partition - Enter the row and column counts (Cols/Rows).
  3. Execute Flip - Click the button to process each cell automatically.
  4. Check Result - View the flipped preview image below.
  5. Download - Click the download button to get the result.

Sprite Merger Workflow

  1. Upload Images - Select the main Sprite Sheet and source sprite.
  2. Set Main Grid - Enter the row and column counts for the main image.
  3. Specify Target Position - Enter the target column and row indices (starting from 0).
  4. Preview Merge - View the merge result preview.
  5. Download - Click the download button to get the merged image.

Inset Crop Tool Workflow

  1. Upload Sprite Sheet - Select an image with chroma key background.
  2. Adjust Background Removal Settings
    • Choose or input the background color (e.g., #ff00ff).
    • Adjust Threshold slider and observe real-time preview on the right.
    • Confirm the background removal result.
  3. Configure Crop Parameters
    • Enter grid row and column counts (Cols/Rows).
    • Set inset distance (px) for all edges.
    • View calculated cell size and output count.
  4. Confirm and Download
    • Click "Confirm and Download ZIP" button.
    • System executes: Remove background → Inset crop → Enlarge back → Package.
    • Download ZIP containing all individual cell PNGs + combined image.

🛠️ Technical Architecture

Core Tech Stack

  • Backend Framework: FastAPI (High-performance asynchronous web framework)
  • Frontend Framework: Tailwind CSS (Utility-first CSS framework)
  • Image Processing: Pillow + OpenCV
  • Color Space: HSV color conversion and processing

System Design

Tool Entry (tool.py)

  • Unified navigation bar middleware.
  • Sub-app mounting mechanism.
  • Home page information display.

Image Processing Pipeline

  • Frontend drag/click interaction → Coordinate transmission.
  • Backend Python image calculation → Binary output.
  • Real-time preview + batch export.

📝 API Endpoints

Grid Tool

  • GET /grid/ - Home page.
  • POST /grid/upload - Upload image and generate preview.

Sprite Picker

  • GET /picker/ - Home page.
  • POST /picker/upload - Upload image.
  • POST /picker/export - Export selected Sprites.

Shiny Maker

  • GET /shiny/ - Home page.
  • POST /shiny/process - Process shiny adjustment.
  • GET /shiny/download - Download result.

Sprite Flipper

  • GET /flipper/ - Home page.
  • POST /flipper/flip - Execute sprite flipping process.

Sprite Merger

  • GET /merger/ - Home page.
  • POST /merger/merge - Execute sprite merge process.

Inset Crop Tool

  • GET /inset/ - Home page.
  • POST /inset/preview - Real-time background removal preview.
  • POST /inset/process - Execute background removal + cropping + packaging.

🎨 UI/UX Features

  • Dark Theme - Eye-friendly dark gray color scheme.
  • Unified Navigation - Navigation bar is automatically injected into all tool pages via FastAPI middleware.
  • Standardized Layout - Consistent wide-screen layout (Max-width 7xl) and header styling across all tools.
  • Responsive Design - Optimized for desktop and tablets.
  • Instant Preview - Lag-free visual feedback.
  • Drag-and-Drop Interaction - Intuitive image manipulation.
  • Touch-Friendly - Precise pixel-level selection.

📊 Common Use Cases

Indie Game Development

  • Sprite Sheet cutting and optimization.
  • Monster/character shiny variant creation.
  • Animation frame sequence organization.

Art Workflow

  • Tilemap asset preparation.
  • UI atlas organization.
  • Character skin variant production.

Resource Optimization

  • Batch Sprite extraction.
  • Unified size normalization.
  • Reduction of resource file counts.

🔧 Troubleshooting

Problem: Image fails to upload

  • Check image format (Supports PNG, JPG, GIF).
  • Ensure file size is reasonable.

Problem: Exported image is blurry

  • Confirm original image is in pixel art format.
  • Check browser zoom level.

Problem: Color adjustment effect is suboptimal

  • Adjust Saturation Mask value.
  • Try different Hue Shift angles.

📄 License

Open-source project, free to use and modify.

👤 Contribution

Issues and Pull Requests are welcome!

Last Updated: May 2026
Version: 1.2.0

Reference in New Issue View Git Blame Copy Permalink