`NodeTypeBuilder`

class Nodes3DAPI.NodeTypeBuilder.NodeTypeBuilder(nodeTypeName)

Bases: object

Class used for defining Node3D node types via an abstracted interface.

class OpChainInterface(opChainInterface)

Bases: BaseOpChainInterface

Interface to the op chain passed to the node NodeTypeBuilder’s callback.

FAIL = 0

NO_OP = 2

SKIP = 1

__init__(opChainInterface): BuildInterface instances should only be constructed internal to the types created with NodeTypeBuilder. User code has no reason to create them directly.

addInputRequest(inputPortName, graphState, invalidInputBehavior=0)

Deprecated:: This function is deprecated. Please use addRequiredInput() instead.

addRequiredInput(inputPortName, invalidInputBehavior=0): Adds a required input by input port name to the node. Any input ports not specified here will not be considered when building the op graph from the node graph. If the specified input port name is missing, it will be treated in accordance with the invalidInputBehavior.

appendOp(opType, opArgs=None): Append the given Op of type ‘opType’ to the op chain.

setExplicitInputRequestsEnabled(state)

Deprecated:: This function is deprecated. Please use setExplicitInputRequirementsEnabled() instead.

setExplicitInputRequirementsEnabled(state)

setMinRequiredInputs(value)

classmethod SetGenericAssignPolicyRegistrationCallback(callback)

__init__(nodeTypeName)

Initializes an instance of the class.

Parameters:: nodeTypeName (str) – The name of the node type to register in NodegraphAPI’s factory.

addInteractiveTransformCallbacks(gb)

Sets up the callbacks to interactively modify the ‘transform’ parameter exposed by the node. If the node doesn’t have a ‘transform’ parameter, it will be created.

Parameters:: gb (FnAttribute.GroupBuilder) – The group builder to which add the transform group attribute if not already available.

addMakeInteractiveParameter(gb)

Adds the ‘makeInteractive’ attribute to the given group builder. Useful to expose the ‘makeInteractive’ parameter in the node’s parameter interface.

Parameters:: gb (FnAttribute.GroupBuilder) – The group builder to which the ‘makeInteractive’ attribute should be added.

addTimingParameters(gb)

Adds the timing group attribute to the given group builder. Useful to expose a timing parameter in the node’s parameter interface.

Parameters:: gb (FnAttribute.GroupBuilder) – The group builder to which add the timing group attribute.

addTransformParameters(gb)

Adds the transform group attribute to the given group builder. Useful to expose a transform parameter in the node’s parameter interface.

Parameters:: gb (FnAttribute.GroupBuilder) – The group builder to which add the transform group attribute.

build(): Commits the definitions and registers as a node type. This should be called only once.

setAddParameterHintsFnc(fnc)

Defines an optional callback function which allows a node to add additional parameter hints when a new parameter is added.

The function should have a signature matching: addCustomParameterHints(self, attrName, inputDict)

It does not return anything.

setAppendToParametersOpChainFnc(fnc)

Allows users of NodeTypeBuilder to modify the standard Op chain with additional Ops (and their arguments) to influence the appearance of values in parameters of an edited node.

setBuildOpChainFnc(fnc)

Registers the function to be used for building the node’s Op chain.

setBuildParametersFnc(fnc)

Defines an optional callback function which has an opportunity to procedurally create parameters on the newly created node instance. This is called following the conversion of values provided by setParametersTemplateAttr.

The function should have a signature matching: buildParameters(node)

Its return value (if any) is discarded.

setCustomMethod(fncName, fnc)

Allows specification of custom methods on the resulting node type. If the name is not valid or clashes with an existing member function on the base class, an exception will be thrown during build.

setGenericAssignRoots(paramRoot, attrRoot)

Sets the parameter and attribute name to be used as roots by the GenericAssign mechanism.

Parameters:

paramRoot (str) – The name of a group parameter in the hierarchy of parameters on a node under which child parameters should show values from the incoming scene, in the form of //Enableable Parameter Groups//.
attrRoot (str) – The name of a group attribute that is the target for attributes that correspond to //Enableable Parameter Groups// under the group parameter specified by paramRoot.

setGetInputPortAndGraphStateFnc(fnc)

Defines an optional callback function which allows a Node to specify which input Port drives the output Port and modify GraphState.

The function should have a signature matching: getInputPortAndGraphState(node, outputPort, graphState)

It should return a tuple of (inputPort, graphState)

A modified GraphState can be created by calling GraphState.edit() to obtain a GraphStateBuilder. Changes can be made using the builder object, and a new GraphState obtained using GraphStateBuilder.build().

For example, a VariableSwitch node will return the particular input Port that is actively driving the given output Port based on the upstream GraphState.

Most nodes do not need to act like a VariableSwitch node. By default, nodes ‘read’ from all their input Ports. This is the default behaviour of the parent-class method Nodes3DAPI.Node3D.getInputPortAndGraphState. Non-switching Nodes should call this method passing the outputPort and the modified GraphState.

Example:

def getInputPortAndGraphState(node, outputPort, graphState):
  # Add a graph state variable
  graphStateBuilder = graphState.edit()
  graphStateBuilder.setDynamicEntry('var:myVariable', 'myValue')
  modifiedGraphState = graphStateBuilder.build()

  return Nodes3DAPI.Node3D.getInputPortAndGraphState(
        self, outputPort, modifiedGraphState)

setGetScenegraphLocationFnc(fnc)

Defines an optional callback function which allows a node to partipate in widgets and parameter expressions

The function should have a signature matching: getScenegraphLocation(node, frameTime)

It should return a single str value in the form of a scenegraph location path. It is allowed to inspect but not mutate its parameters to do so.

setHintsForNode(hints)

Sets the hint dictionary used for the node type itself. This is most useful for setting “help” text.

setHintsForParameter(paramPath, hints)

Sets the hint dictionary for a given parameter path relative to the node’s top-level parameter group.

setInputPortNames(names)

Defines the names and order of input ports to be created on node initialization. By default, newly created types have no input ports.

Parameters:: names (sequence of str) – A list of names

setIsHiddenFromMenus(state)

Allows you to specify whether the created node type should be hidden from UI menus.

setNodeTypeVersion(nodeTypeVersion): Setting this allows you to tag node instances with a version so that you can provide upgrade paths at katana document parse time. The value defaults to 1 if not set. As only one plug-in can register a node type of a given name, the version of the registered type is considered current for document update purposes. This value is recorded in the node’s XML representation as a “nodetypeversion” attribute.

setNodeTypeVersionUpdateFnc(nodeTypeVersion, updateFnc)

Calling this allows you to register a version upgrade function to the specified version from earlier versions. These functions are called during katana document parse and have this signature:

upgradeFnc(nodeElement)

The node element is an instance of PyXmlIO.Element and can be queried and manipulated with the NodegraphAPI.Xio module.

When parsing the document (prior to instantiating nodes), these scripts are run in sequence for the relevant version range. That range is defined by versions greater than document’s recorded version (via the “nodetypeversion” element attribute) and less than or equal to the current registered version.

setOutputPortNames(names)

Defines the names and order of output ports to be created on node initialization. By default, newly created types have a single output port named ‘out’.

Parameters:: names (sequence of str) – A list of names

setParametersTemplateAttr(groupAttr, forceArrayNames=())

Defines the parameter layout of the node using a GroupAttribute as a template. Single-element FloatAttribute, IntAttribute and DoubleAttribute children are converted to number parameters. Single-element StringAttribute children are converted to string parameters. Multi-element attrs are created as array parameters of equivalent type. If forceArrayNames is specified, single-element attrs at the matching relative attribute paths will be created as equivalent array parameters. Child GroupAttributes are created as group parameters.

Op Chain Interfaces

class Nodes3DAPI.NodeTypeBuilder.BaseOpChainInterface(port, graphState)

Bases: object

This is the interface passed to the opchain’s builder method. It exposes some useful methods to get parameters from the node and pass them as arguments to the given Op.

__init__(port, graphState): BuildInterface instances should only be constructed internal to the types created with NodeTypeBuilder. User code has no reason to create them directly.

addOpSystemArgs(gb)

Adds the default Op system arguments to the given group builder.

Parameters:: gb (FnAttribute.GroupBuilder) – The GroupBuilder to be filled with the op system args.

buildAttrFromParam(param, multisample=False, numberType=<class 'PyFnAttribute.FloatAttribute'>, groupInherit=True, includeEmptyGroups=True)

Utility for converting parameters into attributes, optionally with multi-sampling. This can be run on scalar, array or group parameters. Unless specified, number and number array parameters are converted as FnAttribute.FloatAttribute.

Parameters:

multisample (bool) – if True, the parameter will be sampled according to numSamples, shutterOpen and shutterClose hints.
numberType (class) – This should be either FnAttribute.FloatAttribute FnAttribute.IntAttribute or FnAttribute.DoubleAttribute
groupInherit (bool) – allows the group inherit state of the top-level GroupAttribute when building from a group parameter.
includeEmptyGroups (bool) – If False, empty groups are excluded.

buildAttrListForEnableableParameters(enclosingGroupParam)

Utility for converting GenericAssign-style enableable parameter groups into a list of attrPath, attr pairs. This is useful for custom node types with GenericAssign-like behavior.

Parameters:: enclosingGroupParam (NodegraphAPI.Parameter) – This should be a group parameter containing child parameters in the enableable parameter group form.

getExclusiveToNameAndAttribute()

Utility function to be used by nodes that accept interactive transformation, that returns a named tuple representing the relative ‘exclusiveTo’ attribute value, if present.

Return type:: tuple of (str, StringAttribute) or tuple of (str, None).
Returns:: A tuple whose first element is the string ‘attributeEditor.exclusiveTo’. The second element is a StringAttribute with the node’s name if the ‘makeInteractive’ parameter isn’t ‘No’, otherwise None.

getFrameTime()

Returns the frameTime from the context in which the current node is being cooked. This should be used instead of NodegraphAPI.GetCurrentTime() for any parameter evaluation.

Return type:: float

getGraphState()

Returns the graphState from the context in which the current node is being cooked.

Return type:: GraphState

getModifiedFrameTime()

Return type:: float
Returns:: The current frame time modified depending on the timing mode, assuming the node has a timing parameter.

getNumSamples()

Returns the “numSamples” hint available to nodes which are concerned with multi-sample values. For pre-sampled data, typical interpretation is to process animation when the value is greater than 1. For data sampled on the fly, this value is the recommendation for how frequently to sample.

Return type:: int

getOutputPortName()

Returns the name of the output port from which the current node is being cooked.

Return type:: str

getShutterClose()

Returns the “shutterClose” hint available to nodes which are concerned with multi-sample values. This is a frame-relative value.

Return type:: float

getShutterOpen()

Returns the “shutterOpen” hint available to nodes which are concerned with multi-sample values. This is a frame-relative value.

Return type:: float

getTransformAsAttribute()

Return type:: FnAttribute.GroupAttribute
Returns:: A GroupAttribute containing the values from the transform group parameter, if available.

class Nodes3DAPI.NodeTypeBuilder.OpChainInterface(opChainInterface)

Bases: BaseOpChainInterface

Interface to the op chain passed to the node NodeTypeBuilder’s callback.

FAIL = 0

NO_OP = 2

SKIP = 1

__init__(opChainInterface): BuildInterface instances should only be constructed internal to the types created with NodeTypeBuilder. User code has no reason to create them directly.

addInputRequest(inputPortName, graphState, invalidInputBehavior=0)

Deprecated:: This function is deprecated. Please use addRequiredInput() instead.

addRequiredInput(inputPortName, invalidInputBehavior=0): Adds a required input by input port name to the node. Any input ports not specified here will not be considered when building the op graph from the node graph. If the specified input port name is missing, it will be treated in accordance with the invalidInputBehavior.

appendOp(opType, opArgs=None): Append the given Op of type ‘opType’ to the op chain.

setExplicitInputRequestsEnabled(state)

Deprecated:: This function is deprecated. Please use setExplicitInputRequirementsEnabled() instead.

setExplicitInputRequirementsEnabled(state)

setMinRequiredInputs(value)

class Nodes3DAPI.NodeTypeBuilder.ParametersOpChainInterface(port, graphState)

Bases: BaseOpChainInterface

Extended interface to the op chain passed to the node NodeTypeBuilder’s callback used for controlling what’s shown as values of enableable parameters that depend on the GenericAssign mechanism.

__init__(port, graphState): BuildInterface instances should only be constructed internal to the types created with NodeTypeBuilder. User code has no reason to create them directly.

appendOp(opType, opArgs=None)

getOps()

Migration Guide: Modifying Graph State

Node types created with NodeTypeBuilder could update Local Graph State from within a buildOpChain() function registered with setBuildOpChainFnc.

That mechanism, using setExplicitInputRequestsEnabled, is deprecated. Modifications to graph state made using explicit input requests are not visible to all parts of Katana. Some features like dimming nodes disabled due to local graph state; showing the local graph state in the UI; etc - do not work well with explicit input requests.

Instead, nodes that make changes to local graph state should register a function with setGetInputPortAndGraphStateFnc. This function will be called to determine which of the nodes input Ports are active, and allows modifying the local graph state passed to the upstream node connected to the active inputs.

For example, a node that sets a graph state variable like VariableSet, could be implemented with the deprecated explicit input request mechanism:

# NOTE: Example using deprecated setExplicitInputRequestsEnabled
from Katana import (
    Nodes3DAPI,
    FnGeolibServices,
    FnAttribute
)

def buildOpChain(self, interface):
    # Set an example attribute on all locations
    argsbuilder = FnGeolibServices.OpArgsBuilders.AttributeSet()
    argsbuilder.setCEL(FnAttribute.StringAttribute('//*'))
    argsbuilder.setAttr('info.example', FnAttribute.IntAttribute(1))

    interface.appendOp('AttributeSet', argsbuilder.build())

    # Get the graph state
    graphState = interface.getGraphState()

    # Get the parameters at the graphState's current time
    currentTime = graphState.getTime();
    name = self.getParameter('name').getValue(currentTime)
    value = self.getParameter('value').getValue(currentTime)

    # Add a variable to the local graph state
    graphStateBuilder = graphState.edit()
    graphStateBuilder.setDynamicEntry('var:' + name, value)
    modifiedGraphState = graphStateBuilder.build()

    # Enable explicit input requests. This circumvents normal input
    # processing but allows modifying the local graph state.
    # DEPRECATED!
    interface.setExplicitInputRequestsEnabled(True)

    # Add the explicit input request for our input port with the modified graph state
    interface.addInputRequest('in', modifiedGraphState)

# Define the parameter interface for nodes of our custom node type through a
# builder for GroupAttribute objects, which is turned into a GroupAttribute
# that is passed to the `setParametersTemplateAttr()` function on the
# NodeTypeBuilder instance created below
parametersTemplateAttrGroupBuilder = FnAttribute.GroupBuilder()
parametersTemplateAttrGroupBuilder.set('name', 'myVariable')
parametersTemplateAttrGroupBuilder.set('value', 'myValue')
parametersTemplateAttr = parametersTemplateAttrGroupBuilder.build()

# Create the node type using NodeTypeBuilder
ntb = Nodes3DAPI.NodeTypeBuilder('MyVariableSet_Deprecated')
ntb.setInputPortNames(('in',))
ntb.setParametersTemplateAttr(parametersTemplateAttr)
ntb.setBuildOpChainFnc(buildOpChain)
ntb.build()

The deprecated example can be updated to use setGetInputPortAndGraphStateFnc with some minor changes:

Extract the code for modifying the graph state into a new function getInputPortAndGraphState(self, outputPort, graphState)
Remove the call to interface.setExplicitInputRequestsEnabled
Replace the call to interface.addInputRequest with a call through to the default implementation Node3D.getInputPortAndGraphState
Add a call to NodeTypeBuilder.setGetInputPortAndGraphStateFnc to register the new getInputPortAndGraphState function.

# NOTE: Example using new getInputPortAndGraphState
from Katana import (
    Nodes3DAPI,
    FnGeolibServices,
    FnAttribute
)

def buildOpChain(self, interface):
    # Set an example attribute on all locations
    argsbuilder = FnGeolibServices.OpArgsBuilders.AttributeSet()
    argsbuilder.setCEL(FnAttribute.StringAttribute('//*'))
    argsbuilder.setAttr('info.example', FnAttribute.IntAttribute(1))

    interface.appendOp('AttributeSet', argsbuilder.build())

def getInputPortAndGraphState(self, outputPort, graphState):
    # Get the parameters at the graphState's current time
    currentTime = graphState.getTime();
    name = self.getParameter('name').getValue(currentTime)
    value = self.getParameter('value').getValue(currentTime)

    # Add a variable to the local graph state
    graphStateBuilder = graphState.edit()
    graphStateBuilder.setDynamicEntry('var:' + name, value)
    modifiedGraphState = graphStateBuilder.build()

    # Call through to the default implementation of this function
    # with the modified graph state.
    return Nodes3DAPI.Node3D.getInputPortAndGraphState(self, outputPort, modifiedGraphState)

# Define the parameter interface for nodes of our custom node type through a
# builder for GroupAttribute objects, which is turned into a GroupAttribute
# that is passed to the `setParametersTemplateAttr()` function on the
# NodeTypeBuilder instance created below
parametersTemplateAttrGroupBuilder = FnAttribute.GroupBuilder()
parametersTemplateAttrGroupBuilder.set('name', 'myVariable')
parametersTemplateAttrGroupBuilder.set('value', 'myValue')
parametersTemplateAttr = parametersTemplateAttrGroupBuilder.build()

# Create the node type using NodeTypeBuilder
ntb = Nodes3DAPI.NodeTypeBuilder('MyVariableSet')
ntb.setInputPortNames(('in',))
ntb.setParametersTemplateAttr(parametersTemplateAttr)
ntb.setBuildOpChainFnc(buildOpChain)
ntb.setGetInputPortAndGraphStateFnc(getInputPortAndGraphState)
ntb.build()

If the input previously specified through interface.addInputRequest requires a connection to an upstream node, the method interface.addRequiredInput can be used with setExplicitInputRequirementsEnabled set to True to make this input required. With this enabled, any inputs not specified will not be considered when processing node connections during the traversal process. If the specified input is missing, the behaviour can be set to either cause a failure, add a no-op or have the input skipped.

NodeTypeBuilder

Op Chain Interfaces

Migration Guide: Modifying Graph State

`NodeTypeBuilder`