Python Expressions

Katana uses Python to evaluate its expressions. Code that would evaluate as an expression within Python can be used as an expression within Katana. The following page lists functions and variables that are specific to the expression editor and also lists which modules are imported. This is not meant to be an introduction to Python but a quick reference for those wishing to leverage some of the expression specific functions and variables.

Available Modules

A few python modules are available for use in parameter expressions:

Module

Namespace

Example

re

import re

re.sub(r'x', ' by ', '2048x2048')

array

import array

array.array('u', "efficient").buffer_info()[1]

os.path

from os import path

path.exists(getenv("HOME", "") + "/shaders")

math

from math import *

cos(pi/3)

ExpressionMath

from ExpressionMath import *

randval(0, 1, frame)

Parameters

getNode(nodeName)

Returns a parameter reference for the given node’s top-level parameter. For example:

>>> getNode("Transform3D").translate.i0
150

Note

When nodeName is a string literal, the expression will automatically be updated if the referenced node is renamed.

getParam(nodeNameAndParameterPath)

Returns a parameter reference for the given node/parameter path. For example:

>>> getParam("Transform3D.translate.i0")
150

Note

When nodeNameAndParameterPath is a string literal, the expression will automatically be updated if the referenced node is renamed.

getParamRelative(parameterReference, relativePath)

Returns a parameter reference for the parameter related to parameterReference by relativePath.

relativePath should be a slash-delimited parameter path, where each component is one of:

  • . (the current parameter)

  • .. (the parent parameter)

  • A parameter name

For example:

>>> getParamRelative(getParam("Transform3D.translate.i0"), "../i1")
150
self

Evaluates to a parameter reference for the current parameter. For example:

>>> self.getParent().user.foo
"bar"

Parameter References

<path.to.param>

Evaluates to a parameter reference for parameter at the given path. For example:

>>> translate.i0
150

Child parameters references can be retrieved by accessing attributes, for example the expression transform.translate.i0 is equivalent to ((transform).translate).i0.

If a parameter expression evaluates to a parameter reference, the actual value of the parameter is retrieved by calling str() or float(), depending on the type of the expressioned parameter

<path.to.param>.getNode()

Returns the node instance that owns the referenced parameter.

<path.to.param>.getParent()

Returns a parameter reference for the top-level parameter of the parent of the node that owns the referenced parameter.

<path.to.param>.getNodeName()

Returns the name of the node that owns the referenced parameter

<path.to.param>.getChildren()

Returns a list of child parameters of the referenced parameter

<path.to.param>.isNumber()

Returns a boolean indicating whether the referenced parameter is a number

Project Settings

Project settings are stored as parameters on the root node (the top level of the node graph) and shown in the Project Settings tab. They can be accessed similarly to parameters on any other node. The project object contains additional attributes without corresponding parameters; these are described below.

project

Evaluates to a parameter reference describing values in the Project Settings tab. For example:

>>> project.inTime
1001
>>> project.outTime
1500
>>> project.width
1920
>>> project.height
1080
>>> project.assetID
"/path/to/project.katana"
project.<path.to.param>

Evaluates to a parameter reference for a parameter on the root node, as shown in the Project Settings tab.

project.width

Evaluates to the width of the currently selected resolution.

project.height

Evaluates to the height of the currently selected resolution.

project.file

Evaluates to the filesystem path of current project.

project.dir

Evaluates to the filesystem path of the directory that contains the current project.

project.assetID

Evaluates to the name of the file or the ID of the asset that the current project was loaded from.

project.originalAssetID

Evaluates to the name of the original file or the ID of the original asset that the current project was last saved as before loading.

Resolving Assets

assetIdForScope(assetId, scope)

Returns a partial asset ID scoped to the specified level in the asset hierarchy.

scope should be one of:

  • kAssetFieldName

  • kAssetFieldVersion

Under the hood, this function calls the current asset plug-in’s getAssetIdForScope() method.

assetAttr(assetId, attrName, default=None)

Returns metadata associated with an asset.

Under the hood, this function calls the current asset plug-in’s getAssetAttributes() method.

resolveAsset(assetId, default=None)

Returns the resolved asset string for the given asset ID.

Under the hood, this function calls the current asset plug-in’s resolveAllAssets() method.

resolvePath(path, frame, default=None)

Returns the resolved asset string for the given asset ID, with environment variables and file sequences resolved.

Under the hood, this function calls the current asset plug-in’s resolvePath() method.

Renderers

renderers

List of names of available renderers.

New in version 3.0v1.

Resolutions

getres(resolutionName)

Returns a (width, height) tuple for the resolution named resolutionName:

>>> str(getres('hd'))
(1920, 1080)
getresdict(resolutionName)

Returns a dictionary of information for the resolution named resolutionName:

>>> str(getresdict('hd'))
"{'name': 'HD', 'yres': 1080, 'groupname': 'TV', 'xres': 1920, 'proxyname': '', 'aspectRatio': 1.7777777910232544, 'fullname': 'Miscellaneous'}"

Directories

tmpDir

The path to the operating system’s temporary directory

New in version 2.5v1.

katanaTmpDir

The path to Katana’s temporary directory

New in version 2.5v1.

katanaRootDir

The path to Katana’s installation directory

New in version 2.5v1.

Node-specific Functions

scenegraphLocationFromNode(node)

Applicability: 3D nodes that create locations

Returns the scene graph location created by the given node object node:

>>> scenegraphLocationFromNode(getNode('PrimitiveCreate'))
"/root/world/geo/primitive"
getRenderLocation(node, renderPass)

Applicability: Render, ImageWrite

Returns the file asset path created by the given node for the render pass renderPass:

>>> getRenderLocation(getNode('shadow_key'), 'primary')
"/tmp/shadow_key.exr"
getDisplayWindow(port=0, node=None, time=None)

Applicability: 2D nodes

Returns an object representing the display window at the given node, port and time. This object has the following attributes:

  • x0

  • y0

  • x1

  • y1

  • width

  • height

If not given, port defaults to the first input port on the node. If the port is not found amongst the input ports, it will be looked up amongst the output ports.

If not given, node defaults to the current node.

If not given, time defaults to the current time.

getXform(node=None, time=None)

Applicability: 2D nodes

Returns a Imath.M44f object representing the 2D transformation at the given node and time.

If not given, node defaults to the current node.

If not given, time defaults to the current time.

getXformR(node=None, time=None)

Applicability: 2D nodes

Returns an integer representing the 2D rotation at the given node and time.

If not given, node defaults to the current node.

If not given, time defaults to the current time.

getXformS(node=None, time=None)

Applicability: 2D nodes

Returns a Image.Vec3 object representing to 2D scale at the given node and time

If not given, node defaults to the current node.

If not given, time defaults to the current time.

getXformT(node=None, time=None)

Applicability: 2D nodes

Returns a Image.Vec3 object representing to 2D translation at the given node and time

If not given, node defaults to the current node.

If not given, time defaults to the current time.

Graph State

getVar(varName)

Gets the value of the named Graph State Variable in the Local Graph State, where possible.

If the evaluation context does not provide Local Graph State, the Global Graph State is queried. For example, this is the case when getVar() is evaluated in the context of the UI, or when a Parameter is evaluated via Parameter.getValue() in a user script. See NodegraphAPI.StackedLocalGraphState.

Return type:

str, int, or float

Parameters:

varName (str) – The name of the Graph State Variable.

Returns:

The value of the named Graph State Variable.

Raises:
  • TypeError – If the type of varName is not str.

  • Exception – If the name of the variable cannot be found.

Since:

Katana 4.5v1

getFrameTime()

Gets the frame time in the Local Graph State, where possible.

If the evaluation context does not provide Local Graph State, the Global Graph State is queried. For example, this is the case when getVar() is evaluated in the context of the UI, or when a Parameter is evaluated via Parameter.getValue() in a user script. See NodegraphAPI.StackedLocalGraphState.

Return type:

float

Returns:

The Graph State Frame Time.

Since:

Katana 4.5v1

matchGraphStateVariable(variableName, pattern, matchMethod)

Evaluates whether the value of the named Graph State Variable in the Local Graph State matches the given pattern using the specified matchMethod.

If the evaluation context does not provide Local Graph State, the Global Graph State is queried. For example, this is the case when matchGraphStateVariable() is evaluated in the context of the UI, or when a Parameter is evaluated via Parameter.getValue() in a user script. See NodegraphAPI.StackedLocalGraphState.

Return type:

bool

Parameters:
  • variableName (str) – The name of the Graph State Variable.

  • pattern (str) – The pattern to be matched. Typically a CEL statement.

  • matchMethod (str) – The match method. Currently only 'CEL' is supported.

Returns:

Whether the value of the Graph State Variable was matched.

Raises:

ValueError – If matchMethod is not 'CEL'.

Since:

Katana 4.5v1

matchGlobalGraphStateVariable(variableName, pattern, matchMethod)

Evaluates whether the value of the named Graph State Variable matches the given pattern using the specified matchMethod.

Return type:

bool

Parameters:
  • variableName (str) – The name of the Graph State Variable.

  • pattern (str) – The pattern to be matched. Typically a CEL statement.

  • matchMethod (str) – The match method. Currently only 'CEL' is supported.

Returns:

Whether the value of the Graph State Variable was matched.

Raises:

ValueError – If matchMethod is not 'CEL'.

Miscellaneous

sampleTime

New in Katana 4.5v1

The floating point frame time at which the parameter is being evaluated: the time argument given to Parameter.getValue().

frame

Warning

⚠️ Deprecated since Katana 4.5v1: Use sampleTime.

The floating point frame time at which the parameter is being evaluated: the time argument given to Parameter.getValue().

nodeName

The name of the node that the parameter is a part of.

katanaRelease

The Katana release identifier with the maintenance version, e.g. 3.0v1.

katanaVersion

The internal Katana version number, e.g. 3.0.1.000002, which is stored in the node graph document of a Katana project file, in order to determine which upgrade scripts to run when loading the Katana project in a future release.

katanaBranch

The Katana release identifier without the maintenance version, e.g. 3.0.

isLinux

A boolean flag that is True on Linux and False otherwise.

New in version 2.5v1.

isWindows

A boolean flag that is True on Windows and False otherwise.

New in version 2.5v1.

fcurve(fileName, curveName, frameNum)

Returns the value stored within the FCurve file fileName from the curve curveName for the given frame frameNum:

>>> fcurve("/tmp/fcurve.xml", "lgt_spot.shaders.lightParams.intensity.value", frame)
0.1

The FCurve file should be an XML file such as those generated by the menu option Export FCurve… which is obtained by right-clicking on a float parameter within the Parameters tab.

getenv(envVarName, defaultValue)

Returns the value of the environment variable envVarName or if not found the default defaultValue:

>>> getenv("HOME", "/tmp")
'/home/rms'
getExrAttr(fileName, attrHeader, frame, default=None)

Returns the string value of the attribute attrHeader within the file fileName for the given frame frame, or default if the attribute is not found:

>>> getExrAttr('/tmp/beauty.exr', 'compression', frame)
'zips'
isLookFileBaking()

Returns True if the expression is being evaluated during the baking of a Look File, otherwise False.

Equivalent to Nodes3DAPI.LookFileBaking.GetGlobalBakeState.