Package autodesk_toxik :: Module graph

Module graph

Graph module.

This module provides access to the tools and internals of a composition. You use it to access versions of a composition, create and delete nodes in a composition, make or remove connections between nodes, set dynamic values and set the input values of nodes. It also provides access to the metadata and rendered results of a composition.

Introduction

Every Composite composition is accessed through the Composition class. A composition is a container of one or more versions. One of the versions is labeled the Primary version, and is the one that external compositions should link to. One of the versions is labeled the Working version. This is the one that is opened with read/write access by default in the interactive application. However, any version can be edited, not just the Working version (although such a workflow is not recommended). Versions can be added, renamed, and removed. The only exception is the Working version, which cannot be removed.

Each version in a composition is in fact a graph (Graph class). A graph contains nodes (Node class). Some of these nodes are tool nodes (ToolNode class) which represent an instance of a specific plug-in tool (Tool class).

There are various other types of nodes which are deriving from the Node base class. The ToolNode is the one of greatest interest to Python script writers.

The other types of node classes, such as GroupNode, BoundaryNode and ValueNode, provide full access to the internals of the graph.

Nodes have input and output sockets (Socket base class). An Input socket of a node can be connected to an Output socket of another node, and vice-versa. An output socket can be connected to multiple input sockets, but the reverse is not true (i.e. an input socket can accept a connection from only one output socket).

Sockets are all described by a SocketSpec description (available from the Tool). A socket has:

a name: set by the tool to identify the socket.
a layout: single-valued, multi-valued or structured.
a direction: input or output.
a lifescope: static or dynamic; a dynamic lifescope means that the socket was added dynamically after the node was created.
a data type that describes the kind of data that flows through that socket when the graph is processed; the input and outputs of connected sockets must have a matching data type.

In addition, input sockets can be further described by an InputPolicy object that declares some constraints on the input socket.

There are three possible layouts of input sockets:

single-valued sockets (SingleInput): a simple socket that accepts a single connection;
multi-valued sockets (MultiInput): a variable-size vector of sockets of the same data type;
structured sockets (StructuredInput): a container of other sockets, where each contained socket has an associated name.

Special value nodes are connected to inputs to simple values. Thus an input socket can be connected to one of the following:

a value node network that feeds a constant value (ConnectState.CONSTANT);
a value node network that feeds an animated value (ConnectState.ANIMATED);
a value node network that feeds values computed from an expression (ConnectState.EXPRESSION);
the output of another processing tool node (ConnectState.OTHER).

From the Python interface, you manipulate the input socket value node networks by using methods on the input sockets themselves. An input socket has connection states as described above.

Nodes can also have static (non-animated) dynamic values (Value class) associated with them. Dynamic values can be added and removed, and have values set to them analogously as input sockets.

Note that all objects in the graph (nodes, sockets, values, etc) have a unique ID which can be used to identify that object within the graph.

Rendering

Rendering is the action of making available the final result of a version outside of Composite by producing image files.

The function to do this is: render().

Functions

render(comp_or_graph, outputNames=[], renderSettings=None, startLimit=None, endLimit=None, progressCallback=None)
Renders the specified outputs of the version (composition graph) in parallel.

renderPreparedOutputs(comp_or_graph, outputNames, startLimit=None, endLimit=None, progressCallback=None)
Perform rendering on outputs already prepared for rendering: similar to render() but omits the rendering preparation and subsequent update, which must be done elsewhere.

str

uniqueName(comp_or_graph_or_group, strtemplate)
Convenience function that finds a unique node name.

tuple

createOrOpenComp(compPath, overwrite=False, readWrite=True)
Creates or opens (if it already exists) a composition at the specified path.

Node

createNode(comp_or_graph_or_group, toolname, newname=None)
Convenience function that creates and adds a new node in the specified Composition opened version, Graph version, or GroupNode, for the specified tool name.

Node

createNodeFromPreset(compOrGraphOrGroup, presetFilePath, nodeName=None)
Convenience function that creates and adds a new node instantiated from the given tool preset in the specified Composition opened version, Graph version, or GroupNode.

[Node]

createNodes(graph, typenames)
Convenience function that creates a list of nodes within a composition graph (version).

[Node]

createNodesPipeline(graph, typenames, startsock=None, endsock=None)
Convenience function that creates a connected pipeline of nodes within a composition graph (version), to chain image data.

Composition

createSingleFilter(newcompname, typenames, incomp=None)
Convenience function that creates a new composition with a list of filter nodes and optionally binds the output of another composition to the first input of the first node.

[GroupNode]

filterToolNodes(nodelist, toolnames)
Convenience function that filters a toolnodes list to a subset of tools.

[str]

getExternalDepTypeNames()
Returns: A list of all external dependency type names (except graph.ExternalDepType.ALL_TYPES).

str

getExternalDepTypeName(extDepTypeValue)
Converts a graph.ExternalDepType value to a string.

ExternalDepType

getExternalDepTypeValue(extDepTypeName)
Converts a string to a graph.ExternalDepType value.

[ExternalDepType]

externalDepTypeMaskToList(extDepTypeMask)
Converts a binary OR combination of graph.ExternalDepType values into a list of specific graph.ExternalDepType values.

GroupNode

addLinkNodeToGroup(self, comp_or_graph)
Add a link node in this group.

connect(*args)
If called with 4 arguments, they are interpreted positionally as node1, outputSocketName, node2, and inputSocketName, respectively.

setOutputNodeAsPrimary(outputNode, asPrimary=True)
Sets the image format, pixel format and time values of the given output node to be as the primary output node (or not).

removeNode(node)
Removes a node from its parent group.

Output

getFirstConnectedOutput(node)
Returns: An output socket from the given node that is connected; the first one that's encountered.

Output

getFirstConnectedOrPrimaryImageOutput(node)
Returns: An output socket from the given node that is connected; the first one that's encountered or the primary image output if the node doesn't have any connected output or None if the node doesn't have an image output.

replicateOutputConnections(srcOutput, destOutput)
Connects every inputs connected to the source output srcOutput to the destination output destOutput.

replicatePrimaryOutputConnections(srcNode, destNode)
Connects every inputs connected to the primary/first image output of srcNode to the primary/first image output of destNode.

tuple

LinkNode_getTimeParams(self, linkNodeOutput=None)
Gets the following time parameters from the link node for the given output:

Function Details

render(comp_or_graph, outputNames=[], renderSettings=None, startLimit=None, endLimit=None, progressCallback=None)

Renders the specified outputs of the version (composition graph) in parallel. If the first argument is a composition, the open version of the composition will be rendered.

This function performs all three steps required in a complete render operation:

Set up rendering: sets persistent rendering parameters on the outputs for the render.
Perform rendering: creates and runs a render job for the outputs.
Update rendered results: stores the rendered result parameters on the output for the just-completed render.

To perform rendering setup and update, the version must be opened in read-write mode.

startLimit (inclusive) and endLimit (exclusive) constrain the frames that will be rendered; either can be omitted. The stored rendered result parameters will contain start and end frames from the output, but only those within [startLimit, endLimit[ will actually be rendered.

This process is synchronous; i.e. the function does not return until processing is complete.

Parameters:

comp_or_graph (Composition or Graph)
outputNames (list) - A list of output names to render. If left empty, all render enabled outputs will be rendered according to their respective render modes.
renderSettings (tuple) - Overrides render settings. If specified, this parameter must be a list the same size and order as outputNames: it dictates a set of render settings for each specified outputs. Each item in renderSettings must be a tuple with the following information:
```
   (filePathPattern, fileFormatName, fileFormatOptions)
```
filePathPattern is the file path pattern used for the rendered files which can contain special tokens that will be substitued.

fileFormatName is the name of the rendered files format.

fileFormatOptions is an xml string representing the file format options.

Any of the previous render setting override can be set to None, in which case it is dictated by the render settings of the output.
startLimit (int)
endLimit (int)
progressCallback (callable) - If a progressCallback function is specified, it will be called after rendering each frame to indicate progress. It is called in the same thread with two integers: complete, total. Returning True from the progress callback will cancel any further rendering (returning any other value does nothing).

Raises:

RuntimeError - If the first parameter is not a Composition or Graph.

renderPreparedOutputs(comp_or_graph, outputNames, startLimit=None, endLimit=None, progressCallback=None)

Perform rendering on outputs already prepared for rendering: similar to render() but omits the rendering preparation and subsequent update, which must be done elsewhere.

Used in background rendering, where preparation is done by the foreground part of the render, the render job in the background (using this function), and the update in the foreground.

Parameters:

comp_or_graph (Composition or Graph)
outputNames (list) - A list of output names to render. If left empty, all render enabled outputs will be rendered according to their respective render modes.
startLimit (int)
endLimit (int)
progressCallback (callable) - If a progressCallback function is specified, it will be called after rendering each frame to indicate progress. It is called in the same thread with two integers: complete, total. Returning True from the progress callback will cancel any further rendering (returning any other value does nothing).

Raises:

RuntimeError - If the first parameter is not a Composition or Graph.

uniqueName(comp_or_graph_or_group, strtemplate)

Convenience function that finds a unique node name.

Parameters:

comp_or_graph_or_group (Composition, Graph or GroupNode) - This parameter can be a Composition, in which case the opened version (composition graph) will be used. It can also be a Graph version as well as a GroupNode.
strtemplate (str) - The strtemplate must be a string that contains a '%d' string pattern where a varying number is to be added.

Returns: str

A unique node name.

Raises:

RuntimeError - If one of the given parameters is invalid.

createOrOpenComp(compPath, overwrite=False, readWrite=True)

Creates or opens (if it already exists) a composition at the specified path.

If the path is not absolute, it is considered to be relative to the root folder of the current project. The folder hierarchy to the composition is created as well.

If the composition already exists and overwrite is set to True, it is deleted and a new composition is created.

If the composition already exists and is opened, readWrite indicates whether it's opened in read-only or read-write. A composition that's created is always opened in read-write.

Parameters:

compPath (str) - Path for the composition.
overwrite (bool)
readWrite (bool)

Returns: tuple

A tuple with the composition (with its working version opened in read-write) and a bool indicating if the composition was just created (Composition, bool).

Raises:

RuntimeError - If the specified component is not a composition.

createNode(comp_or_graph_or_group, toolname, newname=None)

Convenience function that creates and adds a new node in the specified Composition opened version, Graph version, or GroupNode, for the specified tool name. An optional argument can specify the node name.

Parameters:

comp_or_graph_or_group (Composition, Graph or GroupNode)
toolname (str)
newname (str)

Returns: Node

The new Node.

Raises:

RuntimeError - If the first parameter is not a Composition, Graph or GroupNode.

createNodeFromPreset(compOrGraphOrGroup, presetFilePath, nodeName=None)

Convenience function that creates and adds a new node instantiated from the given tool preset in the specified Composition opened version, Graph version, or GroupNode. An optional argument can specify the node name.

Parameters:

compOrGraphOrGroup (Composition, Graph or GroupNode) - Composition, graph or group node to add the new node into.
presetFilePath (str) - Absolute path to the ".txpreset" tool preset file to load.
nodeName (str) - Name of the new node.

Returns: Node

The new Node.

Raises:

TypeError - If the first parameter is not a Composition, Graph or GroupNode.
GraphError - The tool preset file cannot be loaded.

createNodes(graph, typenames)

Convenience function that creates a list of nodes within a composition graph (version).

Parameters:

graph (Graph)
typenames (str or list) - The typenames can be either of:
- A string: the tool name of a single node to be created.
- A list of pairs (tuples): a list of tool names of nodes to be created (order matters). Each list element can also be just a string, where a simple name will be given to the node.

Returns: [Node]

The list of the created nodes.

createNodesPipeline(graph, typenames, startsock=None, endsock=None)

Convenience function that creates a connected pipeline of nodes within a composition graph (version), to chain image data. Optional start output and/or end input to connect the first and/or last node to can be provided.

This code assumes that each node has an output of type image and a primary input of type image as well.

Parameters:

graph (Graph)
typenames (str or list) - The typenames can be either of:
- A string: the tool name of a single node to be created.
- A list of pairs (tuples): a list of tool names of nodes to be created (order matters). Each list element can also be just a string, where a simple name will be given to the node.
startsock (Socket)
endsock (Socket)

Returns: [Node]

The list of the created nodes.

createSingleFilter(newcompname, typenames, incomp=None)

Convenience function that creates a new composition with a list of filter nodes and optionally binds the output of another composition to the first input of the first node.

Parameters:

newcompname (str) - New composition name.
typenames - The typenames can be either of:
- A string: the tool name of a single node to be created.
- A list of pairs (tuples): a list of tool names of nodes to be created (order matters). Each list element can also be just a string, where a simple name will be given to the node.
incomp (Composition)

Returns: Composition

The new composition.

See Also: The function createNodesPipeline() for more details.

filterToolNodes(nodelist, toolnames)

Convenience function that filters a toolnodes list to a subset of tools.

Parameters:

nodelist (list of GroupNode) - List of tool nodes.
toolnames (str or a list of str)

Returns: [GroupNode]

The list of filtered tool nodes.

getExternalDepTypeNames()

Returns: [str]: A list of all external dependency type names (except graph.ExternalDepType.ALL_TYPES).

getExternalDepTypeName(extDepTypeValue)

Converts a graph.ExternalDepType value to a string.

Parameters:

extDepTypeValue (ExternalDepType) - The external dependency type to convert.

Returns: str

The converted graph.ExternalDepType value (str).

Raises:

RuntimeError - If the given external dependency type is unknown.

getExternalDepTypeValue(extDepTypeName)

Converts a string to a graph.ExternalDepType value.

Parameters:

extDepTypeName (str) - The external dependency name to convert.

Returns: ExternalDepType

The converted str (ExternalDepType).

Raises:

RuntimeError - If the given external dependency name is unknown.

externalDepTypeMaskToList(extDepTypeMask)

Converts a binary OR combination of graph.ExternalDepType values into a list of specific graph.ExternalDepType values. Note that graph.ExternalDepType.ALL_TYPES is never in the returned list.

Parameters:

extDepTypeMask (int)

Returns: [ExternalDepType]

A list of ExternalDepType.

addLinkNodeToGroup(self, comp_or_graph)

Add a link node in this group. If the argument is a composition, connect the link node to the primary version of an external composition. If the argument is a version (composition graph), connect the link node to that version.

Parameters:

comp_or_graph (Composition or Graph)

Returns: GroupNode

The GroupNode.

Raises:

RuntimeError - If the first parameter is not a Composition or Graph.

connect(*args)

If called with 4 arguments, they are interpreted positionally as node1, outputSocketName, node2, and inputSocketName, respectively. Connects the outputSocketName of node1 with the inputSocketName of node2. An exception is raised if there are no or more than a single socket with the given name, or if the connect fails for some other reason.

If called with 3 arguments, they are interpreted positionally as comp_or_graph, node, inputSocketName. Links the primary output of comp_or_graph to the inputSocketName of node. If the first argument is a Composition, the primary version will be used. If the first argument is a version (composition graph), connect the image output of version comp_or_graph to the input socket inputSocketName of node2.

Raises:

RuntimeError - If invalid arguments were specified.

setOutputNodeAsPrimary(outputNode, asPrimary=True)

Sets the image format, pixel format and time values of the given output node to be as the primary output node (or not).

Parameters:

outputNode (Node)
asPrimary (bool)

removeNode(node)

Removes a node from its parent group.

Parameters:

node (Node)

getFirstConnectedOutput(node)

Parameters:

node (Node)

Returns: Output

An output socket from the given node that is connected; the first one that's encountered. Returns None if the node doesn't have any connected output.

getFirstConnectedOrPrimaryImageOutput(node)

Returns: Output: An output socket from the given node that is connected; the first one that's encountered or the primary image output if the node doesn't have any connected output or None if the node doesn't have an image output.

replicateOutputConnections(srcOutput, destOutput)

Connects every inputs connected to the source output srcOutput to the destination output destOutput. Of course, unless the inputs are MultiInput, connections to the source output will be broken.

Parameters:

srcOutput (Output) - Source output.
destOutput (Output) - Destination output.

replicatePrimaryOutputConnections(srcNode, destNode)

Connects every inputs connected to the primary/first image output of srcNode to the primary/first image output of destNode.

Parameters:

srcNode (Node)
destNode (Node)

See Also: replicateOutputConnections() for more details.

LinkNode_getTimeParams(self, linkNodeOutput=None)

Gets the following time parameters from the link node for the given output:

Mark In (integer)
Mark Out (integer; exclusive)
Time Offset (integer)
Repeat Mode (graph.RepeatMode)
Lock Duration (bool)

Parameters:

linkNodeOutput (Output) - The link node output to get the time parameters from. If set to None, the primary output is used.

Returns: tuple

A tuple containing the link node time information as follow: (markIn, markOut, timeOffset, repeatMode, lockDuration).