PDF 图纸签字盖章

批量处理工程图纸 PDF：在图签（标题栏）加手写签名、盖印章、填日期，必要时把"XXX"占位替换为真实姓名。经实战验证（建筑/结构两专业、四个批次共 214 张，含 4 种图幅与旋转页）。

总原则

1. 永不修改源文件。成果输出到图纸目录下新建的"完成版xxx"子文件夹，目录/清单类 PDF 默认不处理（先问用户）。
2. 定位靠几何不靠文字。CAD 导出 PDF 中人名、标签常是矢量曲线，search_for 搜不到；一切坐标以框线测量为准，锚点文字只作首选定位手段。
3. 分批确认节奏：先出 1 张样张给用户确认 → 再做 3 张（覆盖不同图幅/旋转页）→ 确认后全量批处理。用户明确要求过此节奏，勿跳步。
4. 动笔前先查重：检测姓名区/日期区/盖章区是否已有内容（xxx 占位、预填日期、已盖的章、已有手写签名）。已有手写签名和章的图是成品，叠加会重影——拿不准就问用户。
5. 缺手写签名图时立即停下找用户要，不要卡住其他图纸的进度（可先处理有签名的）。

环境准备

依赖 pymupdf + pillow + numpy。按运行时隔离规则装进受管 venv：

<managed-python> -m venv <workspace>/binaries/python/envs/default
<workspace>/binaries/python/envs/default/Scripts/pip install pymupdf pillow numpy

字体：中文姓名用 C:\Windows\Fonts\simfang.ttf（仿宋，匹配 CAD 图签风格）；日期用 arial。

流程

推荐路径：autofill.py 自适应流水线（换图框免改代码）

scripts/autofill.py 运行时自动量规：从图签框线反推全部几何（签名行组、姓名列、日期格、空白盖章区），不写死任何坐标。图幅变化、图框整体平移、旋转页、行高行数不同、盖章区换位置均自动适配。签字/盖章/日期可任意单项或组合。

工作流：

1. 写任务 JSON（spec，见下方字段表）。
2. 量规验证：python autofill.py spec.json --measure --limit 3 —— 只测量不写，输出识别到的行/日期格/盖章区 + 每种版式的预览图 _work_autofill/preview/layout_<n>.png，用 Read 目检是否识别正确。
3. 单张实测：--test（第 1 张 + 渲染图签预览 test_titleblock.png）→ 给用户确认。
4. 3 张验证：--files "a.pdf,b.pdf,c.pdf"（不同图幅/旋转页各一）。
5. 全量：不带参数跑（大批量可 run_in_background），结束看 _work_autofill/report.json 汇总（处理/原样保留/无图签）。

spec 字段（JSON）：

自动量规的识别规则（排障时参考）：
- 图签横线 = 右下区域、长 90-520pt、右端近页边的线；双线取均值合并
- 签名块 = 连续等间距(14-80pt)行线组中行数最多的一组
- 日期格 = 签名块下方最后一个行线 → 图签底边（长竖线上端点，双线取内侧）
- 盖章区 = 签名块上方各横带中"最大空白矩形"（先按行、再按列两次投影）
- 姓名遮盖 = 行底 34% 高度条带内的墨迹 bbox（标签在上半格不受影响）
- --measure 会输出量规置信度（0-100，逐项检查：行数/行高/图签宽/日期格高/盖章区/签名区墨迹）并写 _work_autofill/measure_report.json；置信度 <80 或量规失败时，控制台会明确提示改走视觉辅助定位

换图框标准流程（其他公司图框 / 特殊版式）

autofill 的量规是纯几何反推（不看图框文字、不认公司），常规"右下角表格+签字栏在右"的结构换公司图框通常无需截图直接可用。按以下分支推进：

1. 自动量规 + 自检：--measure --limit N → 看置信度与 layout_*.png 预览。score ≥80 且预览正确 → 走正常"单张→3张→批量"。
2. 置信度 <80 或量规失败 → 视觉辅助定位（不需要用户截图也能做）：
   - 量规失败的文件 autofill 会自动输出右下区域渲染图 layout_fail_*.png；置信度低的看 layout_*.png；
   - agent 用 Read 读渲染图，视觉识别签字栏行界、姓名列、盖章空白区、日期格位置；
   - 用 newframe_assist.py 逐格侦察（必做，防漏格）：python newframe_assist.py 图纸.pdf --outdir 侦察 自动探测图签条带 → 提取列界 → 逐列独立分行（各列行数不同也能正确分格）→ 枚举全部单元格（编号+格内墨迹 bbox+参考文本）→ 输出 cells.json 与红框编号标注图 cells_annotated.png。用 Read 核对标注图，把"每个有墨迹的空白签格"逐格清点列入 sig_cells，杜绝"设计格漏数"这类遗漏；自动探测失败用 --roi x0,y0,x1,y1 手动指定；
   - 需要更精确坐标时，用 pymupdf 对局部区域高倍率渲染 + 像素墨迹扫描（ink_bbox/ink_row_segs）量出 pt 坐标；
   - 用户主动发标注截图：python newframe_assist.py 图纸.pdf --shot 截图.png --points "px,py px,py" 把截图像素坐标按 整页尺寸比例 换算为 PDF pt（视觉坐标，可直接写入 sig_cells/stamp_area/date_cell；截图须为整页、视觉正向；旋转页先转正再截）。截图同时用于与 cells.json 交叉印证格数，对不上以截图为准。
3. 覆写几何：把定位结果写入 spec 的 geometry.manual（字段见上表），--test 单张确认 → 批量。manual 覆写后所有既有保护（已签跳过、无图签复制原样、旋转页自动正向、字号自适应）继续生效。
4. 仍是兜底：如果新图框连表格线都没有（图片型图签、扫描件），退回经典路径（scan_layout.py + 手工量规 + 适配脚本）。

实测案例二（右侧竖排三列式图签，A0 暖通人防）：图签在页面右缘竖排，签名栏为"标签+印刷体姓名+手写签名"三列，上方有注册执业栏、下方有"出图签章 STAMP FOR DRAWING COMPLETED"专用空白区。置信度 67 → newframe_assist 侦察（列界 2157.4/2228.2/2292.0，六行签名行高 22.7-36.9pt 不等）→ geometry.manual 覆写 + 每行 sig_cells 落签名列、出图签章区作 stamp_area、日期行遮旧写新 → 一次通过。经验：①自动量规在该图上误把版次/图号/日期三行当成签名行（等距 19.9pt）——置信度自检里的"签名区墨迹"项就是为这种误判设的；②旧日期起始 x 用 ink_bbox 实测，别目测（本例目测偏右 9pt 导致"20"残留）。

实测案例（通栏底部图签，浙江院风格）：某外司图框为"整幅底部通栏双行条带"，自动量规失败 → 兜底渲染读图 → 框线分析得上下边界与竖线分格 → geometry.manual 覆写（tb=通栏 bbox、两行 y 界、日期格、盖章区）→ 每行 sig_cells 逐格（上行 3 格：审定/项目负责/设计；下行 2 格：审核/校对）+ mask_rects 逐格遮盖旧签名 + text:false → 单张一次通过。要点：①通栏图签分格竖线用 visual_segments 的 x 值直接读；②行分界若左右段 y 不同（相差 2-3pt），取中值即可；③已有签字/章"忽略但作为位置信息"时：签名格先 mask_rects 白块再贴模拟签，章直接按原章位置落模拟章（不遮盖，避免切坏穿越的框线），日期格 date.mask 自动遮旧值；④多签格必须逐格清点防漏——首轮曾漏掉"设计"格（用户发现），正确做法：读渲染图时把图签内所有"标签+空白格"逐一列出并计数，与用户提供的标注截图互相印证，漏格必被截图兜住。

经典路径：手工量规 + 适配脚本（autofill 识别失败时的兜底）

第 1 步：盘点材料

列出图纸目录（含子文件夹）、签名图文件夹、印章文件夹。核对：签名图姓名 × 图签名单是否齐全；印章几张、什么章。缺谁的签名图马上向用户要（白底照片即可，工具会转透明）。

第 2 步：扫描版式

python scripts/scan_layout.py <图纸目录> --anchor "DESIGNED BY/DATE" --outdir <debug>/scan_out

输出每种版式（尺寸+旋转+锚点有无组合）的页数清单、锚点周边横线/竖线坐标、图签区域渲染图 layout_<n>.png。据此判断：
- 行界是否规整（图签行通常 ~28pt 高）
- 姓名区是 xxx、空白还是已填
- 日期栏是否有预填内容（如"2024.11.6"）
- 盖章空白区在哪（常在修订表下方或图签上方）

第 3 步：测量与命名几何

用 Read 看 layout_<n>.png，并用像素级墨迹扫描（numpy）精测：
- 每行 XXX 的精确 bbox（先粗测再收窄 clip 排除行框线干扰，边框会污染检测）
- 日期格内边界（白块遮盖的安全范围，距框线留 ≥0.3pt）
- 盖章区墨迹密度（>1% 即有内容，需查明是什么）

第 4 步：适配脚本

以 scripts/struct_tool.py 为模板复制到 debug 工作目录，改这些常量：

无框线数据的新项目先跑 scan_layout.py 拿横线坐标。名单因楼栋/子项而异时：渲染各图人名栏做像素指纹分组，逐组看图确定名单；新旧版本可比对指纹快速锁定差异。

第 5 步：分批验证

python struct_tool.py --test "A1\S-xxx.pdf"            # 1 张 + 渲染预览
python struct_tool.py --files "a.pdf,b.pdf,c.pdf"      # 3 张（不同图幅/旋转页各一）
python struct_tool.py                                   # 全量（可 run_in_background）

每批用 Read 目检渲染图：姓名、签名、章、日期四要素齐全、方向正、无压线。

第 6 步：自动校验 + 抽检

逐输出文件检查：页数齐全无缺漏；每页日期文字恰好 1 处（旋转页用插入图数代替）；姓名文字可被 search_for 搜到（矢量姓名用插入图数≥12 校验）；渲染抽检 3-4 种版式（必含旋转页、最大图幅、最小图幅）。最后整页渲染抽查 1-2 张确认图签以外区域未受影响。

第 7 步：交付

present_files 附样张；汇报处理明细、校验结果、跳过/特例清单（无图签的裸图、原样保留的成品图等）。

关键坑（必读）

• 页外溢出内容：CAD 导出可能把构造线/文字画到页面外，get_cdrawings 坐标可远超页面尺寸（表现为识别出的行/日期格 y 超出页高）。measure 已按页面边界裁剪线段；排障时先核对识别坐标是否在页内。
• 图签底边与图幅边框重合：此时底线长度远超 90-520pt 窗口被过滤，签名块下方"无行线"——date_top 已改为回退 rows[-1][1] 并钳制在页内，但这种图框的日期格识别必然低置信，直接走 geometry.manual。
• 旋转页（rot 90/270）三套坐标：search_for 与 get_drawings 返回未旋转坐标；get_pixmap(clip=...) 用视觉坐标（未旋转矩形 × page.rotation_matrix）；插入图片前把目标视觉矩形 × page.derotation_matrix 转回未旋转，且 PNG 需预旋转（rot270 页用 Image.ROTATE_270）否则内容横倒。矢量文字用 insert_text(..., rotate=90/270)，但定位易偏，建议一律走 PNG 路线。
• 墨迹检测被框线污染：检测 clip 必须避开行框线和竖向分隔线（收窄边界、必要时逐列/逐行分析区分 1px 全高线段与稀疏文字）。双线边框尤甚：行上界 +1.5pt 可能仍压在第二条框线上，把整行投影连通成一段——姓名区上界至少留 3.5pt。
• get_cdrawings 三个坑：① 零高/零宽矩形的 Rect.intersects() 返回 False，ROI 预筛要用手工区间判断；② 部分直线输出为 qu 四边形图元（按 bbox 细长判定）；③ re 的 rect 是 tuple 不是 Rect 对象，需转换。速度比 get_drawings 快数倍，大图必用。
• 旋转页（rot 90/270）三套坐标：search_for 与 get_drawings 返回未旋转坐标；get_pixmap(clip=...) 用视觉坐标（未旋转矩形 × page.rotation_matrix）；插入图片前把目标视觉矩形 × page.derotation_matrix 转回未旋转，且 PNG 需预旋转（rot270 页用 Image.ROTATE_270）否则内容横倒。draw_rect 遮盖块同样要 derot，否则旋转页上遮盖画到别处（表现为 xxx 没被盖掉）。矢量文字用 insert_text(..., rotate=90/270)，但定位易偏，建议一律走 PNG 路线。
• 白块遮盖勿压线：先逐行扫描确定占位墨迹与边框线的精确间隙，白块边界取中间；姓名遮盖只动行底条带。
• 日期字号随格高：autofill 按 font_ratio×格高自动算并按填写区宽度封顶；格高 ~17pt 约得 11pt 字。
• 预填日期格式不一致（如"2024.11.6" vs "2024-11-06"）：autofill 的日期遮盖区自动覆盖预填内容并统一为本批日期，向用户说明。
• 同批图纸可能有特例：无图签的裸图（autofill 自动原样复制并报告）、已是成品的图（on_presigned:"skip" 自动识别）、盖章区被文字占用（autofill 取带内最大空白矩形，放不下会警告并按整带落章——需问用户是否接受压字）。
• 并行 Edit 同一文件会互相覆盖（各自 read-modify-write，后写胜出），同一文件的多次编辑必须串行。
• 签名图处理：白底转透明（alpha=255-min(RGB)，硬阈值去纸纹 hard=True 用于签名、soft 用于红章）；红章预倾斜（PIL rotate(角度, expand=True, BICUBIC)）。
• 大图用 run_in_background 跑批，完成后必须做校验，不能只看"完成"输出。

捆绑脚本

• scripts/autofill.py：自适应主工具（推荐）。运行时自动量规 + 置信度自检 + 视觉定位覆写（geometry.manual）+ 按任务 JSON 执行签字/盖章/日期任意组合；--measure/--test/--files/--limit 参数；--measure 输出 measure_report.json；量规失败自动输出右下区域渲染图供视觉定位；已签名自动跳过、无图签自动复制原样。换图框流程见"换图框标准流程"一节。
• scripts/newframe_assist.py：新图框侦察助手（v1.4.0 新增）。cell-grid：自动探测图签条带、逐列分格枚举全部单元格（含墨迹 bbox/参考文本）+ 编号标注渲染图，用于防漏格与 geometry.manual 取数；--shot/--points：用户截图像素坐标 → PDF pt 换算。
• scripts/scan_layout.py：版式扫描器（经典路径第 2 步），通用可直接用。
• scripts/struct_tool.py：结构图实战脚本（手工常量版，含 xxx 替换、旋转页、锚点回退），作兜底模板。
• scripts/sign_tool.py：建筑图实战脚本（多设计人分组、纯签名场景），作参考。