Pixel-Preserving Local Image Editing Pipeline
通用局部修图功能 · 技术设计与实现规范(v1.0)
状态:可实现的 MVP 规范 · 最后更新:2026-11-08
1. 目标与适用范围
一句话定义: 在原始图像的像素坐标系内,仅重建明确授权的局部区域(如杂线、物品、污渍、背景缺损),将修复候选图严格裁切合成回原图,并自动证明所有未授权像素未改变。
与“让生成模型重画一张相似图片”不同,本功能中的 AI/修复算法只负责产生候选像素;最终写入权限由确定性的合成程序控制。
适用场景:
- 物体移除、桌面/室内杂物清理、细线或划痕修复;
- 产品摄影中的瑕疵修补;
- 保留人物、商品、文字、Logo、建筑等受保护对象,仅编辑其他区域;
- 多轮局部迭代,要求原始细节不被全图重生成破坏。
MVP 边界: 支持 8-bit、非透明的 RGB 图像;支持用户提供二值保护/编辑蒙版;提供传统 OpenCV Inpainting 和“外部生成候选 ROI”两种模式。SAM2、Diffusers、自动编辑区域提取均是可选扩展,不构成核心保真保证。
不承诺:修复区域能恢复不可见的真实内容;仅凭提示词可以不改人物;AI 生成的局部内容一定自然;没有正确蒙版时能自动判断所有敏感对象。
2. 核心术语与约束
- Canonical Original
I0:按 EXIF 方向统一并解码到 RGB 后的不可变原图像素数组。I0是像素校验基准。 - Protected Mask
P:禁止修改像素,白色 255、黑色 0。可保护人物、文字、商品或任意对象。推荐分割后进行适量膨胀并人工复核边缘。 - Edit Mask
M:允许改变的像素,白色 255、黑色 0。应精确圈出待移除/替换对象及必要修复边界。 - ROI:包含某个编辑区域及其周围上下文的矩形裁剪;ROI 不是授权修改区域。
- Candidate
G:修复算法对 ROI 输出的候选图;未经像素锁定合成前一律不可信。 - Result
O:在I0上仅写入M内候选像素的最终图像。
硬性不变量:
shape(O) == shape(I0);不改变最终宽高、方向、坐标系。P ∩ M = ∅;保护区和编辑区重叠则中止。- 对所有
M(x,y)=0,O(x,y) == I0(x,y)(RGB 三通道逐像素相同)。 - 对所有
P(x,y)=1,O(x,y) == I0(x,y)。 - 不允许静默对
I0、蒙版或 candidate 做 resize / warp 来掩盖尺寸错配。 - 必须无损保存 PNG,并在重新读取后复测像素不变量。
注意:“保护区 0 像素变化”只证明已标记的保护区不变。分割漏掉的头发、手指等仍可能被编辑,故保护蒙版需要单独审查;校验不能代替蒙版质量控制。
3. Mermaid 技术架构
1 | flowchart TD |
关键隔离原则: 修复引擎可阅读带上下文的 ROI,但只通过 Candidate 接口提交候选像素;引擎不能直接写原始画布。
4. 工具与技术选型
| 组件 | 工具/接口 | 职责 | 是否必需 |
|---|---|---|---|
| 图像读取、无损保存 | Pillow、ImageOps.exif_transpose |
统一方向、加载 RGB、导出 PNG | 必需 |
| 像素与蒙版运算 | NumPy |
数组、断言、差异统计 | 必需 |
| 小区域修复与形态学 | opencv-python:cv2.inpaint、cv2.dilate |
Telea/NS 修复、扩张保护区 | 必需 |
| 交互式蒙版标注 | GUI 画笔、多边形工具或自制 Web Canvas | 人工确认允许/禁止修改范围 | 产品必需,代码可读已有蒙版 |
| 自动对象分割 | SAM 2(可选) | 根据点/框生成初始保护蒙版 | 可选;必须人工审查 |
| 生成式修复 | PyTorch + Diffusers Inpainting Pipeline / 其他图像编辑引擎 | 复杂缺损区域生成候选内容 | 可选 |
| 测试 | Python unittest 或 pytest |
自动化不变量与异常测试 | 建议必需 |
常规安装:
1 | python -m pip install numpy pillow opencv-python |
算法分配建议:
| 目标 | 默认策略 | 何时升级 |
|---|---|---|
| 细线、划痕、小灰尘 | cv2.INPAINT_TELEA(初始半径 3 px) |
出现拉丝、重影或结构断裂 |
| 简单背景的轻微缺损 | 比较 INPAINT_TELEA 与 INPAINT_NS |
周围纹理复杂 |
| 大玩具、毛巾、遮挡物 | 外部生成式 Inpainting 输出候选 ROI | 候选不自然则改手工局部修复 |
| 柜门、重复几何、文字等 | 有参考图时局部几何/纹理修复,或生成候选 | 结构真实性不可确认时人工验收 |
不能用算法选择代替掩码权限控制。 无论采用哪一种 Inpainting,都必须经历同一套受控合成与检验。
5. 标准流水线(从输入到交付)
Step 0:任务与授权
输入:原始图片、期望修改的对象/区域、必须保留的对象/区域。每个编辑请求应明确目标(例如“移除桌下 3 根垂线”),并保存对应编辑蒙版。
默认只允许小范围修复;若编辑面积超出阈值则终止或要求显式提高阈值。不要把“简化背景”自动扩展为重做整间房间。
Step 1:规范化并锁定原图
- 读取原始图像,统一 EXIF 方向。
- 明确像素格式;MVP 只接受 RGB 或完全不透明的 RGBA;不支持时立即报错。
- 将解码后的 RGB
I0保存为只读语义的内存数组,记录width、height、原文件哈希。 - 全部后续流程在这一像素坐标系内进行。
禁止: 全图超分、全图锐化、自动色彩增强、全图透视变换、反复 JPEG 保存、从上一轮 AI 渲染图替代原图。
Step 2:构造并验证两类蒙版
- 保护蒙版
P:手工画、分割模型输出、或两者结合;必须覆盖对象的真实边缘。 - 必要时膨胀
P,比如椭圆核25×25(参数非通用常数,需视分辨率调整)。 - 编辑蒙版
M:尽可能贴合需要修复的像素;可以包含目标周围少量过渡区域。 - 两张蒙版均必须与
I0同尺寸,单通道且只含 0 / 255。 - 若
P∩M非空、M为空、目标面积异常,立即失败,不自动删除重叠以“凑成功”。
UI 建议:保护区显示红色、编辑区显示蓝色;可缩放查看边界;发布前显示“允许修改面积占比”和重叠数量。
Step 3:提取 ROI
- 取编辑蒙版非零区域的外接矩形,按需要外扩 Context Padding(可先从 32–64 px 测试)。
- ROI 可包含未授权像素供模型参考,绝不意味着整块 ROI 可以回写。
- 对相距很远的多个区域,分别裁剪、分别处理、分别验收,避免生成大图。
Step 4:生成候选修复图
- 传统修复:
cv2.inpaint(roi, roi_mask, radius, cv2.INPAINT_TELEA)。 - 生成式修复:向支持 Inpainting 的模型传入 ROI 和它自己的编辑蒙版。如果模型接口中白/黑含义不同,要显式转换。
- 模型输出允许内容变化,但必须被标记为候选,不可直接作为最终图像。
- 禁止静默 resize 候选图;需要模型尺寸适配时,可先在工作副本上 padding / tiling,并按可验证的坐标变换撤销;无法可靠恢复坐标则拒绝候选。
Step 5:精确合成
1 | O(x, y) = G(x, y) 当 M(x, y) = 1 |
- 只把候选 ROI 中
M=1的像素写回原始I0。 - 模糊融合(feathering)如有必要,只可影响已授权像素,不能突破
M边界。 - 对
P范围再做一次原始像素覆盖作为防御性措施。 - 多轮编辑以
I0 + 已审核的补丁集合来重建结果,不能把上一轮生成图作为新事实底图。
Step 6:程序化验收
- 输出 RGB 像素阵列与
I0的宽、高完全一致; P范围内三通道变化像素数 = 0;M范围外三通道变化像素数 = 0;- 生成候选与 ROI shape 一致;
- PNG 落盘后重新读取,验证解码像素与内存结果完全一致。
Step 7:视觉验收
放大检查:修补边缘是否有接缝、阴影是否合理、线条是否断裂、纹理是否重复;对含有文字、规则几何形体的背景必须加强人工审核。无真值参考图时,不用 SSIM/PSNR 判定“修复正确”。
6. 参考实现:local_edit.py
下面这份脚本实现保真内核,而非完整 GUI。两张蒙版由编辑器或分割模块提前产出;candidate 模式通过任意外部 AI 引擎产出一张与导出的 ROI 同尺寸的候选 PNG。核心脚本绝不直接调用全图生成。
1 | #!/usr/bin/env python3 |
运行示例:
1 | # 传统 OpenCV 修复:自动导出 input_roi.png 和 input_roi_mask.png |
代码约定: OpenCV 默认把颜色数组视为 BGR,但 cv2.inpaint 在这里对 RGB 各通道独立处理,不涉及颜色空间转换;若后续增加 cv2.cvtColor、颜色匹配、图像编码等操作,必须显式说明 RGB/BGR 约定。
7. 量化质量门槛
| 指标 | MVP 目标 | 如何检验 | 性质 |
|---|---|---|---|
| 输出尺寸一致 | 100% | result.shape == original.shape |
硬性 |
| 保护区变化像素数 | 0 | count_nonzero(changed & P) |
硬性 |
| 授权区外变化像素数 | 0 | count_nonzero(changed & ~M) |
硬性 |
| 候选 ROI shape 匹配 | 100% | candidate.shape == roi.shape |
硬性 |
| PNG 重新解码像素差异 | 0 | np.array_equal(decoded, result) |
硬性 |
| 默认授权像素占比 | ≤ 5% | mean(M);可配置 |
任务策略 |
| 保护区和编辑区交集 | 0 像素 | count_nonzero(P & M) |
硬性 |
| 残留目标物/接缝/重影 | 无明显问题 | 200%–400% 局部放大、人工审核 | 视觉验收 |
自动化测试最低集合
- 正常流程:合成 128×128 RGB 图,画一条细线;只给线绘制编辑蒙版,运行后校验所有授权外像素不变。
- 保护区覆盖:故意让候选图把所有 ROI 改成红色,确认程序仍只写入
M内像素;P区不变。 - 蒙版重叠:
P∩M非空时必须抛错,无结果图。 - 尺寸错误:编辑蒙版尺寸错误、候选尺寸错误都必须拒绝。
- 格式错误:灰度值不是 0/255、透明/高位深输入或不支持的色彩模式必须显式拒绝。
- 面积异常:超过
max_edit_ratio必须拒绝。 - 文件回读:PNG 落盘后逐像素比较,差异 0。
- 负面验证:未被保护蒙版覆盖的对象边缘可能变化;应通过人工蒙版审查发现,不能伪称算法自动证明所有语义对象完整。
8. 严格禁止事项与替代操作
| 禁止 | 必须改用 |
|---|---|
全图 img2img 生成,然后仅凭肉眼声称人物不变 |
局部 ROI 产生候选 + 蒙版精确写回 + 像素断言 |
| 只在 prompt 中写“不要改脸” | 保护蒙版(含发丝/手指/边缘)+ 程序控制写入权限 |
| 让修复引擎直接覆盖原图文件 | 原图只读,候选单独保存,合成器生成新输出 |
对原图或最终输出整张 resize/warpPerspective |
原图坐标不变,仅在工作 ROI 上处理 |
| 把整块 ROI 当成可编辑范围 | 只有 M=255 的像素允许写入 |
| 边缘融合越过编辑蒙版 | 只在蒙版内部设计融合权重 |
| 将前一轮 AI 图当作高保真原始素材 | 以 I0 为锚点,保留已批准的局部补丁层 |
| 以 JPEG 多次保存作为母版 | PNG 无损中间文件与最终交付 |
| 蒙版错位后自动放缩对齐 | 终止并重做同坐标系的蒙版 |
| 仅用 SSIM/PSNR 认定修补真实、自然 | 像素不变量检测 + 人工纹理/结构质量评审 |
9. 功能接口与可维护架构
建议拆成以下接口,便于将来接入 Web App、CLI、Agent 或 MCP Tool:
1 | read_original(file) -> CanonicalImage |
推荐产物目录:
1 | local-edit-job/ |
多次迭代设计: 维护不可变 I0 和已批准补丁列表 patches[],每个补丁含 mask、roi bounds、candidate、engine、approval、QA。新版本从 I0 按顺序重放已批准补丁。若补丁之间区域重叠,必须显式规定顺序并重新验证与原图相比的授权并集,不得静默覆盖。
10. 错误策略与上线验收
- Fail closed:空蒙版、交叠、候选尺寸不符、非法文件模式、超面积阈值、像素断言失败,均直接失败;保留诊断信息,不输出“成功”状态。
- Human-in-the-loop:保护对象轮廓和复杂物体修复必须能让用户审查,尤其是衣服/头发、文字/Logo、规则几何边界。
- 可观测性:保存输入 SHA256、ROI 坐标、引擎名称与参数、授权面积、实际修改像素数、像素校验结果、修复版本;注意人物图像和 Mask 不应默认上传到不受控第三方服务。
- 性能:仅处理小 ROI,不强行要求所有编辑都调用生成模型;可以针对编辑区域大小建立耗时、成本、人工退回率等数据指标。
- 上线门槛:所有硬性不变量自动测试 100% 通过;至少覆盖细线、小物体、复杂纹理、复杂保护轮廓四类样例,并保留人工审核记录。
11. 最小交付定义(Definition of Done)
一个局部修图任务只有满足以下全部条件才算完成:
- 已保存不可变原始图像与输入 SHA256;
- 已确认保护蒙版与编辑蒙版,且两者无重叠;
- 修复算法只在 ROI 上生成候选;
- 合成程序只将候选中授权像素写回原始像素网格;
- 输出尺寸和原图一致;
- 保护区域变化像素数 = 0;
- 授权区域外变化像素数 = 0;
- PNG 无损回读验证通过;
- 修复边缘、几何、纹理已通过视觉检查;
- 附带编辑蒙版与 QA JSON,可审计、可回滚。
最终工程原则:生成模型负责“提出修复内容”,确定性程序负责“控制权限、合成结果、验证正确性”。