cardmask

把银行卡照片上的数字全部抹掉，再把底下被盖住的画面补回来。

凸印卡号、VALID THRU 后面的有效期、卡号下方那排凸印序列号——凡是卡面上由数字组成的部分， 都会被识别、遮盖，然后用 LaMa 把背景纹理重新画出来。成品在正常观看距离下读不出任何数字， 也不容易看出修补痕迹，可以直接拿去展示或发人。

全程在本机 CPU 上跑，照片不上传、不联网（除了第一次下载模型）。

照片 ──► 找到所有数字行 ──► 盖上 ──► AI 补背景 ──► 检查残留 ──► 照片_masked.jpg

安装

需要 Python 3.10+。推荐装官方打好的 wheel：

pip install https://github.com/YuruiHong/cardmask/releases/download/v0.1.0/cardmask-0.1.0-py3-none-any.whl
cardmask fetch-model      # 首次运行前执行一次，下载补全模型（208 MB）

fetch-model 会校验文件大小和 sha256，下坏了不会静默使用；模型存在 ~/.local/share/cardmask/models/， 想换位置可以 cardmask fetch-model -o 路径 或设置 CARDMASK_MODEL。

不想动系统 Python 的话，用独立 venv：

git clone https://github.com/YuruiHong/cardmask
cd cardmask
python3 -m venv .venv && ./.venv/bin/pip install -e .
./.venv/bin/python -m cardmask.cli fetch-model
./scripts/install.sh          # 把 cardmask 链到 ~/.local/bin

用法

cardmask 卡面照片.jpg                  # → 卡面照片_masked.jpg（同目录）
cardmask 卡面照片.jpg -o 输出目录/      # 指定输出位置
cardmask 一堆照片/ -o 输出目录/         # 批量，递归处理图片
cardmask 卡面照片.jpg --debug          # 额外输出目检图，见下

支持 .jpg .jpeg .png .webp .bmp。原图不会被修改或覆盖。

先看目检图，再验收

处理完一定要看一眼 --debug 生成的 *_preview.jpg：红框就是被抹掉的区域，编号对应审计文件里的行带。 没有红框的地方就是没被处理的地方，发现漏了就补框：

cardmask 卡面照片.jpg --extra-box 120,770,700,60 --debug

X,Y,W,H 是像素坐标，原点在左上角：X、Y 是框的左上角，W、H 是宽高。用任何看图软件都能量出来。

输出文件

文件	内容
*_masked.jpg	脱敏后的卡面，可以直接用
*_preview.jpg	红框 + 编号的目检图（--debug）
*_mask.png	二值掩膜（--debug）
*_audit.json	审计记录：每块区域的坐标、掩膜像素数、残留数、耗时

审计文件里没有任何识别出的数字，只有坐标和计数；即使被转发也不泄露卡号。

常用参数

参数	说明
-o, --output	输出文件，或批量时的输出目录
--engine {auto,lama,telea}	auto（默认）有模型用 LaMa、没有就退回 Telea；telea 快但纹理糊
--debug	额外输出目检图和掩膜
--extra-box X,Y,W,H	手工补一块要抹的区域，可重复
--exclude-box X,Y,W,H	手工排除一块误判的区域
--dilate N	掩膜额外向外扩 N 像素
--no-verify	跳过成品回检（快一点，但就没有残留告警了）
--json PATH	指定审计文件路径
--quiet	只输出错误

退出码：0 成功 / 2 参数错 / 3 成品里仍检测到数字行（需要补框）/ 4 图片读不了。

已知限制

• 漏检：如果某条数字行太模糊、和背景太接近，可能被漏掉。跑完看目检图，用 --extra-box 补。
• 金色、低对比卡面比深色卡面更容易漏。
• 最后那道自动检查用的是同一个检测器，它的盲区它也看不见——所以目检图是必要环节，别只看退出码。
• 抹除区域比数字本身略高，紧挨着的 VALID THRU / MONTH/YEAR 小字可能被顺带盖掉一点。
• 只处理数字；银行名、logo、芯片、卡组织标志都保持原样。

耗时

6 核 CPU、无 GPU，一张 1420×2638 的手机照片：找到数字约 20 秒，LaMa 补集约 2 分钟； --engine telea 全程约 25 秒，适合只想快速看效果。

许可证

MIT