Paper-CAD:在浏览器里搭 3D 建筑,一键生成能打印的纸模型展开图

Paper-CAD 解决的是一个很具体、也很少有人做的需求:把建筑 3D 模型自动展平成可以打印、可以剪、可以折的纸模型图纸。

它在浏览器里跑,你可以在里面建 3D 模型,也可以导入 STEP;定好纸张(A4 / A3 / Letter),它就把模型自动展平成 2D 展开图,输出 SVG 或 PDF,折线和切割线分开、每个面自动编号,打印出来照着折就行。展开计算用的是 OpenCASCADE,不是那种近似投影。

Paper-CAD 工作流:在浏览器里建 3D 模型,自动生成纸模型展开图
从 3D 模型到 2D 展开图,一条流水线

它到底在做什么

纸模型(papercraft)这个圈子一直有个痛点:拿到一个 3D 模型,得靠纸艺软件手动拆面、展开、排布,一个复杂的建筑模型能拆一整天,还容易拆出无法折叠的结构。

Paper-CAD 干的就是这件苦力活。它的流程是:

  1. 读取 3D 模型(自己建的,或者导入 STEP)
  2. 分析面、边、相邻关系
  3. 在展开引擎里做 3D→2D 展开
  4. 在版面上排版,适配纸张尺寸
  5. 导出 SVG / PDF

展开结果里,折线和切割线是分开的,每个面有编号,方便对着说明折。这个细节决定了它是”能用的工具”还是”玩具”。

最有意思的部分:直接导入城市模型

它对接了日本 PLATEAU 项目的 CityGML 数据。你只要输入建筑名,就能把真实存在的建筑导进来,然后展开成纸模——做微缩景观、建筑模型、教学演示,这个路径太顺了。

实现上,CityGML 到 STEP 的转换分了好几个阶段,作者在文档里专门标了顺序不能乱:

  • PHASE 0:坐标重新居中(不做的话精度会掉)
  • PHASE 1:构建 XLink 索引(后面所有引用解析的前提)
  • PHASE 2–6:LOD 抽取 → 几何构建 → 校验
  • PHASE 7:输出 STEP

东京 23 区的 CityGML 数据还能提前下载缓存,处理速度能快 10–50 倍。数据量不小:压缩包 500MB 到 1GB,解压后 2–3GB,所以是个可选项,需要 3–5GB 空闲磁盘。

跑起来试试

前后端分开跑,后端是 Python(FastAPI),前端是 TypeScript。

# 后端
cd backend
conda env create -f environment.yml
conda activate paper-cad
python main.py            # http://localhost:8001

# 前端(另开一个终端)
cd frontend
npm install
npm run dev               # http://localhost:8080

没有网络环境也能演示:用 ENV=local_demo python main.py 加 npm run local_demo,它会读 backend/data/local_demo_cache 里的缓存,离线就能跑设施名搜索、3D Tiles 显示、建筑导入和展开图生成。内置了三个样例:芝浦工大附属、JP TOWER、涩谷 FUKURAS。

不想开界面,直接调接口也行:

curl -X POST \
  -F "file=@building.step" \
  -F "page_format=A4" \
  -F "scale_factor=0.01" \
  "http://localhost:8001/api/step/unfold" \
  -o building.svg

架构:前端 Web 技术栈,几何靠 WASM 和 Python

前端是个 npm workspaces 的 monorepo,拆得挺细:chili-ui 用 Web Components + CSS Modules 做界面,chili-core 管文档/模型/材质/选择,chili-three 接 Three.js 做 3D 绘制,chili-cesium 负责 PLATEAU 的 Cesium 3D Tiles 建筑选取,chili-wasm 是 WebAssembly 绑定。

几何内核这块是 C++ 写的 OpenCASCADE,编译成 WASM 给前端用;真正的展开流水线跑在后端:

step_processor.py
  → file_loaders.py        # STEP/BREP 读取
  → geometry_analyzer.py   # 面/边/邻接分析
  → unfold_engine.py       # 3D → 2D 展开
  → layout_manager.py      # 排版
  → svg_exporter.py        # 输出 SVG
  → pdf_exporter.py        # 输出 PDF

有个坑要注意:OpenCASCADE 没装的话,API 还是能启动,但跟 STEP 展开相关的接口会返回 503。所以环境一定按 environment.yml 建。

来龙去脉

这是个学生项目——2025 年度「未踏ジュニア」(日本未踏 Junior)的入选项目,作者 Soynyuu。前端基于开源 3D CAD 框架 chili3d 派生,所以许可证也跟着是 AGPL-3.0。

star 数不多(十几颗),但工程完成度不低:前后端分离、测试、Docker 部署、离线缓存、API 文档、连落地页都单独做了一套。这种项目通常比 star 数更能说明作者做事的认真程度。

适合谁

  • 做建筑模型、微缩景观、立体地图的手工爱好者
  • 老师想做建筑/城市相关的教具
  • 需要把 BIM 模型快速变成实体展示品的团队
  • 想研究 3D 到 2D 展开算法的人(代码结构清晰,展开引擎是独立模块)

几个前提

  • AGPL-3.0,网络服务也要开源;商用前先看清条款
  • 需要 Python 3.10+(建议 Conda)和 Node.js 18+
  • PLATEAU 相关功能主要针对日本数据,其他地区的 CityGML 要自己做适配
  • 离线演示的三栋楼是预置缓存,换成别的建筑需要联网或者自建缓存

最后

这个项目的有趣之处在于:它没有追什么热门方向,就是老老实实解决”3D 模型怎么变成纸模型”这一件事,而且解决得挺扎实——OpenCASCADE 做展开、面编号、折线切割线分离、按纸张排版,该有的都有。

如果你小时候剪过纸模型,或者现在还在做微缩场景,值得试一下。城市模型直接导入那一手,确实有点爽。

  • 仓库:https://github.com/Soynyuu/Paper-CAD
  • 基础框架 chili3d:https://github.com/xiangechen/chili3d
  • PLATEAU:https://www.mlit.go.jp/plateau/
© 版权声明
THE END
喜欢就支持一下吧
点赞1.6W+ 分享