Metadata-Version: 2.4
Name: obj2drc
Version: 1.0.0
Summary: Generate LOD resources from OBJ for Three.js viewer with Draco compression
License: MIT
Project-URL: Homepage, https://github.com/your-username/obj2drc
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

# 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）：**
```bash
brew install draco
```

**Ubuntu/Debian：**
```bash
sudo apt install draco
```

**从源码编译：**
```bash
git clone https://github.com/google/draco.git
cd draco
mkdir build && cd build
cmake .. && make
sudo make install
```

## 快速开始

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