Rust FBX文件解析库ufbx的使用指南

ufbx是一个高性能的FBX格式3D模型加载与处理库，专为Rust设计。它提供了快速、安全的FBX文件解析功能，适用于游戏开发、3D建模工具和其他需要处理FBX文件的应用程序。

主要特性

• 高性能解析FBX文件
• 内存安全的Rust实现
• 支持ASCII和二进制FBX格式
• 完整的场景图访问
• 网格、材质、纹理、动画等数据提取
• 轻量级设计

安装方法

在Cargo.toml中添加依赖：

[dependencies]
ufbx = "0.7"  # 请检查最新版本

基本使用方法

加载FBX文件

use ufbx;

fn main() -> Result<(), ufbx::Error> {
    // 加载FBX文件
    let scene = ufbx::load_file("model.fbx")?;
    
    // 打印场景基本信息
    println!("Loaded scene with {} meshes", scene.meshes.len());
    println!("Scene units: {} meters", scene.unit_meters);
    
    Ok(())
}

遍历场景节点

fn print_node_hierarchy(node: &ufbx::Node, depth: usize) {
    let indent = "  ".repeat(depth);
    println!("{}{}", indent, node.name);
    
    for child in &node.children {
        print_node_hierarchy(child, depth + 1);
    }
}

// 使用示例
let scene = ufbx::load_file("model.fbx")?;
print_node_hierarchy(&scene.root, 0);

提取网格数据

let scene = ufbx::load_file("model.fbx")?;

for mesh in &scene.meshes {
    println!("Mesh: {}", mesh.name);
    println!("  Vertex count: {}", mesh.vertices.len());
    
    // 访问顶点位置
    for vertex in &mesh.vertices {
        println!("    Vertex: {:?}", vertex);
    }
    
    // 访问面数据
    for face in &mesh.faces {
        println!("    Face vertex count: {}", face.num_indices);
    }
}

处理材质和纹理

let scene = ufbx::load_file("model.fbx")?;

for material in &scene.materials {
    println!("Material: {}", material.name);
    
    if let Some(diffuse) &material.diffuse_color {
        println!("  Diffuse color: {:?}", diffuse.value);
    }
    
    if let Some(texture) = material.diffuse_texture.as_ref() {
        println!("  Diffuse texture: {}", texture.texture.name);
        println!("  Texture file: {:?}", texture.texture.file_name);
    }
}

处理动画数据

let scene = ufbx::load_file("animated_model.fbx")?;

for anim_stack in &scene.anim_stacks {
    println!("Animation stack: {}", anim_stack.name);
    
    for layer in &anim_stack.layers {
        println!("  Layer: {}", layer.name);
        
        for anim in &layer.anims {
            println!("    Anim: {}", anim.node.name);
            println!("    Keyframes: {}", anim.curves.len());
        }
    }
}

高级用法

自定义加载选项

let opts = ufbx::LoadOpts {
    target_axes: ufbx::CoordinateAxes {
        front: ufbx::Axis::PositiveZ,
        up: ufbx::Axis::PositiveY,
        right: ufbx::Axis::PositiveX,
        unit_meters: 1.0,
    },
    ..Default::default()
};

let scene = ufbx::load_file_with_opts("model.fbx", opts)?;

内存中加载FBX数据

let data = std::fs::read("model.fbx")?;
let scene = ufbx::load_from_memory(&data, ufbx::LoadOpts::default())?;

性能提示

1. 对于大型FBX文件，考虑在后台线程加载
2. 如果只需要部分数据，可以检查加载选项以跳过不需要的部分
3. 加载后可以释放不再需要的原始数据

错误处理

match ufbx::load_file("model.fbx") {
    Ok(scene) => {
        // 处理场景
    },
    Err(ufbx::Error::Io(e)) => {
        eprintln!("IO error: {}", e);
    },
    Err(ufbx::Error::Data(e)) => {
        eprintln!("FBX data error: {}", e);
    },
    Err(e) => {
        eprintln!("Unknown error: {}", e);
    }
}

完整示例代码

下面是一个完整的示例，展示如何加载FBX文件并提取各种数据：

use ufbx;

fn main() -> Result<(), ufbx::Error> {
    // 1. 加载FBX文件
    let scene = ufbx::load_file("model.fbx")?;
    
    // 2. 打印场景基本信息
    println!("场景单位: {} 米", scene.unit_meters);
    println!("网格数量: {}", scene.meshes.len());
    println!("材质数量: {}", scene.materials.len());
    println!("动画堆栈数量: {}", scene.anim_stacks.len());
    
    // 3. 遍历节点层次结构
    fn print_nodes(node: &ufbx::Node, depth: usize) {
        let indent = "  ".repeat(depth);
        println!("{}- {}", indent, node.name);
        
        for child in &node.children {
            print_nodes(child, depth + 1);
        }
    }
    
    println!("\n场景节点层次:");
    print_nodes(&scene.root, 0);
    
    // 4. 处理网格数据
    println!("\n网格信息:");
    for mesh in &scene.meshes {
        println!("网格名称: {}", mesh.name);
        println!("  顶点数: {}", mesh.vertices.len());
        println!("  面数: {}", mesh.faces.len());
        
        // 打印前10个顶点位置
        println!("  前10个顶点:");
        for vertex in mesh.vertices.iter().take(10) {
            println!("    {:?}", vertex);
        }
    }
    
    // 5. 处理材质数据
    println!("\n材质信息:");
    for material in &scene.materials {
        println!("材质名称: {}", material.name);
        
        if let Some(diffuse) = &material.diffuse_color {
            println!("  漫反射颜色: {:?}", diffuse.value);
        }
        
        if let Some(texture) = material.diffuse_texture.as_ref() {
            println!("  漫反射纹理: {}", texture.texture.name);
            println!("  纹理文件: {:?}", texture.texture.file_name);
        }
    }
    
    // 6. 处理动画数据(如果有)
    if !scene.anim_stacks.is_empty() {
        println!("\n动画信息:");
        for anim_stack in &scene.anim_stacks {
            println!("动画堆栈: {}", anim_stack.name);
            
            for layer in &anim_stack.layers {
                println!("  图层: {}", layer.name);
                
                for anim in &layer.anims {
                    println!("    节点 {} 的关键帧数: {}", 
                        anim.node.name, anim.curves.len());
                }
            }
        }
    }
    
    Ok(())
}

这个完整示例展示了如何使用ufbx库加载FBX文件并提取各种数据，包括场景信息、节点层次结构、网格数据、材质信息和动画数据。您可以根据需要修改或扩展此示例来满足特定的应用需求。