Settings and Configuration

Connect SDK uses Carbonite Settings & Tokens to configure runtime behavior of its libraries and modules. Most Connect SDK specific setting keys & tokens are explicitly defined in the API, but many more are defined by Carbonite as well.

Using Carbonite in the core of our SDK requires any runtime application to set the $CARB_APP_PATH environment variable. This should be set uniquely per client Connector (i.e. it is not a global system or user setting) and should point to the runtime installation of your Connector.

Attention

It is recommended to set $CARB_APP_PATH as early as possible, even before launching the application if possible, or during a specific plugin startup routine. This must be set before any Connect SDK API calls are made.

By layering configuration files utilizing Settings & Tokens we can create complex runtime customization through simple plain-text TOML. For example, the default logging location is set to a timestamped client Connector specific file within a standard Omniverse folder using the /log/file key:

[log]
file = "${logs}/${client_name}_${omni_connect_core_start_time}.log"

Core and Client settings

  • omni_connect_core loads $CARB_APP_PATH/config/omni.connect.core.toml, which configures many underlying systems from Carbonite, such as logging and crash reporting.

  • Each client Connector may optionally override any of these settings, or add unique configuration settings of its own, by installing an omni.connect.client.toml file in the $CARB_APP_PATH/config/ directory.

  • The end user’s Omniverse privacy policy settings will be applied on top of both core & client settings.

Important

Both of these toml files are strictly required at runtime. If they are missing than any call to omni::connect::core::startup() will fail and many of the other Connect SDK functions will have undefined behavior.

Several settings should always be overridden by the client Connector:

  • /app/name : The name of the application being connected

  • /app/version : The version of the application being connected

  • /omni.connect.core/client/name : The name of the client connector

  • /omni.connect.core/client/version : The version of the client connector

Doing so will ensure application-specific collection of logs, data, caches, and crash reports. For example, add the following at the top of your omni.connect.client.toml file:

[app]
name = "foo"
version = "101.2"

["omni.connect.core".client]
name = "bar"
version = "1.2.3"

If you would like to automatically inject /app/version or /omni.connect.core/client/version into your omni.connect.client.toml you can use repo connect_client_config as a pre or post build step.

Python Configuration

The omni_connect_core Shared Library includes optional embedding of a python runtime (see Calling Python from C++ for more details).

Note

If your application includes a native python runtime, be sure to call startup() only after python has been initialized. You can skip the rest of this sub-section.

If your application does not include python natively, Carbonite will initialize python for you, but you must take specific actions to ensure it is available before startup() is called.

Attention

When Carbonite initializes the python interpreter, system-defined environment variables (like PYTHONHOME, PYTHONPATH) are ignored and a Carb setting is used to locate python instead.

  • You must install a valid python runtime distribution alongside your Connector.

  • You must set /plugins/carb.scripting-python.plugin/pythonHome to point to the relative installation path.

For example, if you chose to install a python distribution to $CARB_APP_PATH/python-runtime then you must add the following snippet to your omni.connect.client.toml:

[plugins."carb.scripting-python.plugin"]
pythonHome = "python-runtime"

The following additional search paths are configured automatically:

  • $CARB_APP_PATH/python : A common folder for python modules

  • $CARB_APP_PATH/bindings-python : Another default that many Omniverse libraries use (including Carbonite and Client Library)

Similarly, you can configure additional paths to extend Python’s sys.path using your omni.connect.client.toml:

[app.python]
extraPaths = [
    "my_python_modules",
    "../../other_python_modules",
]

By default Carbonite uses Python 3.10. If your runtime supports Python 3.9 you can set the carb.scripting-python.plugin to use that version instead, but you must also set the config variable /plugins/carb.scripting-python.plugin/pythonVersion to 3.9.

Note

Changing the major.minor version of Python requires select an appropriate flavor of Connect SDK as well.

The omni.connect.client.toml also supports the form:

[plugins."carb.scripting-python.plugin"]
pythonVersion = "%PYTHON_VERSION%"

You will need use the repo tool connect_client_config and pass --pythonVersionOrFile with the python version of your runtime.

Optionally, you can further configure python’s runtime behavior by setting several native Python configuration variables using the following settings in your omni.connect.client.toml:

config variable

python flag documentation

/plugins/carb.scripting-python.plugin/Py_VerboseFlag

Py_VerboseFlag

/plugins/carb.scripting-python.plugin/Py_QuietFlag

Py_QuietFlag

/plugins/carb.scripting-python.plugin/Py_NoSiteFlag

Py_NoSiteFlag

/plugins/carb.scripting-python.plugin/Py_IgnoreEnvironmentFlag

Py_IgnoreEnvironmentFlag

/plugins/carb.scripting-python.plugin/Py_NoUserSiteDirectory

Py_NoUserSiteDirectory

/plugins/carb.scripting-python.plugin/Py_UnbufferedStdioFlag

Py_UnbufferedStdioFlag

/plugins/carb.scripting-python.plugin/Py_IsolatedFlag

Py_IsolatedFlag

USD Configuration

Many Usd plugins will specify strict relative paths between the plugin definitions and any dynamic shared libraries that they require to load. This information is typically contained within a plugInfo.json resource file.

It is important to deploy the resource files and the shared libraries such that this relative pathing is maintained, which is typically done using subfolders of the library directory called usd/*/resources.

Since many Applications will have their own native OpenUSD plugin deployment, Connectors may not be able to install Omniverse USD Resolver alongside the native OpenUSD plugins.

For convenience, we expose a setting for configuring the Omniverse USD Resolver plugin path.

  • /omni.connect.core/usd/resolverPath : The Omniverse USD Resolver plugin directory path. It can be an absolute path or a path relative to the $CARB_APP_PATH environment variable. This setting must be configured to point to a local filesystem directory containing a plugInfo.json file.

Note

This setting is not mandatory, nor is the Omni USD Resolver itself. Many uses of omni_connect_core do not require the Omniverse USD Resolver to be enabled.

If you would like to enable the Omniverse USD Resolver, be sure to use a nucleus-on flavor of Connect SDK, and add the following to your omni.connect.client.toml:

["omni.connect.core".usd]
resolverPath = "../path/to/omni_usd_resolver/usd/omniverse/resources"

Or alternatively, set the $PXR_PLUGINPATH_NAME environment variable.

With either approach, the Omniverse USD Resolver will still be registered & loaded during omni::connect::core::startup(). If you are unable to set either of these mechanisms prior to calling startup(), you can manually load this plugin via omni::connect::core::registerOmniUsdResolverPlugin().

Warning

While the resolver can be located anywhere, the folder structure relative to its dynamic shared library is strictly enforced. You must place the resources in a usd/omniverse/resources subfolder relative to omni_usd_resolver.dll or libomni_usd_resolver.so.

Log Configuration

Additionally, depending on your application type, you may wish to reconfigure logging verbosity or other settings. Carbonite logging is highly flexible, and verbosity can be changed in many ways. For instance, a commandline client Connector may wish to silence anything but fatal errors and its own messages in the stdout stream. This can be easily accomplished by adding the following to your omni.connect.client.toml file:

[log]

outputStreamLevel = "Info"

# most channels should issue fatal errors only
channels."*" = "Fatal"

# make sure our own logs are in stdout
channels."foo_bar" = "Info"

Note

The logging example above uses a foo_bar channel. In order for this channel to exist, the client Connector must initialize itself with Carbonite (e.g OMNI_APP_GLOBALS(“foo_bar”, “Omniverse Foo Bar Connector”);) and issue logs via the various OMNI_LOG_* macros. See Carbonite Logging documentation for more details, including python examples.

You can have logs forwarded to your application by calling omni::core::addLogConsumer(name, callback) with a callback to be invoked during log events. By default all log consumers have their verbosity level set to “info”, meaning they will receive warnings, errors, and fatal logs as well. To configure the log level of a consumer, add the following to your omni.connect.client.toml file:

["omni.connect.core".log.consumerLevel]
# key must match consumer name provided at runtime
foo = "Verbose"

Runtime Settings

Finally, as Carbonite settings are a runtime configuration system, you can simply use the Carbonite API (from C++ or Python) to override any setting at any point during your application’s runtime.

Note

Altering some settings will have immediate effect, while others require explicit re-loading of interfaces that use them.