README.md

---
title: GMIC Filter Studio
emoji: 🎨
colorFrom: yellow
colorTo: green
sdk: gradio
sdk_version: 5.6.0
app_file: app.py
pinned: false
license: apache-2.0
python_version: 3.12
---
# G'MIC Filter Studio

Full modern G'MIC running server-side via Gradio.  
No size restriction, full stdlib, 600+ filters.

## What this is

G'MIC compiled from the Ubuntu apt repository (3.x), with the community
filter definitions (`update.gmic`) fetched at first run. All processing happens
on Hugging Face's CPU — no local compute needed.

## Filters included (highlights — things ImageJ.js and Photopea can't do)

| Category | Filter | Why it's special |
|---|---|---|
| **Document Repair** | Repair Scanned Document | Background normalisation + adaptive contrast for book/document scans |
| **Document Repair** | Clean Text (afre) | Binarise and sharpen text while removing paper tone |
| **Inpainting** | Patch-based & Multi-scale inpaint | Content-aware fill using example patches — better than clone stamp |
| **Smoothing** | Anisotropic diffusion | Edge-preserving noise removal (PDE-based, unlike bilateral or NLM) |
| **Skin** | Smooth Skin | Frequency-split retouching tuned for skin detection |
| **Tone** | Retinex | Local contrast / shadow recovery inspired by human vision |
| **Haze** | DCP Dehaze | Dark channel prior haze / fog removal |
| **Film** | Simulate Film (600+ LUTs) | Film grain, colour response, halation for 600+ film stocks |
| **Artistic** | Brushify | Paint strokes guided by edge flow |
| **Artistic** | Kuwahara | Oil-painting abstraction |
| **Artistic** | Illustration Look | Flat-colour + edge stylisation |
| **Upscale** | Scale2x | Edge-aware pixel-art upscaling |
| **Denoise** | Iain Fast Denoise | Patch NLM denoiser |
| **Analysis** | Frequency split | Separate texture and colour layers |

## How to deploy your own copy

1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
2. Name it anything — pick **Gradio** as the SDK
3. In the repository file browser, create three files:
   - `app.py` — paste the contents from this repo
   - `requirements.txt` — `gradio>=4.0` and `Pillow`
   - `packages.txt` — just the word `gmic` on a single line
4. HF will build and start the Space automatically (takes ~2 min).
5. Bookmark the resulting URL — it works from any browser including mobile.

That's it — no terminal, no git, no local tools required.

## Finding CLI parameters for any filter

Inside the GIMP G'MIC plugin:
1. Set *Output Messages → Verbose (layer name)*
2. Apply any filter with the sliders you want
3. The resulting layer's name contains the exact CLI command

Or in a terminal:
```
gmic echo '$${fx_some_filter}'
```
This prints the filter's source code including parameter order.

## Adding your own filters

Edit `app.py` and add entries to `FILTER_GROUPS`. The format is:
```python
("My Filter Name",
 "gmic_command {param1},{param2}",
 [("param1", "Label", min, max, step, default),
  ("param2", "Label", min, max, step, default)]),
```

## Notes on the `fx_` filters

Community filters (`fx_*`) are downloaded from `gmic.eu` on first use.
If the Space is cold-started (rare), the first request may take a few seconds
longer while the update file fetches. Subsequent requests are fast.

## Licence

G'MIC is distributed under the CeCILL licence (GPL-compatible).
This wrapper code is public domain / CC0.