Package autodesk_toxik :: Module graph :: Class Composition
[frames] | no frames]

Class Composition

 object --+    
          |    
Boost.Python.instance --+
              |
             Composition

Manages versions, provides a proxy API on an opened version, and encapsulates the composition meta-data.

A Composition instance cannot be created using its constructor; it must be obtained from one of the following factory functions: getComp, openComp or createComp.

A Toxik composition is a container of graph versions. The Python Composition class wrapper is used to access and manage composition versions. As a convenience, the Composition class wrapper provides proxy access to one open version. Use of this single-version proxy API in Composition, and opening one version through the Composition API to enable it, is optional. The fully-featured Graph class, which represents a version, is more complete, and allows multiple versions to be opened simultaneously. Instances of Graph are obtained through the version management API of Composition. The Composition single-version proxy API is convenient to simply open the working version and access or modify it, which is a frequent use case.

In Toxik, a composition is not opened, so there is no read-only versus read-write distinction to make on a composition: all compositions are editable, i.e. read-write. Composition versions (Graph class) are the entities that are opened, so correspondingly read-only and read-write open modes must be specified when opening a version.

An OpenMode enumeration class defined at module level is provided for to define read-only and read-write open modes:

Version proxy API

If a version is held opened by the composition, the following functions are available to access and modify it. If no version is held opened by the composition, these functions will raise an exception. They are identical in name and semantics to those in the Graph class:

Instance Methods
 
__cmp__(...)
 
__init__(...)
Raises an exception This class cannot be instantiated from Python
 
__reduce__(...)
helper for pickle
 
closeVersion(...)
If a version is held opened by the composition, it is closed.
Graph
createAndOpenEmptyVersion(...)
Creates a new empty version and opens it in the given mode.
Graph
createAndOpenVersion(...)
Creates a new version from the working version or the version specified by fromVersionName and opens it in the given mode.
 
createEmptyVersion(...)
Creates a new empty version.
 
createVersion(...)
Creates a new version from the working version or the version specified by fromVersionName.
str
evaluateNextVersionName(...)
Returns: The name of the next version that would be generated from the version given as argument, using the project version naming convention.
Output
findOutput(...)
Returns: The socket matching the argument socket ID in the opened composition version.
[Node]
getAllNodes(...)
Returns: A list of all the nodes in the opened composition version, regardless of the group level.
int
getComponents(...)
Returns: The number of components in the images of the primary output node (if no outputName argument is specified) or of the named output node.
int
getDepth(...)
Returns: The bit depth of each channel of the image for the primary output node (if no outputName argument is specified) or the named output node.
str
getDescription(...)
Returns: The description (comment) of the composition.
int
getDuration(...)
Returns: Number of frames (int) in the primary output node or the named output node.
int
getEnd(...)
Returns: The end time index of the primary output node or the named output node.
[str]
getExternalDependencies(...)
Returns: The external dependencies of all versions as a list of absolute paths (str) to the external files.
str
getFileFormat(...)
Returns: The name of the image file format that will be used to produce images when rendering (e.g.: exr, tga, ...)
str
getFileFormatOptions(...)
Returns: File format options (in the form of an XML string) for the file format specified with 'getFileFormat'
str
getFileName(...)
Returns: File format options (in the form of an XML string) for the file format specified with 'getFileFormat'
GroupNode
getGroup(...)
Returns: The topmost group node of the opened version.
int
getHeight(...)
Returns: Height of the images produced by the primary output node (if no output name argument is specified), or the named output node.
str
getId(...)
Returns: The composition uuid string.
tuple
getImageRatio(...)
Returns: The image ratio (width/height ratio taking the pixel ratio into account) as a (numerator, denominator) tuple (2 integers) for the primary output node or a named output node.
Graph
getLatestVersion(...)
Returns: The latest version (an object of type Graph) opened in the specified mode (read-write by default).
str
getLatestVersionPath(...)
Returns: The path of the latest version.
int
getMarkIn(...)
Returns: The opened composition version mark in.
int
getMarkOut(...)
Returns: The opened composition version mark out.
str
getName(...)
Returns: The name of the composition.
int
getNextVersionNumber(...)
Returns: The version number of the next version.
Node
getNodeById(...)
Returns: The Node corresponding to the argument nodeId in the opened composition version.
[Node]
getNodesByTool(...)
Returns: A list of all the tool nodes (ToolNode) or super tool group nodes (GroupNode) matching the specified Tool or tool name in the opened composition version, regardless of the group level.
 
getOpenVersion(...)
If a version is held opened by the composition, return it (object of type Graph).
[GroupNode]
getOutputNodes(...)
Returns: The list of output nodes (GroupNode) in the opened composition version.
str
getPaintStrokesFolder(...)
Returns: The absolute path (str) to the folder containing paint strokes files for the opened composition version.
str
getPath(...)
Returns: The path of the composition.
tuple
getPixelRatio(...)
Returns: The pixel aspect ratio of the image for the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) tuple.
GroupNode
getPrimaryOutputNode(...)
Returns: The primary output node (GroupNode) of the opened composition version.
Input
getPrimaryOutputNodeInput(...)
Returns: The input socket (Input) of the primary output node of the opened composition version.
Graph
getPrimaryVersion(...)
Returns: The primary version (an object of type Graph) opened in the specified mode (read-write by default).
str
getPrimaryVersionPath(...)
Returns: The path (str) of the primary version.
tuple
getRate(...)
Returns: The frame rate of the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) integer tuple.
bool
getRenderEnabled(...)
Returns: True if rendering is enabled on the primary output node or the named output node.
[Node]
getRenderedResults(...)
Returns: A list of rendered result nodes for the opened composition version.
RepeatMode
getRepeatMode(...)
Returns: The opened composition version repeat mode as a module-level RepeatMode class enumeration member.
str
getRole(...)
Returns: The role (str) of the opened composition version.
List of Node.
getSelectedNodes(...)
Returns: The nodes from the opened composition version that are selected in the Toxik UI.
str
getSource(...)
Returns: The source of the opened composition version.
int
getStart(...)
Returns: The start time index of the primary output node or the named output node.
[Node]
getToolNodes(...)
Returns: A list of all the tool nodes (ToolNode) or super tool group nodes (GroupNode) in the opened composition version, regardless of the group level.
Graph
getVersion(...)
Given a version name string, returns the version (an object of type Graph) opened in the specified mode (read-write by default).
str
getVersionFolder(...)
Returns: The absolute path (str) to the folder containing version files for this composition.
[str]
getVersionNames(...)
Returns: A list of the version name strings.
int
getVersionNumber(...)
Returns: The version number associated with a named version.
int
getWidth(...)
Returns: Width of the images produced by the primary output node (if no outputName argument is specified), or the named output node.
str
getWiretapClipName(...)
Returns: Pattern for the wiretap clip name (i.e.
bool
getWiretapEnabled(...)
Returns: Boolean indicating whether rendering will export to wiretap.
str
getWiretapPath(...)
Returns: Path where the wiretap clip will be created when rendering.
Graph
getWorkingVersion(...)
Returns: The working version (an object of type Graph) opened in the specified mode (read-write by default).
 
openVersion(...)
Opens and returns the version given by the argument name in the specified mode (read-write by default).
 
relocateExternalDependencies(...)
Relocates certain types of external dependencies in all versions of the composition.
 
removeVersion(...)
Removes the named version.
 
renameVersion(...)
Renames a version.
 
revertToDefault(...)
Reverts the opened composition version to its default initial state; an empty graph with default settings and no external dependencies (paint strokes).
 
revertToGraph(...)
Reverts the opened composition version to the given Graph.
 
revertWorkingTo(...)
Removes the working version to the named version.
 
setComponents(...)
Sets the number of components in the images of the primary output node (if no outputName argument is specified) or the named output node.
 
setDepth(...)
Sets the bit depth of each channel of the image for the primary output node (if no outputName argument is specified) or the named output node.
 
setDescription(...)
Sets the description (comment) of the composition.
 
setEnd(...)
Sets the end time index of the primary output node or the named output node.
 
setFileFormat(...)
Sets the file format to be used when rendering to files.
 
setFileFormatOptions(...)
Sets the xml file format options to be used when rendering to files.
 
setFileName(...)
Sets the file name pattern to be used when creating image files while rendeing.
 
setHeight(...)
Sets the height of the images produced by the primary output node (if no output name argument is specified), or the named output node.
 
setImageRatio(...)
Sets image ratio (width/height ratio taking the pixel ratio into account) as a (numerator, denominator) tuple (2 integers) for the primary output node (if outputName is unspecified) or a named output node.
 
setMarkIn(...)
Sets the opened composition version mark in frame index.
 
setMarkOut(...)
Sets the opened composition version mark out frame index.
 
setPixelRatio(...)
Sets pixel aspect ratio of the image for the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) tuple.
 
setPrimaryOutputNode(...)
Sets the primary output node of the opened composition version to the given output node.
 
setPrimaryVersion(...)
Sets the primary version to be the one with the argument name.
 
setRate(...)
Sets the frame rate of the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) integer tuple.
 
setRenderEnabled(...)
Sets whether rendering is enabled on the primary output node or the named output node.
 
setRepeatMode(...)
Sets the opened composition version repeat mode.
 
setRole(...)
Sets the role of the opened composition version.
 
setSource(...)
Sets the source of the opened composition version.
 
setStart(...)
Sets the start time index of the primary output node or the named output node.
 
setWidth(...)
Sets the width of the images produced by the primary output node (if no output name argument is specified), or the named output node.
 
setWiretapClipName(...)
Sets the wiretap clip name pattern to use when rendering into a wiretap clip.
 
setWiretapEnabled(...)
Sets whether rendering into a wiretap clip is enabled on the primary output node or the named output node.
 
setWiretapPath(...)
Sets the wiretap path to use when rendering into a wiretap clip.

Inherited from Boost.Python.instance: __new__

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Static Methods
str
getActualFilePath(...)
Adds the composition file extension to the specified name or path if not already present.
Properties

Inherited from object: __class__

Method Details

__init__(...)
(Constructor)

 

Raises an exception This class cannot be instantiated from Python

Overrides: object.__init__

__reduce__(...)

 

helper for pickle

Overrides: object.__reduce__
(inherited documentation)

createAndOpenEmptyVersion(...)

 

Creates a new empty version and opens it in the given mode. The version is named using the naming convention of the current project or the given name newVersionName.

Parameters:
Returns: Graph
The version, opened in the given mode.

createAndOpenVersion(...)

 

Creates a new version from the working version or the version specified by fromVersionName and opens it in the given mode. The version is named using the naming convention of the current project or given name newVersionName.

Parameters:
  • openMode (OpenMode) - Open mode. Defaults to OpenMode.READ_WRITE.
  • newVersionName (str) - Optional new version name.
  • fromVersionName (str) - Optional source version name.
Returns: Graph
The version, opened in read-write.

createEmptyVersion(...)

 

Creates a new empty version. The version is named using the naming convention of the current project or the given name newVersionName.

Parameters:
  • newVersionName (str) - Optional version name.

createVersion(...)

 

Creates a new version from the working version or the version specified by fromVersionName. The version is named using the naming convention of the current project or given name newVersionName.

Parameters:
  • newVersionName (str) - Optional new version name.
  • fromVersionName (str) - Optional source version name.

evaluateNextVersionName(...)

 
Parameters:
  • fromVersionName ()
Returns: str
The name of the next version that would be generated from the version given as argument, using the project version naming convention.

findOutput(...)

 
Parameters:
  • socketId (int)
Returns: Output
The socket matching the argument socket ID in the opened composition version.

getActualFilePath(...)
Static Method

 

Adds the composition file extension to the specified name or path if not already present.

Parameters:
  • path (str) - The name or path of the composition (with or without the file extension).
Returns: str
The actual file path of the given composition name/path.

getAllNodes(...)

 
Returns: [Node]
A list of all the nodes in the opened composition version, regardless of the group level.

getComponents(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: int
The number of components in the images of the primary output node (if no outputName argument is specified) or of the named output node.

getDepth(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: int
The bit depth of each channel of the image for the primary output node (if no outputName argument is specified) or the named output node.

getDescription(...)

 
Returns: str
The description (comment) of the composition.

getDuration(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: int
Number of frames (int) in the primary output node or the named output node.

getEnd(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: int
The end time index of the primary output node or the named output node.

getExternalDependencies(...)

 
Parameters:
Returns: [str]
The external dependencies of all versions as a list of absolute paths (str) to the external files.

getFileFormat(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: str
The name of the image file format that will be used to produce images when rendering (e.g.: exr, tga, ...)

getFileFormatOptions(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: str
File format options (in the form of an XML string) for the file format specified with 'getFileFormat'

getFileName(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: str
File format options (in the form of an XML string) for the file format specified with 'getFileFormat'

getGroup(...)

 
Returns: GroupNode
The topmost group node of the opened version.

getHeight(...)

 
Parameters:
  • outputName (str) - Optional string specifying the output name.
Returns: int
Height of the images produced by the primary output node (if no output name argument is specified), or the named output node.

getId(...)

 
Returns: str
The composition uuid string.

getImageRatio(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: tuple
The image ratio (width/height ratio taking the pixel ratio into account) as a (numerator, denominator) tuple (2 integers) for the primary output node or a named output node.

getLatestVersion(...)

 
Parameters:
Returns: Graph
The latest version (an object of type Graph) opened in the specified mode (read-write by default).

getLatestVersionPath(...)

 
Returns: str
The path of the latest version.

getMarkIn(...)

 
Returns: int
The opened composition version mark in.

getMarkOut(...)

 
Returns: int
The opened composition version mark out.

getName(...)

 
Returns: str
The name of the composition.

getNextVersionNumber(...)

 
Parameters:
  • name () - The version name.
Returns: int
The version number of the next version.

getNodeById(...)

 
Parameters:
  • nodeId (int)
Returns: Node
The Node corresponding to the argument nodeId in the opened composition version. If no such node exists, returns None.

getNodesByTool(...)

 
Parameters:
  • tool (Tool or str) - Tool or tool name.
Returns: [Node]
A list of all the tool nodes (ToolNode) or super tool group nodes (GroupNode) matching the specified Tool or tool name in the opened composition version, regardless of the group level.

getOpenVersion(...)

 

If a version is held opened by the composition, return it (object of type Graph). If no version is open, returns None.

getOutputNodes(...)

 
Returns: [GroupNode]
The list of output nodes (GroupNode) in the opened composition version.

getPaintStrokesFolder(...)

 
Returns: str
The absolute path (str) to the folder containing paint strokes files for the opened composition version.

getPath(...)

 
Returns: str
The path of the composition.

getPixelRatio(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: tuple
The pixel aspect ratio of the image for the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) tuple.

getPrimaryOutputNode(...)

 
Returns: GroupNode
The primary output node (GroupNode) of the opened composition version.

getPrimaryOutputNodeInput(...)

 
Returns: Input
The input socket (Input) of the primary output node of the opened composition version.

getPrimaryVersion(...)

 
Parameters:
Returns: Graph
The primary version (an object of type Graph) opened in the specified mode (read-write by default).

getPrimaryVersionPath(...)

 
Returns: str
The path (str) of the primary version.

getRate(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: tuple
The frame rate of the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) integer tuple.

getRenderEnabled(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: bool
True if rendering is enabled on the primary output node or the named output node.

getRenderedResults(...)

 
Returns: [Node]
A list of rendered result nodes for the opened composition version.

getRepeatMode(...)

 
Returns: RepeatMode
The opened composition version repeat mode as a module-level RepeatMode class enumeration member.

getRole(...)

 
Returns: str
The role (str) of the opened composition version.

See Also: setRole()

getSelectedNodes(...)

 
Returns: List of Node.
The nodes from the opened composition version that are selected in the Toxik UI. The returned list is empty if nodes are not selected or if there's no Toxik UI.

getSource(...)

 
Returns: str
The source of the opened composition version.

See Also: setSource()

getStart(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: int
The start time index of the primary output node or the named output node.

getToolNodes(...)

 
Returns: [Node]
A list of all the tool nodes (ToolNode) or super tool group nodes (GroupNode) in the opened composition version, regardless of the group level. This is a subset of the list returned by getAllNodes().

getVersion(...)

 

Given a version name string, returns the version (an object of type Graph) opened in the specified mode (read-write by default).

Parameters:
Returns: Graph
The version, opened in read-write.

getVersionFolder(...)

 
Returns: str
The absolute path (str) to the folder containing version files for this composition.

getVersionNames(...)

 
Returns: [str]
A list of the version name strings.

getVersionNumber(...)

 
Returns: int
The version number associated with a named version.

getWidth(...)

 
Parameters:
  • outputName (str) - Optional string specifying the output name.
Returns: int
Width of the images produced by the primary output node (if no outputName argument is specified), or the named output node.

getWiretapClipName(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: str
Pattern for the wiretap clip name (i.e. including substitutions) that will be produced when rendering. Only used if wiretap is enabled for this output.

getWiretapEnabled(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: bool
Boolean indicating whether rendering will export to wiretap.

getWiretapPath(...)

 
Parameters:
  • outputName (str) - Optional argument specifying the output name.
Returns: str
Path where the wiretap clip will be created when rendering. Only used if wiretap is enabled for this output.

getWorkingVersion(...)

 
Parameters:
Returns: Graph
The working version (an object of type Graph) opened in the specified mode (read-write by default).

openVersion(...)

 

Opens and returns the version given by the argument name in the specified mode (read-write by default). If another version was previously opened by the composition, it is closed.

Parameters:

relocateExternalDependencies(...)

 

Relocates certain types of external dependencies in all versions of the composition.

For each external dependency files matching the specified types, the file path prefix is replaced with the first encountered substitution that matches.

Parameters:
  • substitution ([tuple]) - An ordered list of tuple: (old_path_prefix, new_path_prefix).
  • depTypes (int) - A combination of external dependency types (integer mask built from a binary OR of graph.ExternalDepType values) which defaults to graph.ExternalDepType.ALL_TYPES.

removeVersion(...)

 

Removes the named version.

Parameters:
  • name () - The version name to remove.

renameVersion(...)

 

Renames a version.

Parameters:
  • oldName ()
  • newName ()

revertToGraph(...)

 

Reverts the opened composition version to the given Graph.

Parameters:

revertWorkingTo(...)

 

Removes the working version to the named version.

Parameters:
  • name () - The version name to revert to.

setComponents(...)

 

Sets the number of components in the images of the primary output node (if no outputName argument is specified) or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • nbComps (int)

setDepth(...)

 

Sets the bit depth of each channel of the image for the primary output node (if no outputName argument is specified) or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • depth (int)

setDescription(...)

 

Sets the description (comment) of the composition.

Parameters:
  • desc (str)

setEnd(...)

 

Sets the end time index of the primary output node or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • index (int)

setFileFormat(...)

 

Sets the file format to be used when rendering to files.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • name (str)

setFileFormatOptions(...)

 

Sets the xml file format options to be used when rendering to files.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • options (str)

setFileName(...)

 

Sets the file name pattern to be used when creating image files while rendeing. The pattern can include substitution tokens.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • pattern (str)

setHeight(...)

 

Sets the height of the images produced by the primary output node (if no output name argument is specified), or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • height (int)

setImageRatio(...)

 

Sets image ratio (width/height ratio taking the pixel ratio into account) as a (numerator, denominator) tuple (2 integers) for the primary output node (if outputName is unspecified) or a named output node.

Setting the image ratio changes the pixel aspect ratio given the current image size and the specified image ratio.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • imageRatio (tuple) - (numerator, denominator) integer tuple that specifies the image ratio.

setMarkIn(...)

 

Sets the opened composition version mark in frame index.

Parameters:
  • frameIndex (int)

setMarkOut(...)

 

Sets the opened composition version mark out frame index.

Parameters:
  • frameIndex (int)

setPixelRatio(...)

 

Sets pixel aspect ratio of the image for the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) tuple.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • pixelRatio (tuple) - (numerator, denominator) integer tuple

setPrimaryOutputNode(...)

 

Sets the primary output node of the opened composition version to the given output node.

Parameters:

setPrimaryVersion(...)

 

Sets the primary version to be the one with the argument name.

Parameters:
  • name (str) - Version name.

setRate(...)

 

Sets the frame rate of the primary output node (if no outputName argument is specified) or the named output node, as a (numerator, denominator) integer tuple.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • rate (tuple) - (numerator, denominator) integer tuple representing the frame rate.

setRenderEnabled(...)

 

Sets whether rendering is enabled on the primary output node or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • renderEnabled (bool)

setRepeatMode(...)

 

Sets the opened composition version repeat mode.

Parameters:

setRole(...)

 

Sets the role of the opened composition version. The role is an arbitrary string, but is typically set to a value returned by one of the following functions, defined at module level:

Parameters:
  • role (str) - The composition role.

setSource(...)

 

Sets the source of the opened composition version.

Parameters:
  • source (str)

setStart(...)

 

Sets the start time index of the primary output node or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • index (int)

setWidth(...)

 

Sets the width of the images produced by the primary output node (if no output name argument is specified), or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • width (int)

setWiretapClipName(...)

 

Sets the wiretap clip name pattern to use when rendering into a wiretap clip. The pattern can include substitution tokens.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • pattern (str)

setWiretapEnabled(...)

 

Sets whether rendering into a wiretap clip is enabled on the primary output node or the named output node.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • enabled (bool)

setWiretapPath(...)

 

Sets the wiretap path to use when rendering into a wiretap clip.

Parameters:
  • outputName (str) - Optional argument specifying the output name.
  • path (str)