Omniverse Client Library

This is the library that all Omniverse clients should use to communicate with Omniverse servers.

Documentation

The latest documentation can be found at https://docs.omniverse.nvidia.com/kit/docs/client_library/latest/index.html

Samples

The Omniverse Connect sample is available through the Omniverse Launcher.

Documentation for the sample can be found at https://docs.omniverse.nvidia.com/connect/latest/connect-sample.html

Getting

You can get the latest build from Packman. There are seperate packages for each platform.

They are all named: omni_client_library.{platform}

platform is one of:

  • windows-x86_64

  • linux-x86_64

  • linux-aarch64

All packages use the same versioning scheme: {major}.{minor}.{patch}

For example:

<project toolsVersion="5.0">
  <dependency name="omni_client_library" linkPath="_deps/omni_client_library">
    <package name="omni_client_library.windows-x86_64" version="2.10.0" />
  </dependency>
</project>

Hub

If Hub is installed via Launcher, it will be used by default. If Hub is not installed, we will fall back to the previous behavior. This will change at some point and Hub will be required.

There are some environment variables to control this:

  • OMNICLIENT_HUB_MODE: Either “disabled” (don’t use Hub), “exclusive” (launch Hub at library initialization & shut down Hub at library shutdown or process termination), or “shared” (use Hub if it’s running, launch if it’s not, never shut it down).

  • OMNICLIENT_HUB_EXE: This is the Hub executable to launch. Defaults to Hub next to your application for exclusive mode or the global Hub from launcher for shared mode.

  • OMNICLIENT_HUB_CACHE_DIR: Use Hub with this cache directory. This is required for exclusive mode, optional for shared mode (defaults to the cache path from omniverse.toml)

Newer Hub versions are backwards compatible to older client-library versions, but older Hub versions are not compatible with newer client-library versions. If you install Hub via Launcher, Hub is guaranteed to be compatible with all applications available on Launcher.

To make it easier to install a compatible Hub executable version if Launcher is not available, client-library packages v2.30.0 and higher are shipped with an additional file deps/public-redist.packman.xml which specifies a compatible Hub version. You can use that file to make the Hub executable available by adding a few lines to your projects packman dependencies. For example:

  <!-- Existing dependency to the client-library -->
  <dependency name="omni_client_library" linkPath="../_build/target-deps/omni_client_library">
    <package name="omni_client_library.${platform}" version="2.28.1" />
  </dependency>
  <!-- Add these lines to make the correct version of Hub available -->
  <import path="../_build/target-deps/omni_client_library/deps/public-redist.packman.xml"/>
  <dependency name="omni-hub" linkPath="../_build/target-deps/omni-hub"/>
  <!-- The Hub executable is now available in ../_build/target-deps/omni-hub/target/release/hub resp. hub.exe -->

Once the Hub executable is available in a known location, you can use that location for OMNICLIENT_HUB_EXE.

Using

URLs

Almost all the functions take a URL as the parameter. Currently the library supports a few URLs types:

  1. omniverse://server:port/path

  2. omni://server:port/path

  3. http://website/stuff/?omniverse://server:port/path

  4. file:///c:/local%20path

  5. c:\local path

  6. https://www.nvidia.com

The port is optional.

For the 3rd case, we ignore everything before “omniverse:”

file: URLs must be in the correct file URI format as described here: https://en.wikipedia.org/wiki/File_URI_scheme

Notably this means special characters must be percent-encoded (and there should be either one or three slashes, not two!)

The 5th type is not a URL at all, but the library understands certain “raw” local file paths. Note that although this is mostly reliable on Windows (because drive letters make it pretty obvious), is is very unreliable on Linux because a path which starts with “/” could be a reference to another path on the same server. For this reason, always prefer using “file:” URLs over raw file paths.

Aliases

You can set aliases for URLs by adding a section to the global omniverse.toml file. For example:

[aliases]
"nvidia:"="http://www.nvidia.com/"

The above alias would turn “nvidia:omniverse” into “http://www.nvidia.com/omniverse”

You can also set aliases at runtime with the “set_alias” function in Python or “omniClientSetAlias” in C.

Basics

Include “OmniClient.h” and you can the basic functions like omniClientList, omniClientRead, etc. without any extra work. Even calling omniClientInitialize and omniClientShutdown is not strictly required (though encouraged, because it enables extra checks).

Providers

File

File provider implements the “file:” scheme and support for “raw” paths like “C:\file”

Nucleus

Nucleus provider implements the “omniverse:” scheme for loading files from an Omniverse Nucleus server. This is the only provider which supports “live mode”

HTTP(S)

HTTP provider supports a variety of HTTP/HTTPS based URLs.

HTTP

Plain old HTTP/HTTPS URLs support stat() via HTTP HEAD verb and readFile() via HTTP GET verb.

Configuration

HTTP providers can be configured using the following environment variables:

  • OMNICLIENT_HTTP_VERBOSE: Set to “1” to enable verbose logging, displaying additional HTTP information in the logs.

  • OMNICLIENT_HTTP_TIMEOUT: Specifies the number of seconds the transfer speed must remain below 1 byte per second before the operation is considered too slow and aborted.

  • OMNICLIENT_HTTP_RETRIES: Defines the number of times a failed operation will be retried before being aborted.

These configuration options apply to all HTTP and HTTP-based providers like HTTP, HTTPS, Azure, S3, CloudFront, etc.

Azure

Azure URLs are identified by the host ending in “.blob.core.windows.net”

“Container Public” containers support stat, list, and readFile operations. “Blob Public” containers support stat and readFile operations (but not list, unless you specified a SAS token). “Private” containers support stat, list, and readFile operations if you specified a SAS token.

A SAS token can be specified in omniverse.toml like this:

[azure."{account}.blob.core.windows.net/{container}"]
sasToken="{sas-token}"

S3

S3 URLs currently support stat(), list(), and readFile() operations. S3 URLs can be identified in one of three ways:

  • The URL ends in .amazonaws.com

  • The URL ends in .cloudfront.net

  • The URL has a S3 configuration in the TOML config file. Useful for S3 buckets with custom domain name.

If the bucket requires access tokens or has a CloudFront distribution, omniverse.toml can be used to configure per bucket.

Example S3 section in omniverse.toml:

[s3]
[s3."{url}"]
bucket = "{bucket}"
region = "{region}"
accessKeyId = "{access-key-id}"
secretAccessKey = "{secret-access-key}"
cloudfront = "http(s)://{cloudfront-distribution-id}.cloudfront.net" # optional
cloudfrontList=false # optional
Note on using CloudFront

The preferred way to use CloudFront is to use CloudFront URLs directly in your application. This requires additional CloudFront configuration as outlined below. When using CloudFront URLs directly, the cloudfront and cloudfrontList options are ignored. These are only used if you are using S3 URLs and want use CloudFront implicitly (which can be slightly more confusing to the end user as they may not know that CloudFront is being used).

Server-Side CloudFront Configuration

CloudFront configuration can also be specified via a .cloudfront.toml file in the root of the S3 bucket.

Example CloudFront configuration in .cloudfront.toml:

cloudfront="http://dcb18d6mfegct.cloudfront.net"
cloudfrontList=false

This configuration is also optional. It is parsed before any configuration in omniverse.toml, so one can always override this server-side configuration with their local configuration.

API Operations when using CloudFront

If cloudfrontList is set to true or you are using CloudFront URLs, list() and stat() operations will also go though cloudfront, but requires further AWS CloudFront configuration. By default CloudFront does not pass any query strings. The following HTTP query parameters have to be forwarded from CloudFront to S3 on the backend:

  1. list-type

  2. delimiter

  3. prefix

  4. continuation-token

See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html for information on how to do this.

Contents