Files
cad-building-showcase/README.md

88 lines
4.9 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
七条门禁:门禁失败即停下修复,绝不绕过;改动任何脚本后必须跑
`pytest tools/cad-building-showcase/tests/test_contracts.py tools/cad-building-showcase/tests/test_delivery.py`
与 `python3 tools/cad-building-showcase/tests/test_extraction_pipeline.py` 且全绿。
```
**任何其他 Agent 的兜底用法**:把上面那段话作为任务开场白直接粘给它——skill 的全部约定都在 `SKILL.md` 里,脚本自含 CLI(`--help` 可查),不依赖宿主工具的任何私有机制。
**运行依赖**:Python ≥3.10,核心运行 `pip install -r requirements-core.txt`,交付验证再装 `requirements-delivery.txt`;Node ≥18。可选:libredwg、ODA File Converter、Blender、IfcOpenShell。先运行 `python3 scripts/cad_showcase.py doctor` 检查环境。
**跨平台**:脚本全用 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`(决策树与硬门禁),详细分支按需读取 `references/`。推荐统一 CLI:
```bash
python3 scripts/cad_showcase.py inspect --input <cad> --work work/<project> --output outputs/<project>/read_report
python3 scripts/cad_showcase.py run --dxf-dir <dxf> --config <config> --source-report <cad_read_report.json> --out-dir outputs/<project> --name <project> --backend trimesh --web --offline --resume
```
核心链路:
```
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` 有说明)
- `schemas/` extraction config、building spec、variants manifest 的版本化 JSON Schema
- `tests/` 契约/交付测试 + 合成 DXF 全链路回归
- `references/` 当前运行规范;历史复盘移到 `docs/history/`,不再作为 Agent 运行上下文
- `assets/` Web 模板与离线 viewer 内联库
`work/`、`outputs/`、源 CAD 均不入库(见 `.gitignore`),由脚本从源数据再生。
## 验证纪律
```bash
pytest tests/test_contracts.py tests/test_delivery.py
python3 tests/test_extraction_pipeline.py
ruff format --check scripts tests && ruff check scripts tests
npm run check:js
```
已在四套真实图纸上端到端验证:贝昂科技厂区(基线)、黄桥文体中心、13号地块(双塔+酒店厂区)、27号地块(7栋混合厂区)。历史质量对比见 `docs/history/generalization_test_log.md`。