2 min read Dev and Pipe Tips

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.
💡
For render performance reasons, ${scene:path} is not available to nodes in a Shader Network.

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.

💡
Most of these nodes allow you to customise the name of the Context Variable(s) to your needs, we list the defaults here.

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.

Tom