fbx2glb

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

✨ 功能特性

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

📦 安装方式

全局安装（推荐）

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:

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

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 的几何压缩库

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
bin		bin
lib		lib
test		test
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
package.json		package.json

yaderick/fbx2glb

Folders and files

Latest commit

History

Repository files navigation