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 Toxik 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:
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 Toxik by producing image files.
The function to do this is: render().
|
|
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
|
|
|
ExternalDepType
|
|
[ExternalDepType]
|
|
GroupNode
|
|
|
|
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: |
|
|
|
|
|
|
|
|
|
Composition
|
createComp(...)
Creates a new composition at the specified path. |
|
|
|
|
detachFileSequence(...)
Detaches the given image reader node or rendered results node from
its file sequence. |
|
|
|
|
enableChangeGroupNodeOverride(...)
This function provides a backdoor to be able to manipulate the
internal representation of group nodes for super tools that normally
prevent external agents to modify their innard nodes and the
connections between them. |
|
|
|
Composition
|
getComp(...)
Creates a Composition instance for the specified composition
path without opening any of its Graph
versions. |
|
|
str
|
|
(str,[str])
|
getFileSequence(...)
Gets the file sequence associated with an image reader or rendered
result node. |
|
|
tuple
|
getFileSequenceRange(...)
Gets the start frame and number of images in the file sequence
associated with an image reader or rendered result node. |
|
|
str
|
|
bool
|
isCompositionOpened(...)
Tests whether the specified composition is opened in the given mode
or simply opened, if a mode is not specified. |
|
|
|
Composition
|
openComp(...)
Creates a Composition instance for the specified composition
path and opens its working Graph
version in the specified mode. |
|
|
|
|
setFileSequence(...)
Sets the list of file paths associated with an image reader node or
rendered results node using the given sequence path. |
|
|
|
|
__package__ = 'autodesk_toxik' |
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:
|
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:
|
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:
- Returns: Node
- The new Node.
- Raises:
|
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:
|
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.
|
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.
|
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:
- Returns:
GroupNode
- The GroupNode.
- Raises:
|
|
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)
|
|
Removes a node from its parent group.
- Parameters:
|
getFirstConnectedOutput(node)
|
|
- Parameters:
- 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:
|
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).
|
|
Creates a new composition at the specified path. The working version
is created and opened in read-write mode.
- Parameters:
path (str) - If the path is not absolute, it is considered to be relative to
the root folder of the current project. Note: it is not
necessary to provide the file extension (.txcomposition), however
it is not an error to do so. - Returns: Composition
- The created composition.
- Raises:
GraphError - If the composition cannot be created (file already exists, invalid
composition name, wrong permissions, etc).
|
|
Detaches the given image reader node or rendered results node from its
file sequence. In other words, it clears the node's sequence path.
- Parameters:
node (Node) - Image reader node or rendered result node.
|
enableChangeGroupNodeOverride(...)
|
|
This function provides a backdoor to be able to manipulate the
internal representation of group nodes for super tools that normally
prevent external agents to modify their innard nodes and the connections
between them. Warning: Using this backdoor can result in unexpected
behaviors and crashes.
- Parameters:
enable (bool) - Whether to enable or disable the group node change override.
|
|
Creates a Composition instance for the specified composition path
without opening any of its Graph
versions.
- Parameters:
path (str) - If the given path is not absolute, it is considered to be
relative to the root folder of the current project. Note:
it is not necessary to provide the file extension
(.txcomposition), however it is not an error to do so. - Returns: Composition
- A Composition object for the specified composition
path.
- Raises:
GraphError - If the specified composition file doesn't exist.
|
- Returns:
str
- The composition role string.
|
|
Gets the file sequence associated with an image reader or rendered
result node.
Nodes that import images will do so using an image reader node,
which have special value inputs that specify where to find the content on
the filesystems.
Rendered result nodes point to their images similarly. You can use
this method to obtain the list of files from these nodes. Note that the
this method return two versions of the same list: the first, called a
sequence path, is a represention of a set of files in a single
string. For example:
mySeq[0:12].tif : mySeq0.tif to mySeq12.tif
mySeq[00:12].tif : mySeq00.tif to mySeq12.tif
mySeq[00:12,20].tif : mySeq00.tif to mySeq12.tif, and mySeq20.tif
mySeq[00:04|2].tif : mySeq00.tif, mySeq02.tif and mySeq04.tif
The second representation is a Python list with all the
files in order.
Note: Some rendered result nodes that result from snapshots do
not actually have an image sequence associated with them. In that case,
the getFileSequence() method returns a (None,
None) pair, and the setFileSequence() method raises an exception.
- Parameters:
node (Node) - Image reader node or rendered result node. - Returns:
(str,[str])
- A
tuple of sequence path, and the
list of the file paths associated with an image
reader node or rendered results node.
- Raises:
GraphError - If the given node is not an image reader or rendered result.
|
getFileSequenceRange(...)
|
|
Gets the start frame and number of images in the file sequence
associated with an image reader or rendered result node. Refer to getFileSequence for more information.
- Parameters:
node (Node) - Image reader node or rendered result node. - Returns:
tuple
- A (start frame, number of images)
tuple of
integers or a (None, None)
tuple if there's no file sequence set on the node.
- Raises:
GraphError - If the given node is not an image reader or rendered result.
|
- Returns:
str
- The footage composition role string.
|
|
Tests whether the specified composition is opened in the given mode or
simply opened, if a mode is not specified. More specifically it checks
whether the working version of the composition is opened.
- Parameters:
path (str) - Path of the composition to check. If the given path is not
absolute, it is considered to be relative to the root folder of
the current project. Note: it is not necessary to provide
the file extension (.txcomposition), however it is not an error
to do so.openMode - If this optional parameter is specified, the function returns
True only if the composition is opened in the given
mode. - Returns:
bool
- Whether the specified composition is opened, optionally in a
specific mode.
|
|
Creates a Composition instance for the specified composition path
and opens its working Graph version in the specified mode.
- Parameters:
path (str) - If the given path is not absolute, it is considered to be
relative to the root folder of the current project. Note:
it is not necessary to provide the file extension
(.txcomposition), however it is not an error to do so.readWrite (bool) - If this optional parameter is set to True (the
default), the working version is opened in read-write mode,
otherwise it is opened in read-only mode. - Returns: Composition
- A Composition object for the specified composition
path.
- Raises:
GraphError - If the composition cannot be opened (file doesn't exist, wrong
permissions, invalid composition, etc).
|
|
Sets the list of file paths associated with an image reader node or
rendered results node using the given sequence path.
- Parameters:
node (Node) - Image reader node or rendered result node.seqPath (str) - Sequence path. - Raises:
Exception - If the sequence path is not valid or empty. No check on the
presence of the files is made.
|