图片局部替换

对已经固化在位图中的小范围内容做可控替换。优先使用确定性的局部像素编辑：读取原图，按配置只处理指定矩形区域，必要时从周边采样背景，再写入新内容或仅覆盖清除。

核心原则

• 只修改用户指定或校准后的局部区域。
• 不使用整图 AI 重绘，不重新生成整张图。
• 不改变图片宽高、文件名和未选中区域。
• 先输出到预览目录，确认无误后再覆盖原图。
• 对残留像素做二次修正时，只覆盖残留区域，不扩大影响范围。

适用场景

不适合：需要理解复杂语义、重建大面积背景、补全缺失物体、改变图像风格或生成新画面的任务；这些应使用专门图像编辑工作流，而不是本技能。

工作流

1. 收集目标图片路径和替换要求，明确哪些区域允许修改。
2. 预览图片，定位需要替换的最小矩形区域。矩形坐标使用 [left, top, right, bottom]。
3. 需要写新文字时，记录文字左上角 [x, y]、颜色、字号和字体；尽量匹配原图视觉风格。
4. 创建 JSON 配置，每个局部替换项只描述一个小区域。
5. 先运行脚本输出到预览目录，逐张检查。
6. 如存在残留、遮挡或颜色突兀，微调 cover、background、padding、textxy、fontsize 后重跑。
7. 确认无误后再使用 --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"
    }
  ]
}

字段说明：

运行方式

安装依赖：

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

验收

• 输出图与原图宽高一致。
• 目标局部区域已按要求替换、遮盖或清理。
• 未选中区域视觉上保持不变。
• 文件名保持不变；如果使用输出目录，只改变目录不改变文件名。
• 覆盖区域边缘没有明显突兀色块、残留像素或误遮挡。