Author, simulate, and visualize a falling cube#
Build a scene with the Foundation API, add rigid-body simulation through OvPhysX, and publish the simulated transforms to an OVGL viewport. The three examples form a progression, but each remains independently runnable.
Learning objectives#
After completing this tutorial, you can:
Author scene objects and transforms through Foundation.
Add collision, rigid-body behavior, and gravity without direct USD access.
Advance OvPhysX at a fixed time step and read measured body state.
Publish physics transforms to a stage before rendering them with OVGL.
Prerequisites#
Complete Install and run.
Run the commands in this tutorial from the repository root.
Use a graphical desktop for the interactive visualization. The authoring, simulation, and headless rendering tests do not require a visible window.
Examples used#
Example |
Role in this tutorial |
|---|---|
Authors a stage and sets the cube size and pose through Foundation. |
|
Authors a physical scene, imports it into OVStage, and advances it with OvPhysX. |
|
Publishes simulated transforms for inspection in a viewport. |
Each example page lists its source directory, requirements, and runner commands.
Author the scene through Foundation#
Create an OpenUSD-backed Stage and a Cube at /World/Cube. Use the
Foundation object API to set its pose, then close the stage to release native
resources:
def main() -> None:
"""Create a stage and author a cube."""
stage = Stage("openusd").create_stage()
try:
position = [0.0, 0.0, 2.0]
Cube("/World/Cube", sizes=1.0).set_world_poses(position)
print(f"Authored /World/Cube at ({position[0]:.1f}, {position[1]:.1f}, {position[2]:.1f}).")
finally:
stage.close_stage()
Cube defines the prim and authors its size. set_world_poses authors the
translation without direct pxr stage, attribute, or transform operations.
Run the authoring example:
source/examples/example.sh run falling_cube.author_cube
.\source\examples\example.bat run falling_cube.author_cube
Add and advance physics#
The simulation example authors the scene with additional Foundation objects and
prim wrappers. GroundPlane creates the static support, ColliderBody
adds a collision shape, RigidBody makes the cube dynamic, and
PhysicsScene defines gravity:
def _author_stage() -> str:
"""Author the scene with Foundation and return its USDA text.
Returns:
Flattened USDA representation.
"""
stage = Stage("openusd").create_stage()
try:
stage.define_prim("/World")
GroundPlane("/World/Ground", sizes=10.0)
Cube("/World/Cube", sizes=1.0).set_local_poses(translations=[0.0, 0.0, 2.0])
PhysicsScene("/World/PhysicsScene").set_gravities([0.0, 0.0, -9.81])
ColliderBody("/World/Cube")
RigidBody("/World/Cube")
return stage.export_stage_to_string()
finally:
stage.close_stage()
The example exports this neutral authoring stage and imports it into OVStage
for simulation. It selects the ovphysx backend, initializes
PhysicsManager at 60 Hz, and reads the cube through RigidBodyEntity:
stage = Stage("ovstage").import_stage_from_string(_author_stage(), make_default=False)
physics_manager = PhysicsManager.get_instance()
if not physics_manager.switch_physics_engine("ovphysx"):
raise RuntimeError("OvPhysX physics engine is unavailable.")
time_step = 1.0 / 60.0
physics_manager.setup(dt=time_step)
if not physics_manager.initialize(stage.get_stage_ptr(), stage.get_stage_id()):
raise RuntimeError("Physics initialization failed.")
cube = RigidBodyEntity("ovphysx", "/World/Cube")
positions, _ = cube.get_world_poses()
initial_height = float(positions.numpy()[0, 2])
physics_manager.step(steps=_SIMULATION_STEPS)
positions, _ = cube.get_world_poses()
final_height = float(positions.numpy()[0, 2])
print(f"Cube height: {initial_height:.3f} -> {final_height:.3f}.")
return initial_height, final_height
Keep the isaacsim.physics_engines.ovphysx import in the application. The
import registers the engine so PhysicsManager can select it. Always
invalidate the manager and close the stage during cleanup, as the complete
example does.
Run the simulation without a viewport:
source/examples/example.sh run falling_cube.simulate_cube
.\source\examples\example.bat run falling_cube.simulate_cube
Publish and render simulation state#
The visualization example adds a distant light and an authored render product,
then passes the populated OVStage to Viewport. The loop accumulates elapsed
wall time, limits catch-up work, advances fixed physics steps, publishes the
latest transforms, and renders a frame:
if step_count:
completed_steps = physics_manager.step(steps=step_count)
simulation_step += completed_steps
accumulated_simulation_time -= completed_steps * _PHYSICS_DT
if not physics_manager.publish_transforms_to_stage():
raise RuntimeError("Physics transform publication failed.")
positions, _ = simulated_cube.get_world_poses()
final_height = float(positions.numpy()[0, 2])
frame = viewport.render()
publish_transforms_to_stage copies the physics result into the stage that
OVGL observes. Without this call, the viewport continues to render the cube’s
authored pose even though the physics entity has moved.
Run the interactive visualization:
source/examples/example.sh run falling_cube.visualize_simulation
.\source\examples\example.bat run falling_cube.visualize_simulation
Drag with the left mouse button to look around, scroll the mouse wheel to dolly, and use W, A, S, D, Q, and E to move. Press R to reset the camera and Escape to close the viewport.
Verify the workflow#
Run each example’s tests:
source/examples/example.sh test falling_cube.author_cube
source/examples/example.sh test falling_cube.simulate_cube
source/examples/example.sh test falling_cube.visualize_simulation:headless
.\source\examples\example.bat test falling_cube.author_cube
.\source\examples\example.bat test falling_cube.simulate_cube
.\source\examples\example.bat test falling_cube.visualize_simulation:headless
The authoring test verifies that stage creation completes successfully. The simulation test verifies that the final cube height is lower than its initial height. The headless viewport test also verifies that OVGL renders changed frame data after the physics transforms are published.
Tradeoffs#
Use the authoring example when you only need to construct a stage, the simulation example for a headless physics workflow, and the visualization example when you need to inspect the result.
Next steps#
Continue with Run simulations locally and remotely with OV SIM to separate simulation from the client, or Build a native OVGL stage viewer to move stage inspection to C++.