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:
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.
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:
list-type
delimiter
prefix
continuation-token
See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html for information on how to do this.