fbx2glb

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

✨ 功能特性

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

📋 目录

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

📦 安装方式

全局安装（推荐）

npm install -g fbx2glb

项目内安装

npm install -D fbx2glb

🔧 系统依赖

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

必需依赖

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

FBX2glTF 安装指南

macOS

# 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

# 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

# 1. 下载二进制文件
# 访问: https://github.com/facebookincubator/FBX2glTF/releases/tag/v0.9.7
# 下载: FBX2glTF-windows-x64.exe

# 2. 重命名为 FBX2glTF.exe
# 3. 添加到系统 PATH 环境变量
# 4. 验证安装
FBX2glTF --version

🚀 快速开始

最简单用法

fbx2glb -i model.fbx

默认输出：model_<timestamp>.glb

启用压缩

# 启用 Draco 几何压缩
fbx2glb -i model.fbx --draco

# 启用 KTX2 纹理压缩
fbx2glb -i model.fbx --ktx2

# 同时启用两种压缩
fbx2glb -i model.fbx --draco --ktx2

指定输出文件

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

📖 使用说明

基本语法

fbx2glb -i <input.fbx> [选项]

命令行选项

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

使用示例

# 示例 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)
  └─ 清理临时文件

详细流程说明

1. FBX → Raw GLB 转换

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

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                # 对比报告

报告文件结构

inspect_before.json / inspect_after.json:

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

comparison.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% | ✅ 必须使用 |

压缩配置说明

当前工具使用的 Draco 配置：

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

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

🛠 技术栈

核心依赖

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

CLI 工具

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

❓ 常见问题

Q: 转换失败，提示找不到 FBX2glTF？

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

Q: macOS 提示"无法打开，因为来自身份不明的开发者"？

A: 运行以下命令移除安全限制：

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

Q: 转换后的模型在 Three.js 中无法显示？

A:

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

Q: 如何批量处理多个 FBX 文件？

A: 可以使用 shell 脚本：

for file in *.fbx; do
  fbx2glb -i "$file" --draco --ktx2
done

Q: 压缩后模型质量下降？

A:

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

📄 许可证

MIT License

🙏 致谢

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

📚 相关资源

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