G4P – part 5 – File Browser Bookmarks

In this instalment of the Gaffer for Pipeline series of ‘ground up’ posts, we look at adding custom bookmarks to the various Gaffer browsers. We’ll recap the tutorial from the Gaffer docs, introduce dynamic bookmarks and look at Gaffer’s own categories in more detail.

There is a step-by-step tutorial in the Gaffer documentation that covers how to add custom bookmarks using a startup script: Startup Config 2; Custom Bookmarks. You may wish to familiarise yourself with this first if you prefer step-by-step guides.

Recap

Bookmarks are aded using the GafferUI.Bookmarks API, which requires the app instance, this makes it easy to use in a startup script, where application is available in the global scope:

bookmarks = GafferUI.Bookmarks.acquire( application )

Defaults can then be set or new paths added:

bookmarks.setDefault( os.getcwd() )
bookmarks.add( "Home", os.path.expandvars( "$HOME" ) )

The Gaffer UI can group bookmarks into categories so they are more relevant to the node/action in question. Specify a category when acquiring the bookmarks object to interact with just that category:

imageBookmarks = GafferUI.Bookmarks.acquire( app, category="image" )

Browsers with a category set will show uncategorised bookmarks and those belonging to the category (more on Gaffer’s built-in categories below), otherwise, only uncategorised bookmarks will be shown.

Bookmark tricks

Dynamic bookmarks

As well as static paths, callables can be registered to allow paths to be built when the bookmark is selected by the user:

import os
from datetime import date

def __todaysWorkDir( widget ) :

    today = date.today().strftime( "%Y-%m-%d" )
    path = os.path.expandvars( os.path.join( "$HOME", "work", today ) )
    if not os.path.exists( path ) :
        try :
            os.makedirs( path )
        except OSError :
            return "$HOME"
    return path

bookmarks = GafferUI.Bookmarks.acquire( application )
bookmarks.add( "Today's work", __todaysWorkDir )

Categories used by Gaffer’s built-in nodes

• image: Used by the Image, Outputs, OIIO and Catalogue nodes as well as the UVInspector.
• font: Used be the Text nodes (2D+3D) when picking a font.
• shader: Used by OSL and Shader nodes when loading custom shaders.
• script: Used by the main File menu and dispatcher UIs when loading scripts.
• reference: Used by Box and Reference nodes.
• sceneCache: Used by the SceneReader/Write nodes.
• procedurals: Used by the ExternanlProcedural node
• vdb: Used by the ArnoldVDB node
• texture: Used by Appleseed and ShaderBall nodes
• color: Used by the LUT node when picking a LUT.
• ass: Used by the ArnoldRender node

Assigning categories to plugs

The UI Editor allows you to change the category of bookmarks used by string plugs that have the “File Chooser” widget.

As this is ultimately just stored in metadata, so you can update whole classes, or specific plugs by registering a value directly, eg:

Gaffer.Metadata.registerValue( aNode, "path:bookmarks", "image" )

The category can also be set when registering a new node, as part of the plug’s metadata:

Gaffer.Metadata.registerNode(                                                  
   MyNode,  
   plugs = {                                                                                                                                            
      "fileName" : [                                                                                                                     
         ...                                         
         "plugValueWidget:type", "GafferUI.FileSystemPathPlugValueWidget",                                                  
         "path:bookmarks", "sceneCache",

Useful Links

• The Gaffer Docs Startup Config 2; Custom Bookmarks tutorial
• The Gaffer Bookmarks API
• More on the Gaffer meatadata system