Crate animsmith_fbx 

load_source and load_source_bytes retain bounded importer-sensitive source facts beside the normalized animsmith_core::Document produced from the same exact FBX bytes. load and load_bytes remain the document-only compatibility APIs and deliberately discard that immutable sidecar. Parser and projection errors are normalized into LoadError.

The loader normalizes FBX scenes into animsmith’s runtime-oriented coordinate space before handing them to animsmith-core: right-handed +Y-up axes, metres, transform-adjust conversion, helper nodes for geometric transforms, and compensated scale inheritance. Depend on this crate only when your pipeline accepts FBX input; it brings the bundled ufbx C build that animsmith-core and animsmith-gltf intentionally avoid.

The source-facts boundary is deliberately narrower than raw FBX bytes. Effective units, signed axes, FPS, take ranges, layer/property bindings, and component-curve presence are parser-projected from ufbx. Advisory OriginalUnitScaleFactor/OriginalUpAxis values are not substituted for the effective settings. Because animation stacks pass through ufbx::bake_anim, the sidecar never claims authored interpolation, keys, or tangents from baked tracks. Resource rows retain bounded relative declarations only; unsafe spellings are classified and redacted, and no dependency is opened solely to build source facts.

load_scale_source and load_scale_source_bytes retain a typed FbxScaleCapabilityInventory from the same parse. It gives every current Appendix D.4 domain an explicit status and records baked curves, normalized transforms, derived binds, truncated/renormalized influences, triangulation, welding, generated data, and unavailable raw-span proof. capability_facts remains the conservative generic refusal projection. rest_bind_capability_facts admits only the complete normalized subset used by the CLI’s narrow FBX rest/bind path: it stages a new GLB, proves that emitted GLB, and never claims raw FBX preservation. Its source-aware companion admits material shader metadata, enumerated scale-invariant conversion-fidelity facts such as triangulation, exact welding, retained effective skinning, and omitted face/edge payload, and only those BindPoses whose converted rows reconcile with the cluster/node matrices consumed by that bridge. require_clip_track_capability_for_source keeps the same raw construct and animation/hierarchy checks while projecting away geometry, deformation, material, camera/light, and bind domains that a clip-only assembly input cannot contribute. The public inventory still records every conversion and its inventory-only projection remains conservative. Whole-document FBX scaling remains refused.

Quick start

fn lint_fbx(
    path: &std::path::Path,
) -> Result<Vec<animsmith_core::Finding>, Box<dyn std::error::Error>> {
    let doc = animsmith_fbx::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())
}

Build and API status

The library crate has no public feature flags and supports the workspace MSRV, Rust 1.88. It includes the bundled ufbx C build. 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 FBX intake and conversion workflows.

Structs

FbxCoordinateNormalization

Coordinate and unit normalization applied by the loader.

FbxScaleCapabilityInventory

Deterministic capability inventory captured from one successfully parsed FBX scene.

FbxScaleDomainInventory

Explicit status for every current domain row in DESIGN.md Appendix D.4.

FbxScaleSource

One immutable FBX source/document owner and scale capability inventory captured from the same parse.

FbxSourceIdentity

Stable source identity retained beside one normalized ufbx element.

Enums

FbxBindMatrixProvenance

Provenance of inverse-bind matrices projected into the source sidecar.

FbxCoordinateAxis

A format-independent spelling of one FBX coordinate axis.

FbxScaleDomainStatus

How one Appendix D.4 domain reaches the normalized FBX document.

LoadError

Errors returned while loading an FBX scene into the core model.

Functions

capability_facts

Project an FBX inventory into the format-neutral core capability gate.

capability_facts_for_source

Project scale capabilities from one immutable captured FBX source.

load

Load an .fbx file into a core Document: skeleton, animation, and scene assets (triangulated meshes, skins, factor-only materials). Consumers that only judge animation ignore Document::assets.

load_bytes

Load an FBX byte slice into a core Document.

load_bytes_with_resource_root

Load captured FBX bytes with one explicit trusted resource root.

load_scale_source

Load an .fbx file and retain its conservative scale capability inventory.

load_scale_source_bytes

Load captured FBX bytes and retain the capability inventory from the same parse.

load_scale_source_bytes_with_resource_root

Load captured FBX bytes with a trusted external-resource root and retain its scale capability inventory.

load_source

Load an .fbx file and retain bounded importer-sensitive source facts.

load_source_bytes

Load captured FBX bytes and retain bounded importer-sensitive source facts.

load_source_bytes_with_resource_root

Load captured FBX bytes and retain source facts plus a rooted dependency closure.

require_clip_track_capability_for_source

Project the FBX domains required by an animation-only assembly input.

rest_bind_capability_facts

Project the narrow FBX subset that can enter rest/bind scaling.

rest_bind_capability_facts_for_source

Project the narrow FBX rest/bind subset from one captured source.