本项目是一个建筑模型专用的 3D 模型转换技术栈，确保：
✅ 顶点精确映射 - 双精度坐标，无损转换
✅ 平面关系保持 - 完整拓扑结构，边面关联
✅ 渲染指令正确 - 法线、UV、材质完整
✅ 格式互操作 - OBJ/STL/MSH/Blend/MAX/SKP 等通过中间格式转换
✅ 建筑语义保留 - 墙、楼板、柱等建筑元素识别
用于将各种 3D 建模软件（Blender、SketchUp、3ds Max、有限元分析软件等）生成的建筑模型转换为 Three.js 可用的格式。
| 格式 | 扩展名 | 来源软件 | 特点 |
|---|---|---|---|
| Blender | .blend, .fbx, .gltf, .glb | Blender | 原生支持，包含完整场景信息 |
| 3ds Max | .max, .fbx, .obj | 3ds Max | 工业标准，材质丰富 |
| Maya | .ma, .mb, .fbx, .abc | Maya | 动画支持优秀 |
| Cinema 4D | .c4d, .fbx | Cinema 4D | 运动图形友好 |
| SketchUp | .skp, .dae | SketchUp | 建筑建模常用 |
| 格式 | 扩展名 | 来源软件 | 特点 |
|---|---|---|---|
| OBJ | .obj | 通用格式 | 简单，广泛支持 |
| STL | .stl | CAD/3D打印 | 三角网格，无材质 |
| PLY | .ply | 扫描/点云 | 支持颜色信息 |
| VTK | .vtk | ParaView/VTK | 科学可视化 |
| INP | .inp | Abaqus | 工程分析专用 |
| MSH | .msh | Gmsh | 网格生成 |
| CGNS | .cgns | CFD软件 | 计算流体力学 |
| 格式 | 扩展名 | 来源软件 | 特点 |
|---|---|---|---|
| STEP | .step, .stp | CAD软件 | 精确几何 |
| IGES | .igs, .iges | CAD软件 | 通用交换 |
| DXF | .dxf | AutoCAD | 2D/3D混合 |
-
GLTF/GLB (推荐)
- 现代标准，支持 PBR 材质
- 支持动画、骨骼、变形目标
- 二进制 GLB 为单文件
-
Three.js JSON
- Three.js 原生格式
- 直接加载，无需解析
-
Optimized GLB
- Draco 压缩
- KTX2 纹理压缩
- Meshopt 优化
model_converter/
├── README.md # 本文件
├── requirements.txt # Python 依赖
├── package.json # Node.js 依赖
├── config/
│ ├── converter.yaml # 转换配置
│ ├── formats.yaml # 格式支持配置
│ └── optimization.yaml # 优化参数配置
├── src/
│ ├── __init__.py
│ ├── core/
│ │ ├── __init__.py
│ │ ├── converter_engine.py # 核心转换引擎
│ │ ├── format_registry.py # 格式注册中心
│ │ ├── pipeline_manager.py # 流水线管理
│ │ └── optimization_engine.py # 优化引擎
│ ├── parsers/
│ │ ├── __init__.py
│ │ ├── base_parser.py # 解析器基类
│ │ ├── blender_parser.py # Blender 文件解析
│ │ ├── obj_parser.py # OBJ 解析
│ │ ├── stl_parser.py # STL 解析
│ │ ├── fbx_parser.py # FBX 解析
│ │ ├── ply_parser.py # PLY 解析
│ │ ├── vtk_parser.py # VTK 解析
│ │ ├── step_parser.py # STEP 解析 (CAD)
│ │ └── fea/
│ │ ├── __init__.py
│ │ ├── abaqus_parser.py # Abaqus INP
│ │ ├── gmsh_parser.py # Gmsh MSH
│ │ └── cgns_parser.py # CGNS
│ ├── converters/
│ │ ├── __init__.py
│ │ ├── base_converter.py # 转换器基类
│ │ ├── mesh_converter.py # 网格转换
│ │ ├── material_converter.py # 材质转换
│ │ ├── animation_converter.py # 动画转换
│ │ └── scene_converter.py # 场景转换
│ ├── exporters/
│ │ ├── __init__.py
│ │ ├── gltf_exporter.py # GLTF/GLB 导出
│ │ ├── threejs_exporter.py # Three.js JSON 导出
│ │ └── optimized_exporter.py # 优化导出
│ ├── optimizers/
│ │ ├── __init__.py
│ │ ├── mesh_optimizer.py # 网格优化
│ │ ├── texture_optimizer.py # 纹理优化
│ │ ├── lod_generator.py # LOD 生成
│ │ └── compression.py # 压缩 (Draco/KTX2)
│ ├── utils/
│ │ ├── __init__.py
│ │ ├── geometry_utils.py # 几何工具
│ │ ├── material_utils.py # 材质工具
│ │ ├── validation.py # 验证工具
│ │ └── logging_config.py # 日志配置
│ └── cli.py # 命令行接口
├── js/
│ ├── package.json
│ ├── src/
│ │ ├── loaders/ # Three.js 加载器
│ │ ├── converters/ # JS 端转换器
│ │ └── utils/
│ └── tests/
├── tests/
│ ├── test_parsers/
│ ├── test_converters/
│ ├── test_exporters/
│ └── fixtures/ # 测试模型文件
├── docs/
│ ├── architecture.md # 架构文档
│ ├── format_specifications.md # 格式规范
│ ├── conversion_pipeline.md # 转换流水线
│ └── api_reference.md # API 文档
└── examples/
├── blender_to_threejs/ # Blender 转换示例
├── fea_to_threejs/ # FEA 转换示例
└── cad_to_threejs/ # CAD 转换示例
输入文件 (OBJ/STL/MSH/Blend/MAX/SKP)
↓
[格式检测] → 确定文件类型和专用解析器
↓
[文件解析] → 提取几何、拓扑、材质、建筑元素
↓
[建筑模型中间格式 BMIF] → 精确顶点映射、拓扑保持
│ • Vertex: 双精度坐标 + 原始ID
│ • Edge: 有向边 + 相邻面引用
│ • Face: 多边形 + 法线 + UV + 材质
│ • BuildingElement: 墙/楼板/柱等语义
↓
[数据验证] → 顶点精度、拓扑完整性、渲染就绪性
│ • 顶点精确性评分
│ • 拓扑完整性评分
│ • 渲染就绪性评分
↓
[建筑优化] → 按材质合并、LOD生成、纹理优化
↓
[格式转换] → 转换为 GLTF/GLB (Three.js 原生)
│ • 顶点精确导出
│ • 材质 PBR 映射
│ • 建筑语义扩展
↓
[导出文件] → 生成优化后的 GLB/GLTF
pip install -r requirements.txtcd js
npm install# 基本转换 (建筑模型)
python -m model_converter convert building.obj building.glb
# 带验证的转换
python -m model_converter convert model.obj output.glb --validate
# 批量转换建筑模型
python -m model_converter batch ./building_models ./output --format glb --optimize
# 格式互转示例
python -m model_converter convert model.skp temp.obj # SketchUp -> OBJ
python -m model_converter convert temp.obj model.glb # OBJ -> GLB (Three.js)from model_converter import FormatConverter, BuildingModel
from model_converter.utils.building_validation import BuildingModelValidator
# 创建转换器
converter = FormatConverter()
# 转换并验证
result = converter.convert(
input_path="building.obj",
output_path="building.glb",
options={
"optimize": True,
"merge_by_material": True,
"validate": True
}
)
# 验证转换质量
validator = BuildingModelValidator()
report = validator.validate(intermediate_model)
print(f"顶点精度: {report.vertex_accuracy}%")
print(f"拓扑完整性: {report.topology_integrity}%")
print(f"渲染就绪性: {report.render_readiness}%")from model_converter import Converter
# 创建转换器
converter = Converter()
# 转换文件
result = converter.convert(
input_path="model.blend",
output_path="model.glb",
options={
"optimize_mesh": True,
"generate_lod": True,
"compress_textures": True
}
)# 双精度坐标存储
class Vertex:
x: float # 双精度
y: float
z: float
original_id: str # 追踪来源
# 顶点去重（容差控制）
tolerance = 1e-10 # 建筑级精度# 边-面拓扑关系
class Edge:
v0: int # 起点
v1: int # 终点
faces: List[int] # 相邻面索引
# 面保持多边形或三角化
class Face:
vertices: List[int] # 有序顶点环
normal: List[float] # 面法线- 法线: 自动计算或保留原始值
- UV: 完整纹理坐标映射
- 材质: PBR 工作流正确映射
- 索引: 正确的三角化索引
SketchUp (.skp) ──┐
3ds Max (.max) ───┼──> BMIF ──> GLB/GLTF ──> Three.js
Blender (.blend) ─┤ (建筑模型中间格式)
Revit (.rvt) ─────┤
OBJ/MTL ──────────┤
STL ──────────────┤
MSH (Gmsh) ───────┘
- numpy: 双精度数值计算
- pygltflib: GLTF/GLB 精确读写
- Pillow: 纹理处理
- trimesh: 辅助网格处理
- meshio: FEA 网格读写
- BMIF: 建筑模型中间格式
- BuildingOBJParser: 建筑语义识别
- BuildingGLTFExporter: 精确 GLTF 导出
- BuildingModelValidator: 转换质量验证
- 顶点精度: 使用双精度浮点数，确保建筑级精度 (1e-10)
- 拓扑保持: 边-面关系完整保留，支持非流形几何
- 建筑语义: 自动识别墙、楼板、柱等建筑元素
- 坐标系: 自动处理 Y-up/Z-up 转换，保持相对位置
- 材质: PBR 材质完整映射，支持纹理嵌入