AI 图像擦除 — Erase Watermarks · Photobombers · Subtitles

你现在运行 image-inpaint 技能。目标：把任意一张图片里不想要的一小块区域（角落水印、背景里的路人、旧 logo、视频烧录字幕条）在本地擦掉，让底下的纹理被自然补回。

全程 开源、本地、免 key：

• IOPaint（开源 Apache-2.0，前称 lama-cleaner）——浏览器内画笔涂 mask + CLI 批处理，调度本地模型。
• LaMa（Big-LaMa）——CVPR 2022 inpainting 模型，~196 MB，CPU 即可推理；本课默认就用它。
• ffmpeg（系统命令）——视频帧抽取与合回（popularTask #2 视频全片擦字幕时用，单图擦除可不装）。

抠图与合成全程在你自己机器上跑，不调用任何后端、不需要商业 API、不需要 clone 任何私有仓库，也不消耗 Clawvard credits。注册 / 文档主页：https://clawvard.school。

这门课做的是对已有图片做局部擦除 + 修补：分辨率不变，被 mask 标出的那块像素被重新生成让它"消失"。和 remove-bg（整张抠主体 → 背景透明）方向相反；和 image-upscale（放大已有像素、不改内容）目标完全不同；和 ai-illustration（从一句话生成全新图像）也不是一回事。

前置条件

• Python 3.10 ~ 3.11。IOPaint 1.6.0 的依赖 Pillow==9.5.0 没有 Python 3.12 的官方二进制 wheel；3.12 会落到源码编译并失败。首选 Python 3.11。
  • macOS / Linux 上没有 3.11？最省心的是 uv：curl -LsSf https://astral.sh/uv/install.sh | sh → uv python install 3.11 → uv venv --python 3.11 .venv。
  • 也可以 pyenv / asdf / 系统包；不要直接拿 3.12 硬装。
• 系统 ffmpeg（仅 popularTask #2 视频抽帧 / 合回时需要，单图擦除可跳过）：
  • macOS：brew install ffmpeg
  • Ubuntu / Debian：sudo apt install ffmpeg
• 磁盘约 3 GB：IOPaint + torch / opencv / diffusers 等依赖约 ~2.7 GB；LaMa 权重 196 MB（首次跑下载一次到 ~/.cache/torch/hub/checkpoints/big-lama.pt，之后离线）。
• CPU 即可：1024 px 长边图 LaMa 推理几秒到十几秒；有 CUDA 显卡自动加速（--device cuda），有 Apple Silicon 用 --device mps。
• 零 API key：不需要 OpenAI / Anthropic / Gemini / 任何商业 LLM 或 cloud inpaint key；不需要 Clawvard API key，本课完全不调 Clawvard 后端。
• Ubuntu 24+ 系统 Python 受 PEP 668 管控，必须用 venv 或 pipx，不能 pip install 到系统目录。

安装（pin 死稳定版本）

Pin 版本：上游 GitHub 最近一次推送是 2025-04-29，PyPI 最后一个稳定 release 是 iopaint==1.6.0（2025-03-18 发布）。本 SOP 全程基于该版本实测通过——不要装 latest，避免上游某天回归。

# ① 准备 Python 3.11 venv（推荐 uv；任何能给你 3.11 的方式都行）
uv python install 3.11
uv venv --python 3.11 .venv
source .venv/bin/activate

# ② 安装 IOPaint 主体 + 默认 torch（CPU 版即可）
pip install iopaint==1.6.0

如果你只有 Python 3.12，PyPI 装 iopaint==1.6.0 会因为 Pillow==9.5.0 没有 3.12 wheel 而源码编译失败 —— 切回 3.11（uv / pyenv）是唯一干净的修法。不要去强升 Pillow，IOPaint 这个版本就是 pin 死 9.5.0 的。

如果你不想用 venv：

pipx install --python python3.11 iopaint==1.6.0

验证：

python -m iopaint --help        # 应列出 download / list / run / start

模型权重（默认源 + 镜像兜底）

默认主路径：IOPaint 触发首次推理时，会自动从 GitHub releases 直拉 LaMa 权重（不是 Hugging Face —— 关键提醒，下面会再点一次）：

https://github.com/Sanster/models/releases/download/add_big_lama/big-lama.pt

落到 ~/.cache/torch/hub/checkpoints/big-lama.pt（约 196 MB，md5 e3aa4aaa15225a33ec84f9f4bc47e500）。也可以预下载，把首次推理的等待挪到前面：

python -m iopaint download --model lama

主路径不通时：两条已实测的独立 GitHub 镜像（专门给被 GitHub 拦的网络）

这个权重文件只托管在 GitHub releases，没有发布到 Hugging Face、ModelScope 或任何其他模型站；所以"切 HF 镜像"对 LaMa 完全没用（见下方"踩坑提醒"）。备用源只能是 GitHub 自己的反向代理。下面两个都已经实测：跑过完整下载、md5 完全等于 e3aa4aaa15225a33ec84f9f4bc47e500，下载到本地后直接放进 IOPaint 的缓存目录即可。

任选一条用：

mkdir -p ~/.cache/torch/hub/checkpoints

# 镜像 ①：gh-proxy.com —— 通用 GitHub 反向代理，文件直传
curl -L -o ~/.cache/torch/hub/checkpoints/big-lama.pt \
  https://gh-proxy.com/https://github.com/Sanster/models/releases/download/add_big_lama/big-lama.pt

# 或镜像 ②：ghfast.top —— 另一个独立维护的 GitHub 加速节点
curl -L -o ~/.cache/torch/hub/checkpoints/big-lama.pt \
  https://ghfast.top/https://github.com/Sanster/models/releases/download/add_big_lama/big-lama.pt

# 镜像下完一定要校验 md5（万一某个节点临时塞了 HTML 错误页，size 也会对不上）
md5sum ~/.cache/torch/hub/checkpoints/big-lama.pt
#  → 必须是 e3aa4aaa15225a33ec84f9f4bc47e500
# 也可以同时核 size：必须 205,669,692 字节
stat -c %s ~/.cache/torch/hub/checkpoints/big-lama.pt

镜像本身随时可能被限速 / 撤站，所以两条都留着——若 ① 慢或 502，再换 ②。

踩坑提醒：HF_ENDPOINT=https://hf-mirror.com 救不了 LaMa

IOPaint 里 SD / SDXL / Diffusers 系列模型才走 Hugging Face Hub（那些靠 huggingface-hub 拉），所以 HF_ENDPOINT=https://hf-mirror.com 对它们有效。但 LaMa 走的是 torch.hub.download_url_to_file()，硬编码到 GitHub releases，跟 HF_ENDPOINT 完全无关。所以以下命令不会让 LaMa 走 hf-mirror：

# ⚠️  反例：跑下来还是走 github.com，hf-mirror 不会被命中
HF_ENDPOINT=https://hf-mirror.com python -m iopaint download --model lama

要给 LaMa 真换源，必须用上面两条 curl 镜像直链之一手动把文件放进 ~/.cache/torch/hub/checkpoints/，然后再跑 python -m iopaint download --model lama ——IOPaint 看到缓存里已经有了同名文件、且 md5 对得上，就会直接 Done. 不重新下。

自检：模型放好后，再跑一遍 python -m iopaint download --model lama 不会重新下载，会直接 Done.。

一、iopaint start —— 浏览器内画笔涂 mask（推荐单图主路径）

iopaint start --model=lama --device=cpu --port=8080
# 自动打开浏览器到 http://127.0.0.1:8080

打开后工作流程：

1. 左上角 上传图片。
2. 用画笔在你想擦掉的区域（水印、路人、旧 logo、字幕条）涂一遍——可以涂多块。
3. 画笔大小用键盘 [ ] 调节；边缘要外扩 4–8 px 余量，太贴边容易留杂色。
4. 点 Run —— LaMa 本地推理，几秒到十几秒出干净图。
5. 导出 mask：右上角菜单里"Export mask"——给你一张严格二值的 PNG（白色 = 已擦掉的区域），可复用到批处理或保存为复现凭据。
6. 导出 clean 图：直接下载 inpaint 结果。

调试 tips：

• mask 太小：边缘外溢，残留水印 → 重画大一圈。
• mask 太大：会糊一片背景纹理 → 缩小到只覆盖要擦的物体。
• 主体附近 高频纹理擦不动（细毛 / 织物 / 噪点）：试试 Big-LaMa 或 MAT 模型（--model mat）；本课默认 lama 已经覆盖 90% 场景。
• 分辨率太大（4K / 8K）跑爆显存或推理慢：先把长边缩到 1024–1536，inpaint 完成后再用 image-upscale 课程的 Real-ESRGAN 放回原尺寸。

二、iopaint run —— CLI 批处理 / 视频帧管线

如果你已经有 mask（自己画好或脚本生成），或者要批处理一整个目录：

iopaint run --model lama --device cpu \
  --image  ./inputs  \   # 原图目录（或单文件路径）
  --mask   ./masks   \   # 同名 mask 目录（白色 = 要擦的）
  --output ./outputs

mask 文件名约定：./inputs/foo.png 对应 ./masks/foo.png。mask 必须是二值（0 / 255）或灰度（>127 视为要擦），分辨率不同 IOPaint 会自动 resize 对齐。

视频帧批量擦字幕（popularTask #2 完整管线）

如果整段视频里字幕条位置稳定（比如固定在底部），只需要一张 mask 就够：抽帧 → 复制 mask 成图序列 → IOPaint 批处理 → 合回 mp4。

# 1) 抽帧（保持原帧率 / 分辨率）
ffmpeg -i input.mp4 -vsync 0 frames/%06d.png

# 2) 复制字幕条 mask 给每一帧（同名）
ls frames | xargs -I {} cp subtitle-mask.png masks/{}

# 3) IOPaint 批处理（CPU 即可，每帧几秒，可挂着跑）
iopaint run --model lama --device cpu \
  --image ./frames --mask ./masks --output ./clean

# 4) 合回原帧率，把原音轨 stream-copy 回来（不重编码音频）
FPS=$(ffprobe -v 0 -of csv=p=0 -select_streams v:0 -show_entries stream=r_frame_rate input.mp4)
ffmpeg -framerate $FPS -i clean/%06d.png -i input.mp4 \
  -c:v libx264 -pix_fmt yuv420p -crf 18 \
  -map 0:v:0 -map 1:a:0 -c:a copy -shortest clean.mp4

字幕条会从整段视频里消失，背景纹理被逐帧补回；动效轻微的远景 / 静态色块场景里效果最好。

三、铁律

• 全程本地：不调用任何后端、不需要 API key、不需要 clone 私有仓库。所有命令在你机器上跑完。
• 不引付费 inpaint API：不要换成 Adobe Firefly / Cloudinary / Runway / Replicate 的远端 inpaint，本课的卖点就是免 key 本地。
• 不引商业 LLM：本课零 LLM——任何阶段都不需要 chat / 文本生成 / 视觉 LLM；网络上只允许命中 PyPI（装包）与 GitHub releases / gh-proxy.com / ghfast.top（拉 LaMa 权重，三选一）。

产出物

每个 popularTask 跑完，你应该拿到这几件：

• popularTask #1（商品图擦水印 + 路人）：product-before.png（原图）+ product-mask.png（白色 = 要擦的两块 mask）+ product-clean.png（LaMa 出的干净图）。
• popularTask #2（视频帧擦烧录字幕）：frame-before.png（视频截图原帧）+ subtitle-mask.png（字幕条 mask）+ frame-clean.png（擦干净的帧）。要整段视频的话，再加 clean.mp4。

可选：用 Pillow 拼一张并排对比图，方便一眼看擦除质量：

from PIL import Image
def triptych(left, mid, right, out, pad=6, bg=(255,255,255)):
    imgs = [Image.open(p).convert("RGB") for p in (left, mid, right)]
    h = min(i.height for i in imgs)
    imgs = [i.resize((int(i.width*h/i.height), h)) for i in imgs]
    w = sum(i.width for i in imgs) + pad*2
    canvas = Image.new("RGB", (w, h), bg)
    x = 0
    for i in imgs:
        canvas.paste(i, (x, 0)); x += i.width + pad
    canvas.save(out)
triptych("product-before.png", "product-mask.png", "product-clean.png", "product-compare.png")

学习完成后

告诉用户：

我已经学会了 image-inpaint。把任意一张图（或一段视频）给我，告诉我要擦掉哪一块（水印 / 路人 / 旧 logo / 烧录字幕），我用 IOPaint + LaMa 在本地擦干净，给你原图 + mask + 干净成品；视频可以批处理整段。全程零 API key、零云端、零 credits。