GIMPSAM — Segment Anything for GIMP

Credits

This project is a hard fork of Shriinivas/gimpsegany — all the original plugin architecture, the GIMP 3 integration, and SAM1/SAM2 support are their work. GIMPSAM is an updated version built on top of that foundation to have support to the latest SAM 3.1 model with text-based segmentation, an easier installer, optimized parallel performance and a tighter integration with the LazyGIMP project.

Install

You can find the downloadable files in the latest release.

One-liner

curl -fsSL https://raw.githubusercontent.com/pierspad/GIMPSAM/main/installer.py | python3 - --ephemeral

From source:

git clone https://github.com/pierspad/GIMPSAM
cd GIMPSAM
python3 installer.py            # GUI
python3 installer.py --help     # CLI

Running with no arguments opens the GUI, which walks you through the plug-in, the Python backend, and a model download. Any subcommand runs headless instead.

CLI

Command	Description
(none)	Opens the GUI wizard
status	Plug-in, backend, and installed models
install	Plug-in + backend + a recommended model, in one go
remove	Removes the plug-in, the backend, and every model
plugin install [--ref <git-ref>] / plugin remove	Just the GIMP plug-in files
backend install [--torch-index <url>] / backend remove	Just the venv + PyTorch + SAM
model list	Every SAM checkpoint and its install state
model install <key> / model remove <key>	Download or delete a specific checkpoint, e.g. sam2_hiera_small
sam3 download --token <hf_token>	Downloads the gated SAM 3.1 weights from Hugging Face
sam3 remove	Deletes the SAM 3.1 checkpoint
sam3 transformers	Installs/upgrades transformers (required to run SAM 3.1)

--torch-index accepts any of the known PyTorch wheel indexes (CPU, CUDA 13.2/13.0/12.8, ROCm 7.2/6.4, Intel XPU) — omit it and it's auto-detected from your GPU. --ephemeral self-deletes the installer once the GUI closes.

---

Manual configuration

If you'd rather not use the installer at all:

1. Find GIMP's plug-ins folder. Edit > Preferences > Folders > Plug-ins inside GIMP, or the defaults:
   • Linux: ~/.config/GIMP/3.0/plug-ins/
   • Windows: C:\Users\[YourUsername]\AppData\Roaming\GIMP\3.0\plug-ins\
   • macOS: ~/Library/Application Support/GIMP/3.0/plug-ins/
2. Copy the plugin files. Create a seganyplugin folder inside it and copy seganyplugin.py and seganybridge.py into it. On Linux/macOS, make sure both are executable (chmod +x seganyplugin.py seganybridge.py).
3. Create a Python environment for the backend (a virtualenv is recommended, e.g. python3 -m venv ~/.local/share/lazygimp/segany/venv).
4. Install PyTorch for your hardware — CPU wheels from https://download.pytorch.org/whl/cpu, or the matching CUDA/ROCm/XPU index for a GPU (see the list above).
5. Install image dependencies: pip install numpy pillow opencv-python-headless.
6. Install a SAM backend package, depending on which model family you want:
   • SAM1: pip install git+https://github.com/facebookresearch/segment-anything.git
   • SAM2: pip install git+https://github.com/facebookresearch/segment-anything-2.git
   • SAM3: pip install transformers huggingface_hub (no separate repo needed — see the SAM3 section below)
7. Download a checkpoint — SAM1/SAM2 URLs are listed in gimpsam/models.py's MODEL_REGISTRY; SAM3 requires requesting access on Hugging Face first, then downloading with huggingface_hub.snapshot_download(repo_id="facebook/sam3.1", local_dir=..., token=...).
8. Verify it works by running the bridge test below.
9. Restart GIMP — it only scans the plug-ins folder on startup.

Bridge test

Sanity-check the backend directly, independent of GIMP:

/path/to/python3 ./seganybridge.py auto /path/to/checkpoint/sam_vit_l_0b3195.pth

A Success!! message indicates a working installation. See tools/bench_bridge.py and tools/headless_e2e.sh for deeper correctness/speed checks.

Plugin usage

Open GIMP. Under the "Image" menu, you'll find a new submenu called "Segment Anything Layers" — open an image and click it to bring up the dialog.

Main options:

• Model: auto-discovered from an installer-managed backend (LazyGimp or this project's own installer); shows "No model found" with a pointer to Expert Mode if none is detected.
• Text Prompt: shown only for SAM3 — a short noun phrase describing what to select, e.g. "car" or "person wearing a red hat".
• Segmentation Type (hidden for SAM3, which uses the text prompt instead):
  • Auto: segments the entire image.
  • Box: segments objects within a user-drawn rectangular selection.
  • Selection: segments objects from sample points inside a user-drawn selection (tune the point count via Selection Points).
• Mask Type: Multiple creates one layer per candidate object; Single keeps only the highest-probability mask.
• Random Mask Color / Mask Color: random colors per layer, or one color of your choice.

Expert Mode (collapsed by default — raw paths and tuning for auto-segmentation):

• Python3 Path / Model Checkpoint: manual overrides when nothing was auto-discovered. The model family (SAM1/SAM2/SAM3) is always inferred from the checkpoint's filename or folder name, never from a manual selector.
• Segmentation Resolution: density of the Auto segmentation grid — higher finds more masks, slower.
• Crop n Layers: segments on overlapping crops of the image, which can improve accuracy on smaller objects.
• Minimum Mask Area: discards masks smaller than this many pixels.
• Max resolution for Auto: downscales large images before running Auto, then upscales the resulting masks — the biggest lever for CPU speed, since Auto's cost scales with pixel count.

SAM3

For SAM3 you need to request access on Hugging Face to download the models. SAM3 uses transformers' own Sam3Model/Sam3Processor rather than Meta's standalone repo, so it runs on CPU (slowly — expect several seconds per image) without needing Python 3.12+.

Workflow

1. Select your desired options in the plugin dialog and click "OK".
2. The plugin will create a new layer group with one or more mask layers.
3. Find the mask layer corresponding to the object you want to isolate.
4. Select that layer and use the "Fuzzy Selection" tool to select the mask area.
5. Hide the new layer group and select your original image layer.
6. You can now cut, copy, or perform any other GIMP operation on the selected object.

---

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss your ideas.

---

AI Disclosure

This project was developed with the assistance of Large Language Models, used to support code writing and documentation.

---

License

This project is licensed under the GPL v3 License — see the LICENSE file for details.