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:
omniverse://server:port/path
omni://server:port/path
http://website/stuff/?omniverse://server:port/path
file:///c:/local%20path
c:\local path
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:
list-type
delimiter
prefix
continuation-token
See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html for information on how to do this.