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 http://omniverse-docs.s3-website-us-east-1.amazonaws.com/client_library/

Samples

The Omniverse Connect sample is available through the Omniverse Launcher.

Documentation for the sample can be found at https://docs.omniverse.nvidia.com/con_connect/con_connect/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>

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.

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) / S3 / CloudFront

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 have 2 configuration options. verbose and timeout that can be specified in omniverse.toml. The timeout contains the time in number seconds that the transfer speed should be below 1 byte per second for it to consider the operation too slow and abort (timeout). These configuration options apply to all HTTP and HTTP-based providers like HTTP, HTTPS, S3, CloudFront, etc.

[http]
verbose = <true|false>
timeout = <timeout in seconds>

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.{bucket|cloudfront-distribution-id}]
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.