Groups and LiveGroups

A Group node acts as a container for a sub-network of nodes. To add a Group node to a recipe under the root node, then create a PrimitiveCreate node inside that group enter the following:

# Create a Group node at root level
groupNode = NodegraphAPI.CreateNode('Group', NodegraphAPI.GetRootNode())

Then, create a PrimitiveCreate node, as in Creating and Retrieving Nodes but give the Group node as parent node, rather than the root node as in the previous example:

primNode = NodegraphAPI.CreateNode('PrimitiveCreate', groupNode)

Alternatively, create a Group node and a PrimitiveCreate node at the root level, then parent the PrimitiveCreate node under the Group node:

# Get the root node
rootNode = NodegraphAPI.GetRootNode()

# Create the Group node at root level
groupNode = NodegraphAPI.CreateNode('Group', rootNode)

# Create the PrimitiveCreate node at root level
primNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)

# Set the Group node as parent of the PrimitiveCreate node
primNode.setParent(groupNode)

NodegraphAPI.GetViewPortPosition(node)

Get the view information of a group network. Each GroupNode also maintains view information for its child network. It is stored in this viewport. The return contains the eyepoint and the viewscale.

The default vewpoint is 0, 0, 10000

The default viewscale is 1, 1, 1

Returns:: the position and scale
Return type:: (int, int, int), (float, float, float)

NodegraphAPI.SetViewPortPosition(node, eyepoint, viewscale)

Set the view information for a group network. Each GroupNode also maintains view information for its child network. It is stored in this viewport. The return contains the eyepoint and the viewscale.

The default vewpoint is 0, 0, 10000

The default viewscale is 1, 1, 1

Send and Return Ports

For Group nodes to be of any significant use, you need to be able to connect their internal structure to the ports of external nodes. The quickest - in the short term - way of doing this is to directly connect a port on a node inside the group to a port on a node outside the group. To do this however, you need to know the internal structure of the Group node and be aware of the maintenance burden on the Python code that does the connecting. Any change to the internal structure of the group can mean the port connecting code needs updating.

A more encapsulated approach is to connect the internal ports to corresponding send or return ports on the Group node. If a Group node were a function in Python, the send ports would be the arguments and the return ports would the return values.

Note

The send and return ports on a Group node only exist if the group has inputs and outputs created. Creating an input or output port on a group automatically creates a send or return port with the same name. See Connecting Nodes for more on creating, and connecting inputs and outputs.

Return Ports

The advantage of send and return ports is that you can connect to them without any knowledge of the group’s internal structure. For example, create a Group containing a PrimitiveCreate node and a Merge node. Connect the output of the PrimitiveCreate node to the input of the Merge node, and connect the output of the Merge node to the return port of the Group node:

# Create the group at root level
rootNode = NodegraphAPI.GetRootNode()
groupNode = NodegraphAPI.CreateNode('Group', rootNode)
groupNode.addOutputPort("out")

# Create the PrimitiveCreate node at group level
primNode = NodegraphAPI.CreateNode('PrimitiveCreate', groupNode)

# Create a Merge nodes at group level
mergeNode = NodegraphAPI.CreateNode('Merge', groupNode)

# Connect PrimitiveCreate output to Merge input

# Get the out port of the PrimitiveCreate node
primOutPort = primNode.getOutputPort("out")
mergeSphereInPort = mergeNode.addInputPort('sphere')
primOutPort.connect(mergeSphereInPort)

# Get the groups Return port
# First create an output port on the group
groupOutPort = groupNode.addOutputPort("goingOut")
groupReturnPort = groupNode.getReturnPort("goingOut")

# Get the output port on the Merge node
mergeOutPort = mergeNode.getOutputPort("out")

# Connect the Merge node's out to the Group node's Return
mergeOutPort.connect(groupReturnPort)

Now you can connect the output of the Group node to external nodes without accessing its internal structure. For example, take the example above, and connect the output of the Group node to a new Merge node:

# Create a Merge node at root level
outerMergeNode = NodegraphAPI.CreateNode('Merge', root)

# Get the input port of the Merge node
outerMergeInPort = outerMergeNode.getInputPort('input')

# Connect the Group’s output to the Merge node's input
outerMergeInPort.connect(groupReturn)

Send Ports

The Group node created above does not take any inputs. For a group to accept inputs, it must have an input port linked to its send port. For example, create a group that merges geometry from a PrimitiveCreate node inside the group, with geometry from a PrimitiveCreate node outside the group:

# Create the group at root level
rootNode = NodegraphAPI.GetRootNode()
groupNode = NodegraphAPI.CreateNode('Group', rootNode)

# Create input and output on the group
groupNode.addInputPort("in")
groupNode.addOutputPort("out")

# Get the corresponding Send and Return ports
groupReturnPort = groupNode.getReturnPort("out")
groupSendPort = groupNode.getSendPort("in")

# Create a PrimitiveCreate node at group level
primNode = NodegraphAPI.CreateNode('PrimitiveCreate', groupNode)

# Get the output port on the PrimitiveCreate
primOutPort = primNode.getOutputPort("out")

# Create a merge node at group level
mergeNode = NodegraphAPI.CreateNode('Merge', groupNode)

# Add two inputs and get the output ports
mergeIn0Port = mergeNode.addInputPort("in0")
mergeIn1Port = mergeNode.addInputPort("in1")
mergeOutPort = mergeNode.getOutputPort("out")

# Connect the PrimitiveCreate out to Merge in0
mergeIn0Port.connect(primOutPort)

# Connect the Merge node to the Group inputs and outputs
mergeIn1Port.connect(groupSendPort)
mergeOutPort.connect(groupReturnPort)

Anything connected to the input of the Group node is now merged with the output of the PrimitiveCreate node contained in the group.

LiveGroups

NodegraphAPI.GetNodeModTime(node)

Get the modification time of the file loaded into a LiveGroup node. This attribute will only be set on LiveGroup nodes. All other nodes return 0.

Return type:: int

NodegraphAPI.SetNodeModTime(node, modTime)

Set the modification time of the file loaded into a LiveGroup node. This attribute should only be set on LiveGroup nodes.

Parameters:: modTime (int) – the new modification time

class NodegraphAPI.LiveGroup.LiveGroupNode

Bases: PythonGroupNode, LiveGroupMixin

Class representing a Group node whose contents are defined by a referenced external node graph file.

__init__(): Initializes an instance of the class.

addParameterHints(attrName, inputDict): Updates the given hints dictionary ‘inputDict’ for the given attribute name, updating the ‘LiveGroup.source’ parameter’s ‘widget’ hint accordingly to the source parameter’s asset or file type.

convertToGroup(): Converts the LiveGroup node to a Group node, keeping all child nodes and parameters except its source and disable parameters.

getGroupXmlIO()

Return type:: Document
Returns:: An XML document that represents the externally referenced file (including local internal modifications).

setAttributes(attrs)

Sets the node attributes to use for the LiveGroup node to the given attributes.

Parameters:: attrs (dict) – A dictionary of node attributes to set for the LiveGroup node.

setLocked(locked)

Overrides the default setLocked() implementation to update the locking of contents of the LiveGroup node after setting the locked state to the given locked state.

Parameters:: locked (bool) – Flag to control whether to lock or unlock the LiveGroup node to prevent or allow changes.

NodegraphAPI.LiveGroup.UpdateAllLiveGroupSources(oldSource, newSource)

Finds all LiveGroup nodes referencing the given oldSource file or asset and changes them to reference the given newSource file or asset.

Parameters:

oldSource (str) – The old filename or asset ID.
newSource (str) – The new filename or asset ID.

NodegraphAPI.LiveGroup.LoadAllLiveGroups(node, lockResult=False, forceLoad=False)

Loads all LiveGroup nodes from their sources starting from the specified node.

It is expected that LockAllLiveGroups() is called after loading all LiveGroup nodes.

Parameters:

node (NodegraphAPI.Node) – The node at which to start loading LiveGroup child nodes.
lockResult (bool) – Deprecated. Has no effect. This flag controlled whether to lock the nodes that have been loaded into the current Katana scene. Contents of loaded LiveGroup nodes are now locked by default.
forceLoad (bool) – Flag to control whether to force loading of LiveGroup nodes from their sources even if the sources have not been modified since they were last loaded according to the modification timestamp stored in an attribute on LiveGroup nodes in the node graph document. If the LiveGroup is disabled, forceLoad will not force it to load.

NodegraphAPI.LiveGroup.LockAllLiveGroups(node)

Locks the contents of all LiveGroup nodes that are non-editable, starting from the specified node.

Parameters:: node (NodegraphAPI.Node) – The node at which to start locking contents of LiveGroup nodes.

NodegraphAPI.LiveGroup.MakeAllLiveGroupsEditable(node)

Makes all LiveGroup nodes starting from the specified node editable.

Parameters:: node (NodegraphAPI.Node) – The node at which to start making the child nodes editable.

NodegraphAPI.LiveGroup.MakeAllParentLiveGroupsEditable(node)

Makes all parent LiveGroup nodes starting from the specified node editable.

Return type:: bool
Parameters:: node (NodegraphAPI.Node) – The node at which to start making the parent nodes editable.
Returns:: True if all parent LiveGroup nodes have successfully been made editable, otherwise False.

NodegraphAPI.LiveGroup.CanBeDifferentFromSource(liveGroupNode)

Return type:: bool
Parameters:: liveGroupNode (LiveGroupMixin) – The LiveGroup node to check.
Returns:: True if the given LiveGroup node has no source set for it, or if it can be different from a source that its parameters and contents are loaded from, otherwise False.
Raises:: TypeError – If the given object is not a LiveGroup node.

NodegraphAPI.LiveGroup.SetLiveGroupLoadingEnabled(state)

NodegraphAPI.LiveGroup.IsLiveGroupLoadingEnabled()

NodegraphAPI.LiveGroup.SetLiveGroupCachingEnabled(liveGroupCachingEnabled)

NodegraphAPI.LiveGroup.IsLiveGroupCachingEnabled()

NodegraphAPI.LiveGroup.ConvertGroupToLiveGroup(groupNode, startType, endType)

Converts a Group node to a LiveGroup node

Parameters:

groupNode (NodegraphAPI.Node) – The group node to be converted to it’s live group counterpart.
startType (str) – The type of the non-live group to be converted.
endType (str) – The live type the startType should be converted to.

NodegraphAPI.LiveGroup.CalculateLiveGroupDepth(liveGroupNode)

Return type:: int
Parameters:: liveGroupNode (NodegraphAPI.LiveGroupMixin or NodegraphAPI.Node) – The node for which to calculate the depth in the LiveGroup nodes hierarchy.
Returns:: The depth of the given LiveGroup node in the node graph taking into account LiveGroup nodes only. -1 if the given not is not a valid LiveGroup node.

class NodegraphAPI.LiveGroup.AssetPublishing

Bases: object

Class representing an asset publishing operation, storing details about an asset to publish, and allowing control over behavior of publishing assets with a set of flags.

Variables:

kAssetPublishingStarted – State indicating that the asset publishing operation has been started, but has not succeeded, failed, or been cancelled yet.
kAssetPublishingSucceeded – State indicating that the asset publishing operation has succeeded. The name of the published file or asset can be obtained using getPublishedFilenameOrAssetID().
kAssetPublishingCancelled – State indicating that the asset publishing operation has been cancelled.
kAssetPublishingFailed – State indicating that the asset publishing operation has failed. Details about a possible error can be obtained using getErrorMessage().

__init__(): Initializes an instance of the class.

errorMessageDialogsEnabled()

Return type:: bool
Returns:: True if error message dialogs are to be shown in case publishing an asset fails, or False to omit those dialogs.

getAssetType()

Return type:: str or None
Returns:: The name of the type of asset to publish, or None if no asset type has been set.

getErrorMessage()

Return type:: str or None
Returns:: An error message describing why asset publishing has failed, or None if no error message has been set.

getExtraOptions()

Return type:: dict
Returns:: A dictionary of extra options the user may have chosen when publishing the asset.

getFilenameOrAssetIdToPublish()

Return type:: str or None
Returns:: The name of the file or the ID of the asset to publish, or None if no filename or asset ID has been set.

getNodeName()

Return type:: str or None
Returns:: The name of the node from which to publish an asset, or None if no node name has been set.

getPublishedFilenameOrAssetID()

Return type:: str or None
Returns:: The name of the published file or the ID of the published asset, or None if no filename or asset ID of a published file or asset has been set.

getState()

Return type:: int
Returns:: The state of the asset publishing operation represented by an instance of the AssetPublishing class.

isErrorLoggingEnabled()

Return type:: bool
Returns:: True if error messages are to be logged when publishing an asset fails, or False to omit such messages.

isOverwriteAssetEnabled()

Return type:: bool
Returns:: True if an existing asset is to be overwritten without showing an asset browser dialog for the user to select an asset ID or filename, and without showing a confirmation dialog prior to overwriting the file, or False to show both.

isSuccessLoggingEnabled()

Return type:: bool
Returns:: True if informational messages are to be logged when successfully publishing an asset, or False to omit such messages.

kAssetPublishingCancelled = 2

kAssetPublishingFailed = 3

kAssetPublishingStarted = 0

kAssetPublishingSucceeded = 1

setAssetType(assetType)

Parameters:: assetType (str or None) – The name of the type of asset to publish, or None to reset the asset type.

setErrorLoggingEnabled(errorLoggingEnabled)

Sets the flag that controls whether error messages are logged when publishing an asset fails.

Parameters:: errorLoggingEnabled (bool) – True if error messages are to be logged when publishing an asset fails, or False to omit such messages.

setErrorMessage(errorMessage)

Parameters:: errorMessage (str or None) – An error message describing why asset publishing has failed, or None to reset the error message.

setErrorMessageDialogsEnabled(errorMessageDialogsEnabled)

Sets the flag that controls whether error message dialogs are to be shown in case publishing an asset fails.

Parameters:: errorMessageDialogsEnabled (bool) – True if error dialogs are to be shown in case publishing an asset fails, or False to omit those dialogs.

setExtraOptions(extraOptions)

Sets a dictionary of extra options the user may have chosen when publishing the asset.

Parameters:: extraOptions (dict) – The extra options to set.

setFilenameOrAssetIdToPublish(filenameOrAssetIdToPublish)

Parameters:: filenameOrAssetIdToPublish (str or None) – The name of the file or the ID of the asset to publish, or None to reset the filename or asset ID.

setNodeName(nodeName)

Parameters:: nodeName (str or None) – The name of the node from which to publish an asset, or None to reset the node name.

setOverwriteAssetEnabled(overwriteAssetEnabled)

Sets the flag that controls whether an existing asset is to be overwritten without showing dialogs for the user to select an asset ID or filename and to confirm the action.

Parameters:: overwriteAssetEnabled (bool) – True if no asset browser dialog and no overwrite confirmation dialog is to be shown when publishing an asset, or False to show both.

setPublishedFilenameOrAssetID(publishedFilenameOrAssetID)

Parameters:: publishedFilenameOrAssetID (str or None) – The name of the published file or the ID of the published asset, or None to reset the filename or asset ID of the published file or asset.

setState(state)

Parameters:: state (int) – The state of the asset publishing operation represented by an instance of the AssetPublishing class to set for the instance.

setSuccessLoggingEnabled(successLoggingEnabled)

Sets the flag that controls whether informational messages are logged when successfully publishing an asset.

Parameters:: successLoggingEnabled (bool) – True if informational messages are to be logged when successfully publishing an asset, or False to omit such messages.