obj2drc 1.1.1

Generate LOD resources from OBJ for Three.js viewer with Draco compression

obj2drc — OBJ 转 Draco LOD 工具

将大型 OBJ 三维模型转换为多级 LOD（Level of Detail）资源，使用 Google Draco 压缩为 .drc 文件，适用于 Three.js 网页查看器。

安装

pip install obj2drc

依赖：Python 3.8+、numpy、draco_encoder 命令行工具。

安装 draco_encoder

# macOS
brew install draco

# Ubuntu/Debian
sudo apt install draco

# 从源码编译（通用）
git clone https://github.com/google/draco.git
cd draco && mkdir build && cd build
cmake .. && make && sudo make install

快速开始

# 最简单的用法
obj2drc model.obj ./output

# 指定纹理
obj2drc model.obj ./output --texture tex.png

# 批量处理目录下所有 OBJ
python -c "from obj2drc import process_all; process_all('models/', 'data/', recursive=True)"

参数说明

LOD 控制

参数	默认	说明
--levels N	自动(3~25)	LOD 层级数
--no-tile	关闭	禁用空间分块，所有层级输出为单文件

编码质量（控制文件大小）

参数	默认	说明
--pos-bits N	16	位置量化精度(1-31)。最核心的体积控制参数，每减2 bits 文件体积约减 25-30%。10-12=移动端，14-16=桌面
--compress N	7	Draco 压缩级别(0-10)，越高文件越小但编码越慢
--skip-normals	关闭	跳过法线编码，文件体积减 15-30%。Three.js 可自动计算法线
--skip-uv	关闭	跳过 UV 编码。无纹理时可开启

性能

参数	默认	说明
--workers N	1	并行编码线程。0=全部 CPU，1=顺序，N=指定数
--no-procedural-tex	关闭	无纹理时跳过，不生成程序化纹理

推荐参数组合

场景	命令
快速预览/移动端	obj2drc model.obj ./out --pos-bits 12 --skip-normals
极致压缩	obj2drc model.obj ./out --pos-bits 12 --compress 10 --skip-normals --skip-uv
桌面平衡	obj2drc model.obj ./out --pos-bits 14 --compress 7
高品质桌面	obj2drc model.obj ./out --pos-bits 16 --workers 0

输出结构

output/
├── mesh_lod/
│   ├── lod_0.drc             最粗糙层级
│   ├── lod_1.drc
│   ├── ...
│   ├── lod_N.drc             分块前最细的单文件层级
│   ├── lod_{N+1}/            分块层级（30 万面以上自动分块）
│   │   ├── tile_0_0_0.drc
│   │   └── ...
├── three_lod/
│   └── {model}_texture.png
└── lod_config.json            元数据

API 用法

from obj2drc import obj2drc, process_all

# 单模型
config = obj2drc("model.obj", "./output", pos_bits=14, workers=8)

# 批量处理
results = process_all("models/", "data/", recursive=True, workers=4)