Customizing GafferThree

Creating a Custom GafferThree Package Class

Package classes in the GafferThree define the types of items that can be created through the GafferThree, the way in which they are displayed in the GafferThree's UI within the Parameters tab, and other properties such as whether the items can accept other items as children.

In order to create a custom package class for the GafferThree, the following components are required:

• Package class

• Edit package class (optional)

• UI delegate class

• Package initialization file

Package Class

The package’s main class is responsible for creating nodes that produce the scene graph locations and attributes for your package, as well as the parameters for modifying these locations and attributes.

To implement a package class, do the following:

• Create a class derived from PackageSuperToolAPI.Packages.Package, or choose a specific type of package class to derive from if appropriate, for example, the GafferThree’s LightPackage class.

• Implement the create() class method. Your implementation should create and connect together the nodes for the package within a Group node, and instantiate and return a new package class instance.

• After defining your package class, register it with the GafferThreeAPI by calling GafferThreeAPI.RegisterPackageClass(), and passing your class.

Tip:  You can store references to nodes you create using the PackageSuperToolAPI.NodeUtils.AddNodeRef() function. AddNodeRef() stores the name of the node as a custom parameter on the package node, and makes it easy to refer to nodes within a package from elsewhere in the code associated with your package. Node references stored in this way can be obtained using the corresponding GetNodeRef() function from the NodeUtils module.

Edit Package Class (Optional)

An edit package class is responsible for creating nodes, which can edit scene graph locations in the incoming scene graph. These locations may have been created by an instance of your custom package class in an upstream GafferThree node.

To implement an edit package class, which is optional, do the following:
Create a class derived from PackageSuperToolAPI.Packages.EditPackage, or choose a specific type of edit package class to derive from if appropriate. For instance, the GafferThree’s LightEditPackage class.

UI Delegate Class

A UI delegate class is responsible for defining the parameter interface shown in tabs below the Gaffer object table in the Parameters tab.

To implement a UI delegate class, do the following:

• Create a class derived from PackageSuperToolAPI.UIDelegate.UIDelegate, or choose a specific type of UI delegate class to derive from if appropriate. For instance, the GafferThree’s LightUIDelegate class.

Tip:  You can use PackageSuperToolAPI.UIDelegate.GetUIDelegateClassForPackageClass() to obtain the UI delegate class that was registered for a specific package class.

• You can also implement the getTabPolicy() instance method, which is optional:

getTabPolicy() receives the name of a tab, Object, Material, or Linking in the case of GafferThree, and is expected to return a QT4FormWidgets.PythonGroupPolicy instance containing parameter policies for editing parameters on the nodes created by your package class.

Tip:   You can use PackageSuperToolAPI.NodeUtils.GetRefNode() to reference nodes in your package that you have previously stored using AddNodeRef().

Package Initialization File

To ensure that your package is initialized, place your package modules in a SuperTools sub-directory of a path, which is contained in your $KATANA_RESOURCES environment variable, alongside an __init__.py file, which imports your package files.

The resulting directory structure should look similar to the following:

SuperTools
`-- SkyDome
    |-- __init__.py
    |-- ExamplePackage.py
    `-- ExampleUIDelegate.py

The UI delegate class can only be imported if Katana is running in UI mode:

import PackageSuperToolAPI
import ExamplePackage

if PackageSuperToolAPI.IsUIMode():
    import ExampleUIDelegate