Chroma Cut

English · 简体中文

Remove solid-color backgrounds from AI-generated images and game asset sheets without
shaving off dark anti-aliased outlines.

Use cases

• Turn AI-generated icons, props, characters, and effects into transparent PNGs.
• Split a chroma-backed sprite or UI sheet into individual assets.
• Remove magenta, green, blue, or cyan backgrounds with mild gradients and noise.
• Keep related assets on matching canvases and anchors for animation or state changes.

Features

• Automatic chroma-color detection from the crop border.
• Soft Color-to-Alpha matting with chroma-spill removal.
• Dark-outline and similar-foreground-color preservation.
• Single-asset CLI and JSON batch processing.
• Optional canvas and anchor normalization for grouped assets.
• Checkerboard, black, and white QA previews.
• Local MCP server with cut_asset and cut_sheet.

Installation

Python 3.11 or newer is required.

python -m pip install "git+https://github.com/avdergh/chroma-cut.git"

For development:

git clone https://github.com/avdergh/chroma-cut.git
cd chroma-cut
python -m pip install -e .

Quick start

Cut one asset

The crop box format is left,top,right,bottom.

chroma-cut cut sheet.png output.png --box 100,50,500,600 --padding 12

Cut a sheet

chroma-cut batch examples/sample-job.json

Example job:

{
  "version": 1,
  "output_dir": "./output",
  "sources": {
    "sheet": "./sheet.png"
  },
  "assets": [
    {
      "name": "energy_icon",
      "source": "sheet",
      "box": [0, 0, 512, 512],
      "padding": 12
    }
  ],
  "qa": {
    "preview": "qa_checker.png",
    "black_preview": "qa_black.png",
    "white_preview": "qa_white.png"
  }
}

Batch jobs can also normalize related assets:

• same_canvas: preserve artwork scale and use one shared canvas.
• resize_same_bounds: resize visible artwork to matching bounds.
• center and bottom_center alignment are supported.

MCP

Start the local stdio server:

chroma-cut-mcp

Available tools:

• cut_asset: cut one image region into a transparent PNG.
• cut_sheet: run a JSON batch job.

DeepSeek Harness

plugins/dsh-chroma-cut/ is an installable
DeepSeek Harness bundle. It
mounts the same Python MCP server through the DSH-shipped MCP client bridge,
so the agent gains two native tools:

• mcp__chroma_cut__cut_asset — cut one image region into a transparent PNG.
• mcp__chroma_cut__cut_sheet — run a JSON batch job.

Install from npm (or a packed tarball) into a profile:

dsh plugin --profile <name> add dsh-chroma-cut
dsh --profile <name>   # first run bootstraps the Python runtime in ~/.cache

Without npm, use the GitHub Release tarball:
dsh plugin --profile <name> add https://github.com/avdergh/chroma-cut/releases/download/v0.1.3/dsh-chroma-cut-0.1.3.tgz

See plugins/dsh-chroma-cut/README.md for
details, environment overrides, and publishing steps.

How it works

Chroma Cut detects the backing hue from pixels around the crop border, separates the
outside background from enclosed foreground regions, and estimates the local backing
color around the silhouette. It then calculates fractional alpha and removes the
backing-color contribution from edge RGB values. Opaque interior pixels are preserved,
so black outlines and foreground colors close to the backing hue remain intact.

Limitations

Automatic mode is intended for bright, saturated, mostly single-hue backgrounds. It is
not a semantic background remover for photographs, hair, smoke, glass, or complex
multicolored scenes.

Testing

python -m unittest discover -s tests -v

License

MIT. See LICENSE.