Connect Sample

The stage created by the HelloWorld 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:

This diagram is an overview of the components that we distribute in the Connect Sample and how an Omniverse Connector might use them:

A diagram showing the components distributed by the Connect Sample

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”:

Go to the Settings from the hamburger menu button

Clicking the folder icon next to the Install Path will open a file browser window to where it is installed:

Click the folder icon to open the install location of the Connect Sample

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

OmniUsdaWatcher in action

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.

Connection Paths of the Simple Sensor Example

Creating a Connector from the Omniverse Connect Sample

Omniverse Client Library and Live Sessions

Advanced Topics

Release Notes