Parse Functions¶

These functions can either return a ColorCorrection, or a ColorCollection, depending on if they are from a container format.

Note

Use the parse_file() function to parse any input file correctly, without worrying about matching the file extension by hand.

parse_file¶

Passes on the file to the correct parser based on auto-detection.

cdl_convert.parse.parse_file(filepath: str | Path, filetype: str | None = None) → ColorCorrection | ColorCollection[source]¶

Parse CDL file using automatic format detection or specified type.

Determines the appropriate parser based on file extension and delegates to the corresponding format-specific parsing function. Supports all CDL-related formats including XML variants and EDL formats.

Parameters:

filepath (Union[str, Path]) – Path to CDL file to parse. File must exist.
filetype (Optional[str]) – File format override. If not provided, format is detected from file extension. Should not include leading dot (e.g., ‘ccc’ not ‘.ccc’).

Returns:

Single ColorCorrection for: formats like .cc and .rcdl, or ColorCollection for multi-correction formats like .ccc, .cdl, .ale, .edl, and .flex.

Return type:

Union[ColorCorrection, ColorCollection]

Raises:

ParseError – If file format is not supported or parsing fails.
FileNotFoundError – If input file path does not exist.

Example

>>> result = parse_file("project.ccc")
>>> if isinstance(result, ColorCollection):
...     print(f"Found {len(result.color_corrections)} corrections")

parse_ale¶

Parse Avid Log Exchange (ALE) files.

cdl_convert.parse.parse_ale(input_file: str | Path) → ColorCollection[source]¶

Parse an Avid Log Exchange (ALE) file for CDL color corrections using OTIO.

Parses an ALE file to extract ASC CDL color correction data embedded as ASC_SOP and ASC_SAT columns. This function uses the OpenTimelineIO otio-ale-adapter for ALE parsing and CDL metadata extraction.

CDL data appears in ALE files as tab-delimited columns: - ASC_SOP: (slope_r slope_g slope_b)(offset_r offset_g offset_b)(power_r power_g power_b) - ASC_SAT: saturation_value

Parameters:

input_file (Union[str, Path]) – The filepath to the ALE file.

Returns:

A collection containing all found ColorCorrections: with the collection type set to ‘ccc’.

Return type:

ColorCollection

Raises:

OTIOAdapterError – If otio-ale-adapter is not installed or available.
ParseError – If ALE file cannot be parsed by OpenTimelineIO adapter.
ValidationError – If color correction values fail validation.
FileNotFoundError – If the input file does not exist.

Example

>>> ale_collection = parse_ale("project.ale")
>>> print(f"Found {len(ale_collection.color_corrections)} clips with CDL")

parse_cc¶

Parse XML Color Correction (cc) files.

cdl_convert.parse.parse_cc(input_file: str | Path | Element) → ColorCorrection[source]¶

Parse XML Color Correction (.cc) file or element.

Parses a single ColorCorrection XML element containing ASC CDL values. CC files represent individual color corrections and are commonly used for single-shot CDL exchange instead of larger CDL or CCC files.

The parser extracts SOP (Slope, Offset, Power) and Saturation values along with descriptions, input/viewing colorspace information, and other metadata from the XML structure.

Parameters:

input_file (Union[str, Path, ElementTree.Element]) – File path to CC file or pre-parsed ElementTree Element containing ColorCorrection data.

Returns:

ColorCorrection instance with parsed CDL values: and metadata.

Return type:

ColorCorrection

Raises:

ParseError – If XML structure is invalid or required elements missing.
ValidationError – If CDL values fail validation checks.
FileNotFoundError – If input file path does not exist.

Example

>>> cc = parse_cc("shot_001.cc")
>>> print(f"ID: {cc.id}, Slope: {cc.slope}")

parse_ccc¶

Parse XML Color Correction Collection (ccc) files.

cdl_convert.parse.parse_ccc(input_file: str | Path) → ColorCollection[source]¶

Parse XML Color Correction Collection (.ccc) file.

Parses a ColorCorrectionCollection XML file containing multiple ColorCorrection elements. CCC files are collections of individual color corrections without ColorDecision or MediaRef elements.

The parser extracts all ColorCorrection elements along with collection- level descriptions, InputDescription (source colorspace), and ViewingDescription (viewing environment and hardware) metadata.

Parameters:

input_file (Union[str, Path]) – File path to CCC file to parse.

Returns:

Collection containing all found ColorCorrections: with type set to ‘ccc’ and parsed metadata.

Return type:

ColorCollection

Raises:

ParseError – If XML structure is invalid or root element is not ColorCorrectionCollection.
ValidationError – If CDL values fail validation checks.
FileNotFoundError – If input file path does not exist.

Example

>>> ccc = parse_ccc("show_corrections.ccc")
>>> print(f"Found {len(ccc.color_corrections)} corrections")

parse_cdl¶

Parse XML Color Decision List (cdl) files.

cdl_convert.parse.parse_cdl(input_file: str | Path) → ColorCollection[source]¶

Parse XML Color Decision List (.cdl) file.

Parses a ColorDecisionList XML file containing ColorDecision elements that link ColorCorrections with MediaRef elements. CDL files represent the complete ASC CDL workflow including media references.

The parser extracts all ColorDecision elements along with collection- level descriptions, InputDescription (source colorspace), and ViewingDescription (viewing environment and hardware) metadata.

Parameters:

input_file (Union[str, Path]) – File path to CDL file to parse.

Returns:

Collection containing all found ColorDecisions: with type set to ‘cdl’ and parsed metadata.

Return type:

ColorCollection

Raises:

ParseError – If XML structure is invalid or root element is not ColorDecisionList.
ValidationError – If CDL values fail validation checks.
FileNotFoundError – If input file path does not exist.

Example

>>> cdl = parse_cdl("project_decisions.cdl")
>>> print(f"Found {len(cdl.color_decisions)} decisions")

parse_cmx¶

Parse CMX EDL files using OpenTimelineIO.

cdl_convert.parse.parse_cmx(input_file: str | Path) → ColorCollection[source]¶

Parse CMX EDL file for ASC CDL color correction information using OTIO.

Parses a CMX Edit Decision List file to extract ASC CDL color correction data embedded as *ASC_SOP and *ASC_SAT comments. This function uses the OpenTimelineIO otio-cmx3600-adapter for EDL parsing and timeline structure handling.

CDL data appears in CMX EDL files as comment lines following edit entries:

001  DS0010.bg1 V     C     00:08:07:23 00:08:16:10 01:00:00:00 01:00:08:11
*ASC_SOP (1.45 1.22 1.15)(-0.14 -0.11 -0.11)(1.00 1.00 1.00)
*ASC_SAT 0.773000

Parameters:

input_file (Union[str, Path]) – File path to CMX EDL file to parse.

Returns:

Collection containing ColorCorrections extracted: from EDL with clip names as IDs and filename as source.

Return type:

ColorCollection

Raises:

OTIOAdapterError – If otio-cmx3600-adapter is not installed or available.
ParseError – If EDL file cannot be parsed by OpenTimelineIO adapter.
FileNotFoundError – If input file path does not exist.

Example

>>> edl_collection = parse_cmx("project.edl")
>>> print(f"Found {len(edl_collection.color_corrections)} clips with CDL")

parse_flex¶

Parse Film Log EDL Exchange (FLEx) files.

cdl_convert.parse.parse_flex(input_file: str | Path) → ColorCollection[source]¶

Parse DaVinci FLEx telecine EDL file for ASC CDL information.

Parses a Film Log EDL Exchange (FLEx) file from DaVinci telecine systems. FLEx uses a strict line-based format with fixed character positions for data fields rather than delimited values.

The parser extracts ASC CDL data from line types 701 (SOP values) and 702 (Saturation values), along with shot identification from line 100 (slate information) and project title from line 010.

FLEx Format Structure: - Lines 000-099: Session information - Line 010: Project title (chars 10-79) - Line 100: Slate info - Scene (10-17), Take (24-31), Reel (42-49) - Line 701: ASC SOP values (space-separated) - Line 702: ASC SAT value (space-separated)

Parameters:

input_file (Union[str, Path]) – File path to FLEx EDL file to parse.

Returns:

Collection containing ColorCorrections extracted: from FLEx with shot identifiers derived from slate information or project title.

Return type:

ColorCollection

Raises:

ParseError – If FLEx file format is invalid or cannot be parsed.
ValidationError – If CDL values fail validation checks.
FileNotFoundError – If input file path does not exist.

Example

>>> flex_collection = parse_flex("telecine_session.flex")
>>> print(f"Found {len(flex_collection.color_corrections)} shots")

parse_nk¶

Parse Foundry Nuke OCIOCDLTransform node files.

Nuke’s OCIOCDLTransform node format is a simple text-based format used for exchanging CDL corrections in Nuke-based VFX and compositing workflows.

cdl_convert.parse.parse_nk(input_file: str | Path) → ColorCorrection[source]¶

Parse Foundry Nuke OCIOCDLTransform node file.

Parses a Nuke script file containing an OCIOCDLTransform node to extract ASC CDL color correction values.

The parser extracts slope, offset, power (as RGB triples), saturation (as a single value), and the node name. This format is commonly used for exchanging CDL corrections in Nuke-based VFX and compositing workflows.

OCIOCDLTransform Format Structure:

OCIOCDLTransform {
  slope {R G B}
  offset {R G B}
  power {R G B}
  saturation S
  name node_name
}

Parameters:

input_file (Union[str, Path]) – File path to .nk file containing OCIOCDLTransform node.

Returns:

ColorCorrection instance with parsed CDL values: and node name as ID.

Return type:

ColorCorrection

Raises:

ParseError – If file does not contain OCIOCDLTransform node, has malformed syntax, or is missing required fields.
ValidationError – If CDL values fail validation checks.
FileNotFoundError – If input file path does not exist.

Example

>>> cc = parse_nk("shot_001.nk")
>>> print(f"ID: {cc.id}, Slope: {cc.slope}")

parse_otio¶

Parse OpenTimelineIO timeline files with embedded CDL metadata.

cdl_convert.parse.parse_otio(input_file: str | Path) → ColorCollection[source]¶

Parse OpenTimelineIO (.otio) timeline file for ASC CDL color corrections.

Parses an OTIO timeline file to extract ASC CDL color correction data embedded in clip metadata. This function uses OpenTimelineIO’s native deserialization to read .otio files and extract CDL metadata from all clips in the timeline structure.

CDL data appears in OTIO files as clip metadata:

clip.metadata['cdl'] = {
    'asc_sop': {
        'slope': [float, float, float],
        'offset': [float, float, float],
        'power': [float, float, float]
    },
    'asc_sat': float
}

Parameters:

input_file (Union[str, Path]) – The filepath to the .otio file.

Returns:

A collection containing all found ColorCorrections: with the collection type set to ‘ccc’.

Return type:

ColorCollection

Raises:

OTIOAdapterError – If OpenTimelineIO is not installed or available.
ParseError – If .otio file cannot be parsed by OpenTimelineIO.
ValidationError – If color correction values fail validation.
FileNotFoundError – If the input file does not exist.

Example

>>> otio_collection = parse_otio("timeline.otio")
>>> print(f"Found {len(otio_collection.color_corrections)} clips with CDL")

parse_rnh_cdl¶

Parse Rhythm & Hues CDL format.

Rhythm & Hues’ implementation of the cdl format is based on a very early spec, and as such lacks all metadata. It’s extremely unlikely that you’ll run into this format in the wild.

But it’s here, because I miss Rhythm greatly.

cdl_convert.parse.parse_rnh_cdl(input_file: str | Path) → ColorCorrection[source]¶

Parse Rhythm & Hues space-separated CDL file format.

Parses a simple text file containing a single line with 10 space-separated numeric values representing ASC CDL parameters. This format was used internally by Rhythm & Hues for shot and sequence level color correction data in their playback software.

The format contains exactly 10 values in ASC CDL order of operations:

SlopeR SlopeG SlopeB OffsetR OffsetG OffsetB PowerR PowerG PowerB Sat

Parameters:

input_file (Union[str, Path]) – File path to space-separated CDL file.

Returns:

Single ColorCorrection with filename (without: extension) as ID and parsed CDL values.

Return type:

ColorCorrection

Raises:

ParseError – If file format is invalid or values cannot be parsed.
ValidationError – If CDL values fail validation checks.
FileNotFoundError – If input file path does not exist.
IndexError – If file does not contain exactly 10 space-separated values.

Example

>>> cc = parse_rnh_cdl("shot_001.cdl")
>>> print(f"Slope: {cc.slope}, Saturation: {cc.sat}")