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

它到底在做什么
纸模型(papercraft)这个圈子一直有个痛点:拿到一个 3D 模型,得靠纸艺软件手动拆面、展开、排布,一个复杂的建筑模型能拆一整天,还容易拆出无法折叠的结构。
Paper-CAD 干的就是这件苦力活。它的流程是:
- 读取 3D 模型(自己建的,或者导入 STEP)
- 分析面、边、相邻关系
- 在展开引擎里做 3D→2D 展开
- 在版面上排版,适配纸张尺寸
- 导出 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/









