image-forge

Image Forge

像素级精准的图像编辑，采用三层路由：精确操作使用确定性的 CLI 工具，语义编辑使用 AI 模型，分析使用视觉模型。

路由决策

当编辑需要理解图像内容时，使用 AI。当编辑需要精确控制像素时，使用 ImageMagick。

第 1 层：确定性操作（magick、sips、transparent-background）

适用于参数精确、数值明确的操作：

任务	工具	命令
调整为精确尺寸	magick	magick in.jpg -resize 800x600! out.jpg
调整大小以适配（保持宽高比）	magick	magick in.jpg -resize 800x600 out.jpg
调整大小以填充并裁剪	magick	magick in.jpg -resize 800x600^ -gravity center -extent 800x600 out.jpg
仅缩小	magick	magick in.jpg -resize '800x600>' out.jpg
按偏移量裁剪	magick	magick in.jpg -crop 600x400+100+50 +repage out.jpg
居中裁剪	magick	magick in.jpg -gravity center -crop 600x400+0+0 +repage out.jpg
自动裁去空白	magick	magick in.jpg -fuzz 10% -trim +repage out.jpg
转换格式	magick	magick in.png -quality 85 out.jpg
添加文字	magick	magick in.jpg -fill white -pointsize 36 -annotate +10+50 'Text' out.jpg
合成叠加层	magick	magick bg.png fg.png -geometry +50+100 -composite out.png
添加水印	magick	magick photo.jpg wm.png -gravity SouthEast -geometry +10+10 -compose Dissolve -define compose:args=25 -composite out.jpg
调整亮度/对比度	magick	magick in.jpg -brightness-contrast 10x20 out.jpg
调整饱和度	magick	magick in.jpg -modulate 100,130,100 out.jpg
转为灰度	magick	magick in.jpg -colorspace Gray out.jpg
转为棕褐色调	magick	magick in.jpg -sepia-tone 80% out.jpg
模糊	magick	magick in.jpg -blur 0x3 out.jpg
锐化	magick	magick in.jpg -sharpen 0x1 out.jpg
移除背景（AI）	transparent-background	参见下方的移除背景部分
移除背景（简单）	magick	magick in.jpg -fuzz 15% -transparent white -trim +repage out.png
清除元数据	magick	magick in.jpg -strip out.jpg
设置 DPI	magick	magick in.jpg -density 300 out.jpg
批量调整大小	batch_ops.py	python3 scripts/batch_ops.py *.jpg --op resize --width 800 --output resized/
拼图/联系表	magick	magick montage *.jpg -geometry 200x200+5+5 -tile 4x out.jpg
快速转换格式（macOS）	sips	sips -s format jpeg in.png --out out.jpg
快速调整大小（macOS）	sips	sips -Z 800 in.jpg --out out.jpg

第 2 层：AI 语义编辑（nano-banana-pro / Gemini）

当编辑需要理解图像内容时，委托给 nano-banana-pro 技能：

• 从照片中移除人物/物体
• 更改天空、天气或一天中的时段
• 应用艺术风格迁移
• 对区域进行修补/扩展
• 从头生成新图像
• 移除物体后进行内容感知填充

Nano Banana 会重新生成图像，而不是编辑图像。 每次调用都会重新生成整幅画面，即使提示词要求原样保留某些区域也是如此。目标区域之外约有 40% 的像素会发生偏移——这是实测结果，并非假设。对于需要精细控制的区域编辑（更改面部，同时保持其他所有内容完全一致），请使用 references/compositing.md § Surgical Regional Edits 中的混合模式：让 NB 生成一张有偏移的参考图，然后使用羽化 Alpha 蒙版，仅将目标区域合成到未经修改的原图上。

Nano Banana 也只支持有限的宽高比（1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9）。对于其他宽高比的输入（例如 3:1 全景图），请参见 references/recipes.md § Aspect Ratio Padding，了解填充-生成-裁剪方案。

第 3 层：视觉分析（Claude Read 工具）

使用 Read 工具检查编辑前后的图像：

• 验证编辑是否成功
• 描述图像内容
• 检查构图和取景
• 识别图像中的颜色、物体和文字

背景移除

使用 transparent-background（InSPyReNet 模型）进行 AI 背景移除。它能生成干净的 Alpha 蒙版，边缘平滑且经过抗锯齿处理，效果远胜于 ImageMagick 的 -transparent/-fuzz 方法；后者会在凹陷区域留下白边，边缘也会参差不齐。

如何选择：

方法	使用场景	质量
transparent-background	任何具有复杂前景的照片或渲染图（头发、半透明边缘、凹陷区域）	Alpha 平滑，无白边
magick -transparent white -fuzz N%	纯白背景上的简单形状，快速粗略处理	速度快，但边缘有锯齿，且无法处理内部白色区域
magick floodfill	仅移除角落处的背景，保留内部白色区域	仅作用于连通区域

Python API（推荐）：

from transparent_background import Remover
from PIL import Image

remover = Remover()
img = Image.open("input.jpg").convert("RGB")
out = remover.process(img, type="rgba")
out.save("output.png")

同时进行修剪（最常见的工作流）：

python3 -c "
from transparent_background import Remover
from PIL import Image
remover = Remover()
img = Image.open('input.jpg').convert('RGB')
remover.process(img, type='rgba').save('/tmp/nobg.png')
"
magick /tmp/nobg.png -trim +repage output.png

安装： uv pip install --system transparent-background

性能： 在 Apple Silicon（MPS）上，每张图像约需 2-3s。首次运行时会下载 InSPyReNet 模型（约 170MB）。

注意： rembg 也可作为替代方案，但截至 2026 年 5 月，其 gradio 依赖存在问题。transparent-background 是更可靠的选择。

脚本

所有脚本都位于 ~/.claude/skills/image-forge/scripts/。使用 python3 运行。

image_info.py — 检查图像元数据

python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field dimensions
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field width

返回整洁的 JSON：尺寸、格式、色彩空间、位深、Alpha、DPI、ICC 配置文件和 EXIF。

image_pipeline.py — 声明式编辑流水线

编写 JSON 规范，即可生成一条串联的 magick 命令。无需中间文件。

# Create spec
cat > /tmp/pipeline.json << 'EOF'
{
    "input": "photo.jpg",
    "output": "result.png",
    "steps": [
        {"op": "resize", "width": 800, "height": 600, "mode": "fill"},
        {"op": "brightness_contrast", "brightness": 5, "contrast": 10},
        {"op": "annotate", "text": "Title", "gravity": "South", "pointsize": 36, "fill": "white", "stroke": "black", "strokewidth": 2},
        {"op": "composite", "overlay": "watermark.png", "gravity": "SouthEast", "opacity": 25},
        {"op": "quality", "value": 90},
        {"op": "strip"}
    ]
}
EOF

# Dry run (print command)
python3 ~/.claude/skills/image-forge/scripts/image_pipeline.py /tmp/pipeline.json --dry-run

# Execute
python3 ~/.claude/skills/image-forge/scripts/image_pipeline.py /tmp/pipeline.json

可用操作：

操作	参数
resize	width、height、mode（fit/fill/exact/shrink/enlarge/percent）、filter
crop	w/width、h/height、x、y、gravity
trim	fuzz（%）
annotate	text、font、pointsize、fill、stroke、strokewidth、gravity、x、y
composite	overlay、gravity、x、y、opacity、compose、resize
rotate	angle、background
blur	sigma、radius
sharpen	sigma、radius
unsharp	sigma、radius、amount、threshold
modulate	brightness、saturation、hue（100 = 不变）
brightness_contrast	brightness、contrast
levels	black、white、gamma
gamma	value
sigmoidal_contrast	strength、midpoint
colorize	color、amount（%）
sepia	threshold（%）
grayscale	（无）
negate	（无）
auto_level	（无）
normalize	（无）
auto_orient	（无）
flip / flop	（无）
border	color、size
extent	width、height、background、gravity
shadow	opacity、sigma、x、y
transparent	color、fuzz（%）
alpha_remove	background
alpha_set	（无）
quality	value（1-100）
strip	（无）
density	value（DPI）
draw	primitive、fill、stroke、strokewidth
raw	args（原始 magick 参数的字符串或数组）

smart_crop.py — 基于重心位置的智能裁剪

python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 800x600
python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 800x600 --gravity north
python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 1080x1080 --output cropped/
python3 ~/.claude/skills/image-forge/scripts/smart_crop.py photo.jpg --target 800x600 --dry-run

重心位置：center、north、south、east、west、northwest、northeast、southwest、southeast。

batch_ops.py — 并行批量处理

python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op resize --width 800 --output resized/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.png --op format --to jpg --quality 85 --output converted/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op thumbnail --width 200 --height 200 --output thumbs/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op strip --output clean/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op watermark --overlay wm.png --opacity 25 --output marked/
python3 ~/.claude/skills/image-forge/scripts/batch_ops.py *.jpg --op resize --width 800 --parallel 8 --output resized/

操作：resize、thumbnail、format、strip、auto_orient、watermark、crop。

montage_builder.py — 联系表

python3 ~/.claude/skills/image-forge/scripts/montage_builder.py *.jpg --output contact.jpg
python3 ~/.claude/skills/image-forge/scripts/montage_builder.py *.jpg --cols 3 --thumb 300x300 --label --output grid.jpg
python3 ~/.claude/skills/image-forge/scripts/montage_builder.py *.jpg --background '#1a1a2e' --border 2 --output dark_grid.jpg

快速配方

社交媒体裁剪

# Instagram square
magick in.jpg -resize 1080x1080^ -gravity center -extent 1080x1080 instagram.jpg

# Instagram story
magick in.jpg -resize 1080x1920^ -gravity center -extent 1080x1920 story.jpg

# Twitter/X header
magick in.jpg -resize 1500x500^ -gravity center -extent 1500x500 header.jpg

# OG image
magick in.jpg -resize 1200x630^ -gravity center -extent 1200x630 og.jpg

水印

# Text watermark
magick photo.jpg -fill 'rgba(255,255,255,0.3)' -gravity SouthEast \
  -font Helvetica -pointsize 24 -annotate +10+10 '© 2026' out.jpg

# Image watermark at 25%
magick photo.jpg wm.png -gravity SouthEast -geometry +10+10 \
  -compose Dissolve -define compose:args=25 -composite out.jpg

边框和阴影

# Solid border
magick in.jpg -bordercolor '#333' -border 10 out.jpg

# Drop shadow
magick in.png \( +clone -background black -shadow 60x5+5+5 \) \
  +swap -background none -layers merge +repage shadow.png

色彩效果

# Vintage
magick in.jpg -modulate 105,80,100 -fill '#704214' -colorize 15% \
  -sigmoidal-contrast 3x60% vintage.jpg

# High contrast B&W
magick in.jpg -colorspace Gray -sigmoidal-contrast 10x50% bw.jpg

几何语法快速参考

语法	含义
800x600	在框内适配，保持宽高比
800x600!	强制精确尺寸（拉伸变形）
800x600>	仅在图像较大时缩小
800x600<	仅在图像较小时放大
800x600^	填满框（最小尺寸匹配）
50%	按百分比缩放
+X+Y	相对于重心锚点的偏移

Shell 转义：为包含 >、<、^ 的几何参数加引号：

magick in.jpg -resize '800x600>' out.jpg

关键提醒

1. 在 -crop 后始终使用 +repage——否则虚拟画布偏移会持续保留
2. -modulate 的顺序是 B、S、H——亮度、饱和度、色相（不是 H、S、L）
3. 设置会持续生效，操作符会立即执行——在 magick 命令中，顺序很重要
4. 使用 rembg 移除背景——rembg i input.jpg output.png（添加 -a 进行 Alpha 抠图）
5. 将几何参数用引号括起来——>、<、^ 是 Shell 元字符
6. 在 IM7 中，-alpha off 是永久性的——临时切换请使用 -alpha deactivate/-alpha activate
7. 编辑前先检查——先运行 image_info.py，了解尺寸、格式和 Alpha 状态
8. 多步骤操作请使用管道——使用 image_pipeline.py，不要串联 Shell 命令
9. Nano Banana 会让整个画面产生偏移——切勿认为 NB 会保持某些区域不变。进行区域编辑时，请使用精细合成模式（参见 compositing.md § Surgical Regional Edits）。使用 magick compare -metric AE -fuzz 5% before after diff.png 验证——AE 值低表示结果干净，约 40% 以上则表示整幅图像都被重新生成。

参考资料

详细参考资料位于 ~/.claude/skills/image-forge/references/：

• magick-reference.md——完整的 ImageMagick 7 命令参考（调整大小、裁剪、颜色、文本、绘图、批处理、识别）
• compositing.md——所有合成运算符（Duff-Porter、数学、光照、HSL、特殊）
• recipes.md——30 多种配方（边框、阴影、水印、社交媒体尺寸、颜色效果、精灵图、批处理模式）

依赖项

工具	版本	安装
ImageMagick	7.1.2-7 (Q16-HDRI)	brew install imagemagick
rembg	2.0.72	uv pip install rembg
sips	macOS 内置	—
Pillow	10.4.0	uv pip install Pillow