Re-using Box based tools

Gaffer Allows you to use the Box node to create reusable tools within your node graph. In this post, we look at how to use Gaffer.ExtensionAlgo to export these so they can be re-used in the same way as Gaffer’s built-in nodes.

TL;DR

Export from Gaffer’s Python Editor

Gaffer.ExtensionAlgo.exportExtension(
    'PackageName',
    [ <boxNode>, ... ],
    '/some/path'
)

Run gaffer with modified extensions path

$ env GAFFER_EXTENSION_PATHS=/some/path gaffer

ExtensionAlgo

Gaffers ExtensionAlgo module provides tools for exporting Box nodes as extension modules. They will then appear in the Node Menu along side Gaffer’s built in nodes.

In this example, we’ve made two new nodes. A ‘Lights’ node that uses a Spreadsheet and CollectScenes to quickly create very simple light rigs, and a ‘LightTweaks’ node that uses a Spreadsheet to edit a lights color, exposure or position downstream.

We’d like to save these out so they can be made from the Node Menu whenever needed.

Exporting

Gaffer.ExtensionAlgo.exportExtension allows us to export one or more Box nodes. So first prepare your boxe’d tools, with what ever values you want to be the defaults for when the new node is created.

You may want to edit the Box’s UI to taste before exporting. See > Edit UI.... The default box icon and plug adders will not be shown for you new node

You next need to decide where you’d like to keep these. In this example, we’re going to put all of our extensions in /data/gaffer/extensions. We can export many different extensions here as long as they have a unique name.

Once you have a name for you new extension, and know where you want to put them, you can export the extension. In Gaffer’s Python Editor your export command would look something like the following, for the screenshot pictured above:

Gaffer.ExtensionAlgo.exportExtension(
   'LightTools',
   [ root['Lights'], root['LightTweaks'] ], 
   '/data/gaffer/extensions'
)

You can middle-mouse-drag nodes from the Graph Editor into the Python editor to help build up the list of boxes to include in the module.

tip

You can only export Box nodes!

Registering your extensions

Once you have exported your extension, you then need to tell Gaffer to load them at startup. This is done by extending the GAFFER_EXTENSION_PATHS environment variable.

It’s up to you how you want to do this, depending on how you like to manage your environment variables. If you want to quickly test your export though, you can run gaffer in a modified environment using the env command. For this example it would be:

env GAFFER_EXTENSION_PATHS=/data/gaffer/extensions:$GAFFER_EXTENSION_PATHS gaffer

Your new nodes should then show up in the Node Menu!

Versioning

As these nodes are now registered at startup, if you change the exported extension module, any nodes in existing scripts will be updated automatically when your script is re-opened. As such you need to be careful about compatibility when making changes. In Gaffer we use startup scripts to help migrate older scripts after breaking changes to nodes.

Useful Links

Leave a Reply