asset-importer-rs

Assimp, but in Rust

A safe, high-performance 3D asset import/export library

:book: Table of Contents

:pencil: About The Project

asset-importer-rs is a Rust implementation of the popular Assimp library, providing safe and efficient 3D asset import and export functionality. Built with Rust's memory safety guarantees and performance characteristics, this library aims to be a modern alternative to the C++ Assimp library.

:cloud: Overview

This project provides a comprehensive solution for loading, processing, and exporting 3D assets in various formats. The library is designed with a modular architecture, allowing for easy extension and customization. It supports modern formats like glTF 2.0, legacy formats like glTF 1.0, and classic formats like OBJ, with plans to support additional industry-standard formats.

Built with Rust's memory safety guarantees and performance characteristics, asset-importer-rs offers:

• Memory Safety - Leverages Rust's ownership system for automatic memory management
• Thread Safety - Built with Rust's thread safety guarantees from the ground up
• Modular Design - Each format is implemented as a separate crate for easy maintenance
• Extensible Architecture - Easy to add new format support through the core importer interface
• Comprehensive Testing - Full test coverage for all supported formats

:floppy_disk: Project Structure

Core Crates

• asset-importer-rs-core - Core import/export functionality and pipeline management
• asset-importer-rs-scene - 3D scene data structures and types
• asset-importer-rs-gltf - glTF 2.0 import/export support
• asset-importer-rs-gltf-v1 - glTF 1.0 import support (legacy)
• asset-importer-rs-obj - OBJ format support

Supporting Crates

• gltf-v1 - glTF 1.0 specification implementation
• gltf-v1-json - JSON serialization for glTF 1.0
• gltf-v1-derive - Procedural macros for glTF 1.0 validation

:book: Getting Started

Add the following to your Cargo.toml:

[dependencies]
asset-importer-rs = "0.3.0"

# Or for specific format support only:
asset-importer-rs-core = "0.2.0"
asset-importer-rs-scene = "0.2.0"
asset-importer-rs-gltf = "0.2.0"        # glTF 2.0 support
asset-importer-rs-gltf-v1 = "0.2.0"     # glTF 1.0 support
asset-importer-rs-obj = "0.2.0"         # OBJ support

Basic usage example:

use asset_importer_rs_gltf::Gltf2Importer;

// Import a glTF file
let importer = Gltf2Importer::new();
let scene = importer.import_file("model.gltf")?;

// Or use the main crate for automatic format detection
use asset_importer_rs::AssetImporter;
let scene = AssetImporter::import_file("model.gltf")?;

:small_orange_diamond: Supported Formats

Currently Supported

• glTF 2.0 - Complete specification support with extensions
• glTF 1.0 - Legacy format support with KHR_materials_common
• OBJ - Wavefront OBJ format with material support

Planned Support

• FBX - Autodesk FBX format
• 3DS - 3D Studio format
• DAE - Collada format

:small_orange_diamond: Implementation Notes

Implementation Plan 1.0.0

The goal for Version 1.0.0 is to ensure robust support for the most widely used 3D file formats in the industry, including GLTF, OBJ, FBX, DAE, 3DS, and MD3. This means being able to import and export these formats with expected results. In addition, the release should aim to provide the most common post-processing operations, such as Triangulation, Splitting Large Meshes, Optimize Meshes, Optimize Graph, Join Nearby Vertices, and Improving Cache Locality. All of these features should be fully implemented, thoroughly tested, and validated to ensure reliability and correctness across a wide range of real-world models.

In addition, a significant emphasis will be placed on expanding the suite of model-based tests.

Achieving parity with the original Assimp library -- or otherwise, justifying differences -- is an important long-term aspiration, though it is not a strict requirement for the 1.0.0 release. Nevertheless, it is desired to begin the process of having code to compare test outputs to similarly exported outputs from assimp.

Implementation Plan 0.1.0

The goal for version 0.1.0 is to produce a working rust-safe version of Assimp that provides GLTF and OBJ files formats. To minimize on potential unsafety, pointers, despite being obvious direct improvements to performance, will be eschewed in favor of base rust smart-types. The goal is to build a working model and slowly introduce unsafety for the sake of matching performance.

As part of 0.1.0, a benchmark system should be set up to compare native assimp versus rust-assimp versions of the same command to begin to focus in on parity. Numbers should be reported and bounties assigned for performance improvements to particular regions.

For the most part, there will be a default towards public external access, but ideally internals are overtime fully encapsulated.

Specific Feature-Flag parity with Assimp will be considered as a future excursion with the exception of double precision as the means of testing feature flags.

The active goal is to lay out the code and then optimize later. As part of this, a redocumentation phase will commence after 0.1.0 works to categorize a set of 'issues' and engage in providing documentation on the work.

All documentation provided should have corresponding testing.

:small_orange_diamond: Key Differences from Assimp

This implementation differs from the original C++ Assimp library in several important ways:

• Enum-based Types - Uses Rust's enum system for texture formats and material properties rather than C-style enums
• Error Handling - Leverages Rust's Result type and custom error types for robust error handling
• AiNodes - Are saved in an Arena instead of using a typical arena structure
• Memory Safety - Leverages Rust's ownership system for automatic memory management

:small_orange_diamond: Roadmap

Version 0.3.0 (Current)

• ✅ glTF 2.0 import/export support
• ✅ glTF 1.0 import support
• ✅ OBJ format support with materials
• ✅ Comprehensive testing suite
• 🔄 Basic post-processing features

Version 1.0.0

• Additional format support (FBX, 3DS, DAE, MD3)
• Performance optimizations and better benchmarking
• Advanced post-processing features
• Export functionality for all supported formats

:small_orange_diamond: Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change. Check out the Contributing Guide for more information.

Please make sure to update tests as appropriate and ensure all documentation is up to date.

:scroll: License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2024 Jackson Levitt