feat(physics): add UsdPhysics schema reader

[bresilla]

Been carrying this code in bevy_openusd (a Bevy plugin that loads USD scenes) for a while as a separate usd_schemas crate. Realised the right home for the schema layer is here in openusd-rs — keeping it inside a Bevy-side crate doesn't make sense when it's pure schema decoding that any consumer would want. So I'm moving it over, starting with physics since it's the most polished. Happy to do follow-up PRs for the other schema families I have lying around (geom, shade, lux, skel, render, ui, media) if you think they're useful.

What's in:

• All 8 concrete prim types: PhysicsScene, generic PhysicsJoint, Fixed / Revolute / Prismatic / Spherical / Distance joint, PhysicsCollisionGroup
• All 7 single-apply APIs: RigidBody, Mass, Collision, MeshCollision, Material, ArticulationRoot, FilteredPairs
• Both multi-apply APIs: PhysicsLimitAPI:<dof> and PhysicsDriveAPI:<dof>
• Material binding via material:binding:physics with fallback to plain material:binding
• One-shot find_physics_prims(&Stage) that walks once and returns categorised path lists, so callers don't re-walk per family

Module shape mirrors the C++ surface in pxr/usd/usdPhysics/:

src/physics/
├── mod.rs       # public surface + docs
├── tokens.rs    # every physics:* attr name + DOF / approx / axis / drive tokens
├── types.rs     # JointKind, Dof, DriveType, CollisionApprox + Read* structs
└── read.rs      # 14 reader functions

I went with physics (single-word, no usd_ prefix) to match the brevity of sdf / pcp / ar / stage. Future schema modules would follow the same shape — geom, shade, lux, etc. The "Usd" is implicit in the crate name. Open to renaming if you'd prefer something else.

Conventions followed by the readers (called out in the module docs):

• Linear values stay in scene units; mass in scene mass units (caller applies metersPerUnit / kilogramsPerUnit)
• Angles stay in degrees, quaternions stay in (w, x, y, z) order — both as USD authors them
• lower > upper on any limit means a locked DOF
• Functions return None when a schema isn't applied / the prim isn't of the expected type

Tests:

• New fixtures/usdPhysics_scene.usda — small scene exercising every reader (gravity, all 6 joint kinds incl. multi-apply limits + drives, material binding, collision group, filtered pairs)
• tests/physics_reader.rs — 15 integration tests, all green
• The existing usdPhysics_schema.usda fixture (used by text_writer_roundtrip) is the schema definition file — fine for parser tests, but not a populated scene, hence the new fixture

Not in this PR (called out in the module + struct docs):

• Authoring helpers (define / apply functions). Happy to do those in a follow-up once there's a higher-level authoring API in the crate to build on, or to add a small set that take &mut sdf::Data directly if that's preferred
• Full UsdCollectionAPI rule evaluation for CollisionGroup membership — the reader currently returns the raw collection:colliders:includes target list, adequate for the common authoring pattern

The reader has been load-tested against the Agilebot GBT-C5A robot (Isaac Sim USDC asset, ~165 prims, 7 rigid bodies, 1 articulation root, 6 revolute + 1 fixed joints) — every schema decodes cleanly.

[Copilot]

Pull request overview

Adds a new physics module to openusd-rs that decodes the UsdPhysics schema family from a composed Stage, along with an integration-test fixture that exercises the full reader surface.

Changes:

• Introduces openusd::physics module with tokens, decoded types, and reader functions (including a one-pass find_physics_prims stage walk).
• Adds a comprehensive USDA fixture scene covering scenes, rigid bodies, mass, collision/material binding, all joint kinds, multi-apply limits/drives, collision groups, and filtered pairs.
• Adds integration tests validating reader behavior against the fixture.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/lib.rs	Exposes the new physics module from the crate root.
src/physics/mod.rs	Defines the module’s public surface and re-exports readers/types/tokens.
src/physics/tokens.rs	Adds canonical UsdPhysics token constants (schema names, attr/rel names, instance tokens).
src/physics/types.rs	Adds decoded enums/structs returned by the reader API.
src/physics/read.rs	Implements schema reader functions and stage-walk discovery helper.
fixtures/usdPhysics_scene.usda	Adds a purpose-built integration-test fixture scene covering all supported readers.
tests/physics_reader.rs	Adds integration tests validating each reader against the fixture.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.