Getting Started

What are the Katana USD Plug-ins?

The Katana USD Plug-ins are a set of node types and libraries which permit loading and manipulating USD assets in Katana. The current functionality matches the original plug-ins developed by Pixar as part of the open source USD library. We have created our own branch in order to ensure a more open set of tools, and such that we can keep them up to date with changes to Katana itself and work on improving them in the future. As part of this, we have started shipping our own version along with our own core USD libraries in order to support USD out of the box. As with all of our example plug-ins, these are disabled by default. This page describes how you can enable them and also how you can fork from our open source repository and add your own pipeline’s details. We also describe how to go about contributing to the community as a whole and submitting any bug fixes or improvements to the Katana USD Plug-ins in order for us to fold them into later shipping releases.

Our Katana USD Plug-ins will be built against and match the features of the USD version shipped with Katana; which can be found in Katana’s About Katana dialog and in the release notes.

How do I Enable the Katana USD Plug-ins?

The Katana USD Plug-ins built and shipped with Katana are enabled by default. To enable your own, you can use the following environment variable setup after setting KATANA_USD_PLUGINS_DISABLED=1, to disable our shipped plugins.

In order to make your Katana USD Plug-ins available in Katana, you have to edit your KATANA_RESOURCES and your LD_LIBRARY_PATH (PATH on Windows) and add the USD plugin folder to them. We have provided how to do this below, along with the relative path of how to add this to your environments.

Windows:
set PATH=%PATH%;<PluginRoot>/plugins/Resources/Usd/lib
set PYTHONPATH=%PYTHONPATH%;<PluginRoot>/plugins/Resources/Usd/lib/python
set KATANA_RESOURCES=%KATANA_RESOURCES%;<PluginRoot>/plugins/Resources/Usd/plugin
set FNPXR_PLUGINPATH=<PluginRoot>/plugins/Resources/Usd/lib/resources

Linux:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<PluginRoot>/plugins/Resources/Usd/lib
export PYTHONPATH=$PYTHONPATH:<PluginRoot>/plugins/Resources/Usd/lib/python
export KATANA_RESOURCES=$KATANA_RESOURCES:<PluginRoot>/plugins/Resources/Usd/plugin
export FNPXR_PLUGINPATH=<PluginRoot>/plugins/Resources/Usd/lib/resources

Once these are in your environment, when you start Katana next, you should be able to create nodes of the additional node types using the standard node creation menus in Katana’s Node Graph tab.

Note

Loading two different versions of the Katana USD Plug-ins in the same Katana session is unsupported. Please only use either the Katana USD Plug-ins we ship with, or your own Katana USD Plug-ins.

Downloading, Building and Installing

We provide the source code of the USD Katana Plug-ins to both facilitate your ability to add custom features onto the base codebase, and to foster an open source community in order to efficiently resolve issues and add features we may not have thought of. The source code can be found at https://github.com/TheFoundryVisionmongers/KatanaUsdPlugins.

There are some important notes to consider when building and using your own Katana USD Plug-ins. The differences depend on your circumstances and reasoning for wanting to use a different set of Katana USD Plug-ins, and below we will outline the scenarios and how best to build and set them up in order to avoid issues or conflicts when loading them into a Katana session.

Scenarios

  1. “We want to use a different set of USD libraries, and therefore will build our own USD and link to this instead.”

    1. This is useful if you require a feature from the latest version or have your own in-house version of USD which provides additional features when dealing with USD assets in your Katana project. In either case, you will need to build your Katana USD Plug-ins against your USD libraries and add those to the LD_LIBRARY_PATH (or PATH on Windows) environment variables when loading Katana. So long as you are using the default/Pixar Katana USD Plug-ins, you should still be able to add our internal Katana USD Plug-ins as well. This is because we have ensured the node type names, Op type names and libraries do not clash.

  2. “We want to rebuild Foundry’s Katana USD Plug-ins with additional features on top and use ours instead.”

    1. In this scenario it is best to do a complete swap of our libraries for your own. You can do this by simply not opting into our plug-ins, and opting into your own using steps similar to How do I Enable the Katana USD Plug-ins? but with the paths to your own Katana USD Plug-ins. Following this method means you will not be able to use both our Katana USD Plug-ins and your own at the same time.

Building Katana USD Plug-ins

In our code base we have provided a Support.cmake file in order to assist when building the Katana USD Plug-ins externally from the USD core libraries. Building against USD can get very complex, and we have tried to simplify as many steps as possible within our own fnUsd version. We have opted to use CMake configurations from third-party libraries and use namespaced library definitions in order to prevent USD writing full library paths to its own CMake configuration when built. If you are using our fnUsd codebase as the starting point, you should be able to follow the build steps within the Katana USD Plug-ins codebase. If you are using your own USD library, you may need to resolve the USD libraries yourself.

Note

In order to ensure that Katana’s USD library does not load plug-ins built for another USD build, it uses FNPXR_PLUGINPATH in place of the stock USD PXR_PLUGINPATH_NAME environment variable.

Submitting Issues or Suggestions

Our Katana USD Plug-ins are hosted on GitHub, giving us the ability to use the features provided by that code-sharing platform. Therefore, if you have any issues, encounter any bugs or have suggestions please use the GitHub issues and pull request systems, and we will track them internally. We may not accept all pull requests as we will always aim to keep the plug-in as generic and open as possible.