Advanced Connect SDK Topics

Locating Runtime Data for a Connector

Logging & data is stored in standard Omniverse locations on the local filesystem within per-user, per-Connector system folders.

Log Files

The Logs folder is used for recording runtime messages. The files in this folder will be generated as soon as the first log message is emitted by any of the Omniverse systems at runtime, subject to the configured log levels of the client Connector. By default, each log file will contain the name of the client Connector (specified via the /omni.connect.core/client/name setting) and the timestamp from when the Connect SDK was first initialized (via omni::connect::core::startup()).

The ${logs} token can be used within settings to locate this folder. On Windows, this usually resolves to C:/Users/[user]/.nvidia-omniverse/logs/connect-sdk/${app_name}-${app_version}/${client_name}-${client_version} and on Linux it usually resolves to $HOME/.nvidia-omniverse/logs/connect-sdk/${app_name}-${app_version}/${client_name}-${client_version}.

Persistent Data

The Data folder is used for persistent data. This is where an application can write anything that must reliably persist between sessions.

The ${data} token can be used within settings to locate this folder. On Windows, this usually resolves to C:/Users/[user]/AppData/Local/ov/data/connect-sdk/${app_name}-${app_version}/${client_name}-${client_version} and on Linux it usually resolves to $HOME/.local/share/ov/data/connect-sdk/${app_name}-${app_version}/${client_name}-${client_version}.

Temporary Caches

The Cache folder is a system folder to be used for ephemeral caching. It might be purged between application runs (though usually it is not). Any application should be able to rebuild the cache if it is missing.

The ${cache} token can be used within settings to locate this folder. On Windows, this usually resolves to C:/Users/[user]/AppData/Local/ov/cache/connect-sdk/${app_name}-${app_version}/${client_name}-${client_version} and on Linux it usually resolves to $HOME/.cache/ov/cache/connect-sdk/${app_name}-${app_version}/${client_name}-${client_version}.

Detailed Runtime Requirements

If you are using the Core components of Connect SDK, you must:

• Provide plugins and config directories located relative to the runtime $CARB_APP_PATH that you will configure during your client Connector startup/initialization routine.

  • See Settings and Configuration for details on this required environment variable.

  • The plugins directory is for Omniverse Carbonite Plugins, and must contain the 6 required carb plugins at a minimum, but may contain more carb plugins as well.

  • The config directory must contain both the provided omni.connect.core.toml and your own omni.connect.client.toml

• The normal shared libraries (i.e. non carb plugins) can be placed anywhere, so long as they can be dynamically loaded at runtime using standard procedures on your operating system (e.g on the PATH or LD_LIBRARY_PATH environment variables).

• The OpenUSD Plugins must be placed relative to the OpenUSD shared libraries. Similarly, the Omniverse USD Resolver plugins must be placed relative to its own shared libraries. See USD Configuration for details.

• If you want to use python, but your application does not have a native python runtime, see Python Configuration for details on how to install and configure one. The Omniverse and OpenUSD python modules can be placed anywhere, so long as they are configured appropriately for sys.path at runtime.

Omniverse Module Runtime Dependencies

It’s important when initializing the Omniverse USD Resolver plugins (the Connect SDK does this for you) the Omniverse Live file format plugin requires at least two DLLs, omniclient.dll and omni_spectree.dll to be discoverable. Connectors will typically link against omniclient.dll already, so it’s quite possible that this will be loaded, but the directory that contains omni_spectree.dll must be in the DLL search path. The typical way to do this is to do one of these things:

• Put the runtime dependencies - omniclient.dll, omni_spectree.dll, and friends - in the application’s CWD or executable directory

• Add the runtime dependencies’ directory to the PATH environment variable

• Use SetDllDirectory() or AddDllDirectory() before initializing the Omniverse USD Resolver plugins

Example runtime file layouts

For clarity, below are some suggested file layouts for our default, nopy, and nucleus-off builds on Linux and Windows.

Note

As suggested above, if you need to use alternate paths for some or all of the normal shared libraries or python modules, that is fine. These are just default suggestions. However, the config and plugins directories are strict requirements.

Linux Default

Note the python runtime is optional.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
│   ├── libboost_python310.so -> libboost_python310.so.1.78.0
│   ├── libboost_python310.so.1.78.0
│   ├── libcarb.so
│   ├── libomniclient.so
│   ├── libomni_connect_core.so
│   ├── libomni.spectree.delegate.plugin.so
│   ├── libomni_transcoding.so
│   ├── libomni_usd_live.so
│   ├── libomni_usd_resolver.so
│   ├── libomniverse_connection.so
│   ├── libpython3.10.so -> libpython3.10.so.1.0
│   ├── libpython3.10.so.1.0
│   ├── libpython3.so
│   ├── libtbb.so.2
│   ├── libusd_arch.so
│   ├── libusd_ar.so
│   ├── libusd_garch.so
│   ├── libusd_gf.so
│   ├── libusd_hdar.so
│   ├── libusd_js.so
│   ├── libusd_kind.so
│   ├── libusd_ndr.so
│   ├── libusd_pcp.so
│   ├── libusd_plug.so
│   ├── libusd_sdf.so
│   ├── libusd_sdr.so
│   ├── libusd_tf.so
│   ├── libusd_trace.so
│   ├── libusd_usdGeom.so
│   ├── libusd_usdLux.so
│   ├── libusd_usdShade.so
│   ├── libusd_usd.so
│   ├── libusd_usdUtils.so
│   ├── libusd_vt.so
│   ├── libusd_work.so
|   └── usd
|       ├── plugInfo.json
|       ├── omniverse
|       │   ├── live
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   ├── resolver
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   └── resources
|       │       └── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
├── plugins
│   ├── libcarb.crashreporter-breakpad.plugin.so
│   ├── libcarb.dictionary.plugin.so
│   ├── libcarb.dictionary.serializer-json.plugin.so
│   ├── libcarb.dictionary.serializer-toml.plugin.so
│   ├── libcarb.scripting-python.plugin.so
│   ├── libcarb.settings.plugin.so
│   ├── libcarb.tokens.plugin.so
│   └── py-spy
├── python
|   ├── carb
|   │   ├── _carb.cpython-310-x86_64-linux-gnu.so
|   │   ├── dictionary
|   │   │   ├── _dictionary.cpython-310-x86_64-linux-gnu.so
|   │   │   └── __init__.py
|   │   ├── __init__.py
|   │   ├── settings
|   │   │   ├── __init__.py
|   │   │   └── _settings.cpython-310-x86_64-linux-gnu.so
|   │   └── tokens
|   │       ├── __init__.py
|   │       └── _tokens.cpython-310-x86_64-linux-gnu.so
|   ├── omni
|   │   ├── client
|   │   │   ├── __init__.py
|   │   │   └── _omniclient.cpython-310-x86_64-linux-gnu.so
|   │   ├── connect
|   │   │   └── core
|   │   │       ├── __init__.py
|   │   │       ├── _omni_connect_core.cpython-310-x86_64-linux-gnu.so
|   │   │       ├── _omni_connect_core.pyi
|   │   │       └── _StageAlgoBindings.py
|   │   ├── core
|   │   │   ├── _core.cpython-310-x86_64-linux-gnu.so
|   │   │   └── __init__.py
|   │   ├── log
|   │   │   ├── __init__.py
|   │   │   └── _log.cpython-310-x86_64-linux-gnu.so
|   │   ├── str
|   │   │   ├── __init__.py
|   │   │   └── _str.cpython-310-x86_64-linux-gnu.so
|   │   └── usd_resolver
|   │       ├── __init__.py
|   │       └── _omni_usd_resolver.cpython-310-x86_64-linux-gnu.so
│   └── pxr
│       └── ...
└── python-runtime
    ├── bin
    ├── lib
    └── ...

Linux nopy

Note OpenUSD is a minimal build with compact dependencies.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
│   ├── libcarb.so
│   ├── libomniclient.so
│   ├── libomni_connect_core.so
│   ├── libomni.spectree.delegate.plugin.so
│   ├── libomni_transcoding.so
│   ├── libomni_usd_live.so
│   ├── libomni_usd_resolver.so
│   ├── libomniverse_connection.so
│   ├── libtbb.so.2
|   ├── libusd_ms.so
|   └── usd
|       ├── plugInfo.json
|       ├── omniverse
|       │   ├── live
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   ├── resolver
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   └── resources
|       │       └── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
└── plugins
    ├── libcarb.crashreporter-breakpad.plugin.so
    ├── libcarb.dictionary.plugin.so
    ├── libcarb.dictionary.serializer-json.plugin.so
    ├── libcarb.dictionary.serializer-toml.plugin.so
    ├── libcarb.settings.plugin.so
    └── libcarb.tokens.plugin.so

Linux nucleus-off

Note the python runtime is optional.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
│   ├── libboost_python310.so -> libboost_python310.so.1.78.0
│   ├── libboost_python310.so.1.78.0
│   ├── libcarb.so
│   ├── libomni_connect_core.so
│   ├── libomni_transcoding.so
│   ├── libpython3.10.so -> libpython3.10.so.1.0
│   ├── libpython3.10.so.1.0
│   ├── libpython3.so
│   ├── libtbb.so.2
│   ├── libusd_arch.so
│   ├── libusd_ar.so
│   ├── libusd_garch.so
│   ├── libusd_gf.so
│   ├── libusd_hdar.so
│   ├── libusd_js.so
│   ├── libusd_kind.so
│   ├── libusd_ndr.so
│   ├── libusd_pcp.so
│   ├── libusd_plug.so
│   ├── libusd_sdf.so
│   ├── libusd_sdr.so
│   ├── libusd_tf.so
│   ├── libusd_trace.so
│   ├── libusd_usdGeom.so
│   ├── libusd_usdLux.so
│   ├── libusd_usdShade.so
│   ├── libusd_usd.so
│   ├── libusd_usdUtils.so
│   ├── libusd_vt.so
│   ├── libusd_work.so
|   └── usd
|       ├── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
├── plugins
│   ├── libcarb.crashreporter-breakpad.plugin.so
│   ├── libcarb.dictionary.plugin.so
│   ├── libcarb.dictionary.serializer-json.plugin.so
│   ├── libcarb.dictionary.serializer-toml.plugin.so
│   ├── libcarb.scripting-python.plugin.so
│   ├── libcarb.settings.plugin.so
│   ├── libcarb.tokens.plugin.so
│   └── py-spy
├── python
|   ├── carb
|   │   ├── _carb.cpython-310-x86_64-linux-gnu.so
|   │   ├── dictionary
|   │   │   ├── _dictionary.cpython-310-x86_64-linux-gnu.so
|   │   │   └── __init__.py
|   │   ├── __init__.py
|   │   ├── settings
|   │   │   ├── __init__.py
|   │   │   └── _settings.cpython-310-x86_64-linux-gnu.so
|   │   └── tokens
|   │       ├── __init__.py
|   │       └── _tokens.cpython-310-x86_64-linux-gnu.so
|   ├── omni
|   │   ├── connect
|   │   │   └── core
|   │   │       ├── __init__.py
|   │   │       ├── _omni_connect_core.cpython-310-x86_64-linux-gnu.so
|   │   │       ├── _omni_connect_core.pyi
|   │   │       └── _StageAlgoBindings.py
|   │   ├── core
|   │   │   ├── _core.cpython-310-x86_64-linux-gnu.so
|   │   │   └── __init__.py
|   │   ├── log
|   │   │   ├── __init__.py
|   │   │   └── _log.cpython-310-x86_64-linux-gnu.so
|   │   └── str
|   │       ├── __init__.py
|   │       └── _str.cpython-310-x86_64-linux-gnu.so
│   └── pxr
│       └── ...
└── python-runtime
    ├── bin
    ├── lib
    └── ...

Linux nopy & nucleus-off

Note OpenUSD is a minimal build with compact dependencies.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
│   ├── libcarb.so
│   ├── libomni_connect_core.so
│   ├── libomni_transcoding.so
│   ├── libtbb.so.2
|   ├── libusd_ms.so
|   └── usd
|       ├── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
└── plugins
    ├── libcarb.crashreporter-breakpad.plugin.so
    ├── libcarb.dictionary.plugin.so
    ├── libcarb.dictionary.serializer-json.plugin.so
    ├── libcarb.dictionary.serializer-toml.plugin.so
    ├── libcarb.settings.plugin.so
    └── libcarb.tokens.plugin.so

Windows Default

Note the python runtime is optional.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
|   ├── boost_python310-vc142-mt-x64-1_78.dll
│   ├── carb.dll
│   ├── omniclient.dll
│   ├── omni_connect_core.dll
│   ├── omni.spectree.delegate.plugin.dll
│   ├── omni_transcoding.dll
│   ├── omni_usd_live.dll
│   ├── omni_usd_resolver.dll
│   ├── omniverse_connection.dll
│   ├── python3.dll
│   ├── python310.dll
│   ├── tbb.dll
│   ├── usd_ar.dll
│   ├── usd_arch.dll
│   ├── usd_garch.dll
│   ├── usd_gf.dll
│   ├── usd_hdar.dll
│   ├── usd_js.dll
│   ├── usd_kind.dll
│   ├── usd_ndr.dll
│   ├── usd_pcp.dll
│   ├── usd_plug.dll
│   ├── usd_sdf.dll
│   ├── usd_sdr.dll
│   ├── usd_tf.dll
│   ├── usd_trace.dll
│   ├── usd_usd.dll
│   ├── usd_usdGeom.dll
│   ├── usd_usdLux.dll
│   ├── usd_usdShade.dll
│   ├── usd_usdUtils.dll
│   ├── usd_vt.dll
│   └── usd_work.dll
|   └── usd
|       ├── plugInfo.json
|       ├── omniverse
|       │   ├── live
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   ├── resolver
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   └── resources
|       │       └── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
├── plugins
│   ├── carb.crashreporter-breakpad.plugin.dll
│   ├── carb.dictionary.plugin.dll
│   ├── carb.dictionary.serializer-json.plugin.dll
│   ├── carb.dictionary.serializer-toml.plugin.dll
│   ├── carb.scripting-python.plugin.dll
│   ├── carb.settings.plugin.dll
│   ├── carb.tokens.plugin.dll
│   └── py-spy.exe
├── python
|   ├── carb
|   │   ├── __init__.py
|   │   ├── _carb.cp310-win_amd64.pyd
|   │   ├── dictionary
|   │   │   ├── __init__.py
|   │   │   └── _dictionary.cp310-win_amd64.pyd
|   │   ├── settings
|   │   │   ├── __init__.py
|   │   │   └── _settings.cp310-win_amd64.pyd
|   │   └── tokens
|   │       ├── __init__.py
|   │       └── _tokens.cp310-win_amd64.pyd
|   ├── omni
|   │   ├── client
|   │   │   ├── __init__.py
|   │   │   └── _omniclient.cp310-win_amd64.pyd
|   │   ├── connect
|   │   │   └── core
|   │   │       ├── _StageAlgoBindings.py
|   │   │       ├── __init__.py
|   │   │       ├── _omni_connect_core.cp310-win_amd64.pyd
|   │   │       └── _omni_connect_core.pyi
|   │   ├── core
|   │   │   ├── __init__.py
|   │   │   └── _core.cp310-win_amd64.pyd
|   │   ├── log
|   │   │   ├── __init__.py
|   │   │   └── _log.cp310-win_amd64.pyd
|   │   ├── str
|   │   │   ├── __init__.py
|   │   │   └── _str.cp310-win_amd64.pyd
|   │   └── usd_resolver
|   │       ├── __init__.py
|   │       └── _omni_usd_resolver.cp310-win_amd64.pyd
│   └── pxr
│       └── ...
└── python-runtime
    ├── bin
    ├── lib
    └── ...

Windows nopy

Note OpenUSD is a minimal build with compact dependencies.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
│   ├── carb.dll
│   ├── omniclient.dll
│   ├── omni_connect_core.dll
│   ├── omni.spectree.delegate.plugin.dll
│   ├── omni_transcoding.dll
│   ├── omni_usd_live.dll
│   ├── omni_usd_resolver.dll
│   ├── omniverse_connection.dll
│   ├── tbb.dll
|   ├── usd_ms.dll
|   └── usd
|       ├── plugInfo.json
|       ├── omniverse
|       │   ├── live
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   ├── resolver
|       │   │   └── resources
|       │   │       └── plugInfo.json
|       │   └── resources
|       │       └── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
└── plugins
    ├── carb.crashreporter-breakpad.plugin.dll
    ├── carb.dictionary.plugin.dll
    ├── carb.dictionary.serializer-json.plugin.dll
    ├── carb.dictionary.serializer-toml.plugin.dll
    ├── carb.settings.plugin.dll
    └── carb.tokens.plugin.dll

Windows nucleus-off

Note the python runtime is optional.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
|   ├── boost_python310-vc142-mt-x64-1_78.dll
│   ├── carb.dll
│   ├── omni_connect_core.dll
│   ├── omni_transcoding.dll
│   ├── python3.dll
│   ├── python310.dll
│   ├── tbb.dll
│   ├── usd_ar.dll
│   ├── usd_arch.dll
│   ├── usd_garch.dll
│   ├── usd_gf.dll
│   ├── usd_hdar.dll
│   ├── usd_js.dll
│   ├── usd_kind.dll
│   ├── usd_ndr.dll
│   ├── usd_pcp.dll
│   ├── usd_plug.dll
│   ├── usd_sdf.dll
│   ├── usd_sdr.dll
│   ├── usd_tf.dll
│   ├── usd_trace.dll
│   ├── usd_usd.dll
│   ├── usd_usdGeom.dll
│   ├── usd_usdLux.dll
│   ├── usd_usdShade.dll
│   ├── usd_usdUtils.dll
│   ├── usd_vt.dll
│   └── usd_work.dll
|   └── usd
|       ├── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
├── plugins
│   ├── carb.crashreporter-breakpad.plugin.dll
│   ├── carb.dictionary.plugin.dll
│   ├── carb.dictionary.serializer-json.plugin.dll
│   ├── carb.dictionary.serializer-toml.plugin.dll
│   ├── carb.scripting-python.plugin.dll
│   ├── carb.settings.plugin.dll
│   ├── carb.tokens.plugin.dll
│   └── py-spy.exe
├── python
|   ├── carb
|   │   ├── __init__.py
|   │   ├── _carb.cp310-win_amd64.pyd
|   │   ├── dictionary
|   │   │   ├── __init__.py
|   │   │   └── _dictionary.cp310-win_amd64.pyd
|   │   ├── settings
|   │   │   ├── __init__.py
|   │   │   └── _settings.cp310-win_amd64.pyd
|   │   └── tokens
|   │       ├── __init__.py
|   │       └── _tokens.cp310-win_amd64.pyd
|   ├── omni
|   │   ├── connect
|   │   │   └── core
|   │   │       ├── _StageAlgoBindings.py
|   │   │       ├── __init__.py
|   │   │       ├── _omni_connect_core.cp310-win_amd64.pyd
|   │   │       └── _omni_connect_core.pyi
|   │   ├── core
|   │   │   ├── __init__.py
|   │   │   └── _core.cp310-win_amd64.pyd
|   │   ├── log
|   │   │   ├── __init__.py
|   │   │   └── _log.cp310-win_amd64.pyd
|   │   └── str
|   │       ├── __init__.py
|   │       └── _str.cp310-win_amd64.pyd
│   └── pxr
│       └── ...
└── python-runtime
    ├── bin
    ├── lib
    └── ...

Windows nopy & nucleus-off

Note OpenUSD is a minimal build with compact dependencies.

$CARB_APP_PATH
├── config
│   ├── omni.connect.client.toml
│   └── omni.connect.core.toml
├── lib
│   ├── carb.dll
│   ├── omni_connect_core.dll
│   ├── omni_transcoding.dll
│   ├── tbb.dll
|   ├── usd_ms.dll
|   └── usd
|       ├── plugInfo.json
|       └── ...
|           └── resources
|               └── plugInfo.json
└── plugins
    ├── carb.crashreporter-breakpad.plugin.dll
    ├── carb.dictionary.plugin.dll
    ├── carb.dictionary.serializer-json.plugin.dll
    ├── carb.dictionary.serializer-toml.plugin.dll
    ├── carb.settings.plugin.dll
    └── carb.tokens.plugin.dll