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.

Added 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

Added in version 2.5v1.

katanaTmpDir: The path to Katana’s temporary directory

Added in version 2.5v1.

katanaRootDir: The path to Katana’s installation directory

Added 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.