Module media

Imports the specified files into a composition.

The folder containing the composition will be created automatically, if it does not exist.

Parameters:

• compositionPath (str) - The path to the composition that this function will create. Specifying a relative path imports relative to the Footage folder.
• files (list of str) - A list of filesystem paths or a string representing a sequence path (for example, "image.[01:10].tif"). File names in a list must have the same pattern and have a sequence number within. For example, files "img001.tif" through "img020.tif" compose a valid sequence.
• fileFormatOptions (str) - An xml string describing some operations that can optionally be applied to the images being imported. Currently, the available operations are Gamma corrections (LUT), Cineon LUT and OpenEXR channel assignments. Those xml strings can be generated with the following functions, respectively:
  • getLutXmlOptions()
  • getCineonXmlOptions()
  • getRGBAChannelAssignmentsXmlOptions() / getChannelGroupAssignmentXmlOptions() / getChannelViewAssignmentXmlOptions()

  The file format options string may be empty.

• pixelRatio (tuple) - A tuple. The first value is the numerator, the second value is the denominator of the pixel ratio. If it is unspecified (default is 0), the pixel ratio is obtained from the file if it supports it, else Composite infers it from the resolution.
• rate (tuple) - A tuple like the pixel ratio. It represents the rate in frame per seconds of the resulting sequence. If it is unspecified (default is 0), the rate is obtained from the file if it supports it, else Composite infers it from the resolution.
• depth (int) - An integer that specifies the bit depth in which the image will be converted when it is imported. The only acceptable values for depth are 16 and 32. The specified depth cannot be lower than the depth of the first file. If depth is left unspecified, the value will be infered from the pixel format of the first file. The infered value will be either 16 or 32 bits, and will never be lower than the first file's original bit depth.
• startTime (int) - An integer that specifies the start time of the footage composition that will be created on import. If it is unspecified (default is None), Composite infers it from the sequence number of the first file contained within the file list.
• source (str) - A string that documents by which source the composition was created from. Default is 'File'.
• unpremultiplyState (bool) - Specifies whether the files being imported will be unpremultiplied. Default is False. If it is set to True, the color components of the images will be divided by their alpha. This parameter is ignored if the given files do not have an alpha component.
• unpreBgColor (tuple) - A tuple containing three floating point numbers [e.g. (0.03, 0.02, 0.1)] specifying the RGB background color to unpremultiply the images with. If it is set to None, the background color will automatically be guessed by Composite.
• motionVectorInfo (tuple) - A tuple containing motion vector information about the given sequence. If the sequence represents motion vectors, the first element of the tuple should correspond to a media.MotionVectorType enum, and the second element should be an integer value that specifies the maximum displacement [e.g. (media.MotionVectorType.ADSK_3DSMAX, 2048)].

  The motion vector type can be one of the following (defined at module level):

  • MotionVectorType.NONE
  • MotionVectorType.ADSK_3DSMAX
  • MotionVectorType.REELSMART
  • MotionVectorType.SMOOTHKIT

Returns: str

The full composition name under which the composition has been imported.

Creates an "Image Import" node into the given group node from the specified files and returns it.

Parameters:

• groupNode (graph.GroupNode) - A graph.GroupNode instance to which the image import node is added.
• files (list of str) - A list of filesystem paths or a string representing a sequence path (for example, "image.[01:10].tif"). File names in a list must have the same pattern and have a sequence number within. For example, files "img001.tif" through "img020.tif" compose a valid sequence.
• name (str) - The name of the resulting image import node. If left empty, it is generated based on the file sequence name.
• fileFormatOptions (str) - An xml string describing some operations that can optionally be applied to the images being imported. Currently, the available operations are Gamma corrections (LUT), Cineon LUT and OpenEXR channel assignments. Those xml strings can be generated with the following functions, respectively:
  • getLutXmlOptions()
  • getCineonXmlOptions()
  • getRGBAChannelAssignmentsXmlOptions() / getChannelGroupAssignmentXmlOptions() / getChannelViewAssignmentXmlOptions()

  The file format options string may be empty.

• pixelRatio (tuple) - A tuple. The first value is the numerator, the second value is the denominator of the pixel ratio. If it is unspecified (default is 0), the pixel ratio is obtained from the file if it supports it, else Composite infers it from the resolution.
• rate (tuple) - A tuple like the pixel ratio. It represents the rate in frame per seconds of the resulting sequence. If it is unspecified (default is 0), the rate is obtained from the file if it supports it, else Composite infers it from the resolution.
• depth (int) - An integer that specifies the bit depth in which the image will be converted when it is imported. The only acceptable values for depth are 16 and 32. The specified depth cannot be lower than the depth of the first file. If depth is left unspecified, the value will be infered from the pixel format of the first file. The infered value will be either 16 or 32 bits, and will never be lower than the first file's original bit depth.
• unpremultiplyState (bool) - Specifies whether the files being imported will be unpremultiplied. Default is False. If it is set to True, the color components of the images will be divided by their alpha. This parameter is ignored if the given files do not have an alpha component.
• unpreBgColor (tuple) - A tuple containing three floating point numbers [e.g. (0.03, 0.02, 0.1)] specifying the RGB background color to unpremultiply the images with. If it is set to None, the background color will automatically be guessed by Composite.
• motionVectorInfo (tuple) - A tuple containing motion vector information about the given sequence. If the sequence represents motion vectors, the first element of the tuple should correspond to a media.MotionVectorType enum, and the second element should be an integer value that specifies the maximum displacement [e.g. (media.MotionVectorType.ADSK_3DSMAX, 2048)].

  The motion vector type can be one of the following (defined at module level):

  • MotionVectorType.NONE
  • MotionVectorType.ADSK_3DSMAX
  • MotionVectorType.REELSMART
  • MotionVectorType.SMOOTHKIT

Returns: GroupNode

The new GroupNode.

Creates an "Image Import" and an "Output" node into the given group node from the specified files. Returns a 2-tuple with the (Image Import, Output) nodes. Both the image import and the output node rendered result will reference the given argument files. The files do not need to be present on disk: they can be rendered later, perhaps by an external process. The image import output will be connected to the output node image input.

Parameters:

• groupNode (graph.GroupNode) - A graph.GroupNode instance to which the image import and output nodes are added.
• files (list of str) - A list of filesystem paths or a string representing a sequence path (for example, "image.[01:10].tif"). File names in a list must have the same pattern and have a sequence number within. For example, files "img001.tif" through "img020.tif" compose a valid sequence.
• importName (str) - The name of the resulting image import node. If left empty, it is generated based on the file sequence name.
• outputName (str) - The name of the resulting output node. If left empty, it is generated based on the file sequence name.
• start (int) - An integer that specifies the start time of the footage. The start time is inclusive: it corresponds to the first frame.
• end (int) - An integer that specifies the end time of the footage. The end time is exclusive: it corresponds to one past the last frame.
• width (int) - Width of the image frames.
• height (int) - Height of the image frames.
• pixelRatio (tuple) - A tuple. The first value is the numerator, the second value is the denominator of the pixel ratio. If it is unspecified (default is 0), the pixel ratio is obtained from the file if it supports it, else Composite infers it from the resolution.
• rate (tuple) - A tuple like the pixel ratio. It represents the rate in frame per seconds of the resulting sequence.
• depth (int) - An integer that specifies the bit depth in which the image will be converted when it is imported. The only acceptable values for depth are 16 and 32.
• comps (int) - An integer that specifies the number of components in the file. Legal values are 1, 3, and 4.
• comment (str) - A description added to the rendered result of the output node.
• fileFormatOptions (str) - An xml string describing some operations that can optionally be applied to the images being imported. Currently, the available operations are Gamma corrections (LUT), Cineon LUT and OpenEXR channel assignments. Those xml strings can be generated with the following functions, respectively:
  • getLutXmlOptions()
  • getCineonXmlOptions()
  • getRGBAChannelAssignmentsXmlOptions() / getChannelGroupAssignmentXmlOptions() / getChannelViewAssignmentXmlOptions()

  The file format options string may be empty.

• unpremultiplyState (bool) - Specifies whether the files being imported will be unpremultiplied. Default is False. If it is set to True, the color components of the images will be divided by their alpha. This parameter is ignored if the given files do not have an alpha component.
• unpreBgColor (tuple) - A tuple containing three floating point numbers [e.g. (0.03, 0.02, 0.1)] specifying the RGB background color to unpremultiply the images with. If it is set to None, the background color will automatically be guessed by Composite.

Returns: GroupNode

A GroupNode object.

Archives the specified components in a file specified by filePath.

Parameters:

• filePath (str) - The path to the file in which the components will be archived.
• components (list of str) - The list of components to archive.
• includeLinkedComps (bool) - Setting this parameter to True will archive recursively all compositions that an archived composition links with, recursively.
• externalDepTypes (int) - Combination of external dependency values (integer mask built from a binary OR of graph.ExternalDepType values) indicating which type of external dependencies must be included in the archive. External dependencies from linked comps are taken into account as well.
• compress (bool) - Setting this parameter to True will create a compressed archive file.
• progressCallback (callable) - This callback is called after some step of the archive process has completed (called from the same thread). It receives two integer parameters representing the number of steps completed and the total number of steps. Returning True from the progress callback will cancel any further archiving.

Restores an archive from filePath. Optionally, you can specify a destination path destPath where the archive entries will be restored. If not specified, the destination path is the home folder of the project in which the archive is restored.

This function will sucessfully restore archives from older versions of Composite as well.

Parameters:

• filePath (str) - The path of the archived file to restore.
• destPath (str) - The destination restoration path.
• externalDepTypes (int) - Combination of external dependency values (integer mask built from a binary OR of graph.ExternalDepType values) indicating which type of external dependencies must be restored from the archive.
• externalDepRelocationCallback (callable) - Callback that is used to relocate external dependency files present in the archive. It is given a list of all the external dependency directories and it must return a list of tuple (old_path_prefix, new_path_prefix) representing the substitutions to apply to the paths in order to relocate the files. The ordering of the returned list is crucial as the first matching path prefix encountered is the one (and only one) used for substitution.
• dbConflictCallback (callable) - Callback that is used to decide what to do when a restored component already exists. This callback must return one of the following decision code:
  • 0: overwrite.
  • 1: skip.
  • -1: cancel (aborts this restoration step and not the whole process).

  If no callback is specified, the default behavior is to overwrite.

• externalDepConflictCallback (callable) - Callback that is used to decide what to do when an external dependency file already exists. This callback must return one of the following decision code:
  • 0: overwrite.
  • 1: skip.
  • -1: cancel (aborts this restoration step and not the whole process)

  If no callback is specified, the default behavior is to overwrite.

• restoreErrorCallback (callable) - Callback is used when a component in the XML file is invalid. It will ask the user if he wishes to continue restoring the archive or abort the process. The default behavior is to continue the restoration.
• xmlFileErrorCallback (callable) - Callback that is used to handle XML file errors generated when a parsing error occurs. The default behavior is to continue the restoration.
• progressCallback (callable) - Callback that is called after some step of the restore process has completed (called from the same thread). It receives three integer parameters representing the number of steps completed and the total number of steps and an optional string that is relevant to the restore process. It can be the path of the restored component or of the file that was relocated. Returning True from the progress callback will cancel any further restoration.

Returns: [str]

A list of paths for the components that were restored.

Caches the image results at the specified output socket.

This could possibly take quite a long time and the function blocks until all caching is completely done.

Parameters:

• outputSocket (Output)
• start (int) - Specifies the start index to cache. If a start time index is not specified (i.e. None), the start index of the composition is used.
• end (int) - Specifies the end index to cache. If an end time index is not specified (i.e. None), the end index of the composition is used.
• resolutions (list) - A list of proxy scale indexes to compute and cache (default caches only full-resolution images). The default is to cache only full resolution images.
• turnOnIR (bool) - If this parameter is set to True, the outputs whose results are computed will have their Intermediate Results (IR) flag set to 'on' so that their results will be cached on disk (in the media cache). This will work only if the IR state on the output socket is already, or can be enabled (the graph can be opened in read-write; see Output.setResultState()). Otherwise, results are simply cached according to the current IR state of the output socket; i.e.cached in memory only when IR is disabled.
• callback (callable) - An optional callback function that can be specified to be called back every time a new frame is cached. The callback should take two parameters: (t, i) where t is the time index and i is the scale index just cached. This allows the client to perform another task synchronously while the files are cached, such as indicating progress to the user.

Caches the primary version of the composition specified by compPath.

Parameters:

• compPath (str) - Composition path.
• outputs (list of Output) - A list of output node names to cache. If set to None (default), only the primary output node is cached. If set to an empty list, all output nodes are cached.
• rendered (bool) - If this parameter is True, the "rendered" output socket of the output nodes are cached, otherwise, the "processing" output sockets are cached (default).
• start (int) - Specifies the start index to cache. If a start time index is not specified (i.e. None), the start index of the composition is used.
• end (int) - Specifies the end index to cache. If an end time index is not specified (i.e. None), the end index of the composition is used.
• resolutions (list) - A list of proxy scale indexes to compute and cache (default caches only full-resolution images). The default is to cache only full resolution images.
• turnOnIR (bool) - If this parameter is set to True, the outputs whose results are computed will have their Intermediate Results (IR) flag set to 'on' so that their results will be cached on disk (in the media cache). This will work only if the IR state on the output socket is already, or can be enabled (the graph can be opened in read-write; see Output.setResultState()). Otherwise, results are simply cached according to the current IR state of the output socket; i.e.cached in memory only when IR is disabled.
• callback (callable) - An optional callback function that can be specified to be called back every time a new frame is cached. The callback should take two parameters: (t, i) where t is the time index and i is the scale index just cached. This allows the client to perform another task synchronously while the files are cached, such as indicating progress to the user.

Caches the given composition version.

Parameters:

• version (Graph) - Composition version to cache.
• outputs (list of Output) - A list of output node names to cache. If set to None (default), only the primary output node is cached. If set to an empty list, all output nodes are cached.
• rendered (bool) - If this parameter is True, the "rendered" output socket of the output nodes are cached, otherwise, the "processing" output sockets are cached (default).
• start (int) - Specifies the start index to cache. If a start time index is not specified (i.e. None), the start index of the composition is used.
• end (int) - Specifies the end index to cache. If an end time index is not specified (i.e. None), the end index of the composition is used.
• resolutions (list) - A list of proxy scale indexes to compute and cache (default caches only full-resolution images). The default is to cache only full resolution images.
• turnOnIR (bool) - If this parameter is set to True, the outputs whose results are computed will have their Intermediate Results (IR) flag set to 'on' so that their results will be cached on disk (in the media cache). This will work only if the IR state on the output socket is already, or can be enabled (the graph can be opened in read-write; see Output.setResultState()). Otherwise, results are simply cached according to the current IR state of the output socket; i.e.cached in memory only when IR is disabled.
• callback (callable) - An optional callback function that can be specified to be called back every time a new frame is cached. The callback should take two parameters: (t, i) where t is the time index and i is the scale index just cached. This allows the client to perform another task synchronously while the files are cached, such as indicating progress to the user.

Parameters:

• type (str) - A case-sensitive string that can be one of "gamma", "sRGB" or "rec.709" (or "none" which is equivalent to no LUT, in which case this function is not typically used).

  Only the "gamma" type requires RGB values:

  • If no value is given, they default to 1.0.
  • If only the red value is given, then green and blue takes that value.

  For "sRGB" and "rec.709", the values are implicit and ignored if any are given.

  If an invalid string is given the type of the LUT will be set to "none". LUT options make sense only for 8-bits images.

• gammaR (float)
• gammaG (float)
• gammaB (float)

Returns: str

The XML str corresponding to the LUT type specified and the gamma values when required.

Parameters:

• mode (str) - A string set to either "convert" or "raw".

  In convert mode, colors are converted while in raw mode, they are not. In raw mode, any values specified are ignored.

  For gamma, cineon ref. and linear ref. the following applies:

  • If no value is given, a default value is provided.
  • If only the red is given, then green and blue takes that value.

  Values:

     Parameter        Default     Min    Max
     -----------------------------------------
     gamma            0.6         0.1    4.0
     cineon ref       685         1      1023
     linear ref       0.9         0.1    10.0
  

  Cineon LUT options make sense only for 10-bits DPX and Cineon images.

• gammaR (float)
• gammaG (float)
• gammaB (float)
• cineonRefR (float)
• cineonRefG (float)
• cineonRefB (float)
• linearRefR (float)
• linearRefG (float)
• linearRefB (float)

Returns: str

The XML str corresponding to the Cineon LUT type specified and the values when required.

Parameters:

• nbChannels - Specifies the number of channels in the output image; valid values are 1 (A), 3 (RGB) and 4 (RGBA).
• r (str) - Specify the name of the input channel that gets assigned to the red channel. Setting a channel parameter to None (the default) or the empty string means that no input channel is assigned to it, so the output channel pixels will be set to zero.
• g (str) - Specify the name of the input channel that gets assigned to the green channel.
• b (str) - Specify the name of the input channel that gets assigned to the blue channel.
• a (str) - Specify the name of the input channel that gets assigned to the alpha channel.

Returns: str

The XML string representation of the specified RGBA channel assignments, used in file import options.

Parameters:

• frameCount (int) - An integer number represents the position of a frame within a clip.
• frameRate (float) - Is a real number representing the frame rate in frames per second.
• nonDropRequested (bool) - An optional flag that is considered only for frame rates for which a drop mode exists, namely 29.97 and 59.94. When this flag is set to True, the timecode string generated is Non-Drop, else if it is in Drop mode. The flag is ignored for other rates.

Returns: str

A timecode string of the form HH:MM:SS:FF. Note that the separator may be different depending on the rate and drop mode if applicable.

Parameters:

• frameCount (int) - An integer number representing the position of a frame within a clip.
• frameRate (float) - A real number representing the frame rate in frames per second.
• nonDropRequested (bool) - An optional flag that is considered only for frame rates for which a drop mode exists, namely 29.97 and 59.94. When this flag is set to True, the timecode string generated is Non-Drop, else if it is in Drop mode. The flag is ignored for other rates.

Returns: tuple

A tuple of four numbers representing respectively hours, minutes, seconds and frames.

This function converts a timecode into a frame count.

hour, min, sec and frames is the timecode broken down into its components.

Parameters:

• hour (int)
• min (int)
• sec (int)
• frames (int)
• frameRate (float) - A real number representing the frame rate in frames per second.
• nonDropRequested (bool) - An optional flag that is considered only for frame rates for which a drop mode exists, namely 29.97 and 59.94. When this flag is set to True, the timecode string generated is Non-Drop, else if it is in Drop mode. The flag is ignored for other rates.

Returns: int

An int representing the frame count.

Converts a standard rate to its corresponding rational value.

Parameters:

• rate (float) - A frame rate.
• tolerance (float)

Returns: tuple

A rational (numerator, denominator) tuple, obtained from the rate registry. For example, the frame rates 30 and 29.97 would respectively yield the (30, 1) and (30000, 1001) rationals. It will find the rate that is closest to the real number passed in, within the specified tolerance. If the given rate is zero or negative, or if no rate entry is found, the function returns (0, 1).

Gets the image file formats supported by Composite in the specified access mode.

Parameters:

• accessMode (FormatAccessMode) - The access mode can be one of the following (defined at module level):
  • FormatAccessMode.ANY
  • FormatAccessMode.READ
  • FormatAccessMode.WRITE
  • FormatAccessMode.READ_WRITE

Returns: dict

A dict where keys are the format identifier and the values a list of the valid format extensions.

Indicates whether the specified image file extension is supported by Composite in the specified access mode.

Parameters:

• ext (str) - An image file extension.
• accessMode (FormatAccessMode) - The access mode can be one of the following (defined at module level):
  • FormatAccessMode.ANY
  • FormatAccessMode.READ
  • FormatAccessMode.WRITE
  • FormatAccessMode.READ_WRITE

Concatenates the given channel view name and sub-channel name to get the full channel name in a multi-channel image file

Parameters:

• view (str) - The name of the channel view (for example: "left" or "right").
• subChannel (str) - The name of the sub-channel (for example: "R", "G" or "B").

Returns: str

The full file channel.

Gets the format of images imported by the given Image Import node.

Parameters:

• importNode (GroupNode) - The Image Import super tool node.

Returns: ImageFormat

The image format of the given Image Import node.

Sets the image format of the given Image Import node.

Parameters:

• importNode (GroupNode) - The Image Import super tool node.
• imageFormat (ImageFormat) - The image format to set.

Gets the resolution of images imported by the given Image Import node.

Parameters:

• importNode (GroupNode) - The Image Import super tool node.

Returns: tuple

Image resolution as a (width, height) tuple.

Gets the start and end frames of images imported by the given Image Import node (the end frame is exclusive).

Parameters:

• importNode (GroupNode) - The Image Import super tool node.

Returns: tuple

A (start, end) tuple of integers or a (None, None) tuple if there's no file sequence set on the Image Import node.

Gets the following time parameters from the given Image Import node:

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

Parameters:

• importNode (GroupNode) - The Image Import super tool node.

Returns: tuple

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

Sets the time parameters on the given Image Import node.

Parameters:

• importNode (GroupNode) - The Image Import super tool node.
• markIn (int) - Import mark in.
• markOut (int) - Import mark out.
• timeOffset (int) - Import time offset.
• repeatMode (graph.RepeatMode) - Import repeat mode.
• lockDuration (bool) - Import lock duration.