| name | image-local-replacer |
| description | 对 PNG/JPG/WebP 等位图做小范围局部替换、局部遮盖、局部文字重写或局部修补。 使用 Python/Pillow 基于矩形区域进行像素级覆盖、背景采样、颜色匹配和可选文字绘制， 保持原图尺寸、文件名和未选中区域不变。适用于用户要求“只改这一小块”“不要整图 AI 重绘” “替换图片里的编号/标签/日期/小段文字”“遮盖局部内容”“修补局部残留像素”等场景。
|
图片局部替换
对已经固化在位图中的小范围内容做可控替换。优先使用确定性的局部像素编辑：读取原图，按配置只处理指定矩形区域，必要时从周边采样背景，再写入新内容或仅覆盖清除。
核心原则
- 只修改用户指定或校准后的局部区域。
- 不使用整图 AI 重绘，不重新生成整张图。
- 不改变图片宽高、文件名和未选中区域。
- 先输出到预览目录，确认无误后再覆盖原图。
- 对残留像素做二次修正时，只覆盖残留区域，不扩大影响范围。
适用场景
| 场景 | 推荐方式 |
|---|
| 替换图中编号、标签、日期、小段文字 | 覆盖旧文字区域，再按相近颜色、字号和字体写入新文字 |
| 遮盖局部敏感信息 | 用背景采样色、指定纯色或模糊前的近似色覆盖局部区域 |
| 清理旧字符残影、标注残留 | 用更小矩形做二次覆盖 |
| 修补地图、工程图、截图中的小块错误 | 只处理错误区域，保留线条、图例、边界、点位等其他内容 |
不适合：需要理解复杂语义、重建大面积背景、补全缺失物体、改变图像风格或生成新画面的任务；这些应使用专门图像编辑工作流，而不是本技能。
工作流
- 收集目标图片路径和替换要求，明确哪些区域允许修改。
- 预览图片，定位需要替换的最小矩形区域。矩形坐标使用
[left, top, right, bottom]。
- 需要写新文字时，记录文字左上角
[x, y]、颜色、字号和字体；尽量匹配原图视觉风格。
- 创建 JSON 配置，每个局部替换项只描述一个小区域。
- 先运行脚本输出到预览目录，逐张检查。
- 如存在残留、遮挡或颜色突兀，微调
cover、background、padding、text_xy、font_size 后重跑。
- 确认无误后再使用
--overwrite 覆盖原图。
配置示例
坐标均为像素坐标：
{
"default": {
"font_size": 24,
"fill": "#d71920",
"stroke_width": 0
},
"items": [
{
"file": "map.png",
"description": "替换左上角机位编号",
"cover": [100, 120, 158, 148],
"text": "XD1",
"text_xy": [102, 116]
},
{
"file": "screenshot.png",
"description": "遮盖手机号",
"cover": [320, 88, 460, 116],
"background": "#ffffff"
}
]
}
字段说明：
| 字段 | 必填 | 说明 |
|---|
file | 是 | 相对输入目录的图片路径 |
cover | 是 | 要覆盖的局部矩形 [left, top, right, bottom] |
description | 否 | 人工复核说明，不参与绘制 |
text | 否 | 覆盖后写入的新文字；不填则只做局部覆盖 |
text_xy | 写文字时必填 | 新文字左上角 [x, y] |
font_size | 否 | 字号，未设置时使用 default.font_size |
font | 否 | 字体文件路径，未设置时尝试常见系统字体 |
fill | 否 | 文字颜色，支持 #RRGGBB 或 [r,g,b] |
background | 否 | 覆盖色；未设置时脚本从覆盖框周围采样中位数颜色 |
padding | 否 | 覆盖框额外扩张像素，默认 0 |
stroke_width | 否 | 文字描边宽度，默认 0 |
stroke_fill | 否 | 文字描边颜色 |
运行方式
安装依赖：
pip install -r resources/requirements.txt
先输出到检查目录：
python3 scripts/apply_local_replacements.py ./images replacements.json -o ./preview-images
检查无误后覆盖原文件：
python3 scripts/apply_local_replacements.py ./images replacements.json --overwrite
如果需要辅助定位红色文字或红色标注，可生成红色像素遮罩：
python3 scripts/apply_local_replacements.py ./images replacements.json --red-mask-dir ./red-mask
验收
- 输出图与原图宽高一致。
- 目标局部区域已按要求替换、遮盖或清理。
- 未选中区域视觉上保持不变。
- 文件名保持不变；如果使用输出目录，只改变目录不改变文件名。
- 覆盖区域边缘没有明显突兀色块、残留像素或误遮挡。
