CAD 矢量 PDF/DXF 怎么读到毫米级精度?house-plan-designer 的 cadvec.py 实现详解

原创2026-11-15 21:23:501,842 阅读

CAD 矢量 PDF/DXF 怎么读到毫米级精度?house-plan-designer 的 cadvec.py 实现详解

house-plan-designer 是一个把一张户型图或 CAD 图纸还原成 2D/3D 装修设计器网页(单文件 HTML、离线可用)的开源项目。它的 CAD 路线脚本 scripts/cadvec.py 直接读取矢量 PDF / DXF 的图元坐标,不靠像素识图,墙体误差可控制在 5mm 以内,墙厚、洞口、开间进深还能逐段等于图纸上的标注数字。本文拆解它是如何做到毫米级精度的。

先分清图纸类型:矢量走 cadvec,位图走 analyze

精度差距的根源在于输入。矢量图纸里每一条墙线、每一个标注数字都是带坐标的图元;扫描件里它们只是像素。所以项目先按输入类型分路线:

输入类型 特征 识别脚本
CAD 导出的矢量 PDF 放大不糊、能选中线条 scripts/cadvec.py(mm 级)
DXF CAD 软件「另存为 DXF」 cadvec.py(自带单位,不用比例)
DWG 二进制读不了 先另存为 DXF 再走 CAD 路线
扫描件 / 截图 / 纯位图 PDF 放大有像素 渲染成图片后用 scripts/analyze.py
一页并排几层、墙线在交接处断开 cadvec 报「没认出墙厚」 scripts/cadsplit.py

判断 PDF 是否为矢量很简单:用 fitz 读一下 get_drawings(),图元几千上万个就是矢量图。完整的路线选择表见 reference/cad-conventions.md 开头。

带完整尺寸标注链的户型图输入样例:外墙三道尺寸、分段标注清晰,正是 cadvec.py 识别的理想输入

上面这种「尺寸链齐全」的图纸,正是 cadvec 精度发挥最大的场景——图上每一段标注都会参与坐标校准。

一条命令启动识别:cadvec.py 用法与关键参数

📐 安装依赖(pip install numpy opencv-python pymupdf ezdxf)后,最小用法只有一行:

python scripts/cadvec.py 图纸.pdf --out 工作目录/cad
python scripts/cadvec.py 图纸.dxf

PDF 是「纸面单位」(1pt = 0.3528mm),比例从哪来?按优先级有 4 种方式,详见 reference/route-cad.md:

参数 含义 什么时候用
(不加参数) 自动从尺寸标注数字里核对比例 图上标注齐全时,首选
--total-width 10540 最外道总尺寸(墙体外皮,mm) 标注读不出来时的兜底
--ratio 100 已知出图比例 1:100 出图比例已知
--scale 22.242 直接指定 mm/pt 已人工量过一次

DXF 自带 $INSUNITS 单位(毫米/米/英寸自动换算),完全不用比例参数。其他常用参数:--bearing-min(实心墙厚度 ≥ 该值记承重,默认 180mm)、--hatch-as(填充墙算新砌墙还是原墙)、--max-opening(多宽的墙线断口算门窗洞口,默认 4200mm)。

实现拆解:从「图元」到「墙」的五步流水线

第一步:统一读取所有图元

cadvec 把两种来源都归一化成四种东西:填充多边形、描边折线、圆弧、文字(scripts/cadvec.py):

  • PDF:贝塞尔曲线按 8 段打平展开成折线;文字取 get_text('words')。若这一页只有位图,脚本会直接退出并提示改用 analyze.py。
  • DXF:块(INSERT)递归展开(最深 6 层);HATCH 图案填充单独标记;DIMENSION 标注直接读测量值(文字被改写过时以文字为准);图框、标题栏、指北针等图层整层跳过。
  • DXF 的 y 轴朝上,统一翻转为「y 向南」,和户型描述方向一致。
  • 黑底图纸(CAD 模型空间截图、深色打印):识别出铺满页面的深色背景并自动反相——浅色填充才是墙。

第二步:坐标压缩,把实心填充切成「零误差」墙段

这是精度声明「不靠像素识图」的底气所在。实心填充(涂黑的承重墙、灰填的原墙)不经过任何栅格化猜测,而是在 rect_pieces 里做坐标压缩:

  1. 收集所有顶点的 x/y 去重排序,得到一张「精确网格」,网格步长 EPS 取全图跨度的 2e-5,只用于合并浮点毛刺,不改变坐标;
  2. 同一路径里的多个闭合圈按奇偶规则填充(带洞的形状、文字框不会误成实心块),不同路径取并集;
  3. 把每个格子所在的水平/竖直连续段实际长度算出来,横截面一致的相邻列合并,横截面变化处(墙垛、L 形)自动断开。

切出来的每一段墙都带着图纸原始坐标,这一步没有任何像素误差。同时脚本还会统计「典型墙厚 T」——实心墙段里按长度加权最常见的厚度,后面几乎所有判断(窗不厚于墙、描边墙厚度范围、起止符号大小)都以它为标尺。

第三步:找尺寸线——先量,再读

识别 45° 起止符号 是读尺寸的第一步:直线上落着 ≥2 个 45° 短斜杠的长线就是尺寸线,斜杠位置就是刻度。细节处理很讲究:

  • 起止符号大小必须和墙厚同量级(墙厚的 0.1~1.6 倍),先把文字碎片、填充短线滤掉;
  • 一个斜杠常由两三个小三角形拼成,中心挨得很近的合并取平均;
  • 尺寸线可能被拆成多段,按位置合并刻度;相邻太近的刻度去重;
  • 每个刻度还找它的尺寸界线——过刻度、垂直于尺寸线的那根线,另一头就是被量的墙面位置。这一步决定了后面「墙面吸到哪个刻度」。

尺寸线和尺寸界线从此被隔离出去,不参与找墙;找墙只在「实心墙包围盒外扩 2 个墙厚」的范围内进行,图框、图例、文字自然被排除。

第四步:平行线配对成墙带,分清墙 / 窗 / 门

描边画法(两条粗实线中间留白)的墙在这里被还原(scripts/cadvec.py):

  1. 同方向直线段两两配对:间距落在 0.3~1.75 倍墙厚之间、沿线有足够重叠 → 一个「墙带」;
  2. 带里的内容决定类型:细短线密度高 = 填充新砌墙;中间还有 1~2 条平行线 = 窗(两条错开各占一半 = 推拉窗);空的 = 描边隔墙;
  3. 抗干扰靠拓扑:窗带、描边墙带的两端必须接到已有的实墙或填充墙上,家具、洁具、柜子的轮廓线就这样被排除;窗必须开在某条实墙的墙线上(外墙上的窗则两侧接墙且外侧空旷 = 飘窗候选)。

第五步:串成墙线,逐段判断门窗

同一条中线(或一侧墙面齐平)的墙段串成一条墙线,并排两层(砖砌内衬 + 混凝土)合成一面复合墙;段间断口 ≤150mm 视为接缝不是洞口。真正的洞口交给 classify_gap 按图元分类,规则完全对应国标画法:

断口里的图元 判定
90°/45° 开启弧线(弧心 = 门轴) 平开门,弧在哪侧往哪侧开;两段弧 = 双开 / 子母门
一条垂直于墙的短扇线 门扇(关闭画法,多见于入户门)
两条错开的半扇门线 推拉门
什么都没有 门洞(原始结构图,装修时一般装门)
彩色矩形框 拆改图里的新开洞口
3~4 条平行细线 窗(中间错开两段 = 推拉窗;窗外凸出一圈 = 飘窗提示)

每个洞口都带一个 why 字段写明判断依据,比如「开启弧线 ×1,半径 900」「断口里 3 条平行线 = 窗」——核对时一眼看出脚本凭什么这么判。

墙线端点最后做一遍「整理」:自由端吸附到相交墙中线;被接上的墙没画到交点就延长;两端顶着垂直墙的短空当识别成靠墙角的门洞;顶着结构柱的墙穿过去;错位的平行墙补一小段横墙接上。

毫米级精度的核心:以标注数字为准,不是以图形为准

这是 cadvec 和普通「量图形 × 比例」做法的本质区别(scripts/cadvec.py)。CAD 图上画的线和标注常差几毫米(量房图更常见:先量好数字再画图),所以脚本的原则是——有标注的地方,墙面、洞口边、墙厚严格等于标注值;标注之间才按比例插值。

具体分四层:

  1. 读标注数字。有文字层直接读;没有文字层(SHX/TrueType 字体炸成轮廓,最常见)就调用 scripts/dimtext.py 做「字形破译」:同一张图里同一个数字的字形完全一样 → 按形状聚类,再用每段量出的长度投票「哪一类字形是哪个数字」,挤在一起的两个数字("390120")会拆开分给相邻两段;读出的数字和图形差超过 12mm / 0.8% 的整段不用。
  2. 每方向加权最小二乘。把所有标注段当成「刻度节点之间的距离约束」,build_axis 解出每个刻度的 mm 坐标。权重体现优先级:外墙外侧分段最细的那道(门窗细部尺寸)> 轴线尺寸 > 总尺寸 > 室内细部尺寸;明显读错的数字(残差 >25mm 或 2%)自动剔除后重解。
  3. 15mm 吸附。墙面、洞口边离某个刻度 15mm 以内,就直接取该刻度的标注值(图上线和刻度常差几毫米);有多个刻度够得着时,优先看哪个刻度的尺寸界线真的伸到了这面墙。
  4. 0.5mm 输出精度。坐标按 R5 精确到半毫米——245、225 这种奇数墙厚的中线落在半毫米上,两侧墙面才是整数毫米。

图纸自己前后矛盾的地方(分段加起来 12070、总尺寸写 12060;两道尺寸量同一段一个 2770 一个 2775)不会被强行抹平,而是如实列进输出的 dim_conflicts,按「细部尺寸优先」处理,交付时逐条告诉用户。

国标图例:cadvec 怎么「看懂」一张建筑图

识别规则依据《房屋建筑制图统一标准》GB/T 50001、《建筑制图标准》GB/T 50104 和装修图惯例(完整 30 条图例表见 reference/cad-conventions.md):

图上画法 含义 cadvec 的处理
涂黑的墙 / 柱 钢筋混凝土(剪力墙、柱) 实心 → 厚 ≥ --bearing-min 记承重
灰色实心填充 非承重原墙 非承重原墙
砖纹 / 斜线 / 网格填充 新砌墙(装修图惯例) status: new
两条粗实线中间留白 轻质隔墙 / 砌体墙 非承重
墙线 3~4 条平行细线 窗 窗 / 推拉窗 / 飘窗提示
断口 + 90° 开启弧线 平开门 弧心 = 门轴,带开向
方框 + 对角线(⊠/╱) 烟道 / 风道 / 管井 结构 shaft
圆 + 十字(⊕) 地漏 结构 drain
墙外直线 + 45° 斜杠 尺寸线 刻度参与坐标校准
单点长画线 + 圆圈编号 定位轴线 axes(DXF 按图层名识别)

DXF 还会利用图层名(WALL / WINDOW / DOOR / COLUMN / AXIS / DIM,家具洁具层排除)做二次校验;文字层里的房间名(卧室、客厅…)、门窗编号(M0921 / C1515,后四位 = 宽高,分米)、「离地 900 / H:1300」(窗台高、窗高)都会读进结果。

跑完看四个文件:核对识别结果的方法

输出在 <图纸名>_cad/ 目录,交付前核对就看这四个文件:

文件 看什么
cad.json 比例来源 scale_from、多源交叉验证 scale_check(width/height/dim_text/dims_read 应当一致);墙段 P、墙线 W、洞口 O(带 why);dims[].labels(读出的数字)和 segs(最终坐标量出的长度)逐段相等才算对上;dim_conflicts 图纸自相矛盾清单
draft.json HouseSpec 初稿:墙(含 flush/status/bearing)、门窗(平开门带 hinge/into)、管井/地漏/柱、房间名、底图——基本可直接用,补房间名和门开向后进入设计器
cad.png 核对图:1m 毫米网格 + 墙段按类型着色(红 = 实心承重、紫 = 填充新砌、绿 = 描边隔墙、蓝 = 窗带)+ W/O 编号 + 尺寸刻度;背景坐标直接就是 mm
underlay.png 底图(PDF 按 200dpi 渲染 / DXF 把线画出来),比例和位置已写好

draft.json 导入设计器后的 2D 平面:尺寸链完整、房间标注面积,可逐段对照图纸标注核对精度

生成结果与原图叠加对比:原图纸尺寸链和设计器尺寸链同时可见,毫米级偏差一眼可查

识别还原后的 3D 鸟瞰视图:毫米级坐标直接进入 3D 设计

实测数据:精度到底多少?

reference/route-cad.md 记录了自带回归用例的实测结果:

  • 装修公司原始结构图 PDF:101 段标注读出 100 段,94 段与设计器尺寸差 ≤1mm,其余 6 段全部是图纸自身矛盾;
  • 另一份原始结构图 PDF:墙体与手工逐面量取一致(≤10mm),16 个洞口全部识别、类型正确;
  • 建筑 CAD 插件图层的 DXF(门弧、图案填充、标注全齐):往返 16/16、墙体 0 误差;
  • 黑底打印的 PDF:墙体全对。

✅ 对使用者的实际意义:交付后拿图纸上的数字逐个对设计器,「和图形差不多」不算数,墙厚、每段墙、洞口、开间进深都必须等于标注——这正是 cadvec 的设计目标。

cadvec 搞不定时:三条兜底路线

症状 兜底方案
报「没认出墙厚」/ 墙只认一半 / 一页并排几层 scripts/cadsplit.py:按楼层切开、描边墙识别、各层对齐(PDF 加 --ref-dim 最外道总尺寸)
墙只靠线色 / 线宽区分、数字炸成线条 scripts/cadpair.py:按线色分层、平行线配墙、灰块认柱、多页共用原点
扫描件 / 截图 / 位图 PDF scripts/analyze.py:渲染成图片走像素路线,按标注定位

兜底路线的详细操作、图层色选择、人工核对要点分别在 reference/route-cad.md 和 reference/route-image.md。

小结

cadvec 的毫米级精度不是「高分辨率渲染 + 像素测量」,而是四条原则叠加:读矢量图元原始坐标(零像素误差)→ 实心填充坐标压缩切墙段 → 标注数字建立分段坐标映射(最小二乘 + 15mm 吸附 + 0.5mm 精度)→ 国标图例规则判门窗符号。初稿出来后还有 cad.png 核对图和 dim_conflicts 矛盾清单兜底,图纸自己矛盾的地方也如实报告。

想完整走一遍「CAD 图纸 → 装修设计器」的流程,从 SKILL.md 的路线选择表读起,识别规范查 reference/cad-conventions.md,整体项目能力看 README.md。

登录后查看全文
house-plan-designer