--- name: pcb-photo-annotate version: 0.1.0 description: > 把 KiCad 设计坐标套到裸板/成品板的实物照片上:判断照片是正面还是背面、模块(XIAO 等)该朝哪放, 并在照片上标出每个焊盘的名字、空焊盘、GND/3V3。用设计里的过孔当「指纹」试 8 种朝向, 分不出就直说判不了。用户说「这块板哪面是正面」「XIAO 怎么对上去」「给照片标一下焊盘/引脚」 「焊之前确认方向」,或发来打样板照片问怎么焊时使用。 --- # pcb-photo-annotate **P0**:焊之前在 Mako 自己拍的照片上指清「哪面、哪头、哪个焊盘是什么」,结论有依据,能被反例推翻。 ## 为什么用过孔 正方形/对称的焊盘排布转 180° 看起来一样,斜走线也常常转 180° 还对称(P44c 实测:只看走线两种朝向都说得通)。 过孔位置几乎不对称:13 个过孔套上去,对的朝向平均偏 16 像素,次好的 43 像素,其余 80+ 像素。 ## 步骤 1. **照片**:HEIC 先转 JPG(`sips -s format jpeg`),按 EXIF 摆正,裁到只剩板子。脚本会再 `exif_transpose`,坐标以你量的那张图为准。 2. **导出设计坐标**(KiCad 自带 Python,`pcbnew` 自己算封装旋转): ``` KPY=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 $KPY -B annotate.py dump board.kicad_pcb U1 > design.json ``` 板子在 git 里就 `git show origin/main:路径 > 本地文件`,别读工作树里可能被别的会话改过的版本。 3. **在照片上量像素**(放大看,`Read` 裁图): - `corners_px`:封装四个角上的焊盘,沿板一圈依次点。从哪个角起、顺逆时针都行,脚本会试遍。 - `vias_px`:看得见的过孔,至少 5 个,越多越稳。漏看不扣分,点错会扣。 4. **出图**(任何带 numpy + Pillow 的 Python;原力手环仓用 `host/.venv-emg/bin/python`): ``` python -I annotate.py draw design.json config.json out.png ``` 配置字段见脚本开头注释:`labels` 按焊盘号改字(例如网名换成 XIAO 的 D0–D10),`colors` 给 GND/3V3 着色并画圈,`arrow` 用板坐标 mm 画「USB-C 朝这头」。 5. **读结论**:脚本打印 8 种对应的偏差。最好的偏差要不到次好的一半才出图,否则退出码 1,并提示「判不了」。行列顺序如果反了(镜像),就说明照片拍的是板子背面(pcbnew 坐标一律按从正面看,与封装在哪面无关),脚本会写「照片是背面」。 6. **交付**:图发给 Mako,并附一条焊前用万用表能做的确认,例如「GND 焊盘应与 J1 第 7/9/20 脚导通」。照片和模型对上,不等于实物验收。 ## 已验证 | 输入 | 结果 | |---|---| | P44c 正面照片(2026-11-01,原力手环 `v12/c08-p44c-xiao-adapter-reflow-20261027`) | 正面,偏差 15.8 px;次好 43.4 px | | 反例:过孔随机点 | 最好 106.8 与次好 109.6 差不到 2 倍,判不了,退出码 1 | | 反例:照片左右镜像 | 判成背面(B),偏差不变 | ## 坑 - 封装角焊盘按「x±y 极值」取。异形封装的角如果不是焊盘,就换一个过孔多、外形规整的封装做 `ref`,再用 `labels` 只标关心的焊盘。 - 字体按 STHeiti → PingFang → Noto CJK 的顺序找,一个都没有就退出并提示装 Noto CJK。 - 过孔很多的板(几百个)只算「可见→投影」会稀释差距,容易报假的「判不了」(复核加 800 个随机过孔时比值降到 1.45);这时只点照片里清楚的过孔,或换局部裁图。没出现过错判。