dwg-extraction

DWG 文件提取

从 AutoCAD DWG 文件（包括 Civil 3D）中提取结构化的工程信息。 DWG 是一种专有二进制格式，需要专用工具——本技能负责处理从原始 .dwg 到结构化项目数据的完整流程。

流程概览

提取分为四个阶段：

1. 编译 libredwg — 从源代码构建开源 DWG 读取器（首次运行后会缓存）
2. 转换 DWG → DXF — 使用编译好的 dwg2dxf 二进制文件生成基于文本的 DXF 文件
3. 解析 DXF 实体 — 自定义 Python 解析器提取所有实体类型及其完整属性数据
4. 整理并存储 — 将提取的数据整理到 plans-spatial.json 的各个部分中

我们选择从源代码编译，而不是使用包管理器，原因是 libredwg 在大多数环境中都没有提供 apt 包；而 Python DXF 库（例如 ezdxf）经常会因专有对象生成的 MATERIAL 条目格式错误，无法处理 Civil 3D 的 DXF 输出。本技能中的手动解析器可以妥善处理这些边缘情况。

阶段 1：编译 libredwg

先检查二进制文件是否已存在。如果不存在，则进行编译。

# Check for cached binary
if [ -f /tmp/libredwg/dwg2dxf ]; then
    echo "dwg2dxf binary found, skipping compilation"
else
    # Clone and compile
    cd /tmp
    git clone --depth 1 https://github.com/LibreDWG/libredwg.git
    cd libredwg

    # Write the config.h that works (this was developed through trial and error
    # to handle missing autotools, cmake, and various header conflicts)
    cat > src/config.h << 'CONFIGEOF'
#define PACKAGE "libredwg"
#define PACKAGE_VERSION "0.13"
#define PACKAGE_STRING "libredwg 0.13"
#define LIBREDWG_SO_VERSION "0:13:0"
#define HAVE_STDINT_H 1
#define HAVE_STDLIB_H 1
#define HAVE_STRING_H 1
#define HAVE_STRINGS_H 1
#define HAVE_INTTYPES_H 1
#define HAVE_UNISTD_H 1
#define HAVE_CTYPE_H 1
#define HAVE_WCHAR_H 1
#define HAVE_WCTYPE_H 1
#define HAVE_MEMCHR 1
#define HAVE_MEMMEM 1
#define HAVE_SCANDIR 1
#define IS_RELEASE 1
#define PACKAGE_NAME "libredwg"
#define HAVE_SYS_STAT_H 1
CONFIGEOF

    # Compile library object files
    # Skip in_json.c (needs jsmn.h submodule) and out_geojson.c (additional errors)
    # These are not needed for DWG→DXF conversion
    gcc -c -I. -Iinclude -Isrc -DHAVE_CONFIG_H \
      src/bits.c src/common.c src/classes.c src/codepages.c \
      src/decode.c src/decode_r11.c src/decode_r2007.c \
      src/dwg.c src/dwg_api.c src/hash.c src/dynapi.c \
      src/dxfclasses.c src/out_dxf.c src/out_json.c \
      src/print.c src/free.c src/encode.c -w

    # Compile the dwg2dxf program
    gcc -c -I. -Iinclude -Isrc -DHAVE_CONFIG_H programs/dwg2dxf.c -w

    # Link everything together
    gcc -o dwg2dxf *.o -lm -w

    echo "Compilation complete: $(ls -la dwg2dxf)"
fi

故障排除：如果 libredwg 仓库结构发生变化，所需的关键文件如下：

• src/*.c — 核心库（bits、common、classes、codepages、decode、decode_r11、decode_r2007、dwg、dwg_api、hash、dynapi、dxfclasses、out_dxf、out_json、print、free、encode）
• programs/dwg2dxf.c — 转换程序
• include/ — 头文件
• src/config.h — 必须手动创建（见上文）

阶段 2：转换 DWG → DXF

/tmp/libredwg/dwg2dxf -o /tmp/output.dxf "/path/to/input.dwg"

预计会看到有关未处理 Civil 3D 对象（AcDbSurface、AcDbAlignment 等）的警告—— 这是正常现象，不会影响标准实体的提取。转换会生成基于文本的 DXF 文件，可逐行解析。

检查输出文件是否存在且大小合理（典型的土木场地平面图通常有数 MB）。

阶段 3：解析 DXF 实体

运行随附的解析器脚本。它可以处理土木工程施工图中常见的所有实体类型：

python3 /path/to/dwg-extraction/scripts/parse_dxf.py /tmp/output.dxf /tmp/dxf_extracted.json

解析器提取以下实体类别：

提取的实体类型

实体	DXF 类型	包含内容
测量点	INSERT + ATTRIB + SEQEND	点号、XYZ 坐标、图层分类
文字标注	TEXT	单行标签（标高、构筑物 ID、管道尺寸）
多行文字	MTEXT	施工说明、关键注释、图例
多段线	LWPOLYLINE	等高线、地界线、管线走向
直线	LINE	网格线、尺寸线、引线
圆弧	ARC	半径回弯、曲线要素
圆	CIRCLE	检查井、清扫口、公用设施符号
点	POINT	控制点、地面高程点
填充	HATCH	铺装区域、建筑轮廓、材料填充
块插入	INSERT	符号（检查井、阀门、计量表、树木、设备）

图层命名约定（Civil 3D）

Civil 3D 使用分层图层命名系统。解析器根据图层前缀对实体进行分类， 以便组织提取的数据：

图层模式	类别	典型内容
C-STRM-*	雨水管网	管道、构筑物、进水口、集水口
C-SSWR-*	污水管网	检查井、管道段、清扫口
C-WATR-*	给水	干管、支管、仪表、消防栓
C-TOPO-*	地形	现状等高线、点高程
C-PROP-*	用地	边界、方位角、地役权
C-ROAD-*	道路	路缘石、路面、标线
C-EROS-*	水土流失控制	防淤栅栏、进水口防护、BMP
C-BLDG-*	建筑	建筑轮廓、FFE、退界
C-SITE-*	场地	场地平整、铺装、景观
C-SV$*	测量	测量点、控制点、基准点
C-ANNO-*	注释	尺寸、标签、备注
V-*	现状（可见）	现状公用设施、地物
0 / Defpoints	系统	默认图层、定义点

不符合这些模式的图层仍会被提取，并归类为“其他”。

测量点提取详情

Civil 3D 中的测量点以 INSERT 实体形式存储在测量点图层上 （图层名称通常包含 SV 或 PNT）。每个 INSERT 都有子级 ATTRIB 实体，其中包含点编号。XYZ 坐标取自 INSERT 的插入点（组代码 10/20/30）。

解析器会跟踪 INSERT → ATTRIB → SEQEND 序列，以便正确地将 属性与其父级块关联起来。这一点很重要，因为简单地逐个实体解析 会丢失父子关系。

构筑物邻近分组

公用设施构筑物（检查井、集水口、接线井）的属性 （井盖高程、管底高程、管径）以单独的 TEXT 实体形式存储， 并放置在构筑物符号附近。解析器使用邻近分析对这些实体进行分组：

1. 收集公用设施图层上的所有 TEXT 实体
2. 对于每个文本，查找可配置半径内的所有其他文本（默认值：州平面坐标系英尺制下的 15 个单位）
3. 将附近的文本分组为构筑物记录
4. 解析高程模式（例如，“RIM=739.90'”、“INV=736.62'(12")”）

这种方法解决了 CAD 图纸没有正式“构筑物对象”的问题 — 图纸中的构筑物由单独的文本实体组成，这些实体以视觉方式彼此靠近放置。

阶段 4：整理并存储

解析完成后，将提取的数据整理到 plans-spatial.json 的各个分区中：

数据分区

分区键	内容	源实体
dwg_survey_data	所有测量点的 XYZ 坐标、高程统计数据、控制点	SV/PNT 图层上的 INSERT+ATTRIB
dwg_storm_sewer	雨水构筑物的井盖/格栅/管底高程、管道数据	C-STRM 图层上的 TEXT，按邻近关系分组
dwg_sanitary_sewer	污水检查井的井盖/管底高程、管径、流向	C-SSWR 图层上的 TEXT，按邻近关系分组
dwg_water	水表、消防栓、干管管径	C-WATR 图层上的 TEXT/INSERT
dwg_property	用地边界、方位角、面积、业主、地块图引用	C-PROP 图层上的 TEXT、边界 LWPOLYLINE
dwg_other_utilities	燃气、电力、电信、现场证据备注	V-* 和公用设施图层上的 TEXT
dwg_erosion_control	BMP 关键注释、水土流失控制地物	C-EROS/KYN 图层上的 MTEXT
dwg_grading	点高程、建筑基底、地形分析、路面剖面	C-SITE/C-BLDG 图层上的 TEXT
dwg_contours	等高线数据，含顶点数和高程范围	C-TOPO 图层上的 LWPOLYLINE

加载到 plans-spatial.json

读取现有的 plans-spatial.json，合并新的 dwg_* 分区（重新处理时覆盖 之前的 DWG 数据），然后写回。添加以下元数据：

{
  "dwg_survey_data": {
    "source_file": "filename.dwg",
    "extraction_date": "2026-02-20",
    "coordinate_system": "Kentucky State Plane NAD83 (US Survey Feet)",
    "total_points": 598,
    "elevation_range": {"min": 736.41, "max": 750.20, "unit": "ft"},
    "points": [...]
  }
}

还要更新 project-config.json 中的 documents_loaded，记录 DWG 提取， 并注明填充了哪些数据分区。

与其他技能集成

此技能会向 Foreman OS 的多个其他技能提供数据：

• quantitative-intelligence：DWG 几何数据是工程量计算的优先级 1（精确）数据源
• project-data：所有提取的部分都遵循 plans-spatial.json 架构
• document-intelligence：在 /process-docs 期间检测到 DWG 文件时，应触发此技能
• construction-takeoff：DWG 测量点和等高线提供真实测量数据

从 /process-docs 或 /set-project 调用时，只要在项目文件夹中发现 .dwg 文件，此技能就会自动运行。提取的数据可与其他文档类型（PDF、规格说明、进度表）的数据无缝集成。

Civil 3D 专有对象的限制

DWG 提取流水线使用 libredwg（开源）将 DWG 转换为 DXF，然后使用 parse_dxf.py 提取实体。由于 Autodesk Civil 3D 专有对象采用未公开的内部格式，libredwg 无法对其进行解码。

受影响的对象类型

Civil 3D 对象	DWG 实体类型	包含内容	影响
对齐线	AcDbAlignment	道路中心线、曲线数据、桩号	无法提取道路几何数据或桩号值
曲面	AcDbSurface / AcDbTinSurface	地形模型、等高线、点高程	无法提取现状/拟建标高数据
管网	AcDbPipeNetwork	雨水/污水管线路由、构筑物	无法从管网对象中提取管径、管底标高和检查井信息
道路走廊	AcDbCorridor	道路横断面、装配体	无法提取道路设计细节
地块	AcDbParcel	土地边界、地块线	无法提取地块数据
纵断面视图	AcDbProfileView	纵向对齐线、纵断面标高	无法提取纵断面/标高信息
压力管道	AcDbPressurePipe	供水管网	无法从管网对象中提取供水系统布局

可正常处理的内容

• 完全支持标准 DXF 实体（LINE、POLYLINE、CIRCLE、ARC、TEXT、MTEXT、INSERT、ATTRIB）
• Civil 3D 图纸通常同时包含专有对象和标准实体（标注、注释、填充线）
• 即使在 Civil 3D 文件中，也能提取标准实体的图层名称、文本标签和属性数据
• 块插入（以块形式表示的检查井、阀门、消防栓）可正常处理

解决方法 — 从 AutoCAD 导出干净的 DXF

如果设计团队拥有 AutoCAD Civil 3D，请按以下设置请求导出 DXF：

1. 在 Civil 3D 中使用 EXPORTTOAUTOCAD 命令（不要使用 SAVEAS DXF）
2. 此操作会将 Civil 3D 对象“炸开”为标准 AutoCAD 实体：
   • 对齐线会变为多段线，桩号标签会变为文本
   • 曲面会变为 3D 面或等高线多段线
   • 管网会变为带属性数据的直线/圆
3. 生成的 DXF 可由 parse_dxf.py 完整解析

替代方案：同时请求 PDF 和 DXF

• 请设计团队同时提供 DXF（用于空间数据）和 PDF 图纸（用于标注/细节）
• document-intelligence 从 PDF 中提取文本/表格
• dwg-extraction 从 DXF 中提取几何数据
• 实用设施数据对照（cross-reference-patterns.md 中的模式 7）会合并两个来源

检测

当 parse_dxf.py 遇到未知实体类型时，会将其记录为警告：

WARNING: Skipped entity type 'AcDbAlignment' at handle 0x1A3 (Civil 3D proprietary)
WARNING: Skipped entity type 'AcDbTinSurface' at handle 0x2B7 (Civil 3D proprietary)

如果文件中超过 20% 的实体因专有对象而被跳过，请通知现场主管，并建议向设计团队请求使用 EXPORTTOAUTOCAD 导出的 DXF。

局限性

• Civil 3D 专有对象：详见上方的详细章节。简而言之，libredwg 不会解码以 AcDb* 对象形式存储的曲面、路线、走廊和管网。该技能会提取 Civil 3D 随这些对象一同写入的标准 DXF 实体，其中通常包含所有注释数据（高程、标签、关键注释）。可使用 EXPORTTOAUTOCAD 作为变通方法。
• 3D 实体：复杂的 3D 几何体（ACIS 实体、网格）会被编目，但不会进行深入解析。
• 外部参照（XREF）：该技能仅处理宿主 DWG。如果关键数据位于 XREF 中，则需要将其绑定或作为单独文件提供。
• 块定义：标准块会按名称和插入点提取。自定义块几何体（内部实体）不会递归解析。
• 坐标系：该技能会保留 DWG 使用的坐标系。对于肯塔基州项目，通常为 State Plane NAD83。不会执行坐标转换。