asset-importer-rs-obj

OBJ file import functionality

Wavefront OBJ format support with material handling

:book: Table of Contents

:pencil: About The Crate

asset-importer-rs-obj provides Wavefront OBJ file import functionality for the asset-importer-rs project. This implementation supports the OBJ format with material library (MTL) handling, making it a complete solution for importing OBJ assets into the asset-importer-rs ecosystem.

This crate provides the essential functionality for:

• OBJ File Import - Complete scene graph construction from OBJ files
• Material Library Support - MTL file parsing and material handling
• Geometry Processing - Vertex, normal, and texture coordinate handling
• Face Data - Support for triangles, quads, and polygons
• Texture Support - Material texture and image handling
• Multiple Objects - Support for multiple objects within a single OBJ file

:cloud: Features

• Complete OBJ Support - Full Wavefront OBJ specification compliance
• Material Library Integration - MTL file parsing and material application
• Geometry Processing - Vertex, normal, and texture coordinate handling
• Face Type Support - Triangles, quads, and polygon face handling
• Texture Mapping - Material texture and image support
• Multiple Objects - Support for multiple objects in single files
• Error Handling - Comprehensive error reporting and recovery
• Memory Efficient - Optimized parsing and memory management

:floppy_disk: Main Components

Core Import

• ObjImporter - Main OBJ import functionality
• ObjImportError - Import error handling and reporting

Import Pipeline

• File Parsing - OBJ and MTL file parsing
• Geometry Processing - Vertex, normal, and texture coordinate handling
• Material Loading - MTL file parsing and material creation
• Face Construction - Triangle, quad, and polygon face building
• Object Separation - Multiple object handling within files
• Texture Management - Material texture and image loading

Supported OBJ Elements

• Vertices (v) - 3D vertex positions
• Texture Coordinates (vt) - 2D texture coordinates
• Normals (vn) - Vertex normal vectors
• Faces (f) - Face definitions with vertex indices
• Objects (o) - Object group definitions
• Material Libraries (mtllib) - Material file references
• Material Applications (usemtl) - Material assignments

:book: Getting Started

Add the following to your Cargo.toml:

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

# Or for development from source:
asset-importer-rs-obj = { path = "../path/to/asset-importer-rs-obj" }

:small_orange_diamond: Usage Examples

Basic OBJ import example:

use asset_importer_rs_obj::{
    ObjImporter,
    ObjImportError,
};
use std::path::Path;

// Create an importer
let importer = ObjImporter::new();

// Import an OBJ file
let scene = importer.import_file(Path::new("model.obj"))?;

// Access scene data
println!("Scene has {} meshes", scene.meshes.len());
println!("Scene has {} materials", scene.materials.len());

// Access mesh data
for mesh in &scene.meshes {
    println!("Mesh has {} vertices", mesh.vertices.len());
    println!("Mesh has {} faces", mesh.faces.len());
}

Importing with material support:

use asset_importer_rs_obj::ObjImporter;

// Create an importer
let importer = ObjImporter::new();

// Import OBJ with MTL file
let scene = importer.import_file("model_with_materials.obj")?;

// Access material data
for material in &scene.materials {
    println!("Material: {:?}", material.name);
    // Access material properties like diffuse, specular, etc.
}

Error handling example:

use asset_importer_rs_obj::{ObjImporter, ObjImportError};

let importer = ObjImporter::new();

match importer.import_file("model.obj") {
    Ok(scene) => {
        println!("Successfully imported OBJ file");
        // Process scene data
    }
    Err(ObjImportError::FileNotFound) => {
        eprintln!("OBJ file not found");
    }
    Err(ObjImportError::ParseError(msg)) => {
        eprintln!("Parse error: {}", msg);
    }
    Err(e) => {
        eprintln!("Other error: {:?}", e);
    }
}

:small_orange_diamond: Architecture

The OBJ crate provides a complete implementation of the Wavefront OBJ format with a focus on efficient parsing and material handling. The importer handles file parsing, geometry processing, material loading, and scene construction, integrating seamlessly with the asset-importer-rs ecosystem.

The crate uses the tObj library for initial parsing but provides optimized handling for the asset-importer-rs pipeline, ensuring efficient memory usage and proper integration with the broader 3D asset ecosystem.

:small_orange_diamond: Dependencies

Core Dependencies

• tobj - Core OBJ parsing and validation
• asset-importer-rs-core - Core import functionality
• asset-importer-rs-scene - Scene data structures
• bytemuck - Safe type casting
• enumflags2 - Flag-based enums
• image - Image processing and format support

Standard Library Dependencies

• std::io - File I/O operations
• std::path - Path handling

:warning: Implementation Notes

Why tObj over obj-rs? tObj provides better separation of models and materials for easy parsing, whereas obj-rs keeps them together. This separation aligns better with the asset-importer-rs architecture.

Future Improvements: While tObj serves as a good foundation, there are several optimizations that could be implemented with a custom parser:

• Direct Parsing - Avoid converting parsed Points, Lines, Triangles, Quads, and Polygons into face_arities, instead let asset-importer-rs handle the conversion
• Memory Streaming - Load one Model at a time, process it, then move on (losing Vec capacity benefits but gaining memory efficiency)
• Better Attribute Handling - Improved handling of missing or rare attributes that tObj doesn't handle well

In general, writing a custom parser would be more efficient for our use case, but getting things to work comes first. The current implementation provides a solid foundation for OBJ import functionality.

:scroll: License

This project is part of the asset-importer-rs workspace and follows its licensing terms. See the main project LICENSE file for details.

Copyright (c) 2024 Jackson Levitt