asset-importer

A comprehensive Rust binding for the latest Assimp 3D asset import library.

This crate provides safe, high-level Rust bindings for Assimp v6.0.2, implementing the vast majority of the C API with idiomatic Rust interfaces.

Example Application

See Model Viewer (asset-importer + wgpu) - A practical model viewer built on top of this Assimp Rust binding. It serves as a real-world sample and testbed to validate asset-importer across common 3D formats.

Status

⚠️ Early Development: This library is functional but lacks extensive real-world testing. Use with caution in production environments.

Features

• Comprehensive API Coverage: Implements the vast majority of Assimp v6.0.2 C API
• Import Support: 71+ 3D file formats (OBJ, FBX, glTF, DAE, etc.)
• Export Support: 22+ output formats (optional)
• Memory Safe: Safe Rust API over unsafe FFI bindings
• Modern Math (Optional): Interop with glam and mint via opt-in Cargo features
• Flexible Building: Multiple build options for different use cases
• Cross-Platform: Supports Windows, macOS, and Linux

Quick Start

Add to your Cargo.toml:

[dependencies]
# Default – Use prebuilt binaries (fastest)
asset-importer = "0.5"

# Or build from source (best compatibility; mutually exclusive build mode)
asset-importer = { version = "0.5", default-features = false, features = ["build-assimp"] }

# Or link a system-installed Assimp (requires libclang/bindgen; mutually exclusive build mode)
asset-importer = { version = "0.5", default-features = false, features = ["system"] }

Basic usage:

use asset_importer::Importer;
use asset_importer::postprocess::PostProcessSteps;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let scene = Importer::new().import_file("model.obj")?;
    
    println!("Loaded {} meshes", scene.num_meshes());
    
    for mesh in scene.meshes() {
        // Zero-copy options are available:
        // - mesh.vertices_raw(): &[asset_importer::raw::AiVector3D]
        // - mesh.vertices_iter(): Iterator<Item = Vector3D>
        let vertices = mesh.vertices();
        println!("Mesh has {} vertices (copied)", vertices.len());
    }
    
    Ok(())
}

Builder-style usage (no repeated path):

use asset_importer::{Importer, postprocess::PostProcessSteps};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let scene = Importer::new().read_file("model.fbx")
        .with_post_process(PostProcessSteps::TRIANGULATE | PostProcessSteps::FLIP_UVS)
        .import()?;
    Ok(())
}

Thread Safety (Send/Sync)

Scene and all scene-backed view types (Mesh, Material, Node, Texture, etc.) are Send + Sync and can be shared across threads (e.g. behind Arc) for read-only access.

Important: do not mutate Assimp-owned scene memory through raw Assimp bindings (asset_importer::sys with feature raw-sys, or the asset-importer-sys crate) while a Scene (or any scene-backed view type) is shared across threads. Doing so violates the crate's safety contract and may cause undefined behavior.

Practical guidance:

• Prefer the safe API for reading scene data (Mesh::*_raw() / *_iter() / MaterialPropertyRef, etc.).
• Only enable raw-sys when you explicitly need raw bindings, and treat the returned pointers as read-only.
• Do not call Assimp APIs that mutate or free the scene (e.g. post-processing, freeing, replacing pointers) on a scene that is still alive on the Rust side.

Build Options

Default: Prebuilt Binaries (Recommended)

asset-importer = "0.5"

• Fastest: No compilation time
• Convenient: No native toolchain required
• Requires: Available release artifacts from GitHub releases
• Note: Only available for released versions

Build from Source

asset-importer = { version = "0.5", default-features = false, features = ["build-assimp"] }

• Best compatibility: Works on all platforms
• Full control: Latest Assimp version with all features
• Requires: CMake, C++ compiler (automatically handled by Cargo)

System Library

asset-importer = { version = "0.5", default-features = false, features = ["system"] }

• Lightweight: Uses existing system installation
• Setup required: Install via brew install assimp (macOS), apt install libassimp-dev (Ubuntu)
• Version dependent: Behavior may vary based on system library version

Additional Features

asset-importer = {
    version = "0.5",
    default-features = false,
    features = [
        "build-assimp",    # Choose exactly one build mode (or use default prebuilt)
        "export",          # Enable export functionality
        "type-extensions", # Enable convenience methods on types
        "raw-sys",         # Expose raw bindings as `asset_importer::sys` (unsafe contract)
        "glam",            # Enable `glam` conversions
        "mint",            # Enable mint math library integration
        "bytemuck",        # Enable zero-copy byte casts for raw views
        "static-link",     # Prefer static linking (source/prebuilt)
        "nozlib"           # Disable zlib compression support
    ]
}

Examples

See asset-importer/examples/README.md for a guided, step-by-step set of examples and recommended commands for each build mode.

Build Requirements

Source Build Dependencies

When building from source (build-assimp feature), you'll need:

• CMake (3.10 or later)
• C++ Compiler (MSVC on Windows, GCC/Clang on Linux/macOS)
• Git (for submodules)

Platform-Specific Setup

• Windows: Install Visual Studio Build Tools or Visual Studio
• macOS: Install Xcode Command Line Tools (xcode-select --install)
• Linux: Install build essentials (sudo apt install build-essential cmake on Ubuntu)

For detailed platform-specific instructions and troubleshooting, see the asset-importer-sys README.

Windows Notes (MSVC CRT)

• Default Rust (MSVC) uses dynamic CRT (/MD). Our build follows Rust’s choice automatically.
• If you need static CRT (/MT), set a target-wide flag so all crates agree:

# .cargo/config.toml
[target.x86_64-pc-windows-msvc]
rustflags = ["-C", "target-feature=+crt-static"]

or per-build:

RUSTFLAGS="-C target-feature=+crt-static" cargo build --release

• Prebuilt binaries: we publish both MD and MT variants on Windows. Filenames include a -md or -mt suffix, for example: asset-importer-<version>-x86_64-pc-windows-msvc-<static|dylib>-md.tar.gz. The build script auto-selects the variant matching your current CRT and falls back to old names if needed.

• vcpkg (with features=["system"]):

  • Choose triplet to match CRT:
    • x64-windows → /MD (dynamic)
    • x64-windows-static → /MT (static)
  • Install: vcpkg install assimp:x64-windows or assimp:x64-windows-static.
  • If using the static triplet, also enable crt-static to avoid LNK2038.

Why prebuilt binaries by default?

• Fast builds: No compilation time for Assimp
• Easy setup: No native toolchain required
• CI/CD friendly: Faster builds in continuous integration
• Consistent: Same binary across environments

If you need more control or compatibility, use:

• --no-default-features --features build-assimp to build from source (best compatibility)
• --no-default-features --features system to link an existing installation

Development and Testing

For development work or when prebuilt binaries are not available:

# Use this for development
asset-importer = { version = "0.5", default-features = false, features = ["build-assimp"] }

This ensures you can always build from source regardless of release availability.

Memory Import Notes

Importer::read_from_memory(&[u8]) stores an owned copy internally so the builder can be 'static and support .import(). If you already have an owned buffer, prefer Importer::read_from_memory_owned(Vec<u8>) or Importer::import_from_memory_owned(Vec<u8>, hint) to avoid an extra copy.

Architecture

This crate provides a high-level safe API. For low-level FFI bindings, see asset-importer-sys.

Platform Support

• Windows: MSVC, MinGW
• macOS: Intel, Apple Silicon
• Linux: x86_64, aarch64

Goals

This project aims to provide the most comprehensive and up-to-date Rust binding for Assimp, supporting both import and export functionality with modern Rust practices.

Versioning

This workspace uses independent versioning for each crate:

• asset-importer-sys: Tracks Assimp versions and FFI binding changes
• asset-importer: Tracks high-level API changes and features

See VERSIONING.md for detailed versioning strategy and release process.

Limitations

• Limited Testing: Needs more real-world usage validation
• API Stability: May change before 1.0 release

Contributing

Contributions welcome! Areas needing help:

• Real-world testing with various file formats
• Performance benchmarking
• Documentation improvements
• Platform-specific testing

Related Projects

If you're working with graphics and UI in Rust, you might also be interested in:

• dear-imgui - Comprehensive Dear ImGui bindings for Rust using C++ bindgen, providing immediate mode GUI capabilities for graphics applications

Acknowledgments

• Assimp - The underlying C++ library
• russimp - Inspiration and reference