Shelf Item Scripts

Shelf Item Scripts are Python scripts that you can run from Katana's UI in order to perform arbitrary operations using Katana's APIs. Shelf item scripts implement Shelf Items, which are grouped into Shelves.

Shelf Item Scripts can use Katana's APIs, like the NodegraphAPI, to access various parts of Katana that can be queried or modified, for example a project's node graph, with its nodes, parameters, ports, and connections. This section explains how they can be run from Katana's UI, what types of shelves there are, and where the folders and script files that define shelves and shelf items are located.

Running Shelf Item Scripts from the UI

The shelf items that are available for you to run from Katana's UI are listed by shelves in the Shelf Actions pop-ups that are shown when clicking the Shelf Actions toolbar buttons, which appear in different types of toolbars in Katana's UI:

• The toolbar next to the main menu bar in Katana's main window.

• The widgets toolbar for a node that is edited in the Parameters tab.

• The toolbar in the Scene Graph tab.

The shelves and shelf items listed in the Shelf Actions pop-up of the Parameters tab are considered to be specific to the type of node that is edited, but this is not enforced: you are free to perform any operation available through Katana APIs or provided by external libraries.

Likewise, the shelves and shelf items listed in the Shelf Actions pop-up of the Scene Graph tab are considered to be dedicated to working with the scene graph.

Types of Shelves

There are three types of shelves:

• Built-in shelves

• User-defined shelves

• Additional shelves

Built-in Shelves

Built-in shelves contain pre-defined shelf items that ship with Katana releases. In Shelf Actions pop-ups, their names are shown with an (App) prefix. The shelf item scripts that correspond to shelf items in built-in shelves are loaded from internal Katana resource directories.

You can view the source code of built-in shelf items through the UI, but you can't modify that source code or delete the items or the shelves they are contained in. You can also not create new built-in shelves or shelf items. If you want to create custom shelves and shelf items, use one of the following types of shelves: User-defined Shelves or Additional Shelves.

User-defined Shelves

User-defined shelves are shelves that you can freely create, modify, and delete according to your needs. They are specific to you as a user, so aren't normally available to other artists. They are shown with your username as a prefix, for example (David), if your username is David.

Scripts that implement user-defined shelf items are loaded from the .katana directory of your HOME folder. You can create and delete shelves for user-defined shelf items, and inside of a shelf, create new shelf items, and edit their source code right from within Shelf Actions pop-ups.

Additional Shelves

Additional shelves are shelves that are loaded from directories whose paths are listed in the KATANA_RESOURCES environment variable. They can be used to share shelf item scripts between artists across a studio: you can simply place the resource directory with a directory structure as described below in a network location, and add its path to KATANA_RESOURCES.

The names of additional shelves are shown with an (other) prefix in Shelf Actions pop-ups. Just like built-in shelf items, you can view the source code of additional shelf items through the UI, but you can't delete them or modify their source code. You can also not add or remove additional shelves using the UI. They are defined exclusively through script files in shelves folders on disk that are picked up through KATANA_RESOURCES.

Directory Structure for Shelf Item Scripts

Within a Katana resource directory, shelves and shelf items are loaded from sub-folders with the following names:

• Shelves - contains shelves that are shown in the Shelf Actions pop-up in the toolbar of Katana's main window.

• ShelvesNodeSpecific - contains shelves that are shown in Shelf Actions pop-ups of the Parameters tab.

• ShelvesScenegraph - contains shelves that are shown in the Shelf Actions pop-up of the Scene Graph tab.

Sub-folders of those folders represent the Shelves available in Shelf Actions pop-ups, and contain the shelf item scripts that correspond to shelf items that are listed for a shelf that is selected in the UI.

Shelf item script files are ASCII text files that use the standard .py file extension of Python source files, and can be edited in source code or regular text editor applications.

Note:  There is a known issue with loading of shelves where shelf entries of the same name are shown multiple times when multiple shelves of the same name are present in Katana resource directories. The shelves' loading mechanism searches from left to right, and shelves in folders listed later win over shelves in folders that are listed first. If multiple shelves with the same name are present in KATANA_RESOURCES directories, all shelf items for that shelf are taken from the last shelf that was loaded with that same name.

Node-Specific Shelf Item Scripts

Node-specific shelf item scripts define shelf items that can be run from the Shelf Actions pop-up in the Parameters tab for a node whose parameters are shown.

Pre-Defined Variables in Node-Specific Shelf Item Scripts

The following variable is pre-defined for use in node-specific shelf item scripts:

• node - The node whose parameters are shown in the Parameters tab.

Note:  In addition to node, other variables may be present, which are set using node interaction delegates.

The following additional variables are defined for certain types of nodes using node interaction delegates:

Nodes	Variables
GafferThree	selectedItems - A list of paths of scene graph locations that are selected in the Gaffer table in the parameter interface of those types of nodes.
GroupStack and GroupMerge	selectedNodes - A list of nodes that are selected in the parameter interface of those types of nodes.
MaterialStack	selectedLocations - A list of paths of scene graph locations that are selected in the parameter interface of MaterialStack nodes.

Targeting Node-Specific Shelf Item Scripts to Specific Types of Nodes

It is possible to add information to node-specific shelf item scripts so that their corresponding shelf items are shown in Shelf Actions pop-ups of the Parameters tab only for specific types of nodes. A special SCOPE field in the docstring of the shelf item script can be used to list names of node types (comma separated) to which the script applies. This information is used in the UI to filter the list of shelf items shown for a selected shelf to only show those shelf items that are compatible with the type of the node whose parameters are shown.

For example, the built-in node-specific shelf item script for updating OpScript nodes contains the following scope information in its docstring:

"""
NAME: Upgrade OpScript Node To New API
SCOPE: OpScript

Migrates OpScript nodes from the legacy syntax to the modern syntax.

"""

Docstrings of Shelf Item Scripts

User-defined shelf item scripts that are created in the UI use the following module docstring at the top of the file:

"""
NAME: <the name of the script to show in the UI>
ICON: <the filename of icon to use in the UI>
DROP_TYPES: <currently unused>
SCOPE: <names of types of nodes to target by node-specific shelf items>
<description>

"""

The SCOPE field applies to node-specific shelf item scripts only (see section above).