obj2drc 1.0.1

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

OBJ → DRC LOD 生成器

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

目录结构

obj2drc/
├── pyproject.toml           # 包元数据与依赖
├── obj2drc/                 # Python 包
│   ├── __init__.py          # 公开 API: generate_lods
│   ├── cli.py               # 命令行入口 (obj2drc 命令)
│   ├── pipeline.py          # 核心逻辑
│   └── lodkit/              # 核心库
│       ├── fast_parser.py   # 高效 OBJ 解析器（支持多 GB 大文件）
│       └── mesh_lod.py      # 网格简化与空间分块
├── requirements.txt         # Python 依赖
└── README.md                # 本文件

环境要求

• Python 3.8+
• numpy（通过 pip install -r requirements.txt 安装）
• draco_encoder 命令行工具 — Draco 压缩必需

安装 draco_encoder

macOS（Homebrew）：

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

快速开始

# 安装 Python 依赖
pip install -r requirements.txt

# 方式一：直接通过 obj2drc 命令运行（推荐，需先 pip install）
pip install .
obj2drc 输入的模型.obj ./输出目录

# 方式二：通过 Python 模块运行
python -m obj2drc.cli 输入的模型.obj ./输出目录

# 指定纹理文件
obj2drc 输入的模型.obj ./输出目录 --texture 纹理.png

输出结构

输出目录/
├── mesh_lod/
│   ├── lod_0.drc               # 最粗糙层级（面数最少）
│   ├── lod_1.drc
│   ├── ...
│   ├── lod_N.drc               # 分块前最细的单文件层级
│   ├── lod_{N+1}/              # 分块层级从这里开始（30 万面以上自动分块）
│   │   ├── tile_0_0_0.drc
│   │   ├── tile_0_0_1.drc
│   │   └── ...
│   └── ...
├── three_lod/
│   └── 模型名_texture.png       # 纹理（复制或程序生成）
└── lod_config.json             # 供前端使用的元数据

选项说明

参数	默认值	说明
--texture PATH	自动检测	纹理 PNG 路径。不指定则自动在 OBJ 目录查找
--compress N	7	Draco 编码压缩级别 (0=最快编码/文件较大, 10=最慢编码/文件最小)。不影响网格质量，质量由固定量化精度（位置 16 位、纹理 14 位）保证
--levels N	自动	LOD 层级数量。自动根据面数对数缩放（3~25 级）。1000 面→3 级，50 万面→15 级，1000 万面→22 级
--no-tile	关闭	禁用空间分块（所有层级都是单文件）。仅 30 万面以上层级才会被分块

工作原理

1. 解析：两遍扫描 OBJ 解析器 — 先计数，再填充预分配的 numpy 数组，支持 GB 级大文件
2. LOD 层级数：根据模型面数对数缩放（3~25 级）。面数越多层级越多，过渡越平滑
3. LOD 目标：从原始面数的 ~0.1% 到 ~85% 的几何级数分布
4. 简化：顶点聚类（Vertex Clustering）— 位于同一 3D 网格单元内的顶点合并为一个
5. 空间分块：超过 30 万面的层级按空间位置分割为 2×2×2 或 3×3×3 的瓦片网格，浏览器可并行加载
6. 压缩：每个网格 → OBJ 临时文件 → draco_encoder → .drc 文件。位置 16 位、纹理 14 位量化保证大模型精度
7. 纹理：优先复制原始纹理，没有则自动生成程序化纹理

查看器集成

输出目录结构与 standalone Three.js 查看器的目录格式完全兼容。 lod_config.json 中包含前端所需的 tile_map 和 lod_thresholds 数组。

许可

MIT