Note
All code for the following lives under cdl_convert.cdl_convert, and is imported into the local space of cdl_convert.
The class structure of cdl_convert mirrors the element structure of the defined XML schema for ccc, cdl and cc files as defined by the ASC. The XML schema’s represent the most complicated and structured variant of the format, and therefore it behooves the project to mimic their structure.
However, where similar elements exist as entirely separate entities in the XML schema, they might have been combined here.
Classes that deal with input and viewer colorspace can subclass from this class to get the input_desc and viewing_desc attributes.
Note
This class is a stub for now. In the future it will have colorspace related functionality.
Base class for Asc XML type nodes that deal with colorspace
This class is meant to be inherited by any node type that used viewing and input colorspace descriptions.
This class doesn’t do a lot right now, as we don’t have any specific controls on how to set or retrieve these fields. In the future however, we’ll parse incoming descriptions to try and resolve input colorspace and viewing colorspace.
Attributes:
- input_desc : (str)
- Description of the color space, format and properties of the input images. Individual ColorCorrections can override this.
- viewing_desc : (str)
- Viewing device, settings and environment. Individual ColorCorrections can override this.
Classes that are allowed to have a description field subclass from this from this class to get the desc attribute. The desc attribute can be set with a single string, which will append to the list of strings already present in desc. If set to a list or tuple, desc will become a list of those values. If set to None, desc will become an empty list.
Base class for most Asc XML type nodes, allows for infinite desc
This class is meant to be inherited by any node type that uses description fields.
Attributes:
- desc : [str]
Since all Asc nodes which can contain a single description, can actually contain an infinite number of descriptions, the desc attribute is a list, allowing us to store every single description found during parsing.
Setting desc directly will cause the value given to append to the end of the list, but desc can also be replaced by passing it a list or tuple. Desc can be emptied by passing it None, [] or ().
ColorDecisionList and ColorCollection use this class as a a base class, since they both are collections of other more specific classes.
Base class for ColorDecisionList and ColorCorrectionCollection.
Collections need to store children and have access to descriptions, input descriptions, and viewing descriptions.
Inherits desc attribute and setters from AscDescBase
Inherits input_desc and viewing_desc from AscColorSpaceBase
Attributes:
- input_desc : (str)
- Description of the color space, format and properties of the input images. Individual ColorCorrections can override this.
- viewing_desc : (str)
- Viewing device, settings and environment. Individual ColorCorrections can override this.
The ColorCorrection class is the backbone of cdl_convert, as it represents the basic level of the color decision list concept- the color decision list itself. All the parse functions exist to extract the CDL metadata and populate this class, and all the write functions exist to write files out from this class.
Parser –> ColorCorrection –> Writer
ColorCorrection can of course be instantiated and used without a parse function, see Usage for a walkthrough.
Warning
When an instance of ColorCorrection is first created, the id provided is checked against a class level dictionary variable named members to ensure that no two ColorCorrection share the same id , as this is required by the specification.
If the id given is a blank string and HALT_ON_ERROR is set to False, id will be set to the total number of ColorCorrection in the file, including the one currently being created. This behavior is not accepted when changing the id after creation.
Warning
cdl_file is likely to not be a required attribute in the future.
The basic class for the ASC CDL
This class contains attributes for all 10 color correction numbers needed for an ASC CDL, as well as other metadata like shot names that typically accompanies a CDL.
These names are standardized by the ASC and where possible the attribute names will follow the ASC schema. Descriptions for some of these attributes are paraphrasing the ASC CDL documentation. For more information on the ASC CDL standard and the operations described below, you can obtain the ASC CDL implementor-oriented documentation by sending an email to: asc-cdl at theasc dot com
Order of operations is Slope, Offset, Power, then Saturation.
Inherits desc attribute and setters from AscDescBase
Inherits input_desc and viewing_desc from AscColorSpaceBase
Class Attributes:
- members : {str: :class`ColorCorrection`}
- All instanced ColorCorrection are added to this member dictionary, with their unique id being the key and the ColorCorrection being the value.
Attributes:
- file_in : (str)
- Filepath used to create this CDL.
- file_out : (str)
- Filepath this CDL will be written to.
- id : (str)
Unique XML URI to identify this CDL. Often a shot or sequence name.
Changing this value does a check against the cls.members dictionary to ensure the new id is open. If it is, the key is changed to the new id and the id is changed.
Note that this shadows the builtin id.
- sat_node : ( SatNode )
- Contains a reference to a single instance of SatNode , which contains the saturation value and descriptions.
- sop_node : ( SopNode )
- Contains a reference to a single instance of SopNode , which contains the slope, offset, power values and descriptions.
This class only exists to be subclassed by SatNode and SopNode and should not be used directly.
Base class for SOP and SAT nodes.
Inherits desc from AscDescBase
Media Ref’s are normally found only inside of ColorDecision, which itself is found only inside of the ColorDecisionList collection. This isn’t a restriction that cdl_convert explicitly enforces, but the parse and write functions will only be creating and writing found MediaRef objects following the rules.
Where possible when writing filetypes that don’t support MediaRef, the information kept in MediaRef will be converted into description field metadata and preserved in that way.
MediaRef is meant to provide a convenient interface for managing and interpreting data stored in CDLs. You can change a broken absolute link directory to a relative link without touching the filename, or retrieve a full list of image sequences contained within a referenced directory.
A directory of files or a single file used for grade reference
MediaRef is a container for an image path that should be referenced in regards to the color correction being performed. What that reference means must be further clarified, either through communication or Description fields.
Requires a ref_uri and an optional parent to instantiate.
An XML URI is usually a filepath to a directory or file, sometimes proceeded by a protocol (such as http://). Note that many of the functions and methods described below do not function properly when given a URI with a protocol in front.
The parent of a MediaRef should typically be a ColorDecision , and in fact the CDL specification states that no other container is allowed to contain a MediaRef. That restriction is not enforced here, but writers for .ccc and .cc will only pass through MediaRef as Description entries.
Class Attributes:
- members : {str: [MediaRef]}
All instances of MediaRef are added to this class level members dictionary, with the key being the full reference URI. Since it’s possible that multiple MediaRef point to the same reference URI, the value returned is a list of MediaRef that all have a value of that same URI.
When you change a single MediaRef ref attribute, it removes itself from the old key’s list, and adds itself to the new key’s list. The old key is removed from the dictionary if this MediaRef was the last member.
Attributes:
- directory : (str)
- The directory portion of the URI, without the protocol or filename.
- exists : (bool)
- True if the path is present in the file system.
- filename : (str)
- The filename portion of the URI, without any protocol or directory.
- is_abs : (bool)
- True if directory is an absolute reference.
- is_dir : (bool)
- True if path points to a directory with no filename portion.
- is_seq : (bool)
True if path points to an image sequence or a directory of image sequences. Image sequences are determined by files ending in a dot or underscore, followed by an integer, followed by the file extension. If the filename reference given already has pound padding or %d indication padding, this will also return true.
- Valid image sequences:
- TCM100X_20140215.0001.exr
- Bobs Big_Score_2.jpg
- 2383-279873.67267_32t7634.63278623781638218763.exr
- 104fl.x034.######.dpx
- 104fl.x034_%06d.dpx
- parent : (ColorDecision)
- The parent that contains this MediaRef object. This should normally be a ColorDecision , but that is not enforced.
- path : (str)
- The directory joined with the filename via os.path.join(), if there is no filename, path is identical to directory. If there is no protocol, path is identicial to ref.
- protocol : (str)
- The URI protocol section of the URI, if any. This is the section that proceeds the ‘://’ of any URI. If there is no ‘://’ in the given URI, this is empty.
- ref : (str)
- The full URI reference which includes the protocol, directory and filename. If there is no protocol and no filename, ref is identical to directory.
- seq : (str)
If is_seq finds that the filename or directory refers to one or more image sequences, seq will return the first found sequence in the form of filename.####.ext (or filename_####.ext if the sequence has an _ in front of the frame numbers). Note that there may be more than one image sequence if ref points to a directory. To get a list of all image sequences found, use seqs.
Only if a reference was given to us already in the form of %d padding will seq and seqs return a sequence filename with %d padding.
- seqs : [str]
- Returns all found sequences in a list. If ref points to a filename, this list will only contain one sequence. If ref points to a directory, all sequences found in that directory will be in this list.
Note
This class is meant only to be created by a container CDL format, and thus has the required arg of parent when instantiating it.
Color node that contains saturation data.
Class Attributes:
- element_names : [str]
- Contains a list of XML Elements that refer to this class for use in parsing XML files.
Attributes:
- parent : ( ColorCorrection )
- The parent ColorCorrection instance that created this instance.
- sat : (float)
The saturation value (to be applied with Rec 709 coefficients) is stored here. Saturation is the last operation to be applied when applying a CDL.
sat can be set with a float, int or numeric string.
Note
This class is meant only to be created by a container CDL format, and thus has the required arg of parent when instantiating it.
Warning
Setting any of the sop node values with a single value as in offset = 5.4 will cause that value to be copied over all 3 colors, resulting in [5.4, 5.4, 5.4].
Color node that contains slope, offset and power data.
slope, offset and saturation are stored internally as lists, but always returned as tuples to prevent index assignment from being successful. This protects the user from inadvertently setting a single value in the list to be a non-valid value, which might result in values not being floats or even numbers at all.
Class Attributes:
- element_names : [str]
- Contains a list of XML Elements that refer to this class for use in parsing XML files.
Attributes:
- parent : ( ColorCorrection )
- The parent ColorCorrection instance that created this instance.
- slope : (float, float, float)
An rgb tuple representing the slope, which changes the slope of the input without shifting the black level established by the offset. These values must be positive. If you set this attribute with a single value, it will be copied over all 3 colors. Any single value given can be a float, int or numeric string.
default: (1.0, 1.0, 1.0)
- offset : (float, float, float)
An rgb tuple representing the offset, which raises or lowers the input brightness while holding the slope constant. If you set this attribute with a single value, it will be copied over all 3 colors. Any single value given can be a float, int or numeric string.
default: (0.0, 0.0, 0.0)
- power : (float, float, float)
An rgb tuple representing the power, which is the only function that changes the response curve of the function. Note that this has the opposite response to adjustments than a traditional gamma operator. These values must be positive. If you set this attribute with a single value, it will be copied over all 3 colors. Any single value given can be a float, int or numeric string.
default: (1.0, 1.0, 1.0)
These functions create and return one of more ColorCorrection, always returning their results in the form of a list, even if the file type can only produce a single cdl.
Parses an Avid Log Exchange (ALE) file for CDLs
An ALE file is traditionally gathered during a telecine transfer using standard ASCII characters. Each line theoretically represents a single clip/take/shot.
Each field of data is tab delineated. We’ll be searching for the ASC_SOP, ASC_SAT fields, alone with the standard Scan Filename fields.
The Data line indicates that all the following lines are comprised of shot information.
Parses a .cc file for ASC CDL information
A CC file is really only a single element of a larger CDL or CCC XML file, but this element has become a popular way of passing around single shot CDLs, rather than the much bulkier CDL file.
A sample CC XML file has text like:
<ColorCorrection id="cc03340">
<SOPNode>
<Description>change +1 red, contrast boost</Description>
<Slope>1.2 1.3 1.4</Slope>
<Offset>0.3 0.0 0.0</Offset>
<Power>1.0 1.0 1.0</Power>
</SOPNode>
<SatNode>
<Saturation>1.2</Saturation>
</SatNode>
</ColorCorrection>
Additional elements can include multiple descriptions at every level, a description of the input colorspace, and a description of the viewing colorspace and equipment.
Parses a space separated .cdl file for ASC CDL information.
A space separated cdl file is an internal Rhythm & Hues format used by the Rhythm & Hues for displaying shot level and sequence level within their internally developed playback software.
The file is a simple file consisting of one line. That line has 10, space separated elements that correspond to the ten ASC CDL elements in order of operations.
SlopeR SlopeG SlopeB OffsetR OffsetG OffsetB PowerR PowerG PowerB Sat
Parses a DaVinci FLEx telecine EDL for ASC CDL information.
The DaVinci FLEx EDL is an odd duck, it’s information conveyed via an extremely strict line & character addressing system.
Each line must begin with a line number header that indicated what type of information the line contains, with line number 100 indicating the start of a new shot/take. Lines 000-099 contain session information.
Within each line, important information is constricted to a certain range of characters, rather than space or comma separated like in an ALE EDL.
Some line numbers we care about, and the character indexes:
| Line # | Line Name | Char Index | Data Type |
|---|---|---|---|
| 010 | Project Title | 10-79 | Title |
| 100 | Slate Info | 10-17 | Scene |
| 24-31 | Take ID | ||
| 42-49 | Camera Reel ID | ||
| 701 | ASC SOP | (This entry can be safely space separated) | |
| 702 | ASC SAT | (This entry can be safely space separated) | |
We’ll try and default to using the Slate information to derive the resultant filename, however that information is optional. If no slate information is found, we’ll iterate up at the end of the title. If no title information is found, we’ll have to iterate up on the actual input filename, which is far from ideal.
Each of these functions takes an ColorCorrection as an arg, then places as many attributes of the ColorCorrection that the format supports into a properly formatted string or XML Tree, then writes that file.