obj2drc 1.1.2

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)"

参数说明

基础

参数	默认	说明
input	必填	输入 OBJ 文件路径
output	必填	输出目录
--texture PATH	自动检测	纹理 PNG。不指定则在 OBJ 同目录查找

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 ./output

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

# 指定 LOD 层级数
obj2drc model.obj ./output --levels 10

控制文件大小

# 降低精度，文件大幅减小（推荐先试这个）
obj2drc model.obj ./output --pos-bits 14

# 再减少法线，体积进一步缩小
obj2drc model.obj ./output --pos-bits 14 --skip-normals

# 极致压缩
obj2drc model.obj ./output --pos-bits 12 --compress 10 --skip-normals --skip-uv

加速编码

# 使用所有 CPU 核心并行编码
obj2drc model.obj ./output --workers 0

# 指定线程数
obj2drc model.obj ./output --workers 8

API 调用

from obj2drc import obj2drc, process_all

# 单模型，控制精度和并行度
config = obj2drc("model.obj", "./output", pos_bits=14, workers=8)

# 批量处理目录下所有 OBJ
results = process_all("models/", "data/", recursive=True, workers=4)

输出结构

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            元数据