Color Decisions

Color Decisions are the mechanism for linking color corrections with media references in ASC CDL workflows. They provide the bridge between the color correction data and the actual media files being graded.

Overview

A ColorDecision is a container that associates:

ColorDecisions are typically found within ColorCollection objects when working with CDL (ColorDecisionList) format files, but can be created and used independently.

When to Use ColorDecision

Use ColorDecision when you need to:

  • Link color corrections to specific media files or sequences

  • Work with CDL (ColorDecisionList) format files

  • Reference the same ColorCorrection from multiple locations

  • Maintain media file paths alongside color correction data

Use plain ColorCorrection when:

  • Working with simple color correction data without media references

  • Exporting to CCC (ColorCorrectionCollection) format

  • You don’t need to track which media files the corrections apply to

Creating ColorDecision

Basic Creation

Create a ColorDecision by providing a ColorCorrection and optional MediaRef:

import cdl_convert as cdl

# Create a color correction
cc = cdl.ColorCorrection(id='shot_001')
cc.slope = (1.2, 1.1, 1.0)
cc.offset = (0.01, -0.02, 0.0)
cc.power = (1.0, 1.0, 0.95)
cc.sat = 1.1

# Create a media reference
media = cdl.MediaRef('footage/shot_001.0001.exr')

# Create the color decision linking them together
decision = cdl.ColorDecision(cc, media_ref=media)

Creating Without Media Reference

ColorDecisions can exist without media references:

cc = cdl.ColorCorrection(id='master_grade')
cc.slope = (1.1, 1.0, 0.9)

# Create decision without media reference
decision = cdl.ColorDecision(cc)

Adding Media Reference Later

You can add or change the media reference after creation:

decision = cdl.ColorDecision(cc)

# Add media reference later
media = cdl.MediaRef('renders/final_v01.mov')
decision.media_ref = media

Working with ColorDecision

Accessing the ColorCorrection

Access the contained ColorCorrection through the cc property:

>>> decision.cc.id
'shot_001'
>>> decision.cc.slope
(Decimal('1.2'), Decimal('1.1'), Decimal('1.0'))
>>> decision.cc.sat
Decimal('1.1')

Accessing the MediaRef

Access the media reference through the media_ref property:

>>> decision.media_ref.ref
'footage/shot_001.0001.exr'
>>> decision.media_ref.is_seq
True
>>> decision.media_ref.seq
'shot_001.####.exr'

Descriptions and Metadata

ColorDecision inherits description capabilities from base classes:

# Add descriptions
decision.desc = 'Hero shot with practical lighting'
decision.desc = 'Increased warmth in highlights'

# Set input and viewing descriptions
decision.input_desc = 'LogC from Alexa'
decision.viewing_desc = 'Rec709 on Eizo CG319X'

# Access descriptions
>>> decision.desc
['Hero shot with practical lighting', 'Increased warmth in highlights']

ColorCorrectionRef - Referencing Existing Corrections

ColorCorrectionRef allows you to reference an existing ColorCorrection by ID rather than duplicating it. This is useful when the same color correction applies to multiple media files.

Creating References

# Create the original color correction
cc = cdl.ColorCorrection(id='day_exterior_grade')
cc.slope = (1.15, 1.05, 0.95)
cc.sat = 1.2

# Create multiple decisions referencing the same correction
ref1 = cdl.ColorCorrectionRef('day_exterior_grade')
decision1 = cdl.ColorDecision(ref1, media_ref=cdl.MediaRef('shot_010.mov'))

ref2 = cdl.ColorCorrectionRef('day_exterior_grade')
decision2 = cdl.ColorDecision(ref2, media_ref=cdl.MediaRef('shot_011.mov'))

ref3 = cdl.ColorCorrectionRef('day_exterior_grade')
decision3 = cdl.ColorDecision(ref3, media_ref=cdl.MediaRef('shot_012.mov'))

Resolving References

Access the actual ColorCorrection through the reference:

>>> ref = cdl.ColorCorrectionRef('day_exterior_grade')
>>> ref.id
'day_exterior_grade'
>>> ref.cc.slope
(Decimal('1.15'), Decimal('1.05'), Decimal('0.95'))

Checking if ColorDecision Contains a Reference

>>> decision1.is_ref
True
>>> decision_with_direct_cc.is_ref
False

Reference Validation

By default, references don’t need to point to existing ColorCorrections when created. Enable strict validation:

import cdl_convert as cdl

# Enable strict error checking
cdl.config.HALT_ON_ERROR = True

# This will raise ValidationError if 'nonexistent_id' doesn't exist
try:
    ref = cdl.ColorCorrectionRef('nonexistent_id')
except cdl.ValidationError as e:
    print(f"Reference validation failed: {e}")

Using ColorDecisions in Collections

ColorDecisions are typically used within ColorCollections:

# Create a collection
collection = cdl.ColorCollection()
collection.type = 'cdl'  # ColorDecisionList format

# Create multiple decisions
cc1 = cdl.ColorCorrection(id='shot_100')
cc1.slope = (1.1, 1.0, 0.9)
decision1 = cdl.ColorDecision(cc1, media_ref=cdl.MediaRef('shot_100.mov'))

cc2 = cdl.ColorCorrection(id='shot_101')
cc2.slope = (1.2, 1.1, 1.0)
decision2 = cdl.ColorDecision(cc2, media_ref=cdl.MediaRef('shot_101.mov'))

# Add decisions to collection
collection.append_child(decision1)
collection.append_child(decision2)

# Access decisions
>>> collection.color_decisions
[
    <cdl_convert.decision.ColorDecision object at 0x...>,
    <cdl_convert.decision.ColorDecision object at 0x...>
]

Parsing ColorDecisions from Files

When parsing CDL files, ColorDecisions are automatically created:

# Parse a CDL file
collection = cdl.parse_cdl('timeline.cdl')

# Access the color decisions
for decision in collection.color_decisions:
    print(f"ID: {decision.cc.id}")
    if decision.media_ref:
        print(f"Media: {decision.media_ref.ref}")
    print(f"Slope: {decision.cc.slope}")
    print()

Writing ColorDecisions

Writing to CDL Format

ColorDecisions with media references are preserved when writing to CDL format:

collection = cdl.ColorCollection()
collection.type = 'cdl'

# Add decisions with media references
decision = cdl.ColorDecision(
    cdl.ColorCorrection(id='shot_001'),
    media_ref=cdl.MediaRef('footage/shot_001.mov')
)
collection.append_child(decision)

# Write to CDL format (preserves media references)
collection.determine_dest('cdl', './output/')
cdl.write_cdl(collection)

See Also