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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 aplugInfo.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.