roicropper / README.md
fazrigading's picture
Add Space metadata
026b5f3 verified
|
Raw History Blame Contribute Delete
2.81 kB
---
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.
[![PyPI version](https://img.shields.io/pypi/v/roicropper.svg)](https://pypi.org/project/roicropper/)
[![Python versions](https://img.shields.io/pypi/pyversions/roicropper.svg)](https://pypi.org/project/roicropper/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
## Installation
Install core + CLI:
```bash
pip install roicropper
```
Install with optional features:
```bash
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:
```bash
roi-cropper crop input.jpg output.png --size 640 --aspect-ratio 1:1
```
Batch process:
```bash
roi-cropper batch ./input_folder/ ./output_folder/ --size 1280 --padding 15
```
Launch the web interface:
```bash
roi-cropper web
```
Open http://localhost:7860 in your browser.
Or run the standalone server directly:
```bash
roi-cropper-web
```
### Docker
Build and run:
```bash
docker build -t roicropper .
docker run -p 7860:7860 roicropper
```
## HuggingFace Spaces
This app is designed to run on [HuggingFace Spaces](https://huggingface.co/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
```bash
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](https://github.com/fazrigading/ROICropper) in 2026