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: NodegraphAPI_cmodule.PythonGroupNode, NodegraphAPI.LiveGroup.LiveGroupMixin

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

Variables

ATTRIBUTES_TO_IGNORE – A list of names of node attributes that are removed from a LiveGroup node’s contents when exporting to file.

ATTRIBUTES_TO_IGNORE = ('selected', 'eyepointx', 'eyepointy', 'eyepointz', 'viewscalex', 'viewscaley', 'viewscalez', 'viewed', 'edited', 'autorenameallowed')
__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 B{source} and B{disable} parameters.

exportAsset(filenameOrAssetID, extraOptions=None)

Exports a LiveGroup node’s contents to the uncompressed XML file with the given name or to a file that corresponds to the given asset ID as determined by the current asset plug-in.

Return type

str

Parameters
  • filenameOrAssetID (str) – The name of the file to write, or the ID of an asset to write a file for. If a filename is given that does not have a ".livegroup" or ".katana" extension, the ".livegroup" extension is added to it.

  • extraOptions (dict or None) – A dictionary of extra arguments to pass to the createAssetAndPath() and postCreateAsset() functions of the current asset plug-in, if the given filenameOrAssetID is a valid asset ID.

Returns

The name of the file that was written, or the asset ID returned by the postCreateAsset() call of the current asset plug-in, if the given filenameOrAssetID is a valid asset ID.

Raises
  • ValueError – If no filename or asset ID is given.

  • Exception – If the LiveGroup node’s contents could not be retrieved.

  • RuntimeError – If an asset operation failed.

getGroupXmlIO()
Return type

Document

Returns

An XML document that represents the externally referenced file (including local internal modifications).

hasContentChanged()
Deprecated

This function is deprecated. Please use isModified() instead.

isModified()
Return type

bool

Returns

True if the LiveGroup node’s state indicates that its user parameters or contents have been modified, otherwise False.

load(lockResult=False, forceLoad=False, forceNonEditable=True)

Loads the currently referenced external file.

Parameters
  • lockResult (bool) – Deprecated. Has no effect. This flag controlled whether to lock the nodes that have been loaded into the LiveGroup node. Contents of loaded LiveGroup nodes are now locked by default.

  • forceLoad (bool) – Flag to control whether to force loading of the LiveGroup node’s source even if the source has not been modified since it was last loaded according to the modification timestamp stored in an attribute on the LiveGroup node in the node graph document.

  • forceNonEditable (bool) – Flag to control whether to force the LiveGroup node to be non-editable after loading.

makeEditable(includingAllParents=False)

Makes the LiveGroup node editable, allowing changes to its contents. Succeeds only if the LiveGroup node is not currently locked.

Return type

bool

Parameters

includingAllParents (bool) – Flag to control whether to recursively make all parent LiveGroup nodes editable as well.

Returns

True on success, False if the operation fails or if the LiveGrop node is locked.

publishAndLoadAsset(filenameOrAssetID=None, extraOptions=None)
Deprecated

This function is deprecated. Please use publishAssetAndFinishEditingContents() instead.

publishAsset(filenameOrAssetID=None, extraOptions=None)

Convenience function that calls exportAsset() with the given arguments, and that updates the LiveGroup node’s source parameter with the result of that function, unless an exception is raised.

Note that this function keeps an editable LiveGroup node in its editable state.

Return type

str

Parameters
  • filenameOrAssetID (str or None) – The name of the file to write, or the ID of an asset to write a file for. If empty or None, the LiveGroup node’s current source is used, if set.

  • extraOptions (dict or None) – See exportAsset().

Returns

The result of exportAsset().

Raises
  • ValueError – If no filename or asset ID is given, and no source is set for the LiveGroup node.

  • Exception – If the LiveGroup node’s contents could not be retrieved.

  • RuntimeError – If an asset operation failed.

publishAssetAndFinishEditingContents(filenameOrAssetID=None, extraOptions=None)

Convenience function that calls exportAsset() with the given arguments, that updates the LiveGroup node’s source parameter with the result of that function, and finishes editing of the LiveGroup’s contents, unless an exception is raised.

Return type

str

Parameters
  • filenameOrAssetID (str or None) – The name of the file to write, or the ID of an asset to write a file for. If empty or None, the LiveGroup node’s current source is used, if set.

  • extraOptions (dict or None) – See exportAsset().

Returns

The result of exportAsset().

Raises
  • ValueError – If no filename or asset ID is given, and no source is set for the LiveGroup node.

  • Exception – If the LiveGroup node’s contents could not be retrieved.

  • RuntimeError – If an asset operation failed.

reloadFromSource()

Reloads the LiveGroup node from its source on disk.

Logs an error and returns False if no source has been set for the LiveGroup node, as LiveGroup nodes without a source set cannot be reloaded from a source on disk.

Return type

bool

Returns

True if the LiveGroup node was successfully reloaded, otherwise False.

See

revertToSource()

revert()

Reverts the LiveGroup node to the state of the source on disk, or to the state of a freshly created LiveGroup node, if no source has been set yet.

Return type

bool

Returns

True if the LiveGroup node was successfully reverted, otherwise False.

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.

writeToAsset(filenameOrAssetID, extraOptions=None, reloadContent=True)
Deprecated

This function is deprecated. Please use exportAsset() instead.

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)

Converts a Group node to a LiveGroup node

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.