How To Write a SuperTool

See also

SuperTools are provided as Python packages, and are loaded from the ‘SuperTools’ subdirectory of Katana Resources.

The package registers SuperTools as Katana plug-ins by defining a PluginRegistry list of plug-in definitions, each of which is a tuple containing the following:

  • The plug-in type name, “SuperTool”.

  • The plug-in type API version number, which is currently 2.

  • Type-specific plug-in data, which is a tuple containing the following:

    • The Node class

    • A function that returns the Editor class.

For example:

PluginRegistry = [("SuperTool", 2, "MySuperTool", (MySuperTool.MySuperToolNode, MySuperTool.GetEditor))]

The Node class is a NodegraphAPI.SuperTool, and is responsible for the SuperTool’s top-level parameters and internal node graph, typically presenting API for updating its properties programmatically. The Editor class provides the SuperTool’s GUI, as populated in the Parameters tab. It is a QWidget whose constructor accepts a parent widget and an instance of the Node class.

It is also possible to define a GetGenericAssignDirectory function that returns a directory path (as a str) containing GenericAssign node specifications (see Args Files for GenericAssign), allowing these files to exist within the SuperTool package, rather than a separate GenericAssign Katana Resource.

Example SuperTools

Katana ships with several example SuperTools for demonstration purposes. The relevant files can be found in $KATANA_ROOT/plugins/Resources/Examples/SuperTools/, and the SuperTools themselves can be made accessible in the Node Graph tab by adding $KATANA_ROOT/plugins/Resources/Examples to the KATANA_ROOT environment variable (see the User Guide for more information). There are two SuperTool node base classes. A SuperTool whose node derives from NodegraphAPI.SuperTool is a general SuperTool while a SuperTool whose node derives from PackageSuperToolAPI.BaseNode is a more specialized type called a ‘Package SuperTool’. See How To Write a Package SuperTool for more information on the latter type.

The example SuperTools that ship with Katana are as follows:

SuperTool Name

Node Base Class

Description

PonyStack

NodegraphAPI.SuperTool

Adds Pony assets at the click of a button, listing the created ponies in a tree widget and exposing the transform parameters of the currently selected pony.

This example shows how a range of built-in widget types can be incorporated into a SuperTool.

ImageCoordinate

NodegraphAPI.SuperTool

Loads an image for display in the Parameters tab and stores user-selected image coordinates as attributes in the scene graph.

This example shows how pure Qt widgets can be used to achieve customization beyond Katana’s built-in widgets.

ExamplePackageSuperTool

PackageSuperToolAPI.BaseNode

Creates simple ‘package’ locations in the scene graph.

This is a minimal example of a Package SuperTool (see How To Write a Package SuperTool for more information).

PonyFarm

PackageSuperToolAPI.BaseNode

Creates ‘Pony’, ‘Cow’ and ‘Herd’ packages in the Parameters tab. These packages are scene graph locations representing pony assets, cow assets and groups of cow or pony assets, respectively.

This is a more realistic example of a Package SuperTool (see How To Write a Package SuperTool for more information).

SuperTools in the NetworkMaterial Node Graph Context

In order to allow your SuperTool to be used in the NetworkMaterial Context, and to expose it in the Node Graph tab’s layered menus, you must apply the context’s Node Flavor:

NodegraphAPI.AddNodeFlavor(<SuperToolTypeName>, NodegraphAPI.Context.NetworkMaterial)

Additionally if your SuperTool should only be used in association with a particular renderer, you should also add the following Node Flavor:

NodegraphAPI.AddNodeFlavor(<SuperToolTypeName>, <rendererName>)

If this flavor is added, it will only appear in the Node Graph tab’s layered menu when the renderer set in the context matches that of the SuperTool.

Alternatively, if your SuperTool can be used with all shading nodes types, you should add the following Node Flavor:

NodegraphAPI.AddNodeFlavor(<SuperToolTypeName>, NodegraphAPI.Flavor.Predefined.RendererAgnostic)