oxigaf-cli

Command-line interface for OxiGAF — Gaussian Avatar Reconstruction.

Overview

The OxiGAF CLI provides a complete toolkit for working with Gaussian head avatars:

• Train — End-to-end avatar reconstruction from monocular images
• Render — Render existing avatars from novel viewpoints
• Export — Export avatars to PLY, glTF, or safetensors
• Convert — Convert FLAME model files (.pkl to .npy format)
• Benchmark — Run performance benchmarks
• Doctor — Check system configuration and dependencies
• Setup — Download and cache required model weights
• Cache — Manage cached assets (list, clean, verify, path)

Installation

[dependencies]
oxigaf-cli = "0.1"

Or install as a binary:

cargo install oxigaf-cli

Features

Usage

Train an Avatar

Reconstruct a 3D avatar from a monocular video:

oxigaf train \
  --input input_video.mp4 \
  --output avatar.safetensors \
  --flame-model path/to/flame \
  --iterations 1000

Render from Novel Views

Render an existing avatar from custom viewpoints:

oxigaf render \
  --avatar avatar.safetensors \
  --output-dir renders/ \
  --camera-path camera_trajectory.json \
  --width 512 \
  --height 512

Export to Standard Formats

Export avatar to PLY for use in other tools:

# Export as PLY (3D Gaussian point cloud)
oxigaf export \
  --avatar avatar.safetensors \
  --output avatar.ply \
  --format ply

# Export as glTF (textured mesh)
oxigaf export \
  --avatar avatar.safetensors \
  --output avatar.gltf \
  --format gltf

Convert FLAME Model

Convert FLAME model from pickle format to numpy:

oxigaf convert \
  --input generic_model.pkl \
  --output flame_model/ \
  --format npy

Check System Configuration

Verify GPU support and dependencies:

oxigaf doctor

Benchmark Performance

Run performance benchmarks:

oxigaf benchmark \
  --flame-model path/to/flame \
  --iterations 100 \
  --report benchmark_results.json

Programmatic Usage

You can also use the CLI components as a library:

use oxigaf_cli::{InteractiveController};
use oxigaf::prelude::*;

fn main() -> anyhow::Result<()> {
    // Load configuration
    let config = TrainingConfig::default();

    // Create trainer
    let trainer = Trainer::new(config)?;

    // Run training loop with interactive controls
    let controller = InteractiveController::new()?;

    for iteration in 0..1000 {
        // Check for user commands (pause, stop, etc.)
        if controller.should_stop() {
            break;
        }

        // Training step
        // trainer.step(...)?;

        // Report progress
        println!("Iteration {}/1000", iteration + 1);
    }

    Ok(())
}

Configuration

The CLI supports configuration files in TOML format:

# config.toml
[training]
iterations = 1000
learning_rate = 0.001
batch_size = 4

[render]
width = 512
height = 512
tile_size = 16

[optimizer]
lr_positions = 0.00016
lr_rotations = 0.001
lr_scales = 0.005
lr_opacities = 0.05
lr_sh = 0.0025

Load configuration with:

oxigaf train --config config.toml --input video.mp4

Output Formats

Training Output

• *.safetensors — Trained Gaussian model (recommended)
• checkpoint_*.json — Training checkpoints with metadata

Render Output

• *.png — RGB images (default)
• *.jpg — JPEG images (lossy compression)
• *.exr — High dynamic range (HDR) images

Export Formats

• *.ply — Point cloud (3D Gaussian Splatting)
• *.gltf / *.glb — glTF 2.0 mesh with textures
• *.safetensors — Native format (all Gaussian parameters)

Logging

Control verbosity with -v flags:

# Quiet (errors only)
oxigaf train --quiet ...

# Normal (info)
oxigaf train ...

# Verbose (debug)
oxigaf train -v ...

# Very verbose (trace)
oxigaf train -vv ...

Save logs to file:

oxigaf train \
  --log-file training.log \
  --log-rotation daily \
  --log-max-files 7 \
  ...

Documentation

• API Documentation
• Repository
• Crate

License

Licensed under the Apache License, Version 2.0 (LICENSE)