v0.8.0

This release introduces openusd-build, a code generator that turns a schema library's schema.usda into typed Rust views. It generates every schema in openusd-schemas, which replaces the hand-written views of earlier releases, and adds UsdSemantics as a new family. UsdGeom gains primvars, VisibilityAPI and MotionAPI. Opening and traversing a stage is faster and takes less memory thanks to @bresilla and @doubleailes; #142 and this comment have the figures.

Also in this release: the new usd_utils module ports UsdUtils dependency discovery, .usdz packaging and asset-path rewriting (compute_all_dependencies, create_new_usdz_package, modify_asset_paths), and a .usdz package nested in another package now reads. usd::ResolveInfo, through Attribute::resolve_info, reports which spec a resolved value came from and what composed into it. usd::Stage::flatten writes a composed stage into one layer.

Schema codegen

openusd-build serves the purpose usdGenSchema serves for C++, and runs from a build script:

[dependencies]
openusd = "0.8"

[build-dependencies]
openusd-build = "0.8"

// build.rs
fn main() -> Result<(), openusd_build::Error> {
    openusd_build::configure()
        .search_path("schemas")
        .schema("schemas/usdGeom/schema.usda")
        .generate()
}

openusd::include_schema! includes the generated views under the libraryName the schema.usda declares, and the generated SCHEMAS constant registers the library with a stage:

use openusd::{gf, usd};

pub mod geom {
    openusd::include_schema!("usdGeom");
}

let registry = usd::SchemaRegistry::builder().register(geom::SCHEMAS).build()?;
let stage = usd::Stage::builder().schema_registry(registry).open("scene.usda")?;

let mesh = geom::Mesh::get(&stage, "/World/Mesh")?.expect("a Mesh");
let points = mesh.points_attr().get::<Vec<gf::Vec3f>>()?;

Primvars

geom::PrimvarsAPI creates, lists, blocks and removes a prim's primvars, and geom::Primvar reads one together with its interpolation and indices:

use openusd::usd::{self, SchemaBase};
use openusd::sdf;
use openusd_schemas::geom;

let stage = usd::Stage::builder()
    .schema_registry(openusd_schemas::schema_registry())
    .in_memory("scene.usda")?;
let mesh = geom::Mesh::define(&stage, "/Mesh")?;

// Four vertices share two values through the indices.
let heat = geom::PrimvarsAPI::from_prim_unchecked(mesh.prim().clone())
    .primvar_builder("heat", "float[]")
    .interpolation(geom::Interpolation::Vertex)
    .set(sdf::Value::FloatVec(vec![20.0, 35.0]))
    .indices(vec![0, 1, 1, 0])
    .build()?;

// `get_at` reads the values as authored; `compute_flattened` applies the
// indices and yields one value per vertex.
assert_eq!(heat.get_at::<Vec<f32>>(None)?, Some(vec![20.0, 35.0]));
assert_eq!(
    heat.compute_flattened::<Vec<f32>>(None)?,
    Some(vec![20.0, 35.0, 35.0, 20.0])
);

Compliance

New AOUSD Core Spec coverage in this release:

• 11.3.3 Scene graph instancing
• 11.5 Stage queries
• 12.2.8 Fallback values
• 13.3 Schema registry
• 13.3 Schema codegen
• 13.4 Core schema types
• 15.1 CollectionAPI

Changes

Schema codegen (openusd-build)

Features:

• Add the openusd-build crate skeleton (aaae6d5)
• Add schema name, type and doc conversions (e60539f)
• Read a schema library into the generator's model (21bae65)
• Generate the schematics and manifest layers (eab9cc8)
• Generate Rust schema views (ff6f660)
• Generate openusd-schemas with openusd-build (b7df5ad)
• Carry schema data as Rust declarations (eb39c84)
• Generate the core usd family from its definitions (fc043b4)
• Generate views for abstract schema classes (9887b92)
• Make a lowered schema always carry a view (9f31ec4)
• Recognise a prim once for both typed shapes (bc75fbf)
• Improve the documentation the generator writes (d19633e)
• Settle every generated name in one table (af4b1f9)
• Name a view's prim constructors for what they ask (df1e447)
• Generate token enums from allowedTokens (a1dd629)
• Generate the core family's schema views (56b015c)
• Take instance-name rules from the registry (5235043)
• Generate the builder a property declares itself as (9ffc971)
• Convert the sectioning commands and nested lists (13eae0e)
• Close the remaining schema codegen gaps (231d94d)
• Ask the prim for a schema's instance names (4d252a7)
• Generate typed reads, metadata and shader nodes (f4c262c)

Dependencies:

• Update the generator to syn 3 and prettyplease 0.3 (2cc9a1b)
• Keep single-consumer deps in their own crate (aa8c0b8)

Schemas (openusd-schemas)

UsdGeom:

• Compute purpose visibility through VisibilityAPI (85c9f61)
• Compute inherited UsdGeomMotionAPI settings (0e6d602)
• Add geom::XformCache (8b99014)
• Add geom::Primvar and the PrimvarsAPI queries (55c9009)
• Add usage examples to the geom schema docs (933aa8f)
• Build rotation xformOps through gf::Rotation, as C++ does (8507b68) by @doubleailes

UsdSemantics:

• Label prims by taxonomy with UsdSemantics (965c48e)
• Answer what a prim is labelled under a taxonomy (e34ed25)

UsdPhysics:

• Reach a collision group's colliders (5e8bbf6)
• Resolve which collision groups collide (5774287)

UsdSkel:

• Read skel influence primvars through Primvar (f764a92)
• Enumerate a skeleton animation's sample times (efc475d)

UsdVol:

• Choose a Gaussian splat's authored precision (da0621e)

Collections:

• Reshape Collection onto the generated CollectionAPI (d03a181)
• Read a collection's values through its definition (fe8e9e8)

Stage (usd)

Features:

• Add schema view roots and gate prim authoring (29e50e4)
• Register the vendored core usd schema family (08e8d8c)
• Seed the registry builder with the core family (89f5301)
• Flatten a composed stage into one layer (0c2a53d)
• Author a property spec through one orchestration (a74b107)
• Clear a property spec without creating one (306a932)
• Author a property, or a batch of them, as one edit (3b9179e)
• Name a prim's clip sets after what they are (1eeece2)
• Name the spec a resolved value came from (859e606)
• Report what composed into a resolved value (3fac170)
• Compose an attribute's value across its sources (f422d82)
• Read a value as the path expression it spells (5fb54f8)
• Read attribute values as C++ typed reads do (61b76ea)
• Compare usd handles by stage and path (88622d7)
• Add attribute presence and undecoded reads (098a02b)
• List a prim's attributes by namespace (928dd9c)
• Author metadata and blocks with an attribute (e432e5f)
• Queue a group of properties as one (8f69d0a)
• Add a registry of user-declared kinds (7bbb36d)

Fixes:

• Resolve search-path identifiers as C++ does (9a2c416)
• Keep a relationship's variability when flattening (7ae7fb2)
• Read prototype roots through an empty prim index (19b2714)
• Return the caller's error from Stage::edit (ae162a4)
• Sort property specs under the opinions gate (53a51ff)
• Keep an inactive prim's descendants off the stage (e9d0bd5)

Performance:

• perf(usd): read root layers once when opening (55dfd83) by @bresilla
• perf(usd): reuse the active check for loaded (42b897a) by @bresilla
• perf(usd): resolve abstract ancestry in one query (3b91cb3) by @bresilla
• perf(usd): resolve defined and abstract in one walk (8c53ee9) by @bresilla
• perf(usd): sort properties in one cache query (8bcee14) by @bresilla
• perf(usd): carry parent status through traversal (dfa151e) by @bresilla
• Open a prepared root stack without an Option (75e23fe)
• Compose a prim's status from its parent's (7e8ce93)
• Add a phase-split stage open benchmark (f90ea62)

Composition engine (pcp)

Fixes:

• fix(pcp): keep empty path out of index cache (b4ce551) by @bresilla
• fix(pcp): interpolate across clip activations (a401fe6) by @bresilla
• fix(pcp): match identity payload offsets (4efacf0) by @bresilla
• fix(pcp): report missing reference targets (778d1a9) by @bresilla
• fix(pcp): report missing same-layer targets (805967f) by @bresilla
• Fix lazy clip reads and composition diagnostics (746c2af)
• fix(pcp): check unresolved targets after variants (37d0f2a)
• Key instances on the arcs C++ PcpInstanceKey does (46fba59) by @doubleailes
• Require an instanceable node to make an instance (0e83641)

Scene description (sdf)

Features:

• Give a value type the unit it measures in (dc8e46c)
• Record a value no schema can type (8b0b3cd)
• Ask a value how many elements it holds (be72bc4)
• Gather array elements by position (b872766)
• Name the ancestor walk that stops below the root (b1dc8e7)
• Add the format and registry seams packaging shares (653f7c2)
• Save a layer as a replace transaction (80353ec)
• Rebind a saved layer from the writer's tables (1599fc0)
• Mint process-unique ids from one counter (cbaf6cf)

Fixes:

• Keep a replaced file's access control on Windows (9529f42)

Performance:

• perf(sdf): share a path's text between clones (57cab20) by @bresilla
• Share the empty and root path text (40bb570)
• Carry a layer's bytes in one type (ca63895)
• Open a layer through one resolve-and-read step (b6c8ba3)

Text format (usda)

Fixes:

• Write a lone list-op item the way C++ does (d05a68d)
• Store variantSetNames as a list op of strings (2fa5937)
• Parse schema metadata as its declared type (58970c1)
• fix(usda): write customData on references (4a0f3b6) by @bresilla

Binary format (usdc)

Fixes:

• Write a vector field as the type C++ reads (151f42d)
• Return errors instead of aborting on damaged USDC files (9484705) by @humships
• Read compact USDC path tables without rejecting valid files (6eb70c6)
• Match the C++ compressed-array threshold (1f18ada)

Performance:

• Decode crate values from the layer's bytes (25ff503)

Packages (usdz)

Features:

• feat(usdz): read packages nested in packages (8028bbf) by @bresilla
• Resolve a nested package path one level at a time (2669f23)

Performance:

• perf(usdz): find default layer without full read (3c777ca) by @bresilla
• Serve package entries as views of the package (f24e8df)
• Move the package cache from ar to usdz (b0aa164)

Asset resolution and memory mapping (ar)

Features:

• Map file assets on resolver opt-in (ae80142)
• Cache packages, advise maps, remap saved layers (c4f6d07)
• Make the mmap feature opt-in (75af213)

Fixes:

• Read \ as a separator in relative asset paths (c2c1afc)

Performance:

• perf(ar): hand over cursor buffer in read_all (a06dfa4) by @bresilla
• perf(ar): share asset bytes with file formats (e6142c3) by @bresilla
• Consume an asset to hand its buffer over (7b82033)
• Decode shared asset bytes in every format (2b2db0f)
• Rename AssetBytes to AssetBuffer (fe13a26)
• View shared asset bytes through a range (e3c7f9e)

Utilities (usd_utils)

Features:

• feat(usd_utils): compute all dependencies (324e347) by @bresilla
• feat(usd_utils): create new usdz package (07d3533) by @bresilla
• feat(usd_utils): modify asset paths (894ff01) by @bresilla
• Split usd_utils into walk, discovery and packaging (08fbf3c)

Graphics foundations (gf)

Features:

• Spell open interval bounds with gf::Interval (eae8cdf)

Fixes:

• Match C++ on NaN quaternions and Quatf normalize (5faa266)