Run simulations locally and remotely with OV SIM#
Author and simulate a falling cube through the OV SIM client API. Start with an in-process client, then use the same client model to transfer a stage to a standalone gRPC server and advance the simulation remotely.
Learning objectives#
After completing this tutorial, you can:
Author prims and typed data through the OV SIM client API.
Initialize and advance an in-process simulation.
Transfer an authored stage to a gRPC server and read remote simulation state.
Choose between local and remote deployment based on lifecycle and transport requirements.
Prerequisites#
Complete Install and run.
Run the commands in this tutorial from the repository root.
Configure the gRPC server runtime paths for your operating system as described in Move simulation to a gRPC server. The in-process examples do not require a server.
Examples used#
Example |
Role in this tutorial |
|---|---|
Authors a stage through the OV SIM client API. |
|
Runs the simulation with the in-process OV SIM implementation. |
|
Runs the same workflow through a remote gRPC transport. |
Each example page lists its source directory, requirements, and runner commands.
Use one client model for two deployments#
An in-process client executes operations in the calling process. A gRPC client sends the operations to a separate OV SIM server. Both expose authoring, simulation, and data interfaces, but the remote workflow must also manage the server, endpoint, and stage transfer.
Client |
Best suited for |
Additional responsibility |
|---|---|---|
|
Local authoring and simulation with the lowest coordination overhead. |
Keep the stage and simulation lifecycle in the application process. |
|
Process isolation or simulation on another host. |
Manage connectivity, transfer stage data, and operate the server. |
Add local simulation#
Apply ColliderBody and RigidBody behavior to the cube, add a ground
plane and physics scene, then initialize and step OvPhysX through the client’s
simulation interface:
cube = "/World/Cube"
client.control.authoring.define_prim(cube, "Cube")
client.data.write(cube, "size", 1.0)
client.data.write(cube, "position", [0.0, 0.0, 2.0])
client.control.authoring.define_prim(cube, "ColliderBody")
client.control.authoring.define_prim(cube, "RigidBody")
ground_plane = "/World/GroundPlane"
client.control.authoring.define_prim(ground_plane, "GroundPlane")
physics_scene = "/World/PhysicsScene"
client.control.authoring.define_prim(physics_scene, "PhysicsScene")
client.data.write(physics_scene, "physics:gravityDirection", [0.0, 0.0, -1.0])
client.data.write(physics_scene, "physics:gravityMagnitude", 9.81)
client.control.simulation.set_parameter("physics", "physics-engine", "ovphysx")
client.control.simulation.initialize()
simulation_initialized = True
initial_height = float(client.data.read(cube, "position").numpy()[0, 2])
for _ in range(10):
client.control.simulation.step()
The position read after stepping is simulation output. The same
client.data.read operation retrieves the authored and simulated values, so
the application does not need a backend-specific entity wrapper.
Run the in-process simulation:
source/examples/example.sh run falling_cube_ovsim.simulate_cube
.\source\examples\example.bat run falling_cube_ovsim.simulate_cube
Move simulation to a gRPC server#
Start the server from the installed developer environment. Do not run the
executable from _cmake_build/isaacsim-libraries-release/modules/isaacsim_ovsim/bin;
that build-tree directory does not contain all required runtime libraries.
In the first terminal, configure the runtime paths, prepare the example dependencies, and start the server:
$prefix = (Resolve-Path "_cmake_build\isaacsim-libraries-release\developer-environment").Path
$runtimePaths = @(
"$prefix\bin"
"$prefix\plugins"
"$prefix\bin\plugins"
"$prefix\bin\plugins\omni.client.lib"
"$prefix\bin\plugins\omni.usd_resolver"
)
$env:PATH = ($runtimePaths + $env:PATH) -join ";"
source\examples\example.bat build falling_cube_ovsim.simulate_cube_grpc
isaacsim-ovsim-grpc-server --listen-address 127.0.0.1:50051
prefix="$PWD/_cmake_build/isaacsim-libraries-release/developer-environment"
export PATH="$prefix/bin:$PATH"
source/examples/example.sh build falling_cube_ovsim.simulate_cube_grpc
isaacsim-ovsim-grpc-server --listen-address 127.0.0.1:50051
The server listens on 127.0.0.1:50051 and runs in the foreground. Keep the
first terminal open while you run the client.
In a second terminal, run the client from the repository root:
source\examples\example.bat run falling_cube_ovsim.simulate_cube_grpc -- --endpoint 127.0.0.1:50051
source/examples/example.sh run falling_cube_ovsim.simulate_cube_grpc -- --endpoint 127.0.0.1:50051
The client authors the scene locally, exports it as text, imports it through the remote client, and advances simulation on the server:
stage_content = local_client.control.authoring.export_stage_to_string()
if not remote_client.control.authoring.import_stage_from_string(stage_content):
raise RuntimeError("Remote simulation creation failed.")
remote_stage_open = True
remote_client.control.simulation.initialize()
initial_height = float(remote_client.data.read(cube, "position").numpy()[0, 2])
for _ in range(10):
remote_client.control.simulation.step()
The client-side authoring, data, and simulation operations keep the same structure, while the application explicitly owns transport configuration and both stage lifecycles. Stop the server with Ctrl+C when you finish.
Verify local and remote behavior#
Run the example tests:
source/examples/example.sh test falling_cube_ovsim.author_cube
source/examples/example.sh test falling_cube_ovsim.simulate_cube
source/examples/example.sh test falling_cube_ovsim.simulate_cube_grpc:loopback
.\source\examples\example.bat test falling_cube_ovsim.author_cube
.\source\examples\example.bat test falling_cube_ovsim.simulate_cube
.\source\examples\example.bat test falling_cube_ovsim.simulate_cube_grpc:loopback
The authoring test verifies that stage creation completes successfully. The local and remote simulation tests compare the initial and final cube heights. The loopback test starts a server on a temporary local port, waits for it to become ready, runs the client, and shuts down the server.
Tradeoffs#
The example uses an insecure gRPC channel on loopback. Supply the network access and security controls required by your deployment before using a non-loopback endpoint. Prefer the in-process client when process separation does not justify serialization, server lifecycle, and network overhead.
Next steps#
Continue with Build a native OVGL stage viewer to inspect stages in a lightweight C++ application.