产品图统一

概述

chanpintu — 产品图对齐入表

把一批背景透明或纯白的产品图，处理成「左边距一致 + 视觉大小一致」后，逐张插进 Excel 第一列。

快速开始

1. 安装依赖（需 Python ≥ 3.9）：python -m pip install pillow numpy openpyxl
2. 运行：python scripts/build.py --folder "图片文件夹"
3. 验证：控制台打印验收表，所有「左边距」= 16 即成功

安装后建议先跑 python scripts/check_env.py 自检依赖版本。

文件结构

第一性原理（踩过的坑，必须理解）

原理 1 — "产品"指的是产品本体，不是整张图。透明 PNG 的画布通常比产品本体大，且留白不对称（常见左边留白更多）。白底 JPG 同理，产品往往没居中。如果直接缩放整张图插进表格：① 产品本体看起来偏小；② 因为左边透明留白多，产品整体偏右、左边距很大。→ 必须先抠出产品本体（去掉透明/白色留白），再处理。

原理 2 — "等面积"归一化是错的。曾试过让每张图面积相等，结果因为长宽比不同，宽度各不相同 → 左边距参差 → 看起来乱。已否决。

原理 3 — "固定宽度"归一化是左对齐的锁。让每个产品本体的宽度都等于同一个常数（如 288px），高度按比例。因为宽度一致、又都左对齐锚定贴到同尺寸画布上，每一张的左边距 = (画布宽 − 固定宽) / 2，对所有产品完全相等 → 左边严丝合缝对齐。同时因为同类产品长宽比相近，固定宽度后「看起来大小也一致」。这是最终成功的方案。

原理 4 — 取「最大连通块」当产品本体。直接对整张图取 alpha bbox 会被细电缆、探头、软阴影、附件撑歪。改用：硬前景里面积最大的连通分量 = 产品本体，天然排除这些干扰。

原理 5 — WPS/Excel 有绘制缓存，会显示旧图。反复改图后重开表格，可能看到的是上一次的旧样子（表现为"我改了第3/4行但还是老样子"）。→ 重开前彻底关掉 WPS；或写入带时间戳的新文件（--fresh）绕开缓存；或删掉旧 xlsx 再重开。

算法步骤（详见 scripts/build.py）

1. 遍历文件夹图片（png/jpg/jpeg/webp，按名排序，大小写扩展名均可）。
2. foreground_mask(im)：
   • 含透明（alpha 最小值 < 255，即有透明像素）→ 硬前景 = alpha ≥ 128。
   • 不透明（白底等）→ 计算四角平均色，前景 = 与角点色距 > BG_TOL（默认 60）的像素；若几乎无前景则回退亮度阈值。
3. product_body_bbox(im)：对前景做连通分量，取面积最大块；若最大块 < 全图 0.5% 视为检测失败，回退整图。
4. 紧裁到本体 bbox。
5. 固定宽度归一：scale = TARGET_W / 本体宽，宽=TARGET_W、高按比例；若最长边超画布则整体等比压回。
6. 左对齐锚定贴到 CANVAS × CANVAS 透明画布：横向永远 x=(CANVAS−TARGET_W)//2（固定=16，与本体宽无关），纵向居中 y=(CANVAS−nh)//2。

这样正常图与溢出窄图左距恒为 16，不再漂移。

1. 存临时 PNG（序号前缀防同名覆盖），用 openpyxl 的 XLImage 插入 A{row}；A1="产品"；设列宽与行高使画布约 1:1 显示。

参数（scripts/build.py 均可命令行覆盖）

用法

# 默认：处理指定文件夹，输出 产品图对齐.xlsx
python scripts/build.py --folder "C:/.../温湿度压差"

# 更新已有表（清空 sheet1 旧图、覆盖 A1，保留其他 sheet）
python scripts/build.py --folder "C:/.../温湿度压差" --out "C:/.../新建 XLSX 工作表.xlsx"

# 白底图 / 规避缓存
python scripts/build.py --folder "C:/.../白底产品" --fresh

# 既生成 Excel，又把统一尺寸图另存到 resized/ 子文件夹（不改动原图）
python scripts/build.py --folder "C:/.../温湿度压差" --save-resized

⚠️ 需要 Python ≥ 3.9，且已安装 Pillow / numpy / openpyxl（python -m pip install pillow numpy openpyxl）。

首次使用先跑 python scripts/check_env.py 自检，避免 ModuleNotFoundError: No module named 'PIL'。

脚本运行结束会自打印验收表：每张图的 主体宽×高 与 左边距。正常情况下所有 左边距 都等于 (canvas−target_w)//2（默认 16）。任意一张不一致会标 ⚠️，据此判断有没有翻车。

已知边界（务必先读）

⚠️ 「左对齐」与「看起来一样大」对极端长宽比是零和博弈。

本技能默认用固定宽度锁左对齐——保证所有产品左边距绝对相等。

但代价：若产品 A 是 1:3 窄高条、产品 B 是 3:1 扁宽条，固定同宽后它们高度差 3 倍，视觉大小并不一致。

同类产品（温湿度屏等）长宽比接近，此问题不出现。若长宽比差异巨大，先想清要哪个：

• 要严格左对齐 → 保持默认，接受大小略有差异；
• 要严格等大 → 改用面积归一（未来计划新增 --mode 参数支持，届时左边距会参差；当前未实现，请勿传 --mode）。

不要指望一个模式同时满足，那物理上矛盾。

边界情况与处理

• 白底/纯色不透明图：用角点色距阈值（四角平均色为参考），不依赖 alpha；已在真实 21 张白底样本（含 2 张 PNG 看板）实测闭环 ✅。
• 软阴影：浅灰阴影与白色色距小，被归为背景；过深阴影可能误判为前景，靠「最大连通块」过滤掉小噪点。
• 产品贴到图片边缘（角落无留白）：角点色被产品污染 → 检测可能整张反掉；已加保护：前景占比 >95% 时直接取整图。
• 同图多个产品：取「最大块」= 只保留最大的那个；检测到 >1 个显著连通块时会打印 ⚠️ 提示，不再静默丢图。多产品请先拆图。
• 极端长宽比（又高又窄）：固定宽后高度可能超出画布 → 触发等比压回，此时宽度略小于 288，左边距仍一致但大小略缩。同类产品长宽比相近时不会触发。
• 混合透明+白底同目录：逐张自动识别模式，互不影响。
• 参数契约：--canvas 必须 ≥ --target-w，脚本已强制校验，违反直接报错退出（避免左对齐锁静默失效）。
• 坏图/文件占用：单张损坏图会被跳过并提示；目标 xlsx 被 WPS/Excel 打开时保存失败并提示关表，不再整批崩溃。
• 透明判定陷阱（曾踩坑）：必须用 alpha.min()<255 判透明（含透明像素＝透明图）。不能用 max——产品不透明时 alpha 最大值恒为 255，用 max 会误判为白底图、走错分支，圆角类图会被当整图回退、左距漂移。v1.1.3 已修。
• WPS 缓存：见原理 5，用 --fresh 或关 WPS 后重开；覆盖已有表时留意文件 mtime 是否更新，没更新就是被缓存了。
• --save-resized 产物：resized/ 子文件夹的 PNG 是画布产物（320×320 透明画布 + 288 宽本体），每次运行自动清空再写。不要把这些 PNG 拷回原文件夹再跑——glob 虽不递归不会被二次扫描，但原图会被覆盖。若文件夹新增/删除图片后重跑，resized/ 会自动同步为当前镜像。

验收标准（交付前必查）

1. 打印表里所有左边距相等（默认 16）。
2. 打开 xlsx，肉眼看第一列各产品左边齐、大小近似。
3. 若用 WPS 重开发现没变化 → 关 WPS / 用 --fresh 重跑，别误判脚本没改。

依赖与版本要求

安装：python -m pip install pillow numpy openpyxl。支持 Windows / macOS / Linux。与 WPS / Microsoft Excel 均兼容。

许可证

• MIT License（见 frontmatter license: MIT 声明）