Context Variable cheat sheet

Contexts are an essential part of Gaffer. We’re working on some more structured documentation about them. In the mean time, here is a list of common Context Variables set by Gaffer as part of the compute process. Amongst other things, they can be used in expressions or via ${variables} in string plug values.

Standard variables

The following variables are set by Gaffer where appropriate and can be used in expressions, string plugs, etc…

Common

• ${script:name} (doesn’t include the full path, or extension)
• ${frame}, ${framesPerSecond}
• ${frameRange:start}, ${frameRange:end}
• Any variables set in File > Settings... > Variables, which includes, by default:
  • ${project:name}
  • ${project:rootDirectory

GafferScene

• ${scene:path} The path to the location being computed.
• ${scene:renderer} The name of the renderer the scene is being computed for. For the Viewer, this will be "OpenGL", it will be None for other panels such as the HierarchyView.

GafferImage

• ${image:defaultFormat} A GafferImage.FormatData object, use .value to get the GafferImage.Format.
• ${image:channelName} The channel of the image being computed.
• ${image:tileOrigin} The current tile coordinates within the image being computed.

Node specific variables

The following variables are set by specific Gaffer nodes, so are only available upstream – in graphs that use them.

Wedge

• ${wedge:value}
• ${wedge:index}

Loop

• ${loop:index}

CollectScenes

• ${collect:rootName}

CollectImages

• ${collect:layerName}

Context modifiers

Context modifiers affect the Context upstream of their placement in the graph.

ContextVariables / DeleteContextVariables

Hopefully these nodes are fairly self explanatory, they allow you to set/remove arbitrary variables from the Context. They don’t have any defaults per se.

TimeWarp

This node modifies ${frame} to create time offsets/re-times.

Accessing Context Variables

Expressions

Python

• script = context["script:name"]
• mightNotExist = context.get( "custom:layerName", "default" )

The predefined context dictionary allows subscript access to available Context Variables, eg: script = context["script:name"]. If the variable you are retrieving may not exist in some scenarios, it’s best to use the context.get( name, defaultValue ) mechanism to avoid RuntimeErrors breaking your expressions.

OSL

• script = context( "script:name" )
• mightNotExist = context( "custom:layerName", "default" )

In OSL, the context function allows access to available Context Variables both with and without defaults. If the requested variable doesn’t exist, and no default is provided, and empty string or 0 will be returned, depending on the variable type being assigned to.