Crate animsmith_gltf

Expand description

load_source and load_source_bytes read .gltf/.glb input into an immutable normalized-document plus raw-source-facts owner. load and load_bytes retain the legacy document-only surface, and write::write emits a document as glTF/GLB, and the fix module provides byte-surgical quaternion repairs. preflight_scale_source inventories the original raw source and fails closed on domains that current scale producers cannot preserve. Malformed inputs report LoadError; output failures report WriteError.

This crate is the glTF/GLB format edge around animsmith-core. Loading preserves authored animation values for checks and also carries meshes, skins, materials, and embedded textures into Document::assets. Writing is a model round-trip for convert and transform; use fix::FixSession when a repair must preserve every non-animation byte of the original container.

§Quick start

Load a document and run the shared core checks:

fn lint_clip(
    path: &std::path::Path,
) -> Result<Vec<animsmith_core::Finding>, Box<dyn std::error::Error>> {
    let doc = animsmith_gltf::load(path)?;
    let roles = animsmith_core::detect_profile(&doc.skeleton).unwrap_or_default();
    let config = animsmith_core::Config::default();
    let grids = animsmith_core::MetricGrids::new(&doc);
    let ctx = animsmith_core::CheckCtx::new(&grids, &roles, &config);
    let results = animsmith_core::evaluate_checks(
        &ctx,
        &animsmith_core::all_checks(),
        animsmith_core::CheckSelection::All,
    )?;
    Ok(results
        .into_iter()
        .flat_map(|check| check.findings().to_vec())
        .collect())
}

Compose byte-surgical repairs through one session:

fn repair_quaternions(
    input: &std::path::Path,
    output: &std::path::Path,
) -> Result<(), Box<dyn std::error::Error>> {
    use animsmith_gltf::fix::{FixSession, Repair};

    let mut session = FixSession::read(input)?;
    session.apply(Repair::QuatNorm);
    session.apply(Repair::QuatFlip);
    session.write(input, output)?;
    Ok(())
}

§Build and API status

This crate has no public feature flags and supports the workspace MSRV, Rust 1.88. Its Rust API is pre-1.0; see animsmith-core’s crate-level API status for the shared stability boundary.

See the GitHub embedding guide for crate selection and the pipeline scenario guide for raw-to-game-ready workflows.

Modules§

fix: Byte-surgical clip repairs: mutate only the animation accessor bytes that need to change and copy everything else through verbatim. A fixed character GLB keeps its meshes, skins, materials, and textures byte-identical — the output diff is exactly the repaired keys.
write: Minimal glTF 2.0 writer for convert/transform: emits the skeleton (node hierarchy + rest TRS), each clip’s writable animation tracks, and whatever scene assets the Document carries (Document::assets — triangulated meshes, skins, factor-only materials, and embedded base-color and normal textures). A document with default-empty assets writes animation + skeleton only, so animation data can still enter glTF-based tooling (including animsmith itself) straight from a DCC export.

Structs§

GltfAccessorCapability: One raw accessor layout required by a future exact-source rewrite.
GltfAnimationChannelCapability: One animation channel and its exact accessor identities.
GltfAttributeCapability: One vertex attribute declaration and its source accessor.
GltfBufferCapability: One source buffer recorded before normalized loading.
GltfBufferViewCapability: One raw buffer-view layout.
GltfCapabilityManifest: Deterministic facts captured from the original glTF/GLB source.
GltfCapabilityViolation: One deterministic, source-indexed preflight rejection.
GltfInstancingCapability: One raw EXT_mesh_gpu_instancing declaration and its accessor identities.
GltfNodeCapability: One source node identity and authored rest representation.
GltfPrimitiveCapability: One source primitive and every declared attribute semantic.
GltfRawJsonDifference: One value-free raw JSON difference found by an artifact preservation proof.
GltfRawJsonDifferenceSummary: Bounded raw JSON diagnostics for an artifact preservation proof failure.
GltfScaleArtifact: A rewritten glTF/GLB container and the exact locations that changed.
GltfScaleArtifactProof: Observed artifact-level evidence from prove_rewritten_artifact or super::prove_rewritten_rest_bind.
GltfScaleSource: A captured, immutable source that passed the common scale preflight.
GltfSkinCapability: Read-side inverse-bind declaration for one source skin.

Enums§

ExternalResourceFailure: Sanitized failure classes for external resources required by the loader.
FixError: fix errors are classified by defect, not by phase: LoadError means the input was unreadable or malformed (even when detected while assembling the output, e.g. re-deriving GLB chunk bounds or validating an input-supplied buffer URI); WriteError means emitting the output failed.
GltfBufferSourceKind: How one source buffer was declared.
GltfCapabilityViolationKind: Stable machine identity for one fail-closed capability violation.
GltfContainerKind: Whether the captured top-level source is JSON glTF or a binary GLB.
GltfNodeRestKind: Whether a node authored decomposed TRS or a matrix.
GltfRawJsonDifferenceKind: The structural relationship of one raw JSON difference to the source.
GltfScalePreflightError: Failure to load or safely preflight a captured scale source.
GltfScaleRewriteError: Typed, fail-closed rejection from rewrite_linear_units or prove_rewritten_artifact.
LoadError: Errors returned while loading .gltf or .glb input.
WriteError: Errors returned while writing a core document as glTF/GLB.

Functions§

capability_facts: Project a raw glTF capability manifest onto the format-neutral ScaleCapabilityFacts that animsmith_core::scale::plan_scale consumes.
capability_facts_for_source: Project scale capability facts from one immutable captured source.
load: Load a .glb or .gltf file into a core Document, including the scene assets (meshes, skins, materials, and embedded base-color and normal textures) its geometry describes — the symmetric read side of write::write, and the same one-call shape animsmith_fbx::load uses. Consumers that judge only animation (lint, inspect) simply ignore Document::assets. Non-triangle primitives are skipped rather than reinterpreted.
load_bytes: Load a .glb or .gltf byte slice into a core Document.
load_bytes_with_resource_root: Load captured bytes with an explicit trusted local root for external resources.
load_source: Load a .gltf or .glb file with immutable importer-sensitive source facts.
load_source_bytes: Load captured .gltf or .glb bytes with immutable raw-source facts.
load_source_bytes_with_resource_root: Load captured bytes with an explicit trusted local root for external resources.
operation_capability_facts: Validate a raw glTF capability manifest for one selected scale operation.
operation_capability_facts_for_source: Validate one captured glTF source for a selected scale operation.
preflight_scale_source: Read and preflight a glTF/GLB file without creating a candidate or output.
preflight_scale_source_bytes: Preflight captured glTF/GLB bytes without creating a candidate or output.
prove_rewritten_artifact: Independently re-derive and check every artifact-level claim.
prove_rewritten_rest_bind: Independently re-derive and check every artifact-level claim of the rest/bind reparameterization.
rewrite_linear_units: Rewrite source’s linear units by the caller-declared finite factor > 0.
rewrite_rest_bind: Reparameterize source’s rest/bind hierarchy, removing the compensating uniform factor expected_factor from the closure anchored at source_root_node_index and the joints of source_skin_index.
rewrite_scale_plan: Apply one already-compiled core scale plan to the raw glTF source.