图片二维码无痕替换

海报改码时的常见痛点

把活动海报、名片或公众号题图里的二维码从飞书换成微信，或是为不同渠道切换引流码时，直接覆盖旧码往往连带擦掉四周的绿色科技边框、角线与点缀。这些装饰是设计稿里反复调整的细节，重新修图既费时又容易失真；手动框选再贴码，又常因坐标不准或背景匹配不当留下码点残留与色差。

技能如何完成替换

底层脚本 scripts/qr_swap.py 只依赖 Pillow，不引入 numpy、OpenCV 或 pyzbar，核心是「先定位，再替换」：

• 定位旧码：简单背景可直接让脚本自动检测，白底密集像素与边缘密度两种策略都能覆盖；复杂海报建议先用读图工具肉眼分析坐标，通过 --region x,y,w,h 手动传入，精度 ±2 像素即可。
• 保留装饰边框：--keep-border 控制保留四周装饰的像素数，默认 4；--shape 提供四种模式——rect 直角矩形（最稳）、round 圆角矩形蒙版、circle 圆形蒙版（适配徽章与头像类设计）、auto 自动判 rect/round。蒙版模式只在内层形状内贴码，装饰环像素原样保留。
• 适配复杂背景：--bg 可选 white、#RRGGBB 或 auto，auto 会采样原码区域外围平均色填充，适合彩色或深色背景上的码。

适用边界与注意点

• 建议手动传 --region 的场景：极小码（<40px 缩图后特征丢失）、高纹理照片背景（边缘检测易被淹没）、多码同图（自动检测只返回最大一块）。
• 圆角/圆形框必须显式指定形状：默认 rect 会「涂方角」，装饰环外露破损，需传 --shape round 或 --shape circle；auto 不自动判圆形，以避免几何特征误判。
• 新码预处理：非正方形二维码会被自动裁短边居中，建议预先裁成正方形避免变形。输出请用 .png、.jpg、.webp 等标准扩展名，以匹配 PIL 的格式支持。
• 暂不支持：动态 GIF，以及与背景对比极弱的低分辨率码。