Connect Sample
Overview
Build your own NVIDIA Omniverse™ Connectors by following our samples that use OpenUSD and Omniverse Client Library APIs.
You can download the prebuilt Samples for Windows and Linux from the Launcher by searching for “Connect Sample”. Once downloaded, you can directly run each sample using the provided run_*.bat
files (or run_*.sh
on Linux). See the Locating the Samples source from the Launcher section for directions on how to find where the samples are installed. See below for detailed explanations of each sample.
Alternatively, you can build from source by running .\repo.bat build
(or ./repo.sh build
on Linux) which will download prebuilt USD and Omniverse dependencies and re-compile the samples.
The default arguments for some of the samples expect that a localhost
Nucleus Workstation is installed on the system. See Nucleus Workstation Documentation for more information.
Note
On Windows this will automatically generate the Visual Studio solution file and build it.
Tip
If you are interested in a Quick Start feel free to jump directly to our HelloWorld sample.
If you are interested in what dependencies are necessary to build your own Connector, examine either the premake5.lua
build configuration file, the xml files in the deps
folder, or the output files in the _compiler
folder.
This is a summary of the main things provided by the Connect Sample:
C++ and Python samples for working with OpenUSD and Material Definition Language (MDL) on Nucleus
Omniverse and USD HelloWorld
Live Session
Live Sensors
C++ classes and Python module utilities
Unified handling of USD transforms
USD Prim and Layer utilities
UsdLuxLight Schema/API compatibility
Live Session channel, config, etc. classes
C++ OmniCLI that exercises the Omniverse Client Library interfaces
File/Folder copy
Logging
Other client utilities
A distribution mechanism for
This diagram is an overview of the components that we distribute in the Connect Sample and how an Omniverse Connector might use them:
Locating the Samples source from the Launcher
To find where the Connect Sample is installed, find the Connect Sample under the Library:Connectors tab, click the hamburger icon and select “Settings”:
Clicking the folder icon next to the Install Path will open a file browser window to where it is installed:
Sample Details
Omni Asset Validator - A command line USD validation tool.
Omni CLI - A command line utility to manage files on a Nucleus server.
HelloWorld (C++ and Python) - A sample program that shows how to connect to an Omniverse Nucleus server, create a USD stage, create a polygonal box, bind a material, add a light, save data to .usd file, create and edit a .live layer, and send/receive messages over a channel on Nucleus. This sample is provided in both C++ and Python to demonstrate the Omniverse APIs for each language.
LiveSession (C++ and Python) - A sample program that demonstrates how to create, join, merge, and participate in live sessions. This sample is provided in both C++ and Python to demonstrate the Omniverse APIs for each language.
OmniUsdaWatcher (C++) - A live USD watcher that outputs a constantly updating USDA file on disk.
OmniSimpleSensor (C++) - A C++ program that demonstrates how to connect external input (e.g. sensor data) to a USD layer in Nucleus.
Omni Asset Validator
Introduced in 201.0
A command line USD validation tool (omni_asset_validator.bat|sh
).
The Omniverse Asset Validator is a Python framework to provide Usd.Stage
validation based on the USD ComplianceChecker (i.e. the same backend as the usdchecker commandline tool), with an aim to validate assets against Omniverse specific rules to ensure they run smoothly across all Omniverse products.
Complete Asset Validator Documentation
To get the supported command line arguments, run omni_asset_validator.bat|sh --help
. For example, the --fix
flag will automatically apply fixes to a stage if possible (not all validation failures are automatically repairable):
omni_asset_validator.bat|sh --fix omniverse://localhost/Users/test/helloworld.usd
The asset validator may also be run against stages in-memory. This is demonstrated in the Python version of the LiveSession example with the v
option.
Omni CLI
A command line utility to manage files on a Nucleus Server (omnicli.bat|sh
).
This program was initially created to exercise most of the Omniverse Client Library API, but has grown to be a useful utility to interact with Nucleus servers. Typing help
will produce a menu that shows the many functions available. Among the most useful are the move/copy functions which can transfer data to and from servers.
HelloWorld (C++ and Python)
A sample program that creates a USD stage on a Nucleus server (run_hello_world.bat|sh
or run_py_hello_world.bat|sh
).
The sample demonstrates how to:
Connect to an Omniverse server - by default a localhost Nucleus Workstation
Create a USD stage
Create a physics scene to define simulation parameters
Create a polygonal box and add it to the stage and make it a dynamic rigid
Create a cube and add it to the stage and make it a dynamic rigid
Create a quad and add it to the stage and make it a collider
Upload an MDL material and its textures to an Omniverse server
Bind an MDL and USD Preview Surface material to the box
Add a distant and dome light to the stage
Add a skinned skeletal mesh quad
Add a folder in Nucleus - An empty folder will be generated when first creating the HelloWorld.usd.
Create Nucleus checkpoints
Move and rotate the box with live updates
Tweak skeletal mesh animation data with live updates
Disconnect from an Omniverse server
Print verbose Omniverse logs
Open an existing stage and find a mesh to do live edits
Send and receive messages over a channel on an Omniverse server
LiveSession (C++ and Python)
A sample program that demonstrates how to create, join, merge, and participate in live sessions (run_live_session.bat|sh
or run_py_live_session.bat|sh
).
A .live layer is used in the stage’s session layer to contain the changes. An Omniverse channel is used to broadcast users and merge notifications to all clients, and a session config (TOML) file is used to determine the “owner” of the session.
The sample demonstrates how to:
Initialize the Omniverse Resolver Plugin
Display existing live sessions for a stage
Connect to a live session
Set the edit target to the .live layer so changes replicate to other clients
Make xform changes to a mesh prim in the .live layer
Rename a prim in the .live layer
Display the owner of the live session
Display the current connected users/peers in the session
Emit a GetUsers message to the session channel
Display the contents of the session config
Validate a stage using the Omniverse Asset Validator (Python example only)
Merge the changes from the .live session back to the root stage
Respond (by exiting) when another user merges session changes back to the root stage
OmniUSDAWatcher (C++)
The Omniverse USDA Watcher is a command line program that keeps an updated USDA file on local disk that maps to a Live USD layer (.live) resident on a Nucleus server (run_omniUsdaWatcher.bat|sh
).
It takes two arguments, the USD layer to watch and the output USDA layer:
Acceptable forms:
URL:
omniverse://localhost/Users/test/helloworld.live
URL:
C:\USD\helloworld.usda
A local file path using shell variables:
~\helloworld.usda
A relative path based on the CWD of the program:
helloworld.usda
Note: Since the version 200.0 releases of the Connect Sample (Client Library 2.x) only .live
layers synchronize through Nucleus. This tool will export any supported USD file format as USDA, but if you intend to watch live file edits it must be a .live
layer. For more information on where to find the root.live
layer for Live Sessions, see the Live Session Worlflow section.
The “watcher” demonstrates how to:
Initialize Omniverse
Set the Omniverse Client log callback (using a lambda)
Set the Omniverse Client log level
Initialize the Omniverse Client library
Register a connection status callback
Open the USD stage
Create and register the Sdf layer reload, layer change, and USD notice listeners
Subscribe to file changes with omniClientStatSubscribe
Start a thread that loops, receiving live changes from other clients (if the specified layer is a
.live
layer)When the stage is modified it’s written out to the specified USDA
The main thread loops on keyboard input, waiting for a ‘q’ or ESC
Cleanup the callbacks (unsubscribe and revoke)
Destroy the stage object
Shutdown the Omniverse Client library
For example, to monitor the stage that the HelloWorld sample creates by default in “live” mode: run_omniUsdaWatcher.bat omniverse://localhost/Users/test/helloworld.live C:\USD\helloworld.usda
OmniSimpleSensor (C++)
The Omniverse Simple Sensor example demonstrates how to connect external input (e.g sensor data) to a USD layer in Nucleus(run_omniSimpleSensor.bat|sh
).
This could effectively be a large number of inputs that report current values for IoT sensors or could be locations from robots and a real-time synchronization of the data in the virtual world is desired.
It takes three arguments, the Nucleus server path, the number of inputs and a timeout value.
run_omniSimpleSensor.bat <server path> <number of inputs> <timeout>
Acceptable forms
Server Path:
omniverse://localhost/Users/test
(a location on a Nucleus server)Number of Inputs:
4
(integer value of 1 to any number)Timeout:
-1 or 20
(-1 is for infinity to run until killed, otherwise a number in seconds)
For example, run_omniSimpleSensor.bat omniverse://localhost/Users/test 27 -1
There are two parts to this project.
OmniSimpleSensor will build a USD with a number of boxes (meshes) on one layer.
Initialize Omniverse
Check for an existing SimpleSensorExample.live stage at the <server path> location, if it does not exist, create it
Edit SimpleSensorExample.live at <server path>
Build a simple array of box meshes, starting with /World/Box_0 then /World/Box_1 and so on
Save the Live layer
Destroy the stage object
Shutdown the Omniverse Client library
OmniSensorThread is then started for each ‘input’ specified in the command line.
Initialize Omniverse
Open SimpleSensorExample.live at <server path>
Find the box mesh in USD this process will change
Create a worker thread to update the box’s color every 300ms
In the main loop, wait until the timeout occurs, then
Stop the worker thread
Destroy the stage object
Shutdown the Omniverse Client library
For example, if 6 inputs are specified then there will be 6 OmniSensorThread processes running, independently of each other. The OmniSensorThread will launch a thread that will update the color of its assigned box at a given frequency (300ms in the code, but this can be altered). When opening the SimpleSensorExample.live
stage in USD Composer the boxes will change colors at regular intervals.
This project can easily be extended to change the transform of the boxes or to add some metadata with a custom string attached to the USD or do change visibility states.
Some things to note here:
Using separate processes for each input allows the USD to be changed independently
This example could be re-written to have one main process with many worker threads launched for each input. In this case there would need to be a mutex when writing data to same live layer. This will ensure that the writing to USD via the Omniverse Client Library resource is dedicated. Wrapping the mutex around the smallest bit of code writing to USD is recommended in this case to prevent thread starvation (especially when the frequency of input is high).
Reading USD via Omniverse Client Library does not have this issue and multiple threads in the same process can read from a USD, even the same layer in USD, without a mutex.