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 内候选像素的最终图像。

硬性不变量:

  1. shape(O) == shape(I0);不改变最终宽高、方向、坐标系。
  2. P ∩ M = ∅;保护区和编辑区重叠则中止。
  3. 对所有 M(x,y)=0,O(x,y) == I0(x,y)(RGB 三通道逐像素相同)。
  4. 对所有 P(x,y)=1,O(x,y) == I0(x,y)。
  5. 不允许静默对 I0、蒙版或 candidate 做 resize / warp 来掩盖尺寸错配。
  6. 必须无损保存 PNG,并在重新读取后复测像素不变量。

注意:“保护区 0 像素变化”只证明已标记的保护区不变。分割漏掉的头发、手指等仍可能被编辑,故保护蒙版需要单独审查;校验不能代替蒙版质量控制。

3. Mermaid 技术架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
flowchart TD
A[原始文件 Original] --> B[EXIF 方向标准化 / 解码 RGB]
B --> I0[(不可变原始像素 I0)]
U[用户修图意图] --> C[标注编辑区域 Edit Mask M]
U --> D[标注保护对象 Protected Mask P]
D --> E[人工复核轮廓 + 保护区膨胀]
C --> F{蒙版验证}
E --> F
F -->|交叠 / 越界 / 空掩码| X[失败并要求修正]
F -->|通过| R[计算 ROI + Context Padding]
I0 --> R
R --> S{选择修复策略}
S -->|细线 / 划痕 / 简单纹理| T[OpenCV Telea / NS]
S -->|大物体 / 复杂结构| G[生成式 Inpainting / 外部候选]
T --> K[候选 ROI G]
G --> K
K --> V{候选尺寸 / 格式验证}
V -->|不符| X
V -->|通过| W[基于 I0 仅写入 M 内像素]
I0 --> W
W --> Q[像素不变量校验]
Q -->|未通过| X
Q -->|通过| Z[无损 PNG 保存]
Z --> J[重新解码 / 二次像素校验]
J -->|通过| Y[结果图 + Mask + QA JSON]
J -->|失败| X

关键隔离原则: 修复引擎可阅读带上下文的 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:规范化并锁定原图

  1. 读取原始图像,统一 EXIF 方向。
  2. 明确像素格式;MVP 只接受 RGB 或完全不透明的 RGBA;不支持时立即报错。
  3. 将解码后的 RGB I0 保存为只读语义的内存数组,记录 width、height、原文件哈希。
  4. 全部后续流程在这一像素坐标系内进行。

禁止: 全图超分、全图锐化、自动色彩增强、全图透视变换、反复 JPEG 保存、从上一轮 AI 渲染图替代原图。

Step 2:构造并验证两类蒙版

  1. 保护蒙版 P:手工画、分割模型输出、或两者结合;必须覆盖对象的真实边缘。
  2. 必要时膨胀 P,比如椭圆核 25×25(参数非通用常数,需视分辨率调整)。
  3. 编辑蒙版 M:尽可能贴合需要修复的像素;可以包含目标周围少量过渡区域。
  4. 两张蒙版均必须与 I0 同尺寸,单通道且只含 0 / 255。
  5. 若 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
2
O(x, y) = G(x, y)  当 M(x, y) = 1
O(x, y) = I0(x, y) 当 M(x, y) = 0
  • 只把候选 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
#!/usr/bin/env python3
"""Pixel-locked local editing on opaque RGB images."""
import argparse
import hashlib
import json
from pathlib import Path

import cv2
import numpy as np
from PIL import Image, ImageOps


def sha256_file(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as fh:
for chunk in iter(lambda: fh.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()


def read_rgb(path: Path):
with Image.open(path) as opened:
# Canonical orientation is set once for the original image.
im = ImageOps.exif_transpose(opened)
if im.mode == "RGB":
pass
elif im.mode == "RGBA" and im.getchannel("A").getextrema() == (255, 255):
im = im.convert("RGB")
else:
raise ValueError(f"Unsupported image mode {im.mode}; expected opaque RGB")
icc = im.info.get("icc_profile")
return np.asarray(im, dtype=np.uint8).copy(), icc


def read_mask(path: Path, expected_hw):
with Image.open(path) as im:
if im.mode != "L":
raise ValueError(f"{path}: expected grayscale L mode")
data = np.asarray(im, dtype=np.uint8).copy()
if data.shape != expected_hw:
raise ValueError(f"{path}: expected {expected_hw}, got {data.shape}")
if not np.all((data == 0) | (data == 255)):
raise ValueError(f"{path}: mask must contain only 0 and 255")
return data == 255


def roi_bounds(mask, pad):
ys, xs = np.nonzero(mask)
if xs.size == 0:
raise ValueError("Empty edit mask")
h, w = mask.shape
return (max(0, int(xs.min()) - pad),
max(0, int(ys.min()) - pad),
min(w, int(xs.max()) + pad + 1),
min(h, int(ys.max()) + pad + 1))


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--original", type=Path, required=True)
parser.add_argument("--protect-mask", type=Path, required=True)
parser.add_argument("--edit-mask", type=Path, required=True)
parser.add_argument("--output", type=Path, default=Path("result.png"))
parser.add_argument("--mode", choices=["opencv", "candidate"], default="opencv")
parser.add_argument("--candidate", type=Path, help="Generated RGB ROI PNG in candidate mode")
parser.add_argument("--algorithm", choices=["telea", "ns"], default="telea")
parser.add_argument("--radius", type=float, default=3.0)
parser.add_argument("--padding", type=int, default=48)
parser.add_argument("--protect-dilate", type=int, default=25)
parser.add_argument("--max-edit-ratio", type=float, default=0.05)
args = parser.parse_args()

if args.padding < 0 or args.radius <= 0:
parser.error("padding must be >= 0 and radius must be > 0")
if args.protect_dilate < 1 or args.protect_dilate % 2 == 0:
parser.error("protect-dilate must be an odd positive integer")
if not 0 < args.max_edit_ratio <= 1:
parser.error("max-edit-ratio must be in (0, 1]")

original, icc = read_rgb(args.original)
h, w = original.shape[:2]
P = read_mask(args.protect_mask, (h, w)).astype(np.uint8)
M = read_mask(args.edit_mask, (h, w))
kernel = cv2.getStructuringElement(
cv2.MORPH_ELLIPSE, (args.protect_dilate, args.protect_dilate))
P = cv2.dilate(P, kernel).astype(bool)

if np.any(P & M):
raise ValueError("Protected and editable masks overlap: FAIL CLOSED")
if not np.any(M):
raise ValueError("Empty edit mask")
if float(M.mean()) > args.max_edit_ratio:
raise ValueError("Editable area exceeds configured limit")

x0, y0, x1, y1 = roi_bounds(M, args.padding)
roi = original[y0:y1, x0:x1].copy()
roi_mask = M[y0:y1, x0:x1].astype(np.uint8) * 255
args.output.parent.mkdir(parents=True, exist_ok=True)
Image.fromarray(roi).save(args.output.parent / "input_roi.png")
Image.fromarray(roi_mask).save(args.output.parent / "input_roi_mask.png")

if args.mode == "opencv":
flag = cv2.INPAINT_TELEA if args.algorithm == "telea" else cv2.INPAINT_NS
candidate = cv2.inpaint(roi, roi_mask, args.radius, flag)
else:
if args.candidate is None:
raise ValueError("--candidate required in candidate mode")
candidate, _ = read_rgb(args.candidate)
if candidate.shape != roi.shape:
raise ValueError("Candidate ROI shape mismatch: resizing is forbidden")

# Pixel-locked composition: only explicit edit-mask pixels are writable.
result = original.copy()
target = result[y0:y1, x0:x1]
target[roi_mask != 0] = candidate[roi_mask != 0]
result[P] = original[P]

changed = np.any(result != original, axis=2)
protected_changes = int(np.count_nonzero(changed & P))
unauthorized_changes = int(np.count_nonzero(changed & ~M))
assert result.shape == original.shape
assert protected_changes == 0
assert unauthorized_changes == 0

# Save losslessly; retain ICC profile when present.
kwargs = {"icc_profile": icc} if icc else {}
Image.fromarray(result, mode="RGB").save(args.output, format="PNG", **kwargs)
with Image.open(args.output) as saved:
decoded = np.asarray(saved.convert("RGB"), dtype=np.uint8)
assert np.array_equal(decoded, result), "PNG round-trip mismatch"

report = {
"status": "PASS",
"original_sha256": sha256_file(args.original),
"width": w, "height": h,
"roi_xyxy": [x0, y0, x1, y1],
"protected_pixels": int(P.sum()),
"editable_pixels": int(M.sum()),
"actually_changed_pixels": int(changed.sum()),
"protected_changed_pixels": protected_changes,
"unauthorized_changed_pixels": unauthorized_changes,
"png_roundtrip_equal": True,
"mode": args.mode,
}
report_path = args.output.with_suffix(".qa.json")
report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
print(json.dumps(report, ensure_ascii=False, indent=2))


if __name__ == "__main__":
main()

运行示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 传统 OpenCV 修复:自动导出 input_roi.png 和 input_roi_mask.png
python local_edit.py \
--original original.jpg \
--protect-mask protect_mask.png \
--edit-mask edit_mask.png \
--mode opencv \
--algorithm telea \
--radius 3 \
--output output/result.png

# 生成式分支:先用任意模型对导出的 input_roi.png 修复,
# 生成与 ROI 同尺寸的 candidate_roi.png,再作为候选提交
python local_edit.py \
--original original.jpg \
--protect-mask protect_mask.png \
--edit-mask edit_mask.png \
--mode candidate \
--candidate candidate_roi.png \
--output output/result.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% 局部放大、人工审核 视觉验收

自动化测试最低集合

  1. 正常流程:合成 128×128 RGB 图,画一条细线;只给线绘制编辑蒙版,运行后校验所有授权外像素不变。
  2. 保护区覆盖:故意让候选图把所有 ROI 改成红色,确认程序仍只写入 M 内像素;P 区不变。
  3. 蒙版重叠:P∩M 非空时必须抛错,无结果图。
  4. 尺寸错误:编辑蒙版尺寸错误、候选尺寸错误都必须拒绝。
  5. 格式错误:灰度值不是 0/255、透明/高位深输入或不支持的色彩模式必须显式拒绝。
  6. 面积异常:超过 max_edit_ratio 必须拒绝。
  7. 文件回读:PNG 落盘后逐像素比较,差异 0。
  8. 负面验证:未被保护蒙版覆盖的对象边缘可能变化;应通过人工蒙版审查发现,不能伪称算法自动证明所有语义对象完整。

8. 严格禁止事项与替代操作

禁止 必须改用
全图 img2img 生成,然后仅凭肉眼声称人物不变 局部 ROI 产生候选 + 蒙版精确写回 + 像素断言
只在 prompt 中写“不要改脸” 保护蒙版(含发丝/手指/边缘)+ 程序控制写入权限
让修复引擎直接覆盖原图文件 原图只读,候选单独保存,合成器生成新输出
对原图或最终输出整张 resize/warpPerspective 原图坐标不变,仅在工作 ROI 上处理
把整块 ROI 当成可编辑范围 只有 M=255 的像素允许写入
边缘融合越过编辑蒙版 只在蒙版内部设计融合权重
将前一轮 AI 图当作高保真原始素材 以 I0 为锚点,保留已批准的局部补丁层
以 JPEG 多次保存作为母版 PNG 无损中间文件与最终交付
蒙版错位后自动放缩对齐 终止并重做同坐标系的蒙版
仅用 SSIM/PSNR 认定修补真实、自然 像素不变量检测 + 人工纹理/结构质量评审

9. 功能接口与可维护架构

建议拆成以下接口,便于将来接入 Web App、CLI、Agent 或 MCP Tool:

1
2
3
4
5
6
7
8
9
read_original(file) -> CanonicalImage
create_or_load_masks(image, protect, edit) -> Masks
validate_masks(image, masks, policy) -> ValidationResult
extract_roi(image, edit_mask, padding) -> ROI
propose_patch(roi, roi_mask, engine) -> CandidateROI
validate_candidate(candidate, roi) -> ValidationResult
compose_locked(original, candidate, roi_bounds, edit_mask) -> Image
verify_pixels(original, output, protect_mask, edit_mask) -> QAReport
export_png_and_report(output, metadata, qa) -> Artifacts

推荐产物目录:

1
2
3
4
5
6
7
8
9
10
local-edit-job/
├── original.jpg # 原始文件,不可改写
├── protect_mask.png # 人工确认的保护区
├── edit_mask.png # 人工确认的授权区
├── input_roi.png # 从原图导出的上下文区域
├── input_roi_mask.png # ROI 局部编辑蒙版
├── candidate_roi.png # 可选:生成式算法产出的候选
└── output/
├── result.png # 无损修复图
└── result.qa.json # 可追溯验收记录

多次迭代设计: 维护不可变 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,可审计、可回滚。

最终工程原则:生成模型负责“提出修复内容”,确定性程序负责“控制权限、合成结果、验证正确性”。