README.md

metadata

title: Image Cutter
emoji: 🌍
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.2.0
app_file: app.py
pinned: false

✂️ Image Grid Cutter

Blog: www.airabbit.blog

A powerful Gradio-based tool to split images into customizable grids, crop individual tiles, and generate animated GIFs.

---

🎯 Features

1. Grid Cutting

• Upload any image and split it into a customizable grid (up to 16×16 = 256 tiles)
• Live preview with grid lines overlaid on the image
• Adjustable rows and columns with real-time updates
• Download all tiles as a ZIP file

2. Individual Tile Cropping

• Navigate through tiles with Previous/Next buttons
• Jump to first or last tile instantly
• Crop each tile individually using an interactive crop tool
• Background options: Choose transparent or custom color fill for cropped areas
• Apply a single crop uniformly to all tiles
• Download edited tiles as ZIP

3. GIF / MP4 Animation

• Generate animated GIFs from your tiles
• Export MP4 videos with the same animation styles, plus optional transitions
• Animation styles:
  • Reveal (build up): Tiles appear one by one, building the complete image
  • Cycle (one at a time): Each tile appears alone in sequence
  • Flash (all tiles): Each tile shown centered, one after another
  • Shuffle (random order): Tiles revealed in random order
• Single tile mode: Create a slideshow of individual tiles
• Adjustable frame duration (50ms - 1000ms)
• Transparent or custom color backgrounds

---

🚀 Getting Started

Prerequisites

• Python 3.8+
• pip

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/image-grid-cutter.git
   cd image-grid-cutter
   

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the app:

   python app.py
   

5. Open your browser: Navigate to http://127.0.0.1:7860

Docker

docker build -t image-cutter .
docker run --rm -p 7860:7860 image-cutter

---

📖 How It Works

Step 1: Cut Your Image

1. Go to the "1. Cut" tab
2. Upload an image (drag & drop, paste, or click to upload)
3. Adjust the Rows and Columns sliders to define your grid
4. The preview updates in real-time showing grid lines
5. Click "✂️ Cut Image" to split the image
6. Download all tiles as a ZIP file

Step 2: Crop Tiles (Optional)

1. Go to the "2. Crop (Optional)" tab
2. Choose your background fill: Transparent or a custom color
3. Use ◀ ▶ arrows or ⏮ First / Last ⏭ buttons to navigate tiles
4. Use the crop tool in the editor to crop the current tile
5. Click "💾 Save This Tile" to save individual crops
6. Or click "✅ Apply to All" to apply the same crop to every tile
7. Download the edited tiles as ZIP

Step 3: Generate Animation

1. Go to the "3. Export" tab
2. Select an animation style from the dropdown
3. Enable "Single tile per frame" for slideshow mode
4. Adjust the frame duration in milliseconds
5. Click "🎬 Generate GIF" or "🎥 Generate MP4"
6. Download your animated GIF or MP4 video

---

🎨 Use Cases

• Sprite sheets: Extract individual sprites from game assets
• Puzzle creation: Split images into puzzle pieces
• Social media grids: Create Instagram grid posts
• Animation frames: Generate frame-by-frame animations
• Image analysis: Divide images for detailed inspection
• Collage preparation: Prepare tiles for collage projects

---

🛠️ Technical Details

Dependencies

Package	Version	Purpose
Gradio	≥6.0.0	Web UI framework
Pillow	≥10.0.0	Image processing
NumPy	≥1.24.0	Numerical operations

File Structure

image-grid-cutter/
├── app.py              # Main Gradio application
├── requirements.txt    # Python dependencies
├── README.md          # This file
├── LICENSE            # Apache 2.0 license
└── .gitignore         # Git ignore rules

Key Functions

• split_image_into_grid() - Divides image into equal-sized tiles
• create_grid_preview() - Generates preview with grid overlay
• process_image() - Main cutting logic with ZIP creation
• generate_gif_from_tile_list() - Creates animated GIFs from tiles
• save_single_tile() - Handles individual tile cropping with background options

---

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📬 Contact

• Blog: www.airabbit.blog

---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference