Files
cad-building-showcase/references/pipeline.md
zhengwr a6ac166049 Initial commit: cad-building-showcase skill
Agent-led CAD-drawing → 3D web showcase pipeline. Inspects CAD reports,
maps layers/floors, extracts a normalized building spec (with block-probed
glazing and audit gates), builds Blender/trimesh GLB variants, and assembles
a Three.js web viewer. Includes XREF-shell detection and a regression test.

Large inputs/outputs (work/, outputs/, source_cad/, renders) are gitignored.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 16:16:04 +08:00

13 KiB

CAD to Web Building Showcase Pipeline

1. Inventory and Conversion

Start by listing source files and preserving names. CAD drawing names often encode floor numbers, building zones, and drawing type.

Recommended workspace layout:

work/
  cad_showcase/
    dxf_raw/
    dxf_sanitized/
    reports/
    building_spec.json
outputs/
  <project>/
    <project>.blend
    <project>.glb
    <project>.png
    web/

For DWG conversion:

dwg2dxf -y -o work/cad_showcase/dxf_raw/A208.dxf "work/XREF/A208 - 主楼首层、二层平面图.dwg"

LibreDWG DXF files may contain 999 comment records. Sanitize before using brittle importers. ezdxf.recover usually tolerates them, but sanitizing keeps the files friendlier to FreeCAD and other tools.

2. CAD Read Report

Run:

python3 <skill>/scripts/cad_dxf_report.py --input work/XREF --work work/cad_showcase --output outputs/cad_read_report

If ezdxf is missing:

python3 -m pip install --target work/vendor ezdxf

Read the report and identify:

  • Which drawings are plans versus elevations/details.
  • Whether the unit scale is probably millimeters or meters.
  • Main modelspace bounding boxes.
  • Layer counts and top layers.
  • Entity types that matter: LINE, LWPOLYLINE, POLYLINE, INSERT, HATCH, TEXT, MTEXT, DIMENSION.

3. Layer Mapping

Default layer heuristics:

Category Common layer names
walls I-WALL, A-WALL, L-SITE-WALL, names containing WALL, 墙
glazing A-GLAZ*, names containing GLAZ, CURT, WINDOW, 幕墙, 玻璃, 窗
roof A-ROOF, A-FLOR-ROOF, A-FLOR-OVHD, names containing ROOF, 屋面, 屋顶, 雨棚
columns S-COLS, names containing COL, COLUMN, 柱
beams S-STRS, S-STRS-MBND, names containing BEAM, 梁, 结构
railings names containing RAIL, HANDRAIL, 栏杆, 扶手
doors names containing DOOR, DR, 门, 开启
detail_lines A-GENM, A-DETL*, parking/area/detail layers that should stay as low plan context
floor_lines A-FLOR, A-FLOR-OVHD, names containing FLOOR, FLOR, 楼面, 地面
grid S-GRID, names containing GRID, 轴网, 轴线

Do not include annotation/dimension/text layers in geometry categories unless the user wants a drawing-like overlay.

4. Floor Detection and Alignment

Many architectural sheets place multiple floor plans side by side. Do not assume one DWG equals one floor.

Use this order of evidence:

  1. File name and drawing title.
  2. Text labels in modelspace/paperspace.
  3. Large separated plan clusters in the drawing bounding box.
  4. S-GRID or equivalent structural axis layers.
  5. Repeated column/grid patterns across floors.

For side-by-side plans, create a config with one floors[] entry per floor, each with a source clip rectangle and optional offset.

Example:

{
  "project_name": "Main Building",
  "scale": 0.001,
  "origin_strategy": "center",
  "floor_height": 4.2,
  "curve_chord_source_length": 750,
  "expand_blocks": false,
  "expand_blocks_max_depth": 2,
  "block_insert_layer_fallback": true,
  "generate_footprints": true,
  "use_footprint_slabs": true,
  "use_footprint_roofs": true,
  "footprint_categories": ["walls", "glazing", "floor_lines", "railings", "columns"],
  "footprint_concave_ratio": 0.85,
  "footprint_simplify_tolerance": 0.12,
  "slab_thickness": 0.38,
  "default_disabled_categories": [],
  "shorten_unsupported_columns": true,
  "shorten_unsupported_columns_floor_keys": ["1F"],
  "unsupported_column_height": 1.2,
  "column_support_distance": 0.55,
  "column_support_requires_upper_plate": true,
  "column_support_allow_plate_only": false,
  "block_name_categories": {
    "walls": ["*WALL*", "*墙*"],
    "glazing": ["*GLAZ*", "*CURT*", "*幕墙*", "*玻璃*"],
    "columns": ["*COL*", "*柱*"],
    "beams": ["*BEAM*", "*梁*"]
  },
  "min_length_meters_by_category": {
    "walls": 0.25,
    "columns": 0.18,
    "beams": 0.35,
    "floor_lines": 0.40,
    "grid": 1.0
  },
  "drawings": [
    {
      "file": "A208.dxf",
      "split_x": 0,
      "floors": [
        {"key": "1F", "name": "首层", "side": "left"},
        {"key": "2F", "name": "二层", "side": "right", "offset": [-158029.255, 0]}
      ]
    }
  ],
  "layers": {
    "walls": ["I-WALL", "A-WALL", "L-SITE-WALL"],
    "glazing": ["A-GLAZ*"],
    "roof": ["A-ROOF", "A-FLOR-ROOF"],
    "columns": ["S-COLS"],
    "beams": ["S-STRS", "S-STRS-MBND"],
    "railings": ["*RAIL*"],
    "doors": ["*DOOR*", "*DR*"],
    "detail_lines": ["A-GENM", "A-DETL*", "*PRKG*", "A-AREA"],
    "floor_lines": ["A-FLOR", "A-FLOR-OVHD"],
    "grid": ["S-GRID"]
  },
  "roof_specs": [
    {
      "floor_key": "RF",
      "bounds_from": ["RF"],
      "footprint_from": ["RF"],
      "thickness": 0.35,
      "margin": 0.4
    }
  ]
}

In the A208 test project, 1F and 2F were on the same sheet and the second floor required an X shift of about -158029.255 mm to align the grids. Treat this as an example, not a constant.

Use origin_strategy: "center" for large CAD coordinates. It mirrors the A208 proven workflow and keeps Blender/Web coordinates numerically stable.

Use clip rectangles for irregular sheet layouts. Use split_x plus side when a sheet cleanly places plans left/right; this is less likely to accidentally cut off geometry than a tight clip rectangle.

Keep expand_blocks false for the first pass. If the audit shows important geometry in INSERT, set expand_blocks to true or to a list of block-name patterns, then rerun extraction/audit/overlays. When virtual block entities live on layer 0, block_insert_layer_fallback: true lets the parent INSERT layer participate in category matching.

5. Spec Extraction

Run:

python3 <skill>/scripts/derive_showcase_spec.py --dxf-dir work/cad_showcase/dxf_sanitized --config work/cad_showcase/config.json --out work/cad_showcase/building_spec.json

Review building_spec.json before rendering:

  • Floors are ordered correctly.
  • Bounds are plausible in meters.
  • Each major floor has nonzero walls, columns, and grid or floor_lines.
  • Segment counts are not dominated by dimensions/hatches/annotations.
  • Footprint polygons exist when slabs/roofs are meant to follow CAD floor plates.
  • default_disabled_categories does not hide slab for presentation/digital-twin views.

6. Agent Audit and Overlay Review

Do not proceed to Blender until the Agent has reviewed extraction evidence.

Run the audit:

python3 <skill>/scripts/audit_showcase_extraction.py \
  --dxf-dir work/cad_showcase/dxf_sanitized \
  --config work/cad_showcase/config.json \
  --spec work/cad_showcase/building_spec.json \
  --out work/cad_showcase/extraction_audit \
  --vendor-dir work/vendor

Generate 2D overlays:

python3 <skill>/scripts/draw_coverage_overlay.py \
  --dxf-dir work/cad_showcase/dxf_sanitized \
  --config work/cad_showcase/config.json \
  --spec work/cad_showcase/building_spec.json \
  --out-dir work/cad_showcase/overlays \
  --vendor-dir work/vendor

Agent review rules:

  • Treat INSERT, HATCH, ACAD_PROXY_ENTITY, SOLID, 3DFACE, and large unclassified layers as potential missing-model risks.
  • Open overlay SVGs. Gray means source vectors already classified, red dashed means source vectors not classified, color means extracted model geometry.
  • If red dashed geometry forms walls, columns, beams, stairs, grids, or floor outlines, update layer mapping or parser strategy and rerun extraction.
  • If frequent blocks appear in the audit, inspect block names and decide whether to recursively explode block geometry.
  • If hatches carry wall/slab/column information, do not rely only on line extraction.
  • Continue only when missing geometry is acceptable for the requested output level.

7. Blender Generation

Run:

/Applications/Blender.app/Contents/MacOS/Blender -b \
  --python <skill>/scripts/build_blender_showcase.py -- \
  --spec work/cad_showcase/building_spec.json \
  --out-dir outputs/<project> \
  --name <project>

Expected outputs:

  • <project>.blend
  • <project>.glb
  • <project>.png
  • model_metadata.json

If Blender CLI fails, verify the path. On this machine, the app path has been:

/Applications/Blender.app/Contents/MacOS/Blender

8. Web Showcase

For a quick single-model preview, run:

python3 <skill>/scripts/write_web_showcase.py \
  --template <skill>/assets/web-showcase-template \
  --glb outputs/<project>/<project>.glb \
  --metadata outputs/<project>/model_metadata.json \
  --out-dir outputs/<project>/web \
  --title "<project> Web 展示模型"

For Web or digital-twin presentation, generate three reusable variants and let the Web writer consume the manifest:

python3 <skill>/scripts/build_showcase_variants.py \
  --spec work/cad_showcase/building_spec.json \
  --out-dir outputs/<project>/variants \
  --name <project> \
  --build \
  --blender /Applications/Blender.app/Contents/MacOS/Blender

python3 <skill>/scripts/write_web_showcase.py \
  --template <skill>/assets/web-showcase-template \
  --variants-manifest outputs/<project>/variants/variants_manifest.json \
  --out-dir outputs/<project>/web \
  --title "<project> Web 展示模型"

npm install --prefix outputs/<project>/web three@0.181.2 lucide@0.468.0
python3 -m http.server 8188 --directory outputs/<project>/web

The manifest path makes standard the default model.glb, copies overview.glb, standard.glb, and detail.glb, and writes model_variants for the download controls.

Use another port if 8188 is occupied.

Notes:

  • GLBs are Draco-compressed (Blender built-in, or post-process with node tools/compress.mjs in.glb out.glb). npm install three ships the matching decoder under node_modules/three/examples/jsm/libs/draco/; the template already registers a DRACOLoader pointing there, so no CDN is needed.
  • The template is glTF-standard Y-up. If you swap in a Z-up GLB the building will render lying down — keep GLB and viewer on the same up-axis.
  • write_web_showcase.py stamps a ?v=<build> token on app.js / model.glb / model_metadata.json to defeat browser caching; if a user reports "no change after rebuild", confirm the served folder and hard-refresh.

9. Verification

Run the Blender-free QA pass first, then eyeball the previews before opening the Web viewer:

python3 <skill>/scripts/verify_showcase.py \
  --spec work/cad_showcase/building_spec.json \
  --glb outputs/<project>/variants/overview.glb outputs/<project>/variants/standard.glb outputs/<project>/variants/detail.glb \
  --out outputs/<project>/verify_previews.png --budget-mb 0.6

It prints per-floor segment/cap/glazing-continuity counts and a GLB size-budget pass/fail, and writes front/side/plan orthographic previews. Use these to catch missing floors, a lying-down (wrong up-axis) model, uncapped columns, or discontinuous glazing before declaring the model done — early visual verification avoids most rework.

Minimum verification:

  • Preview PNG is nonblank, building is framed, and floors are visible.
  • GLB file exists and has reasonable size.
  • Browser loads the Web viewer with zero console errors.
  • Floor toggles, component toggles, explode slider, section slider, presets, screenshot, and GLB download work.
  • Variant download links exist for overview, standard, and detail when the task is Web/digital-twin presentation.
  • Slabs are visible from side views; transparent glazing should not make floor plates look missing.
  • Roof caps do not visibly overrun unrelated lower floor footprints.
  • Ground-level columns that have no upper support are not left full-height without explanation.
  • Mobile viewport around 390 px wide has no incoherent overlap.
  • Extraction audit is attached or summarized, including high-risk entity counts and unclassified layers.
  • Overlay review result is stated: accepted, accepted with known gaps, or rejected and iterated.

For BIM branch:

  • Validate IFC schema with IfcOpenShell.
  • Count IfcBuildingStorey, IfcSlab, IfcWall, IfcColumn, IfcBeam, and property sets.
  • Run geometry extraction on all products.
  • Do not claim BIM replacement unless semantic and geometric validation has passed.

Generate IFC:

python3 <skill>/scripts/build_ifc_poc.py \
  --spec work/cad_showcase/building_spec.json \
  --out-ifc outputs/<project>/<project>_bim_poc.ifc \
  --out-report outputs/<project>/<project>_bim_poc_report.json \
  --out-notes outputs/<project>/<project>_bim_poc_notes.md \
  --vendor-dir work/vendor \
  --validate-geometry

Render IFC geometry when Blender cannot import IFC directly:

python3 <skill>/scripts/extract_ifc_meshes.py \
  --ifc outputs/<project>/<project>_bim_poc.ifc \
  --out work/cad_showcase/<project>_ifc_meshes.json \
  --vendor-dir work/vendor

/Applications/Blender.app/Contents/MacOS/Blender -b \
  --python <skill>/scripts/render_ifc_meshes_blender.py -- \
  --meshes work/cad_showcase/<project>_ifc_meshes.json \
  --out-dir outputs/<project> \
  --name <project>_ifc_render