AttributeScript Reference ========================= Available Modules ----------------- The following modules are available without importing: - :mod:`ExpressionMath` - :mod:`FnAttribute` - :mod:`ScenegraphAttr` Other Katana modules may be importable, but users should take care not to attempt to modify the Katana project from within an AttributeScript. Attributes ---------- .. function:: 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. :param attributePath: Path to the attribute, e.g. :kat:attr:`visible` or :kat:attr`material.surfaceParams.Surf_Col`. :param inherit: If ``True``, the attribute is queried globally, i.e. from ancestor locations. :param 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. :param atLocation: If given, the attribute is read from the given scene graph location. Otherwise the attribute is read from the current location. :param asNumpy: Deprecated - do not use. :param asFnAttribute: If ``True``, changes the return type from ``ScenegraphAttr`` to ``FnAttribute``, provided that *asAttr* is also ``True``. .. function:: 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 :func:`DelAttr` .. function:: DelAttr(attributePath) Deletes the attribute at the given attribute path. .. function:: 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. :param worldSpace: If ``True``, the transformation is returned in world space. Otherwise the transformation is in local space. :param atLocation: If given, the transformation is read from the given scene graph location. Otherwise the transformation is read from the current location. :param 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. :param atSamples: A sequence of time samples at which to return the xform, or ``None`` to use the first time sample. :param asFnAttribute: If ``True``, changes the return type from ``ScenegraphAttr`` to ``FnAttribute``, provided that *asAttr* is also ``True``. Scene Graph ----------- .. function:: GetName() Returns the base name of the current scene graph location. .. function:: 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. .. function:: GetChildNames([atLocation=None]) Returns the child names from the current or specified scene graph location. .. function:: GetType() Returns the type of the current scene graph location. Graph State ----------- .. function:: GetFrameTime() Returns the current frame time as a float. .. function:: GetShutterOpen() Returns the shutter open value as defined (and only as defined) by :kat:attr:`renderSettings.shutterOpen`. .. function:: GetShutterClose() Returns the shutter close value as defined (and only as defined) by :kat:attr:`renderSettings.shutterClose`. .. function:: GetNumSamples() Returns the scene-wide recommendation for the number of samples to generate. Assets ------ .. module:: DefaultAssetPlugin :noindex: .. function:: isAssetId(str) Returns ``True`` if input string represents a valid asset id. .. function:: containsAssetId(str) Returns ``True`` if input string contains a valid asset id anywhere within it. .. function:: resolveAsset(assetId) Look up asset id in asset system and return path (or other string) that it references. .. function:: resolvePath(path, frame) Resolves env vars in input path string, then resolves asset ids and file sequences. .. function:: getUniqueScenegraphLocationFromAssetId(assetId, includeVersion) Returns a valid scene graph location path that uniquely represents the input asset id. .. function:: getRelatedAssetId(assetId, relation) Returns asset id that is related to input asset, given a relationship type. User Parameters --------------- .. currentmodule:: None .. py:data:: 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 ---- .. function:: GetConfig(name) Returns a named configuration value. .. function:: 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. .. function:: 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. :param asOpArgs: If ``True``, return Op arguments to the AttributeScript Op. Otherwise return arguments in the same format as used in Katana 1.x. :param asFnAttribute: If ``True``, changes the return type from ``ScenegraphAttr`` to ``FnAttribute``.