avdergh/chroma-cut

Chroma Cut

English · 简体中文

移除 AI 生成图片和游戏素材表中的纯色背景，同时保留黑色抗锯齿描边。

使用场景

- 将 AI 生成的图标、道具、角色和特效转换为透明 PNG。
- 把带色键背景的精灵图或 UI 素材表拆成独立素材。
- 去除带有轻微渐变和噪声的洋红、绿色、蓝色或青色背景。
- 统一动画帧、建筑阶段和同组图标的画布尺寸与锚点。

功能

- 从裁切区域边缘自动检测色键背景。
- 使用软 Color-to-Alpha 蒙版移除背景及边缘溢色。
- 保留黑色描边和接近背景色的前景内容。
- 支持单素材命令行裁切和 JSON 批处理。
- 可统一同组素材的画布、尺寸与锚点。
- 自动生成棋盘格、黑底和白底检查图。
- 提供 cut_asset、cut_sheet 两个本地 MCP 工具。

安装

需要 Python 3.11 或更高版本。

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

开发模式安装：

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

快速开始

裁切单个素材

裁切矩形格式为 左,上,右,下。

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

批量裁切素材表

chroma-cut batch examples/sample-job.json

任务配置示例：

{
"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"
}
}

批处理还可以统一同组素材：

- same_canvas：保持素材原始比例，统一画布大小。
- resize_same_bounds：把可见主体缩放到相同尺寸。
- 支持 center 和 bottom_center 对齐。

MCP

启动本地 stdio MCP Server：

chroma-cut-mcp

可用工具：

- cut_asset：把一个图片区域切成透明 PNG。
- cut_sheet：执行 JSON 批处理任务。

DeepSeek Harness

plugins/dsh-chroma-cut/ 是一个可安装的
DeepSeek Harness 组合包。它通过
DSH 自带的 MCP 客户端桥接挂载同一个 Python MCP Server，为 agent 提供两个原生工具：

- mcp__chroma_cut__cut_asset — 把一个图片区域切成透明 PNG。
- mcp__chroma_cut__cut_sheet — 执行 JSON 批处理任务。

从 npm（或打包后的 tarball）安装到 profile：

dsh plugin --profile  add dsh-chroma-cut
dsh --profile    # 首次运行会在 ~/.cache 中引导 Python 运行时

无 npm 时可用 GitHub Release 的 tarball：
dsh plugin --profile  add https://github.com/avdergh/chroma-cut/releases/download/v0.1.3/dsh-chroma-cut-0.1.3.tgz

详见 plugins/dsh-chroma-cut/README.md，包含环境变量覆盖与发布步骤。

工作原理

Chroma Cut 从裁切区域边缘检测背景色相，区分外部背景与被轮廓包围的前景区域，并估算素材边缘附近的局部背景颜色。随后计算连续 Alpha，并从边缘 RGB 中移除背景色成分。主体内部保持完全不透明，因此黑色描边和接近背景色的前景内容不会被误删。

使用限制

自动模式适用于明亮、高饱和、基本为单一色相的背景。它不是面向照片、毛发、烟雾、玻璃或复杂多色场景的语义背景移除工具。

测试

python -m unittest discover -s tests -v

开源协议

MIT，详见 LICENSE。