AttributeScript Reference

Available Modules

The following modules are available without importing:

Other Katana modules may be importable, but users should take care not to attempt to modify the Katana project from within an AttributeScript.

Attributes

GetAttr(attributePath[, inherit=False, asAttr=False, atLocation=None, asNumpy=False, asFnAttribute=False])

Returns the value of an attribute at the given attribute path. If the attribute does not exist, None is returned.

Parameters:
  • attributePath – Path to the attribute, e.g. visible or :kat:attr`material.surfaceParams.Surf_Col`.
  • inherit – If True, the attribute is queried globally, i.e. from ancestor locations.
  • asAttr – If True, returns the value of the attribute as a ScenegraphAttr or FnAttribute, depending on the value of asFnAttribute. Otherwise, returns the values of the attribute as a Python list. This may be useful if more than one time sample is needed, or if the conversion to a list is unnecessary.
  • atLocation – If given, the attribute is read from the given scene graph location. Otherwise the attribute is read from the current location.
  • asNumpy – Deprecated - do not use.
  • asFnAttribute – If True, changes the return type from ScenegraphAttr to FnAttribute, provided that asAttr is also True.
SetAttr(attributePath[, attrValue=None])

Given an attribute path, overrides an attribute with the value provided. If attrValue is a list of values, the length and type must match any pre-existing attribute at that location or an error is raised. This is to prevent accidental changes to the definition of an attribute. If attrValue is a ScenegraphAttr, it is used without regard to any existing attribute. If attrValue is not provided, this is equivalent to DelAttr()

DelAttr(attributePath)

Deletes the attribute at the given attribute path.

GetXform([worldSpace=False, atLocation=None, asAttr=False, atSamples=None, asFnAttribute=False])

Returns the current transformation as a 16-element list of float values representing a 4x4 transform matrix.

Parameters:
  • worldSpace – If True, the transformation is returned in world space. Otherwise the transformation is in local space.
  • atLocation – If given, the transformation is read from the given scene graph location. Otherwise the transformation is read from the current location.
  • asAttr – If True, returns the transformation as a ScenegraphAttr or FnAttribute, depending on the value of asFnAttribute. Otherwise, returns the transformation as a Python list. This may be useful if more than one time sample is needed, or if the conversion to a list is unnecessary.
  • atSamples – A sequence of time samples at which to return the xform, or None to use the first time sample.
  • asFnAttribute – If True, changes the return type from ScenegraphAttr to FnAttribute, provided that asAttr is also True.

Scene Graph

GetName()

Returns the base name of the current scene graph location.

GetFullName()

Returns the full path of the current scene graph location.

Tip

If you wish to generate a stable sequence of pseudorandom numbers in your attribute script, use this to set your PRNG seed.

GetChildNames([atLocation=None])

Returns the child names from the current or specified scene graph location.

GetType()

Returns the type of the current scene graph location.

Graph State

GetFrameTime()

Returns the current frame time as a float.

GetShutterOpen()

Returns the shutter open value as defined (and only as defined) by renderSettings.shutterOpen.

GetShutterClose()

Returns the shutter close value as defined (and only as defined) by renderSettings.shutterClose.

GetNumSamples()

Returns the scene-wide recommendation for the number of samples to generate.

Assets

DefaultAssetPlugin.isAssetId(str)

Returns True if input string represents a valid asset id.

DefaultAssetPlugin.containsAssetId(str)

Returns True if input string contains a valid asset id anywhere within it.

DefaultAssetPlugin.resolveAsset(assetId)

Look up asset id in asset system and return path (or other string) that it references.

DefaultAssetPlugin.resolvePath(path, frame)

Resolves env vars in input path string, then resolves asset ids and file sequences.

DefaultAssetPlugin.getUniqueScenegraphLocationFromAssetId(assetId, includeVersion)

Returns a valid scene graph location path that uniquely represents the input asset id.

DefaultAssetPlugin.getRelatedAssetId(assetId, relation)

Returns asset id that is related to input asset, given a relationship type.

User Parameters

user

User parameters of the AttributeScript node itself are available in a module called user. Each parameter (array or otherwise) is converted to a list of values. For example, a number parameter is available as a list containing one float value:

>>> user.path.to.param
[42.0]

Misc

GetConfig(name)

Returns a named configuration value.

GetResolution([name=None, asDict=False])

Returns the dimensions of a named resolution, or the current resolution if name is not specified. If the asDict is False, the value returned is a 2-tuple of the width and height values. If the asDict parameter is True, then it returns a dictionary containing more information about the resolution than simply the dimensions.

GetArguments([asOpArgs=False, asFnAttribute=False])

Returns a list of arguments to the attribute script. The arguments include CEL expressions, the name of the node, and similar.

Parameters:
  • asOpArgs – If True, return Op arguments to the AttributeScript Op. Otherwise return arguments in the same format as used in Katana 1.x.
  • asFnAttribute – If True, changes the return type from ScenegraphAttr to FnAttribute.