Files
cad-building-showcase/README.md
zhengwr a6856f903d Windows support: install-path probing + platform notes
- Blender discovery adds the Windows versioned install dir (Program Files/
  Blender Foundation/Blender */blender.exe); ODA adds Program Files/ODA
  (both still env > PATH first; shutil.which resolves .exe via PATHEXT)
- README cross-platform section: pathlib + explicit UTF-8 I/O + bytes-decoded
  subprocesses throughout; Windows advice (PYTHONUTF8=1, LongPathsEnabled,
  ODA as the primary DWG path since libredwg is rare there)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-04 15:10:44 +08:00

78 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# cad-building-showcase
把中国建筑施工图(DWG/DXF,天正 t3/t8 导出为主)自动转成可交互的 3D 展示模型(GLB + 离线单文件 Web viewer),并支持多栋厂区按总平面装配。Agent-led:脚本负责证据与可重复执行,判读权在 Agent;任何门禁失败即停,不静默出错模型。
## 安装到 Agent CLI
`SKILL.md` 自带 frontmatter(`name`/`description`),符合 Anthropic skill 格式;本仓库即 skill 本体,克隆即装。
**Claude Code**(原生 skill 机制,自动发现与触发):
```bash
# 全局(所有项目可用)
git clone ssh://git.latent.chat/zhengweirong/cad-building-showcase.git \
~/.claude/skills/cad-building-showcase
# 或装进单个项目
git clone ... <project>/.claude/skills/cad-building-showcase
```
装好后对 Claude Code 说"把这套 DWG 做成 3D 展示模型"即可自动触发,或显式 `/cad-building-showcase`。
**opencode / Codex CLI / 其他 AGENTS.md 系工具**(无 skill 机制,用指令文件指路):
```bash
git clone ... tools/cad-building-showcase # 克隆到项目内任意位置(或 git submodule)
```
然后在项目的 `AGENTS.md`(opencode、Codex 都读它)加一段:
```markdown
## CAD → 3D 展示模型
处理 DWG/DXF 转 3D/Web 展示任务时,必须先完整阅读
tools/cad-building-showcase/SKILL.md 并遵守其中 One-Shot Definition of Done
七条门禁:门禁失败即停下修复,绝不绕过;改动任何脚本后必须跑
`python3 tools/cad-building-showcase/tests/test_extraction_pipeline.py` 且全绿。
```
**任何其他 Agent 的兜底用法**:把上面那段话作为任务开场白直接粘给它——skill 的全部约定都在 `SKILL.md` 里,脚本自含 CLI(`--help` 可查),不依赖宿主工具的任何私有机制。
**运行依赖**:Python ≥3.10 + `ezdxf`(惯例装到 `pip install --target work/vendor ezdxf`)、`shapely`、`trimesh`、`matplotlib`;Node ≥18(`tools/compress.mjs`、无原生转换器时的 WASM DWG 兜底)。可选:libredwg(`dwg2dxf` 批量转换)、ODA File Converter(坏件/天正大图兜底,脚本自动调用)、Blender(高保真渲染分支)。
**跨平台**:脚本全用 pathlib + 显式 UTF-8 I/O + 子进程 bytes 解码,macOS/Linux/Windows 均可跑。工具发现顺序:Blender = env `BLENDER` → PATH → 平台安装默认(macOS 应用包 / Windows `Program Files\Blender Foundation`);ODA = env `ODA_CONVERTER` → PATH → 平台默认(Windows 含 `Program Files\ODA`)。Windows 建议:设 `PYTHONUTF8=1`(防重定向输出按 GBK 解码)、开启 LongPathsEnabled(中文长文件名的深层 work/ 目录可能触及 260 字符 MAX_PATH);Windows 上 libredwg 少见,DWG 转换以 ODA 为主路径。
## 用法
入口是 `SKILL.md`(操作手册):决策循环、One-Shot Definition of Done 七条门禁、天正图层方言预设、多栋厂区流程。核心链路:
```
cad_dxf_report.py 读图报告(警告:多框图纸/缓存XREF/陌生图层方言…)
detect_sheet_frames.py 图框检测(图签块定框、网格投票/墙剖面互相关对齐、
多层图名展开、逐框标高梯+层高建议)
derive_showcase_spec.py 按 config 提取 building_spec.json(分簇 footprint/楼板/顶盖)
audit_showcase_extraction.py 硬门禁审计(楼层对齐+跨层基准、幕墙、框收支表、
面积/层数互证…),FAIL 即退出码 3
spec_to_glb.py GLB 生成;write_offline_viewer.py 离线单文件 viewer
register_site_outlines.py / massing_from_outline.py / assemble_campus.py
总平面配准(点-边ICP)、无图纸楼体量、厂区装配
```
## 目录
- `scripts/` 全部流水线脚本(自含 CLI,`--help` 有说明)
- `tests/test_extraction_pipeline.py` 回归套件(改任何脚本后必跑)
- `references/` 案例记录与校准资料:`pipeline.md`(详细流程)、
`generalization_test_log.md`(泛化测试与缺口修复清单)、
`贝昂CAD诊断与skill优化.md`(首个案例全程)
- `assets/` Web 模板与离线 viewer 内联库
`work/`、`outputs/`、源 CAD 均不入库(见 `.gitignore`),由脚本从源数据再生。
## 验证纪律
```bash
python3 tests/test_extraction_pipeline.py # 必须全绿
```
已在四套真实图纸上端到端验证:贝昂科技厂区(基线)、黄桥文体中心、13号地块(双塔+酒店厂区)、27号地块(7栋混合厂区)。质量对比表见 `references/generalization_test_log.md`。