Skip to main content

Crate oxigaf_flame

Crate oxigaf_flame 

Source
Expand description

§oxigaf-flame

FLAME parametric head model implementation in Pure Rust.

This crate implements the FLAME (Faces Learned with an Articulated Model and Expressions) parametric 3D head model in pure Rust, with no dependencies on Python or C/C++ libraries.

§Features

  • FLAME model loading from .npy files (converted from the original .pkl)
  • Linear Blend Skinning (LBS) forward pass: parameters → posed mesh
  • CPU normal map rendering for diffusion model conditioning
  • Mesh surface point sampling for Gaussian initialization
  • Zero-cost abstractions with extensive use of #[inline] for performance

§Cargo Features

This crate supports the following feature flags:

  • simd (optional, requires nightly Rust with portable_simd): Enables SIMD-accelerated vector operations for:

    • Normal map rendering (3-4× faster)
    • Rodrigues rotation computation
    • Blend shape evaluation

  • parallel (optional): Enables parallel batch processing with rayon:

    • forward_batch_par() - parallel mesh generation
    • compute_normals_batch_par() - parallel normal computation
    • Near-linear speedup with CPU core count

  • full (convenience): Enables both simd and parallel for maximum performance

Example usage:

# In Cargo.toml
oxigaf-flame = { version = "0.1", features = ["parallel"] }

§Quick Start

use oxigaf_flame::{FlameModel, FlameParams};

// Load FLAME model from directory containing .npy files
let model = FlameModel::load("path/to/flame/model")?;

// Create neutral parameters (zero shape, expression, pose)
let params = FlameParams::neutral();

// Run forward pass to get posed mesh
let mesh = model.forward(&params);

println!("Generated mesh with {} vertices", mesh.vertices.len());

§FLAME Parameters

The FLAME model is controlled by several parameter types:

  • Shape parameters (β): Control identity-specific features (typically 100-300 coefficients)
  • Expression parameters (ψ): Control facial expressions (typically 50-100 coefficients)
  • Pose parameters (θ): Control joint rotations (5 joints × 3 = 15 values)
    • Root rotation (global head orientation)
    • Neck rotation
    • Jaw rotation
    • Left eye rotation
    • Right eye rotation
  • Translation: Global 3D translation applied after posing

§Coordinate System

FLAME uses a right-handed coordinate system:

  • +X: Right (from the subject’s perspective)
  • +Y: Up
  • +Z: Forward (out of the face)

Rotations are specified as axis-angle vectors and converted to rotation matrices using Rodrigues’ formula.

§Performance

The LBS forward pass is optimized for real-time performance:

  • ~1-2ms for standard FLAME mesh (5023 vertices) on modern CPUs
  • Critical path functions are marked with #[inline]
  • Uses ndarray for efficient BLAS-accelerated operations

Run benchmarks with: cargo bench -p oxigaf-flame

§References

Re-exports§

pub use error::FlameError;
pub use mesh::Mesh;
pub use model::compute_normals_batch;
pub use model::compute_normals_into;
pub use model::recompute_batch_normals;
pub use model::rodrigues;
pub use model::BatchBufferPool;
pub use model::BatchedFlameOutput;
pub use model::FlameModel;
pub use normal_map::Camera;
pub use normal_map::NormalMapRenderer;
pub use params::FlameParams;
pub use sampler::sample_mesh_surface;
pub use sampler::SurfacePoint;

Modules§

conversion
Conversion utilities for FLAME model formats.
error
Error types for the FLAME module.
io
Load FLAME model data from a directory of .npy files.
io_safetensors
Load and save FLAME models using the safetensors format.
mesh
Triangle mesh with per-vertex normals.
model
FLAME model: loading, blend shapes, LBS forward pass.
normal_map
CPU software rasterizer for FLAME normal maps.
params
FLAME model parameters for a single frame / pose.
sampler
Area-weighted random point sampling on a triangle mesh surface.
sequence
Video sequences of FLAME parameters

Structs§

FlameParamsBuilder
Builder for constructing FlameParams with a fluent API.