Getting Started

What is the FnUsdShim?

The FnUsdShim is a shim library which sits between USD and Katana. It allows any USD library to be used in conjunction with Katana, regardless of the USD version built against Katana. There are some caveats here in that if there are API changes or feature additions, Katana may or may not support those. The API changes would require updates to the FnUsdShim source to ensure the expected interface is maintained.

The FnUsdShim is the library in which all of Katana’s UsdNative codebase calls into when it wants to work with USD. The FnUsdShim allows our code to continue to have a stable interface regardless of the changes to the USD codebase. The C style interface also allows a more robust symbol lookup.

Where is the FnUsdShim?

The FnUsdShim is shipped with Katana pre-compiled against the USD (FnUsd) Katana ships with. If you do not require your own custom USD build, then there is nothing to do!

The source for this library can be found in <KATANA_ROOT>/plugins/Src/FnUsdShim where <KATANA_ROOT> is the folder where Katana is installed.

How do I use my own USD libraries

Note

The Viewer Tab links directly to FnUsd at all times. This is currently being worked upon to utilise the FnUsdShim instead.

To utilise a custom USD library, the FnUsdShim library must be built against the custom USD build as described by the How to build FnUsdShim section.

The Environment variable setup section details how to then utilise a custom FnUsdShim in place of the FnUsdShim shipped with Katana, and built against FnUsd.

If building and wanting to use the USD Python bindings, these must be built against the same Python version. This can be found in the Help > About Katana menu within Katana.

If you build FnUsdShim against a custom USD you MUST build KatanaUsdPlugins as well. More information on KatanaUsdPlugins can be found within the KatanaUsdPlugins Getting Started section.

How to build FnUsdShim

The same Python version as the application must be used. It is also strongly recommended to use the same TBB library as well, to avoid thread over-subscription or worse.

We provide a simplified CMakeLists.txt with this source code which should help starting out a build process. You may wish to modify this if your third party dependencies, like OpenSubDiv are not set up as CMake Targets in the same way.

  • FdkBase_DIR : Where the FdkBaseConfig.cmake can be found using find_package.

  • FnUsdAbstraction_DIR : Where the FnUsdAbstractionConfig.cmake can be found using find_package.

  • OpenSubdiv_DIR: Where OpenSubDivConfig.cmake can be found, or the root to a

    standard OpenSubdiv installation. Check the CMakeLists.txt file for how this tries to search for the required libraries. If using USD’s default install, pass the same as $pxr_DIR/lib/cmake/OpenSubdiv.

  • pxr_DIR - path to the root of your custom USD installation.

  • CMAKE_INSTALL_PREFIX - prefix to where FnUsdShim will be installed.

Linux:
rm -rf build && mkdir build && cd build
cmake -S <KATANA_ROOT>/plugins/Src/FnUsdShim -G Ninja \
-DCMAKE_BUILD_TYPE="Release" \
-Dpxr_DIR=<path to USD installation> \
-DFdkBase_DIR=<KATANA_ROOT>/plugin_apis/cmake \
-DFnUsdAbstraction_DIR=<KATANA_ROOT>/plugin_apis/cmake \
-DFnCrateCache_DIR=<KATANA_ROOT>/plugin_apis/cmake \
-DOpenSubdiv_DIR=<path to USD installation>/lib/cmake/OpenSubdiv \
-DCMAKE_INSTALL_PREFIX=<Path to where you want to install FnUsdShim>
cmake --build .
cmake --install .

Windows:
mkdir build && cd build
cmake -S <KATANA_ROOT>/plugins/Src/FnUsdShim -G Ninja ^
-DCMAKE_BUILD_TYPE="Release" ^
-DHAVE_SNPRINTF=True ^
-Dpxr_DIR=<path to USD installation> ^
-DFdkBase_DIR=<KATANA_ROOT>/plugin_apis/cmake ^
-DFnUsdAbstraction_DIR=<KATANA_ROOT>/plugin_apis/cmake/ ^
-DFnCrateCache_DIR=<KATANA_ROOT>/plugin_apis/cmake ^
-DOpenSubdiv_DIR=<path to USD installation>/lib/cmake/OpenSubdiv ^
-DCMAKE_INSTALL_PREFIX=<Path to where you want to install FnUsdShim>
cmake --build .
cmake --install .
cd ..

Environment variable setup

The main environment variable to disable Katana’s internal FnUsdShim library is KATANA_USD_ABSTRACTION_DISABLED. Otherwise, ensure all dependencies are added. Below is an example after using USD’s build_script.py.

Linux:
export KATANA_USD_ABSTRACTION_DISABLED=1
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path to install of USD>/lib
export PYTHONPATH=$PYTHONPATH:<path to install of USD>/lib/python
export PXR_PLUGINPATH_NAME=$PXR_PLUGINPATH_NAME:<path to install of FnUsdShim>/Libs
export USG_SHIMLIB_PATH=<path to install of FnUsdShim>/Libs
export USG_SHIMLIB_NAME=<Name of FnUsdShim>.so

Windows requires the additional usg_LIB_DIRS because directories on PATH are no longer added to the dll_directories for Python 3.8+. Therefore we manually add any library under usg_LIB_DIRS when the Python bindings are loading its dependencies, which are FnUsdShim and USD by default.

Windows:
set KATANA_USD_ABSTRACTION_DISABLED=1
set usg_LIB_DIRS=<path to install of USD>/lib
set PATH=%PATH%;<path to install of USD>/lib;<path to install of USD>/bin
set PYTHONPATH=%PYTHONPATH%;<path to install of USD>/lib/python
set PXR_PLUGINPATH_NAME=%PXR_PLUGINPATH_NAME%;<path to install of FnUsdShim>/Libs
set USG_SHIMLIB_PATH=<path to install of FnUsdShim>/Libs
set USG_SHIMLIB_NAME=<Name of FnUsdShim>.dll

Troubleshooting

Setting the environment variable USG_DEBUG_USDSHIMLIB=1 will print plugin loading information to the terminal describing how the FnUsdShim lib plugin is being discovered.