openusd 0.4.0

Rust native USD library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186

//! `PhysicsRigidBodyAPI` and `PhysicsMassAPI` authoring.
//!
//! `apply_rigid_body` adds the API to any UsdGeomXformable; the chain
//! exposes the 6 spec'd attributes. `apply_mass` does the same for
//! `PhysicsMassAPI` (5 attrs).

use anyhow::Result;

use crate::sdf::Path;
use crate::usd::{Prim, Stage};

use crate::schemas::physics::tokens::{
    API_MASS, API_RIGID_BODY, A_ANGULAR_VELOCITY, A_CENTER_OF_MASS, A_DENSITY, A_DIAGONAL_INERTIA, A_KINEMATIC_ENABLED,
    A_MASS, A_PRINCIPAL_AXES, A_RIGID_BODY_ENABLED, A_SIMULATION_OWNER, A_STARTS_ASLEEP, A_VELOCITY,
};

use super::common::{
    author_bool, author_float, author_float3, author_point3f, author_quatf, author_rel_targets, author_uniform_bool,
    author_vector3f,
};

// ── PhysicsRigidBodyAPI ─────────────────────────────────────────────

/// Apply `PhysicsRigidBodyAPI` to the prim at `path` and return a
/// chainable [`RigidBodyAuthor`] for the 6 spec-defined attrs plus the
/// `simulationOwner` relationship.
pub fn apply_rigid_body<'s>(stage: &'s Stage, path: impl Into<Path>) -> Result<RigidBodyAuthor<'s>> {
    let prim = stage.override_prim(path)?.add_applied_schema(API_RIGID_BODY)?;
    Ok(RigidBodyAuthor { prim })
}

pub struct RigidBodyAuthor<'s> {
    prim: Prim<'s>,
}

impl<'s> RigidBodyAuthor<'s> {
    pub fn into_prim(self) -> Prim<'s> {
        self.prim
    }

    /// Set `physics:rigidBodyEnabled` (spec default true).
    pub fn set_enabled(self, enabled: bool) -> Result<Self> {
        author_bool(self.prim.stage(), self.prim.path(), A_RIGID_BODY_ENABLED, enabled)?;
        Ok(self)
    }

    /// Set `physics:kinematicEnabled` (spec default false). A kinematic
    /// body is moved through animated poses; the simulator derives
    /// velocities from the motion rather than integrating forces.
    pub fn set_kinematic(self, kinematic: bool) -> Result<Self> {
        author_bool(self.prim.stage(), self.prim.path(), A_KINEMATIC_ENABLED, kinematic)?;
        Ok(self)
    }

    /// Set `physics:startsAsleep` (uniform bool, spec default false).
    pub fn set_starts_asleep(self, asleep: bool) -> Result<Self> {
        author_uniform_bool(self.prim.stage(), self.prim.path(), A_STARTS_ASLEEP, asleep)?;
        Ok(self)
    }

    /// Set `physics:velocity` in distance/second.
    pub fn set_velocity(self, velocity: [f32; 3]) -> Result<Self> {
        author_vector3f(self.prim.stage(), self.prim.path(), A_VELOCITY, velocity)?;
        Ok(self)
    }

    /// Set `physics:angularVelocity` in degrees/second.
    pub fn set_angular_velocity(self, angular_velocity: [f32; 3]) -> Result<Self> {
        author_vector3f(
            self.prim.stage(),
            self.prim.path(),
            A_ANGULAR_VELOCITY,
            angular_velocity,
        )?;
        Ok(self)
    }

    /// Set `physics:simulationOwner` — relationship to the
    /// `PhysicsScene` driving this body.
    pub fn set_simulation_owner(self, scene: impl Into<Path>) -> Result<Self> {
        author_rel_targets(self.prim.stage(), self.prim.path(), A_SIMULATION_OWNER, [scene.into()])?;
        Ok(self)
    }
}

// ── PhysicsMassAPI ──────────────────────────────────────────────────

/// Apply `PhysicsMassAPI` to the prim at `path` and return a chainable
/// [`MassAuthor`] for the 5 spec-defined attrs.
pub fn apply_mass<'s>(stage: &'s Stage, path: impl Into<Path>) -> Result<MassAuthor<'s>> {
    let prim = stage.override_prim(path)?.add_applied_schema(API_MASS)?;
    Ok(MassAuthor { prim })
}

pub struct MassAuthor<'s> {
    prim: Prim<'s>,
}

impl<'s> MassAuthor<'s> {
    pub fn into_prim(self) -> Prim<'s> {
        self.prim
    }

    /// Set `physics:mass` (spec default 0.0 — meaning "ignored, derive
    /// from density × volume"). Per spec, parent's mass overrides
    /// child's.
    pub fn set_mass(self, mass: f32) -> Result<Self> {
        author_float(self.prim.stage(), self.prim.path(), A_MASS, mass)?;
        Ok(self)
    }

    /// Set `physics:density` (spec default 0.0 — ignored). Child's
    /// density overrides parent's (opposite precedence vs `mass`).
    pub fn set_density(self, density: f32) -> Result<Self> {
        author_float(self.prim.stage(), self.prim.path(), A_DENSITY, density)?;
        Ok(self)
    }

    /// Set `physics:centerOfMass` in the prim's local space.
    pub fn set_center_of_mass(self, center: [f32; 3]) -> Result<Self> {
        author_point3f(self.prim.stage(), self.prim.path(), A_CENTER_OF_MASS, center)?;
        Ok(self)
    }

    /// Set `physics:diagonalInertia` along the principal axes.
    pub fn set_diagonal_inertia(self, inertia: [f32; 3]) -> Result<Self> {
        author_float3(self.prim.stage(), self.prim.path(), A_DIAGONAL_INERTIA, inertia)?;
        Ok(self)
    }

    /// Set `physics:principalAxes` orientation. Quat order `(w, x, y, z)`.
    pub fn set_principal_axes(self, quat: [f32; 4]) -> Result<Self> {
        author_quatf(self.prim.stage(), self.prim.path(), A_PRINCIPAL_AXES, quat)?;
        Ok(self)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::sdf;

    #[test]
    fn rigid_body_roundtrip() -> Result<()> {
        let stage = Stage::builder().in_memory("anon.usda")?;
        stage.define_prim("/Body")?.set_type_name("Xform")?;
        stage.define_prim("/Scene")?.set_type_name("PhysicsScene")?;
        apply_rigid_body(&stage, sdf::path("/Body")?)?
            .set_enabled(true)?
            .set_kinematic(false)?
            .set_starts_asleep(true)?
            .set_velocity([1.0, 0.0, 0.0])?
            .set_angular_velocity([0.0, 0.0, 30.0])?
            .set_simulation_owner(sdf::path("/Scene")?)?;

        let body =
            crate::schemas::physics::read_rigid_body(&stage, &sdf::path("/Body")?)?.expect("PhysicsRigidBodyAPI");
        assert!(body.rigid_body_enabled);
        assert!(!body.kinematic_enabled);
        assert!(body.starts_asleep);
        assert_eq!(body.velocity, Some([1.0, 0.0, 0.0]));
        assert_eq!(body.angular_velocity, Some([0.0, 0.0, 30.0]));
        assert_eq!(body.simulation_owner.as_deref(), Some("/Scene"));
        Ok(())
    }

    #[test]
    fn mass_roundtrip() -> Result<()> {
        let stage = Stage::builder().in_memory("anon.usda")?;
        stage.define_prim("/Body")?.set_type_name("Xform")?;
        apply_mass(&stage, sdf::path("/Body")?)?
            .set_mass(10.0)?
            .set_density(1000.0)?
            .set_center_of_mass([0.0, 0.5, 0.0])?
            .set_diagonal_inertia([1.0, 2.0, 3.0])?
            .set_principal_axes([1.0, 0.0, 0.0, 0.0])?;

        let mass = crate::schemas::physics::read_mass(&stage, &sdf::path("/Body")?)?.expect("PhysicsMassAPI");
        assert_eq!(mass.mass, Some(10.0));
        assert_eq!(mass.density, Some(1000.0));
        assert_eq!(mass.center_of_mass, Some([0.0, 0.5, 0.0]));
        assert_eq!(mass.diagonal_inertia, Some([1.0, 2.0, 3.0]));
        assert_eq!(mass.principal_axes, Some([1.0, 0.0, 0.0, 0.0]));
        Ok(())
    }
}