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, 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 source and 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 will be removed. 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 will be removed. 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 will be removed. 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.