本地图像工具

一句话定位：不看任何付费 API、不上传任何素材，在你自己的电脑上把图片处理好——去水印、去背景、超分放大、压缩、转格式，五件事一个入口；有 NVIDIA 显卡自动走 GPU 加速。

核心原则（四条铁律）

免费，零成本。 全程本地处理，不调用任何付费 API、不需要 Token、没有次数限制。任何让用户付费、充值、买次数的说法都违背本技能定位，一律禁止。
本地处理，不上传。 用户的素材只在本地加工，绝不要求用户上传到第三方网站或在线工具。用户强调「不想上传网页」时直接使用本技能。
不编造结果。 处理完必然交给用户成品文件路径，不做「假装处理成功」。效果有限时如实告知（如水印面积过大、背景与主体颜色过于接近）。走降级方案一定明说，不把传统插值放大说成 AI 超分。
只处理授权素材。 仅用于用户自有版权或已获授权的图片/视频，处理他人版权素材前提醒用户自行确认授权。

首次使用须知（只影响第一次，之后完全离线）

本工具不把 AI 模型塞进技能包（否则安装包会有几百 MB）。各功能第一次使用时会自动联网取一次引擎/模型，此后缓存在本机、长期离线可用。

| 功能 | 首次需要下载 | 体积 | 大概耗时 | 下不来怎么办 | |------|--------------|------|----------|--------------| | 去水印 · 图片（AI 修复） | LaMa 模型权重 | 约 200 MB | 视网速 10 秒~几分钟 | 自动多源轮换 + 分片并发 + 断点续传；仍失败会打印手动下载链接与放置目录（见下方「模型拿不到怎么办」）。也可加 --engine opencv 用传统修复，零下载，质量略逊 | | 去水印 · SAM 自动定位（--sam，可选） | SAM vit-b 权重 | 约 375 MB | 视网速 1~5 分钟 | 同上；不用 --sam 则完全不下载 | | 去水印 · 扩散修复档（--engine powerpaint，可选） | PowerPaint + SD1.5 权重 | 约 4.0 GB | 视网速 10~30 分钟 | 同上；不用该引擎则完全不下载；推荐 6GB+ 显存显卡使用 | | 去水印 · 视频 | FFmpeg 便携版（本机已有 ffmpeg 则零下载） | 约 80~170 MB | 1~3 分钟 | 自行安装 ffmpeg 并加入 PATH（Windows 可 winget install Gyan.FFmpeg） | | 去背景 | BiRefNet 模型 | 约 214 MB | 视网速 10 秒~几分钟 | 见下方「模型拿不到怎么办」 | | 超分放大 | Real-ESRGAN 权重 | 约 64 MB | 视网速数秒~1 分钟 | 见下方「模型拿不到怎么办」 | | 压缩 / 转格式 | 无需下载 | — | 立即 | — |

GPU 加速（自动，无需配置）

检测到 NVIDIA 显卡时：去水印（LaMa）、超分自动走 CUDA；去背景自动走 DirectML；首次使用若 torch 是 CPU 版会提示升级为 CUDA 版（用分片下载器拉取，约 3GB）。没有显卡时一切功能照常可用（CPU 兜底），抠图单张约 6~8 秒、超分约 1 分钟，有显卡分别约 3 秒和 16 秒（4060 Ti 实测）。

下载失败只影响那一项功能，其余功能照常可用。 不需要为了用压缩/转格式去下载任何东西。

模型拿不到怎么办

「拿不到模型」不是一个可以拿来做取舍的理由，而是要当场解决掉的问题——工具到不了手上，功能就没有意义。所以取模型这件事做了四层：

多源轮换：每个模型配 4 个下载源（原始源 + 3 个国内可达镜像），一个不通立刻换下一个。
分片并发 + 断点续传：大文件切成许多小片、多线程同时拉，实测比单线程快一个量级（200 MB 级模型从"十几分钟"降到"十几秒"）。片数故意多于线程数，某片中途断了，空闲线程立刻接手补上；已下好的片不会重来，文件越大越不容易被一两次断流卡死。
完整性校验：下完自动核对字节数与 md5——残缺文件绝不会被当成可用模型去跑。
手动兜底 + 离线导入：万一所有源都不通，脚本会打印全部下载链接 + 存放目录，你用浏览器或下载器拿到文件、按提示改名放进目录即可，脚本自动校验并认。

模型只下载一次，之后长期离线可用。想换存放位置，设环境变量 IMGTOOLKIT_MODEL_DIR 指向自定义目录即可（多个工具共用同一份模型时很有用）。

环境要求：去背景需要 Python ≥ 3.11（onnxruntime 的要求）；去水印 AI 修复与超分需要 Python ≥ 3.10（torch）；压缩/转格式需要 Python ≥ 3.10（Pillow）。若你的 Python 版本较老，对应功能会自动不可用或降级，并在报错里明确指出是哪一项、怎么装——其余功能不受影响。

想先看看这台机器现在能用哪些功能，跑一次体检（不联网、不下载）：

python3 scripts/img_toolkit.py doctor

Windows 上如果没有 python3 命令，把下文所有 python3 换成 python 即可。

五项能力总览

| 能力 | 做什么 | 命令入口 | |------|--------|----------| | 去水印 | 图片抹掉文字/Logo/角标水印；视频去掉台标、滚动字幕 | img_toolkit.py watermark <文件> ... | | 去背景 | AI 抠图，主体留下、背景去除，输出透明 PNG | img_toolkit.py bg <文件或目录> ... | | 超分放大 | AI 放大，小图/老图变清晰 | img_toolkit.py sr <文件或目录> --scale 2 ... | | 压缩体积 | 压到指定大小以内、限制长边、PNG 减色 | img_toolkit.py compress <文件或目录> ... | | 转换格式 | jpg / png / webp / bmp / tiff 互转 | img_toolkit.py convert <文件或目录> --to jpg ... |

批量：去水印、去背景、超分、压缩、转格式五项都支持把整个目录当输入，配 -o 输出目录 一次处理完。

安全约定：所有功能都不会覆盖你的原图。默认在原名后加后缀（_clean / _nobg / _sr2x / _min），或按你指定的输出目录/文件名写出。即使你把输出目录指定成输入目录，脚本也会自动加上后缀避让。想自定义后缀，给去背景 / 超分 / 压缩 / 转格式加 --suffix _xxx（如 --suffix _白底）；去水印则用 --output 直接指定成品文件名。

一、去水印

Step 1 · 确认素材与类型

| 素材 | 类型 | 处理方式 | |------|------|----------| | 单张图片 | jpg/png/webp/bmp | AI 修复 LaMa（装不了 AI 引擎时降级 OpenCV 传统修复） | | 多张图片（同批水印位置一致） | 目录 | 批量修复 | | 单个视频 | mp4/mkv/mov/webm/flv/avi | FFmpeg delogo / 裁剪 / 局部模糊 | | 平台链接（抖音/小红书等） | — | 不处理：那是内容解析赛道，不是本地去水印。引导用户提供本地素材文件 |

Step 2 · 定位水印区域（先用视觉，不确定再脚本辅助）

图片与视频的 x,y,宽,高（像素）获取方式，按「先智能、再辅助」顺次尝试：

首选：视觉自动定位 —— 绝大多数水印（角标、Logo、文字）看一眼就能定位。单张图直接读图给坐标；视频抽 1~3 帧关键帧（ffmpeg -ss）后定位；批图先抽 1 张，位置一致就复用坐标。
拿不准时：脚本自动检测（只标候选、不直接删）——
```
python3 scripts/remove_image_watermark.py photo.jpg --auto-detect --output photo_detect.png
```
脚本用边缘密度启发式标出疑似水印区域（红框 + score），生成 *_detect.* 标注图与候选坐标。把标注图展示给用户：「我找到 N 处疑似水印，确认去除吗？」确认后再用 --box 正式去除。

这是启发式辅助，不是万能：它在背景较干净的照片（天空、纯色墙、卡片）上比较准；画面本身纹理极密的图（比如插画、噪点很重的照片）里水印不算"异类"，可能一个都找不到。返回 0 处候选不代表没有水印——这时回到方式 1/3/4 用视觉定位或让用户给坐标，不要因为脚本没找到就告诉用户"没有水印"。
让用户直接给坐标：最准（「右上角 1680,920,220,100」）。
让用户描述位置猜区域：--corner tr/bl/tl/br + --size 预设角标模式。
全自动盲猜：无任何信息时用角标预设滚动尝试，必须告知这是猜测、效果需确认。

坐标系是普通像素坐标（左上角为原点），与手机截图/电脑截图一致。更多定位技巧见 references/coordinate-guide.md。

Step 3 · 图片去水印

图片默认走 AI 修复引擎 LaMa（对前景文字/Logo/半透明角标的修复远优于传统算法），仅在无法安装 AI 引擎时自动降级 OpenCV。

# 指定区域（AI 修复）
python3 scripts/remove_image_watermark.py photo.jpg --box 820,40,180,60

# 多个水印一次去掉（--box 可重复）
python3 scripts/remove_image_watermark.py photo.jpg --box 820,40,180,60 --box 10,10,120,40

# 归一化区域：用户说「右下角占宽 20% 高 15%」时直接换算，无需像素坐标
python3 scripts/remove_image_watermark.py photo.jpg --region 0.75,0.8,0.2,0.15

# 区域外扩，让过渡更自然
python3 scripts/remove_image_watermark.py photo.jpg --box 820,40,180,60 --pad 12

# 掩膜图（白色=要去除区域，精度最高）
python3 scripts/remove_image_watermark.py photo.jpg --mask mask.png --output clean.png

# 批量：同一区域应用到整目录
python3 scripts/remove_image_watermark.py ./in_dir --box 820,40,180,60 --output ./out_dir

# 预设角标（不知道精确坐标时）
python3 scripts/remove_image_watermark.py photo.jpg --corner tr --size 260,80
# tl=左上 tr=右上 bl=左下 br=右下

引擎与设备：

| 参数 | 作用 | |------|------| | --engine lama | 默认，AI 修复，快，CPU/GPU 都可跑 | | --engine powerpaint | 扩散修复档（实验性）：SD1.5+BrushNet 扩散重绘，按掩膜分窗推理。⚠️ 实测特性：在自然纹理（树叶/石板/墙面）上过渡更自然，但在插画/贴图/字幕条等素材上可能幻觉出不存在的内容（假文字、假物体），此时请用默认 LaMa。默认引擎仍是 LaMa；首次用本档需下载约 4GB 权重、单窗口约 5~20 秒（GPU，8GB 显存实测峰值 5.0GB），失败自动降级 LaMa 并明示 | | --engine opencv | 传统修复兜底，无需 torch、无需下载模型，质量略逊 | | --device auto/cpu/cuda | 推理设备，默认 auto（有 GPU 用 GPU） | | --radius / --alpha / --method | 仅 opencv 兜底引擎：修复半径（默认 3）/ 迭代次数（默认 1）/ telea 或 ns | | --mask-mode tight/rect | 掩膜生成方式，默认 tight（见下） |

自动定位与半透明水印（治"位置不准"与"留痕迹"的三件新武器）：

| 参数 | 场景与用法 | |------|-----------| | --sam | SAM 自动精确定位：配合 --box/--corner/--region 使用，你只需把水印大致圈住，Segment Anything（Apache-2.0）自动分割出贴合水印形状的精确掩膜——掩膜更准、误伤更少（首次用下载约 375 MB） | | --alpha-restore | 半透明水印逆混合：对均匀半透明水印先按光学模型 O=(1-α)B+αW 算术还原底层像素再修复，纹理保真度显著高于纯修复（α 自动估计，可用 --alpha-value 指定、--wm-color 指定水印黑白） | | --tiled | 平铺水印自动检测：满图重复平铺的水印无需给区域，FFT 频域自动找重复周期并生成掩膜（零模型）；先加 --tiled-preview 只看标注确认再删 |

--mask-mode 是决定"去完干不干净、看不出痕迹"的关键参数：

rect：把整个矩形框内部全部重绘。框里本来完好的画面也被一起抹平——这正是用户报怨的"擦过、发糊"的痕迹来源。实测在 1920×1440 图上，矩形掩膜会比真实水印多擦约 1.6 倍面积，框内正常纹理锐度掉四成以上。
tight（默认）：先在框内把掩膜收紧到真正的水印像素（文字、角标、Logo 这类与紧邻背景对比明显的结构），只重绘水印本身。实测水印去净程度不变、框内正常画面保真度提升约四成。
兜底：若框内检出面积过小（例如对比度极低的半透明水印），会自动退回矩形掩膜，宁可多擦一点也不留残影。
建议优先组合：普通角标/文字水印用默认 tight；希望更精准就加 --sam；半透明水印加 --alpha-restore；确认"没去干净是收紧过头"时才对比 --mask-mode rect。

效果调优顺序：默认 LaMa + tight → 更准加 --sam → 半透明加 --alpha-restore → 自然纹理素材想更自然的过渡可试 --engine powerpaint（插画/文字条慎用，可能幻觉） → 残留明显就扩大 --box / --pad，或换 --mask 精修 → 实在装不了 AI 引擎再用 --engine opencv，并如实告知这是降级方案。

输出格式：不指定 --output 时，输出扩展名跟随输入（jpg→jpg / png→png / webp→webp），保留原压缩；只有掩膜图或无扩展名输入才默认 .png。

透明通道：输入是含 alpha 的 PNG 时会保留透明通道——输出 .png 透明不变；输出 .jpg/.webp 时透明会被丢弃（有损格式不支持透明）。

Step 4 · 视频去水印

依赖：脚本自动探测 FFmpeg（优先级：系统 PATH → 本地缓存 ~/.cache/qushuiyin/ffmpeg/ → Windows 自动下载便携版），仅首次。

三种模式，按水印形态选择：

| 模式 | 适用水印 | 命令 | |------|----------|------| | delogo 插值去标（默认，保真高） | 台标、Logo、角落图标、半透明角标 | python3 scripts/remove_video_watermark.py in.mp4 --box x,y,w,h | | 裁剪去标 | 水印在画面边缘可整条裁掉、字幕条 | python3 scripts/remove_video_watermark.py in.mp4 --crop w:h:x:y | | 局部模糊 | 大面积文字水印、不想留插值痕迹 | python3 scripts/remove_video_watermark.py in.mp4 --blur x,y,w,h |

# 右下角台标：delogo 插值
python3 scripts/remove_video_watermark.py video.mp4 --box 1680,920,220,100

# 顶部 30px 为滚动字幕：裁掉顶部
python3 scripts/remove_video_watermark.py video.mp4 --crop 1920:1050:0:30

# 画面中段固定文字水印：局部模糊
python3 scripts/remove_video_watermark.py video.mp4 --blur 500,300,200,120

可调参数：--output/-o（默认 原名_nowm.mp4）、--crf（画质，默认 18，越小越清晰）、--preset（编码速度，默认 veryfast，慢机器可 --preset faster）、--show（调试用：把去除区域用色块高亮，确认坐标后正式处理不要加）。

坐标调试技巧：先用播放器看关键帧 → 截图 → 按图片流程确认 x,y,w,h → 再对整段视频处理。delogo 对坐标敏感，偏了会留残边，宁可框大一圈。

视频也可以走统一入口，脚本按扩展名自动分流：
python3 scripts/img_toolkit.py watermark video.mp4 --box 1680,920,220,100

二、去背景（AI 抠图）

把主体抠出来，输出带透明通道的 PNG；也可以合成纯色底（证件照、白底商品图）。

适用边界（务必先判断，能省一次返工）：这类模型找的是「画面里最显著的那一个主体」，它不会去理解"什么是背景"。

✅ 适合：人像、宠物、商品、单个物件、logo 等主体明确的图——边缘干净，可直接用。
⚠️ 不适合：风景、建筑全景、街拍、多人合影等没有单一主体的图——算法只会挑一块最显著的区域抠出来，画面其余部分变成半透明残影，看着像"没抠干净"，其实是用错了地方。
遇到抠不干净的图：先裁出主体再抠仍然是最有效的一招。本功能的模型已是当前开源最强的那一档，没有"换个模型再试试"的空间——换更弱的只会更差。
判断不清时：先 --only-mask 出一张掩膜图给用户确认，别直接承诺抠图效果。

# 基础：输出透明 PNG（默认后缀 _nobg）
python3 scripts/img_toolkit.py bg photo.jpg

# 合成白底（适合证件照、电商图；此时默认输出 JPG，体积小很多）
python3 scripts/img_toolkit.py bg photo.jpg --bg-color white

# 批量抠图
python3 scripts/img_toolkit.py bg ./photos -o ./cutout

# 只要掩膜，方便自己精修
python3 scripts/img_toolkit.py bg photo.jpg --only-mask

| 参数 | 作用 | |------|------| | --model | 只有一个模型 birefnet-general（约 214 MB，当前开源最强通用抠图），默认即用它 | | --bg-color | 把透明区域合成到纯色底：white / black / red / 255,255,255 / #ffffff | | --feather | 边缘羽化半径，默认 0.5（设 0 关闭，边缘更硬但更干净） | | --only-mask | 只输出黑白掩膜（白=主体） | | --list-models | 列出可选模型与体积 |

关于模型档位——这里只留最强的那一个

去背景只保留 birefnet-general（BiRefNet，约 214 MB）。它在发丝、玻璃、半透明、建筑与器物细节上的边界处理，比上一代 U²-Net / ISNet 系整整高一档（它本就是踩着那一代上来的）。

因此本功能不做"小模型先顶上、大模型当升级"的档位设计：抠图这件事用户要的就是质量，一个"秒出但抠不干净"的档只会让人误选、拉低成品。要么给到最好的结果，要么明确说清为什么暂时给不了——不拿次一档的成品去凑。

现实代价（提前告知用户，别让人等得莫名其妙）：输入固定 1024×1024，单张在本机 CPU 上约需 数秒到十几秒，峰值内存较高；若机器有 NVIDIA 显卡并装了 onnxruntime-gpu，会自动走 GPU，快数十倍。批量前先拿一张试，确认耗时能接受再跑全量。

三、超分放大

把小图、老图、低分辨率截图放大，比「直接拉大」锐利得多。

# 放大 2 倍（最常用）
python3 scripts/img_toolkit.py sr small.jpg --scale 2

# 放大 4 倍
python3 scripts/img_toolkit.py sr small.jpg --scale 4

# 批量
python3 scripts/img_toolkit.py sr ./photos -o ./big --scale 2

| 参数 | 作用 | |------|------| | --scale | 放大倍率，默认 2，支持 1~4 | | --model | x4plus（默认，通用照片最强）/ x2plus（原生 2 倍专用，2× 时优于"4× 再缩"） | | --engine | auto（默认，优先 AI、失败自动降级传统插值）/ ai / lanczos | | --tile | 分块推理的块大小，默认 192（内存小的机器可调小；0 = 不分块） | | --list-models | 列出可选模型与体积 |

模型说明：两个都是 Real-ESRGAN 官方旗舰权重（RRDB 23 块、约 1670 万参数），没有"轻量档"——放大要的就是质量，这里不设"先用小模型凑合"的选项。x2plus 是原生 2× 训练的，需要 2 倍时它比"跑 x4plus 再缩一半"更自然。

现实代价（提前告知用户）：这两个模型计算量大，CPU 上比轻量模型慢得多（384×384 小图约 20 秒，大图会到分钟级）；有 NVIDIA 显卡时自动走 GPU，速度相差数十倍。批量前先拿一张试速度，能接受再跑全量。

如实告知：走的是 AI 超分还是降级插值，脚本会在结果行里直接标出来；如果降级了，要跟用户说清「锐度不如 AI 超分」，不要含糊。

倍率的现实：放大倍率越高，「无中生有」的成分越多。4 倍放大一张很小的图（如 180×135 → 720×540）时，模型要把 2.4 万像素补成 39 万像素，细节主要靠模型重绘——画面明显比插值清晰，但不等于还原了原始细节。倍率越接近 2、输入图本身越清晰，结果越可靠；手上有原始大图时，直接用大图，不要用超分。

耗时预期：纯 CPU 上 4 倍放大会比 2 倍明显慢，大图建议先用 --scale 2 试效果，再决定要不要上 4 倍。

四、压缩体积

# 按画质压（默认画质 80）
python3 scripts/img_toolkit.py compress photo.jpg --quality 70

# 压到 500KB 以内（自动二分找画质，直到达标）
python3 scripts/img_toolkit.py compress photo.jpg --max-size 500

# 限制长边 1920 + 画质 75
python3 scripts/img_toolkit.py compress photo.jpg --max-dim 1920 --quality 75

# PNG 减色（PNG 体积大时很有效）
python3 scripts/img_toolkit.py compress shot.png --colors 256

# 批量压到 300KB 以内
python3 scripts/img_toolkit.py compress ./photos -o ./small --max-size 300

# 压缩时顺便转格式
python3 scripts/img_toolkit.py compress photo.png --to jpg --quality 85

| 参数 | 作用 | |------|------| | --quality | 画质 1~95，默认 80（越小文件越小） | | --max-size | 目标体积上限，单位 KB（如 500）。给了它就自动二分找画质，忽略 --quality | | --max-dim | 限制长边像素（如 1920） | | --colors | PNG 减色到 N 色（如 256），对 PNG 很有效 | | --keep-metadata | 保留 EXIF 等元数据（默认抹掉；方向信息已提前写进像素，图不会歪） | | --to | 顺便转格式 |

压不到目标时如实说：脚本会标注「未压到目标 N KB 以内（该图压缩空间已到极限）」，这时可以加 --max-dim 缩小尺寸再试。

五、转换格式

python3 scripts/img_toolkit.py convert photo.png --to jpg
python3 scripts/img_toolkit.py convert photo.jpg --to webp --quality 85
python3 scripts/img_toolkit.py convert ./photos --to png
python3 scripts/img_toolkit.py convert logo.png --to jpg --bg-color white   # 透明区域合成白底

支持 jpg / png / webp / bmp / tiff。透明通道处理：转成 png/webp/tiff 会保留透明；转成 jpg/bmp 时用 --bg-color 指定的底色合成（默认白）。

交付与话术

成功后把成品文件路径发给用户，并说明原图/原视频未动：

✅ 已处理完成：
原图：/path/photo.jpg
成品：/path/photo_nobg.png
处理方式：AI 去背景（BiRefNet，输出透明 PNG）

✅ 已处理完成：
原图：/path/photo.jpg（1444x1444，5.0 MB）
成品：/path/photo_min.jpg（1200x1200，451 KB）
处理方式：压缩，质量 75，长边限制 1200，体积省 88%

排版规矩：给路径用代码块或单行引用；不贴脚本日志；不输出 JSON；不出现「正在为您处理」这类废话，直接给结果。一次处理不完美时给调参建议，不要反复跑同一命令空转。

🔒 硬边界

绝不收费：本技能是免费本地工具。任何涉及充值、Token、套餐、API 次数的话术一律不得出现。
本地优先：不得引导用户上传第三方网站处理素材（除非用户明确要求且自行承担风险）。
不编造成功：脚本失败就如实报告失败原因与解决建议（装依赖、装 FFmpeg、调坐标）。降级必标注，不把降级结果说成 AI 结果。
不覆盖原图：任何功能都不得改写用户的原始文件。
版权提示：默认假设用户有权处理素材；明显是消除他人版权水印的用途，提醒一句授权问题即可，不替用户做判断。

参考资料（按需加载）

references/coordinate-guide.md — 水印坐标定位方法、角标预设说明、常见台标尺寸参考
references/troubleshooting.md — 各功能常见失败原因与修复方法

脚本一览

| 脚本 | 作用 | |------|------| | scripts/img_toolkit.py | 统一入口：五项能力 + doctor（体检）+ selftest（离线自检） | | scripts/remove_image_watermark.py | 图片去水印（LaMa / OpenCV） | | scripts/remove_video_watermark.py | 视频去水印（FFmpeg delogo / crop / blur） | | scripts/lama_infer.py | LaMa 模型推理模块（被图片去水印调用） | | scripts/powerpaint_infer.py | PowerPaint 扩散修复引擎（--engine powerpaint 时被图片去水印调用） | | scripts/powerpaint/ | PowerPaint 管线代码（vendor 自 IOPaint/PowerPaint 官方，Apache-2.0） | | scripts/sam_mask.py | SAM 自动掩码模块（--sam 时被图片去水印调用） | | scripts/bg_remove.py | 去背景引擎（ONNX BiRefNet） | | scripts/sr_upscale.py | 超分引擎（Real-ESRGAN） | | scripts/imgexport.py | 压缩 / 转格式引擎（Pillow） | | scripts/toolkit_common.py | 公共底座：多源下载、批量、依赖自举 |

自检（不联网、不下载，用来确认引擎逻辑没被改坏）：

python3 scripts/img_toolkit.py selftest