README.md

metadata

title: ROICropper
emoji: 🌍
colorFrom: green
colorTo: pink
sdk: gradio
sdk_version: 6.31.0
app_file: app.py
pinned: false
license: mit

ROICropper

Crop image objects from files or folders into any aspect ratio (1:1, 4:3, 16:9, etc.) focused on the main object against a white background.

Installation

Install core + CLI:

pip install roicropper

Install with optional features:

pip install roicropper[cli]    # CLI tools
pip install roicropper[web]    # Gradio web UI
pip install roicropper[dev]    # Testing and linting
pip install roicropper[cli,web]  # Everything

Usage

CLI

Single image crop:

roi-cropper crop input.jpg output.png --size 640 --aspect-ratio 1:1

Batch process:

roi-cropper batch ./input_folder/ ./output_folder/ --size 1280 --padding 15

Launch the web interface:

roi-cropper web

Open http://localhost:7860 in your browser.

Or run the standalone server directly:

roi-cropper-web

Docker

Build and run:

docker build -t roicropper .
docker run -p 7860:7860 roicropper

HuggingFace Spaces

This app is designed to run on HuggingFace Spaces as a Gradio app. The root app.py launches the interface.

Parameters

Flag	Short	Type	Default	Description
--size	-s	int	640	Output dimensions for square crop
--max-size		int	1280	Maximum dimension for aspect crop
--aspect-ratio	-a	str	1:1	Aspect ratio, e.g. 16:9
--padding	-p	int	10	Padding in pixels around object
--format	-f	str	png	Output format: jpg or png
--host	-h	str	0.0.0.0	Host to bind (web command)
--port	-p	int	7860	Port to listen on (web command)

Web Interface Features

• Single crop: Upload one image and preview the result instantly
• Batch mode: Upload multiple images, download all cropped results as a ZIP archive
• Presets: Quick-select common ratios (1:1, 4:3, 16:9, 3:2, A4)
• Custom ratios: Enter any width:height combination

Development

Setup

uv pip install -e '.[dev,cli,web]'
python -m pytest tests/ -v

Adding Fixtures

Place sample images in tests/fixtures/ for integration tests. Use common names like sample.png, landscape.jpg.

---

Built by Fazri Gading in 2026