NodeTypeBuilder¶

class Nodes3DAPI.NodeTypeBuilder.NodeTypeBuilder(nodeTypeName)¶

Bases: object

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

class OpChainInterface(opChainInterface)¶

Bases: Nodes3DAPI.NodeTypeBuilder.BaseOpChainInterface

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

FAIL = 0¶

NO_OP = 2¶

SKIP = 1¶

__init__(opChainInterface)¶

addInputRequest(inputPortName, graphState, invalidInputBehavior=0)¶

appendOp(opType, opArgs=None)¶

Append the given Op of type ‘opType’ to the op chain.

setExplicitInputRequestsEnabled(state)¶

setMinRequiredInputs(value)¶

classmethod NodeTypeBuilder.SetGenericAssignPolicyRegistrationCallback(callback)¶

NodeTypeBuilder.__init__(nodeTypeName)¶

Initializes an instance of the class.

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

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

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

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

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

NodeTypeBuilder.build()¶

Commits the definitions and registers as a node type. This should be called only once.

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

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

NodeTypeBuilder.setBuildOpChainFnc(fnc)¶

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

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

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

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

NodeTypeBuilder.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)

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

NodeTypeBuilder.setHintsForNode(hints)¶

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

NodeTypeBuilder.setHintsForParameter(paramPath, hints)¶

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

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

NodeTypeBuilder.setIsHiddenFromMenus(state)¶

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

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

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

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

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

# 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()

# 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()