Metadata-Version: 2.4
Name: obj2drc
Version: 1.1.1
Summary: Generate LOD resources from OBJ for Three.js viewer with Draco compression
License: MIT
Project-URL: Repository, https://github.com/your-username/obj2drc
Project-URL: Documentation, https://github.com/your-username/obj2drc#readme
Keywords: 3d,lod,obj,draco,three.js
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy

# obj2drc — OBJ 转 Draco LOD 工具

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

## 安装

```bash
pip install obj2drc
```

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

### 安装 draco_encoder

```bash
# 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
```

## 快速开始

```bash
# 最简单的用法
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 用法

```python
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)
```
