tobj – Tiny OBJ Loader
Inspired by Syoyo’s excellent tinyobjloader.
Aims to be a simple and lightweight option for loading OBJ files.
Just returns two Vecs containing loaded models and materials.
Triangulation
Meshes can be triangulated on the fly or left as-is.
Only polygons that are trivially convertible to triangle fans are supported. Arbitrary polygons may not behave as expected. The best solution would be to convert your mesh to solely consist of triangles in your modeling software.
Optional – Normals, Texture Coordinates and Vertex Colors
It is assumed that all meshes will at least have positions, but normals, texture coordinates and vertex colors are optional.
If no normals, texture coordinates or vertex colors are found, then the
corresponding Vecs for the Mesh will be empty.
Flat Data
Values are stored packed as floats in flat Vecs.
For example, the positions member of a Mesh will contain [x, y, z, x, y, z, ...] which you can then use however you like.
Indices
Indices are also loaded and may re-use vertices already existing in the mesh,
this data is stored in the indices member.
When a Mesh contains per vertex per face normals or texture coordinates,
positions can be duplicated to be per vertex per face too via the
single_index flag. This potentially changes the topology (faces may become
disconnected even though their vertices still share a position in space).
By default separate indices for normals and texture coordinates are created.
This also guarantees that the topology of the Mesh does not change when
either of the latter are specified per vertex per face.
Materials
Standard MTL attributes are supported too. Any unrecognized parameters will be
stored in a HashMap containing the key-value pairs of the unrecognized
parameter and its value.
Features
-
ahash– On by default. UseAHashMapfor hashing when reading files and merging vertices. To disable and use the slowerHashMapinstead, unset default features inCargo.toml:[dependencies.tobj] default-features = false
-
merging– Adds support for merging identical vertex positions on disconnected faces during import.Warning: this feature uses const generics and thus requires at least a
betatoolchain to build. -
reordering– Adds support for reordering the normal- and texture coordinate indices. -
async– Adds support for async loading of obj files from a buffer, with an async material loader. Useful in environments that do not support blocking IO (e.g. WebAssembly).
Documentation
Rust docs can be found here.
Installation
Add the crate as a dependency in your
Cargo.toml and you’re all set!
Example
The print mesh example (also below) loads an OBJ
file from the command line and prints out some information about its faces,
vertices, and materials.
fn main() {
let obj_file = std::env::args()
.skip(1)
.next()
.expect("A .obj file to print is required");
let (models, materials) =
tobj::load_obj(
&obj_file,
&tobj::LoadOptions::default()
)
.expect("Failed to OBJ load file");
// Note: If you don't mind missing the materials, you can generate a default.
let materials = materials.expect("Failed to load MTL file");
println!("Number of models = {}", models.len());
println!("Number of materials = {}", materials.len());
for (i, m) in models.iter().enumerate() {
let mesh = &m.mesh;
println!("");
println!("model[{}].name = \'{}\'", i, m.name);
println!("model[{}].mesh.material_id = {:?}", i, mesh.material_id);
println!(
"model[{}].face_count = {}",
i,
mesh.face_arities.len()
);
let mut next_face = 0;
for face in 0..mesh.face_arities.len() {
let end = next_face + mesh.face_arities[face] as usize;
let face_indices = &mesh.indices[next_face..end];
println!(" face[{}].indices = {:?}", face, face_indices);
if !mesh.texcoord_indices.is_empty() {
let texcoord_face_indices = &mesh.texcoord_indices[next_face..end];
println!(
" face[{}].texcoord_indices = {:?}",
face, texcoord_face_indices
);
}
if !mesh.normal_indices.is_empty() {
let normal_face_indices = &mesh.normal_indices[next_face..end];
println!(
" face[{}].normal_indices = {:?}",
face, normal_face_indices
);
}
next_face = end;
}
// Normals and texture coordinates are also loaded, but not printed in
// this example.
println!(
"model[{}].positions = {}",
i,
mesh.positions.len() / 3
);
assert!(mesh.positions.len() % 3 == 0);
for vtx in 0..mesh.positions.len() / 3 {
println!(
" position[{}] = ({}, {}, {})",
vtx,
mesh.positions[3 * vtx],
mesh.positions[3 * vtx + 1],
mesh.positions[3 * vtx + 2]
);
}
}
for (i, m) in materials.iter().enumerate() {
println!("material[{}].name = \'{}\'", i, m.name);
println!(
" material.Ka = ({}, {}, {})",
m.ambient[0], m.ambient[1], m.ambient[2]
);
println!(
" material.Kd = ({}, {}, {})",
m.diffuse[0], m.diffuse[1], m.diffuse[2]
);
println!(
" material.Ks = ({}, {}, {})",
m.specular[0], m.specular[1], m.specular[2]
);
println!(" material.Ns = {}", m.shininess);
println!(" material.d = {}", m.dissolve);
println!(" material.map_Ka = {}", m.ambient_texture);
println!(" material.map_Kd = {}", m.diffuse_texture);
println!(" material.map_Ks = {}", m.specular_texture);
println!(" material.map_Ns = {}", m.shininess_texture);
println!(" material.map_Bump = {}", m.normal_texture);
println!(" material.map_d = {}", m.dissolve_texture);
for (k, v) in &m.unknown_param {
println!(" material.{} = {}", k, v);
}
}
}