Module gltf 

Available on crate feature gltf only.

glTF scene-graph import (opt-in via the gltf feature). glTF 2.0 scene-graph import into trees of MeshItems, opt-in via the gltf cargo feature. The gltf crate itself is re-exported here, so callers can parse documents without their own matching dependency.

Two loaders: node_tree_from_path reads a .glb (embedded blob) or .gltf (external buffer files resolved relative to the file) from disk, and the I/O-free node_tree_from_gltf takes a parsed document plus a buffer resolver.

Mapping

glTF	ranim
node TRS / matrix	Node pose as a DAffine3 (T * R * S)
node name (non-empty)	Node::id (payload nodes fall back to the mesh name)
node children	Node::children, source order kept
mesh (single primitive)	the node’s own payload MeshItem
mesh (multiple primitives)	primitive leaves before the children, identity transforms

glTF also addresses nodes by document index (animation channels, skin.joints) — GltfTree::node resolves that, Node::by_id resolves names. POSITION/indices/NORMAL/COLOR_0 map to the MeshItem fields with zero-normals and default colors as the absent-attribute fallbacks; COLOR_0 is stored as-is (no sRGB conversion for normalized integer variants).

Scope

Only the default scene imports (missing scene → empty tree). Cameras, lights, materials/textures (color comes from COLOR_0 or whatever you set after loading), TEXCOORD/TANGENT streams, animations, skins, morph targets and all extensions are not interpreted — Draco-compressed primitives therefore import as empty meshes with a warning. Non-TRIANGLES modes import their indices unchanged after a warning. glTF’s mandated Y-up is converted to ranim’s Z-up by composing Rx(π/2) into the root pose — apply the inverse there for verbatim coordinates.

Examples

use ranim_items::mesh::gltf::node_tree_from_path;

let tree = node_tree_from_path("model.glb")?;

For custom I/O, parse yourself and hand over a buffer resolver:

use ranim_items::mesh::gltf::{gltf, node_tree_from_gltf};

let bytes = std::fs::read("model.gltf")?;
let parsed = gltf::Gltf::from_slice(&bytes)?;
let blob = parsed.blob.clone();
let tree = node_tree_from_gltf(&parsed.document, |buffer| match buffer.source() {
    gltf::buffer::Source::Bin => blob.as_deref(),
    gltf::buffer::Source::Uri(_) => None, // read the file here
});

Re-exports

pub use gltf;

Structs

GltfTree

A glTF scene imported as a Node tree, plus the mapping from glTF node indices to index paths in the tree.

Enums

GltfLoadError

Errors from loading a glTF/GLB file via node_tree_from_path.

Functions

node_transform 🔒

Converts a glTF node transform to a [DAffine3]: the 4x4 matrix as-is, or the decomposed T * R * S (glTF semantics; the glTF crate’s [gltf::scene::Transform::matrix] uses the same equation).

node_tree_from_gltf

Builds the node tree of the default glTF scene as Nodes of MeshItems, wrapped in a GltfTree with the document-index → tree-path mapping.

node_tree_from_gltf_node 🔒

Converts one glTF node (recursively, via [gltf::scene::Node::children]).

node_tree_from_path

Loads a .glb or .gltf file from disk into a GltfTree.

non_empty 🔒

None for empty strings, so blank glTF names do not become ids.

primitive_leaf_id 🔒

The id of the leaf holding primitive index of a mesh on a node: the mesh name when present (disambiguated by index), else the node name, else none.

primitive_mesh_item 🔒

Converts one glTF primitive to a MeshItem.

warn_if_not_triangles 🔒

Warns when a primitive’s drawing mode is not TRIANGLES (its indices are imported as-is; no re-triangulation happens in the POC).

y_up_to_z_up 🔒

glTF mandates a right-handed Y-up; ranim is Z-up. The conversion is a fixed, spec-mandated convention translation, composed into the root pose so a loaded model stands upright and no vertex data moves.