fbx2glb

> 🚀 一款用于 FBX 模型工程化处理 的 CLI 工具
> 面向 Three.js / WebGL 的标准化 FBX → glTF / GLB 工作流


---

✨ 功能特性

- ✅ FBX → GLB 一键转换 - 基于 FBX2glTF 的可靠转换
- ✅ 智能场景优化 - 自动执行顶点焊接、场景清理、数据去重
- ✅ Draco 几何压缩 - 支持 Edgebreaker 方法，可配置量化位深
- ✅ KTX2/BasisU 纹理压缩 - UASTC 格式，自动纹理尺寸优化
- ✅ 详细优化报告 - 生成前后对比分析，包含顶点、几何、材质等统计
- ✅ 适配 CI/CD - 支持批量自动化流水线处理
- ✅ 标准 glTF 2.0 - 输出标准格式，兼容所有主流引擎

---

📋 目录

- 安装方式
- 系统依赖
- 快速开始
- 使用说明
- 技术实现流程
- 命令行选项
- 输出文件说明
- Draco 压缩建议
- 技术栈
- 常见问题
- 贡献指南

---

📦 安装方式

$3

``bash
npm install -g fbx2glb
`

$3

`bash
npm install -D fbx2glb
`


---

🔧 系统依赖

⚠️ 重要：本工具不内置原生转换器，请提前安装以下系统级依赖。

$3

| 工具 | 作用 | 版本要求 |
|------|------|----------|
| FBX2glTF | FBX → glTF 转换 | v0.9.7+ |
| Node.js | 运行环境 | v18.0.0+ |

$3

#### macOS

`bash


1. 下载二进制文件

访问: https://github.com/facebookincubator/FBX2glTF/releases/tag/v0.9.7

下载: FBX2glTF-darwin-x64

2. 安装到用户目录（推荐，无需 sudo）

mkdir -p ~/bin
mv ~/Downloads/FBX2glTF-darwin-x64 ~/bin/FBX2glTF
chmod +x ~/bin/FBX2glTF

3. 添加到 PATH

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4. 移除 macOS 安全限制（如遇到提示）

sudo xattr -r -d com.apple.quarantine ~/bin/FBX2glTF

5. 验证安装

FBX2glTF --version
`

#### Linux

`bash


1. 下载二进制文件

访问: https://github.com/facebookincubator/FBX2glTF/releases/tag/v0.9.7

下载: FBX2glTF-linux-x64

2. 安装到系统目录（需要 sudo）

sudo mv FBX2glTF-linux-x64 /usr/local/bin/FBX2glTF
sudo chmod +x /usr/local/bin/FBX2glTF

或安装到用户目录（无需 sudo）

mkdir -p ~/bin
mv FBX2glTF-linux-x64 ~/bin/FBX2glTF
chmod +x ~/bin/FBX2glTF
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

3. 验证安装

FBX2glTF --version
`

#### Windows

`bash


1. 下载二进制文件

访问: https://github.com/facebookincubator/FBX2glTF/releases/tag/v0.9.7

下载: FBX2glTF-windows-x64.exe

2. 重命名为 FBX2glTF.exe

3. 添加到系统 PATH 环境变量

4. 验证安装

FBX2glTF --version
`

---

🚀 快速开始

$3

`bash
fbx2glb -i model.fbx
`

默认输出：model_.glb

$3

`bash


启用 Draco 几何压缩

fbx2glb -i model.fbx --draco

启用 KTX2 纹理压缩

fbx2glb -i model.fbx --ktx2

同时启用两种压缩

fbx2glb -i model.fbx --draco --ktx2
`

$3

`bash
fbx2glb -i model.fbx -o output.glb --draco --ktx2
`

---

📖 使用说明

$3

`bash
fbx2glb -i [选项]
`

$3

| 选项 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| --input | -i | 必需 指定输入 FBX 文件 | - |
| --output | -o | 输出 GLB 文件路径 | _.glb |
| --draco | - | 启用 Draco 几何压缩 | false |
| --ktx2 | - | 启用 KTX2/BasisU 纹理压缩 | false |
| --maxTex | - | 最大纹理尺寸（像素） | 2048 |

$3

`bash


示例 1: 基础转换

fbx2glb -i character.fbx

示例 2: 启用所有压缩，自定义纹理尺寸

fbx2glb -i scene.fbx -o optimized.glb --draco --ktx2 --maxTex 1024

示例 3: 仅几何压缩（适合无贴图模型）

fbx2glb -i mesh.fbx --draco

示例 4: 仅纹理压缩（适合低精度几何）

fbx2glb -i textured_model.fbx --ktx2 --maxTex 512
`

---

🔄 技术实现流程

工具内部按照以下 6 个步骤执行转换：

`
┌─────────────────────────────────────────────────────────────┐
│ FBX → GLB 转换流程 │
└─────────────────────────────────────────────────────────────┘

步骤 1: FBX → Raw GLB
├─ 使用 FBX2glTF 进行基础转换
└─ 生成临时 GLB 文件 (temp_raw.glb)

步骤 2: 初始化 GLTF Transform 引擎
├─ 注册扩展 (Draco, KTX2/BasisU)
└─ 加载依赖模块 (draco3d encoder/decoder)

步骤 3: 读取并解析 GLB 文档
├─ 加载临时 GLB 文件
└─ 生成优化前数据分析 (inspect_before.json)

步骤 4: 场景优化
├─ weld() - 顶点焊接（合并重复顶点，tolerance: 0.0001）
├─ prune() - 场景瘦身（清理无用数据）
└─ dedup() - 数据去重（复用 Accessor/Mesh）

步骤 5: 可选压缩
├─ Draco 压缩（如启用）
│ ├─ 方法: Edgebreaker
│ ├─ 量化位深:
│ │ ├─ POSITION: 14 bits
│ │ ├─ NORMAL: 10 bits
│ │ ├─ TEX_COORD: 12 bits
│ │ ├─ COLOR: 8 bits
│ │ └─ GENERIC: 12 bits
│ └─ 量化体积: mesh
│
└─ KTX2 压缩（如启用）
├─ 编码器: BasisU
├─ 格式: UASTC
├─ 质量: 128
└─ 最大尺寸: --maxTex 参数

步骤 6: 写入最终 GLB 文件
├─ 生成优化后数据分析 (inspect_after.json)
├─ 生成对比报告 (comparison.json)
└─ 清理临时文件
`

$3

#### 1. FBX → Raw GLB 转换

使用 FBX2glTF 命令行工具将 FBX 文件转换为初始 GLB 文件。这是整个流程的基础步骤。

`bash
FBX2glTF -b -i "input.fbx" -o "temp_raw.glb"
`

- -b: 输出二进制 GLB 格式
- -i: 输入文件
- -o: 输出文件

#### 2. GLTF Transform 初始化

初始化 @gltf-transform 引擎，注册必要的扩展和依赖：

- 扩展: KHRDracoMeshCompression, KHRTextureBasisu
- 依赖: draco3d encoder/decoder 模块

#### 3. 场景优化管道

应用三个核心优化函数：

- weld(): 合并距离小于 0.0001 的重复顶点，减少顶点数量
- prune(): 清理场景中未使用的节点、材质、纹理等资源
- dedup(): 检测并复用相同的 Accessor 和 Mesh，减少数据冗余

#### 4. 压缩算法

Draco 几何压缩（可选）:
- 使用 Edgebreaker 算法进行网格压缩
- 针对不同属性设置优化的量化位深
- 适合中大型模型（>1MB），可减少 50-95% 体积

KTX2/BasisU 纹理压缩（可选）:
- 使用 UASTC 格式，提供高质量压缩
- 自动调整纹理尺寸到指定最大值
- 适合包含大量纹理的模型

#### 5. 报告生成

工具会自动生成三个分析文件：

- inspect_before.json: 优化前的详细数据统计
- inspect_after.json: 优化后的详细数据统计
- comparison.json: 前后对比分析报告

---

📊 输出文件说明

转换完成后，会在输出目录生成以下文件：

`
output_directory/
├── model_1234567890.glb # 最终优化的 GLB 文件
├── inspect_before.json # 优化前数据分析
├── inspect_after.json # 优化后数据分析
└── comparison.json # 对比报告
`

$3

inspect_before.json / inspect_after.json:
`json
{
"meshes": { ... }, // 网格统计
"geometry": { ... }, // 几何数据统计
"buffers": { ... }, // 缓冲区统计
"materials": { ... }, // 材质统计
"scenes": { ... } // 场景统计
}
`

comparison.json:
`json
{
"summary": {
"bufferSize": {
"before": "10.5 MB",
"after": "2.3 MB",
"difference": "-8.2 MB",
"percentChange": "-78.1%"
}
},
"details": { ... }
}
`

---

💡 Draco 压缩建议

根据模型大小选择合适的压缩策略：

| 模型大小 | Draco 压缩效果 | 是否推荐 |
|---------|---------------|---------|
| < 1MB | 意义不大 | ❌ 不推荐 |
| 1-5MB | 减小 50-70% | ✅ 推荐 |
| 5-20MB | 减小 70-90% | ✅ 强烈推荐 |
| > 20MB | 减小 80-95% | ✅ 必须使用 |

$3

当前工具使用的 Draco 配置：

- 方法: Edgebreaker（适合大多数模型）
- 量化体积: mesh（按网格独立量化）
- 量化位深:
- POSITION: 14 bits（位置精度）
- NORMAL: 10 bits（法线精度）
- TEX_COORD: 12 bits（UV 坐标精度）
- COLOR: 8 bits（颜色精度）

这些配置在压缩率和质量之间取得了良好平衡。

---

🛠 技术栈

$3

- @gltf-transform/core - glTF 处理核心库
- @gltf-transform/functions - 优化函数集合
- draco3d - Draco 压缩算法
- FBX2glTF - FBX 转换工具

$3

- commander - 命令行参数解析
- chalk - 终端颜色输出
- ora - 加载动画
- boxen - 终端框线

---

❓ 常见问题

$3

A: 请确保已正确安装 FBX2glTF 并添加到系统 PATH。运行 FBX2glTF --version 验证安装。

$3

A: 运行以下命令移除安全限制：
`bash
sudo xattr -r -d com.apple.quarantine ~/bin/FBX2glTF
`

$3

A:
1. 检查是否启用了 Draco 压缩，如果是，需要加载 draco/gltf/draco_decoder.js
2. 检查是否启用了 KTX2 压缩，如果是，需要加载 KTX2Loader
3. 查看浏览器控制台错误信息

$3

A: 可以使用 shell 脚本：
`bash
for file in *.fbx; do
fbx2glb -i "$file" --draco --ktx2
done
`

$3

A:
- 对于 Draco，可以调整量化位深（需要修改源码）
- 对于 KTX2，可以调整 --maxTex` 参数或质量设置
- 建议先用默认设置测试，再根据需求调整

---

📄 许可证

MIT License

---

🙏 致谢

- FBX2glTF - Facebook 的 FBX 转换工具
- glTF Transform - Don McCurdy 的 glTF 处理库
- Draco - Google 的几何压缩库

---

📚 相关资源

- glTF 2.0 规范
- Three.js 文档
- Draco 压缩指南
- KTX2 纹理格式

---