Word report generation with adaptive 2-column photo grid algorithm
A4 geometry · MD5 dedup · Caption generation · Full helper library
Python-based Word (.docx) 报告生成，配自适应 2 栏相片网格算法。解决「固定 2×2 布局浪费空间」的经典问题，按每页实际行数动态缩放相片。
生成有大量相片的 Word 报告时：
- 固定 2×2 排版，行数少时相片太细、浪费空间
- 手动拖相对位，几十张相搞几个钟
- 不同报告（灯具/Lux/风扇）格式不统一
- caption 编号、页码、签署区每次重复做
python-docx-photo-grid 将这些全部自动化。
- 最多 3 行 × 2 栏 = 6 张/页
- 按每页实际相片数量动态缩放
- A4 / Letter 页面几何常数精准计算
- 长宽比自动适配，不变形
- MD5 相片去重（重复相自动跳过）
- 图片压缩（控制文件大小）
- caption 自动生成（避开
_01后缀 bug）
- 字体设定（中英文混排）
- 表格边框样式
- 页码 + 页眉抬头图
- 统一签署区块
- 结构完整性检查脚本
- 17 个 documented pitfalls
适用于工程各类图文并茂测试竣工报告 （统一蓝色系 + 承建商抬头图 + 章节结构）
🔒 工程竣工报告模板与SOP 为非公开内容，不在此公开 repo 中。 包含完整模板、排版规格、SOP 流程、实机交付件参数。 如需商业使用，请邮件联络：david_1999cn@hotmail.com
| 场景 | 例子 |
|---|---|
| 竣工/验收/测试报告 | 灯具/Lux/风扇/电箱/设备验收 |
| 巡查/勘察记录 | 现场勘察备忘录、质量检验报告 |
| 任何「文字+大量相片」报告 | 施工日志、售后报告、工作总结 |
| 需要相片排版好看 | 标书附件、客户报告、年报 |
不适用：纯文字文档；修改现有 docx（用 officecli-workflow）；表格数据为主。
python-docx-photo-grid/
├── README.md # 本文件
├── DOCUMENTATION.md # 完整技能文档
├── assets/
│ └── photo-grid-comparison.jpg # 效果对比图
├── references/
│ └── 竣工报告三件套_模板与SOP.md 🔒 # 模板 & SOP 参考（非公开，需邮件授权）
└── scripts/
└── adaptive_photo_grid.py # 可重用程式码模组
- Python + python-docx — Word 文档生成
- Pillow — 图片处理与尺寸计算
from adaptive_photo_grid import PhotoGridBuilder
builder = PhotoGridBuilder(page_size="A4", columns=2, max_rows=3)
builder.add_photos(["photo1.jpg", "photo2.jpg", "photo3.jpg"])
builder.save("report.docx")详细用法请参阅 DOCUMENTATION.md。
MIT License — feel free to use, modify, and share.
Part of the MEP & construction document automation toolkit — open-source tools built from real jobsite workflows.
- Handbook — ai-agent-manual (8-level AI cultivation for engineers)
- Document generation — material-approval-pipeline · material-submittal-generator · excel-template-filler · daily-construction-log · officecli-workflow
- Engineering calculation — lighting-lux-calculator · ups-discharge-time-calculator · gantt-chart-pro · electrical-test-report-generator
- CAD & drawings — electrical-panel-label-plates
- Data & OCR — ocr-skill · VBA-Macro-Reader-v2.0.0
- Compliance & AI ops — confined-space-planner · 路由规则 · consulting-services