Script Usage¶
cdl_convert can be used both as a command-line script and as a Python library. The command-line interface provides a simple way to convert between CDL formats.
Basic Conversion¶
Convert to a .cc XML file (default output):
$ cdl_convert ./di_v001.flex
Override the default output format or provide multiple outputs:
$ cdl_convert ./di_v001.flex -o cc,cdl
Specify output directory:
$ cdl_convert ./input.flex -d ./output_directory/ -o cc,ccc,cdl
Character Encoding Configuration¶
cdl_convert supports configurable character encoding for both input and output files, allowing you to work with CDL files in various text encodings.
Input Encoding¶
By default, cdl_convert automatically detects the encoding of XML files (.cc, .ccc, .cdl) from their XML declaration. For non-XML formats (.ale, .flex, .nk, .rcdl), UTF-8 is used by default.
Override the automatic detection with the --input-encoding option:
$ cdl_convert ./input.cc --input-encoding latin-1
This is useful when:
Working with legacy files that use non-UTF-8 encodings
The XML declaration is missing or incorrect
Processing files with special characters in non-standard encodings
Output Encoding¶
Control the character encoding used when writing output files with the --output-encoding option:
$ cdl_convert ./input.flex --output-encoding latin-1 -o cc
The output encoding affects:
The XML declaration in output files (e.g.,
<?xml version="1.0" encoding="ISO-8859-1"?>)How characters are encoded in the output file
Note
cdl_convert automatically converts Python encoding names to their IANA standard equivalents in XML declarations. For example, latin-1 becomes ISO-8859-1 in the XML declaration, ensuring compatibility with XML standards and other tools.
Python API Usage¶
Configure encoding programmatically:
import cdl_convert as cdl
# Set input encoding (None for auto-detection)
cdl.config.config.input_encoding = 'latin-1'
# Set output encoding
cdl.config.config.output_encoding = 'utf-8'
# Parse with configured encoding
cc = cdl.parse_cc('path/to/file.cc')
# Write with configured encoding
cdl.write_cc(cc)
The encoding configuration is validated when set:
try:
cdl.config.config.output_encoding = 'invalid-encoding'
except LookupError as e:
print(f"Error: {e}")
Configurable XML Tag Names¶
Control the XML element tag names used for SOP and Saturation nodes to improve compatibility with different color correction systems.
Use ASC CDL specification-compliant tag names:
$ cdl_convert ./input.ale --sop-tag ASC_SOP --sat-tag ASC_SAT -o cc
This will generate XML with <ASC_SOP> and <ASC_SAT> tags instead of the default <SOPNode> and <SatNode> tags.
Maintain legacy SATNode tag for backward compatibility:
$ cdl_convert ./input.flex --sat-tag SATNode -o ccc
Available Options:
--sop-tag {SOPNode,ASC_SOP}- XML tag name for SOP nodes (default:SOPNode)--sat-tag {SatNode,SATNode,ASC_SAT}- XML tag name for Saturation nodes (default:SatNode)
Note
The default Saturation tag changed from SATNode to SatNode in v1.0 for consistency. Use --sat-tag SATNode to maintain legacy behavior if needed.
Specifying Input Format¶
Sometimes it might be necessary to disable cdl_convert’s auto-detection of the input file format. This can be done with the -i flag:
$ cdl_convert ./ca102_x34.cdl -i rcdl
Note
You should not normally need to do this, but it is possible especially since there are multiple formats sharing the same file extension. In this case, .cdl could have indicated either a space separated cdl (an rcdl), or an XML cdl. cdl_convert does its best to try and guess which one the file is, but if you’re running into trouble, it might help to indicate to cdl_convert what the input file type is.
Output Directory¶
By default, converted files will be written to the ./converted directory, but a custom destination directory can easily be specified with the -d flag:
$ cdl_convert ./hk416_210.ccc -d /hello_kitty/luts/cdls/
Warning
It’s possible to pass a . to the -d flag, causing converted files to be written to the same directory as the directory you’re calling cdl_convert from, and often that ends up being the same directory as the file you’re converting from. If one isn’t careful, there’s a possibility you could overwrite the original files.
Enhanced Error Checking and Validation¶
cdl_convert includes enhanced error checking and validation. Use the --check flag to validate CDL values and get warnings about potentially incorrect values.
For Slope, Power and Saturation, any values below 0.1 or above 3.0 will flag. For Offset, any values below -1.0 or above 1.0 will flag:
$ cdl_convert ./di_v001.flex --check
The ColorCorrection "a347.x700" was given a Slope value of "0.978", which
might be incorrect.
The ColorCorrection "a400.x050" was given a Saturation value of "3.1",
which might be incorrect.
Use enhanced error handling with the --halt flag to stop processing on the first error:
$ cdl_convert --check --halt ./input.ale -o ccc
This is especially useful when combined with the --no-output flag for dry run mode:
$ cdl_convert ./timeline.otio --check --no-output
Python API Usage¶
cdl_convert can also be used as a Python library:
import cdl_convert as cdl
# Parse a CDL file
cc = cdl.parse_cc('path/to/file.cc')
# Access CDL values
print(cc.slope) # (Decimal('1.2'), Decimal('1.0'), Decimal('0.8'))
print(cc.offset) # (Decimal('0.1'), Decimal('0.0'), Decimal('-0.1'))
print(cc.power) # (Decimal('1.0'), Decimal('1.1'), Decimal('0.9'))
print(cc.sat) # Decimal('1.2')
# Write to different format
cdl.write_ccc(cc)
See Color Corrections for detailed Python API examples and Color Collections for working with collections.
Command Line Reference¶
Full help is available using the standard --help command:
$ cdl_convert --help
usage: cdl_convert [-h] [-i INPUT] [-o OUTPUT] [-d DESTINATION] [--halt]
[--no-output] [--check] [--single] [-v] [--debug]
input_file
Convert between ASC Color Decision List (CDL) formats
positional arguments:
input_file Path to the CDL file to be converted
options:
-h, --help show this help message and exit
-i, --input INPUT Specify input format when auto-detection fails.
Choices: ale, cc, ccc, cdl, edl, flex, otio, rcdl
-o, --output OUTPUT Output format(s), comma-separated for multiple outputs.
Choices: cc, ccc, cdl, rcdl. Default: cc
-d, --destination DESTINATION
Output directory for converted files. Default: ./converted/
--halt Stop processing on first error instead of using default
values. Useful for strict validation of CDL files. Turn
this on if you want the conversion process to fail and
not continue,rather than relying on default behavior
for bad values. Examples are clipping negative values
to 0.0 for Slope, Power and Saturation, and
automatically generating a new id for a ColorCorrect
if no or a bad id is given.
--no-output Parse files without writing output. Useful with --halt
and --check for validation-only runs.
--check Check for unusual color correction values. Flags
slope/power/saturation outside 0.1-3.0 range and offset
outside -1.0 to 1.0 range.
--single Write each color decision to a separate file instead of
collections. Converts one input file to multiple output
files.
-v, --verbose Enable verbose output with detailed processing information
--debug Enable debug output with extensive diagnostic information
--sop-tag {SOPNode,ASC_SOP}
XML tag name for SOP nodes. Default: SOPNode. Use 'ASC_SOP' for ASC CDL specification compliance.
--sat-tag {SatNode,SATNode,ASC_SAT}
XML tag name for Saturation nodes. Default: SatNode. Use 'SATNode' for legacy behavior (pre-v1.0) or 'ASC_SAT' for ASC CDL specification compliance.
--input-encoding INPUT_ENCODING
Character encoding for reading input files. Default: auto-detect from XML declaration for XML files, UTF-8 for others. Specify to override auto-detection. Examples: utf-8, latin-1, iso-8859-1, cp1252
--output-encoding OUTPUT_ENCODING
Character encoding for writing output files. Default: utf-8. Examples: utf-8, latin-1, iso-8859-1, cp1252
Supported input formats: ale, cc, ccc, cdl, edl, flex, otio, rcdl
Supported output formats: cc, ccc, cdl, rcdl