Note
All code for the following lives under cdl_convert.cdl_convert, and is imported into the local space of cdl_convert.
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.
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.
Public Methods:
- parse_xml_input_desc()
- Parses an ElementTree Element to find & add an InputDescription. If none is found, input_desc will remain set to None.
- parse_xml_viewing_desc()
- Parses an ElementTree Element to find & add a ViewingDescription. If none is found, viewing_desc will remain set to None.
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 ().
Public Methods:
- parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends any text they contain to the desc.
Base class for nodes which can be converted to XML Elements
This class contains several convenience attributes which can be used to retrieve ElementTree Elements, or nicely formatted strings.
Attributes:
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node.
- xml : (str)
- A nicely formatted XML string representing the node.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line.
Public Methods:
- build_element()
- A placeholder method to be overridden by inheriting classes, calling it will always return None.
This class functions as both a ColorDecisionList and a ColorCorrectionCollection. It’s children can be either ColorDecisions, ColorCorrections, or a combination of the two. Despite being able to have either type of child, the ColorCollection still needs to know which type of collection you want it to represent.
Setting the type of the ColorCollection to either ccc or cdl causes children of the opposite type to be converted into the appropriate type when exporting the class.
Note
parse_ale and parse_flex both return as a ccc at this time, contrary to the documentation below.
In addition, the inclusion of parent metadata into orphaned children is also a work in progress.
If parse_ale is used to parse an ale edl file, the ale will be read into a ColorCollection set to cdl and the children the ale creates will actually be ColorDecision , as that allows for the easy inclusion of MediaRef objects. If you then use write_ccc to write a ccc file, all the children ColorDecision will create XML elements for their ColorCorrection children, adding in any MediaRef that were found as Description elements. Finally the ColorCollection type is set to ccc and the xml_root field is called, which knows to return a ccc style XML element to write_ccc.
Container class for ColorDecisionLists and ColorCorrectionCollections.
Collections need to store children and have access to descriptions, input descriptions, and viewing descriptions.
Class Attributes:
- members : [ :class`ColorCollection` ]
All instanced ColorCollection are added to this member list. Unlike the ColorCorrection member’s dictionary, ColorCollection do not need any unique values to exist.
This is currently only used for determining an id value when exporting and no file_in attribute is set.
Attributes:
- all_children : (ColorCorrection, ColorDecision)
- A tuple of all the children of this collection, both Corrections and Decisions.
- color_corrections : (ColorCorrection)
- All the ColorCorrection children are listed here.
- color_decisions : (ColorDecision)
- All the ColorDecision children are listed here.
- 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 ().
Inherited from AscDescBase .
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node. Inherited from AscXMLBase .
- file_in : (str)
- Filepath used to create this ColorCollection .
- file_out : (str)
- Filepath this ColorCollection will be written to.
- input_desc : (str)
- Description of the color space, format and properties of the input images. Inherited from AscColorSpaceBase .
- is_ccc : (bool)
- True if this collection currently represents .ccc.
- is_cdl : (bool)
- True if this collection currently represents .cdl.
- type : (str)
- Either ccc or cdl, represents the type of collection this class currently will export by default.
- viewing_desc : (str)
- Viewing device, settings and environment. Inherited from AscColorSpaceBase .
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
- xmlns : (str)
- Describes the version of the ASC XML Schema that cdl_convert writes out to files following the full schema (.ccc and .cdl)
Public Methods:
- append_child()
- Appends the given object, either a ColorCorrection or a ColorDecision , to the respective attribute list, either color_corrections or color_decision depending on the class of the object passed in.
- append_children()
- Given a list, will iterate through and append each element of that list to the correct child list, using the append_child() method.
- build_element()
Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
Here on ColorCollection , this is a pointer to build_element_ccc() or build_element_cdl() depending on which type the ColorCollection is currently set to.
- build_element_ccc()
- Builds a CCC style XML tree representing this ColorCollection instance.
- build_element_cdl()
- Builds a CDL style XML tree representing this ColorCollection instance.
- copy_collection()
- Creates and returns an exact new instance that’s an exact copy of the current instance. Note that references to the child instances will be copied, but that the child instances themselves will not be.
- merge_collections()
- Merges all members of a list containing ColorCollection and the instance this is called on to return a new ColorCollection that is primarily a copy of this instance, but contains all children and description elements from the given collections. input_desc, viewing_desc, file_in, and type will be set to the values of the parent instance.
- parse_xml_color_corrections()
- Parses an ElementTree element to find & add all ColorCorrection.
- parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends any text they contain to the desc. Inherited from AscDescBase
- parse_xml_input_desc()
- Parses an ElementTree Element to find & add an InputDescription. If none is found, input_desc will remain set to None. Inherited from AscColorSpaceBase
- parse_xml_viewing_desc()
- Parses an ElementTree Element to find & add a ViewingDescription. If none is found, viewing_desc will remain set to None. Inherited from AscColorSpaceBase
- reset_members()
- Resets the class level members list.
- set_parentage()
- Sets all child ColorCorrection and ColorDecision parent attribute to point to this instance.
- set_to_ccc()
- Switches the type of this collection to export a ccc style xml collection by default.
- set_to_cdl()
- Switches the type of this collection to export a cdl style xml collection by default.
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 Script 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.
Reset the members dictionary by either calling the reset_members method on ColorCorrection or by reseting all cdl_convert member lists and dictionaries with the reset_all function.
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.
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:
- 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 ().
Inherited from AscDescBase .
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node. Inherited from AscXMLBase .
- file_in : (str)
- Filepath used to create this ColorCorrection .
- file_out : (str)
- Filepath this ColorCorrection will be written to.
- has_sat : (bool)
- Returns True if SOP values are set
- has_sop : (bool)
- Returns True if SOP values are set
- 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.
- input_desc : (str)
- Description of the color space, format and properties of the input images. Inherited from AscColorSpaceBase .
- parent : (ColorCollection)
- The parent node that contains this node.
- 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.
- viewing_desc : (str)
- Viewing device, settings and environment. Inherited from AscColorSpaceBase .
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
Public Methods:
- build_element()
- Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
- determine_dest()
- When provided an output extension, determines the destination filename to be written to based on file_in & id.
- parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends any text they contain to the desc. Inherited from AscDescBase
- parse_xml_input_desc()
- Parses an ElementTree Element to find & add an InputDescription. If none is found, input_desc will remain set to None. Inherited from AscColorSpaceBase
- parse_xml_viewing_desc()
- Parses an ElementTree Element to find & add a ViewingDescription. If none is found, viewing_desc will remain set to None. Inherited from AscColorSpaceBase
- reset_members()
- Resets the class level members list.
Reference marker to a full color correction
This is a fairly basic class that simply contains a reference to a full ColorCorrection . The id attribute must match the id attribute in order for this class to function fully.
When writing to a format that allows empty references (like cdl), the reference can write correctly without breaking. However, if writing to a format that does not support reference objects at all (like ccc), attempting to write an empty reference will result in a ValueError (if HALT_ON_ERROR is set to True, or simply skip past the reference entirely.
Class Attributes:
- members : {str: [:class`ColorCorrectionRef` ]}
- All instanced ColorCorrectionRef are added to this member dictionary. Multiple ColorCorrectionRef can share the same reference id, therefore for each reference id key, the members dictionary stores a list of ColorCorrectionRef instances that share that id value.
Attributes:
- cc : (ColorCorrection)
- If the stored reference resolves to an existing ColorCorrection, this attribute will return that node using the resolve_reference method. This attribute is the same as calling that method.
- parent : (ColorDecision)
- The parent ColorDecision that contains this node.
- id : (str)
- The ColorCorrection id that this reference refers to. If HALT_ON_ERROR is set to True, will raise a ValueError if set to a ColorCorrection id value that doesn’t yet exist.
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
Public Methods:
- build_element()
- Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
- reset_members()
- Resets the class level members list.
- resolve_reference()
Attempts to return the ColorCorrection that this reference is supposed to refer to.
If HALT_ON_ERROR is set to True, resolving a bad reference will raise a ValueError exception. If not set, it will simply return None.
Otherwise (if the id attribute matches a known ColorCorrection id, the ColorCorrection will be returned.
ColorDecision’s are normally found only within ColorCorrection but this limitation of the ASC CDL schema is not enforced by cdl_convert.
Contains a media ref and a ColorCorrection or reference to CC.
This class is a simple container to link a ColorCorrection (or ColorCorrectionRef ) with a MediaRef . The MediaRef is optional, the ColorCorrection is not. The ColorCorrection does not need to be provided at initialization time however, as ColorDecision provides an XML element parser for deriving one.
The primary purpose of a ColorDecision node is to associate a ColorCorrection node with one or more items of Media Reference.
Along with Media Reference, a ColorDecision can contain the normal type of input, viewer and description metadata.
Additional, it is the only node that can contain ColorCorrectionRef nodes, which link the same ColorCorrection to many different ColorDecisions (and thus, many different items of media reference)
An example containing a ColorCorrection node:
<ColorDecision>
<MediaRef ref="http://www.theasc.com/foasc-logo2.png"/>
<ColorCorrection id="ascpromo">
<SOPNode>
<Description>get me outta here</Description>
<Slope>0.9 1.1 1.0</Slope>
<Offset>0.1 -0.01 0.0</Offset>
<Power>1.0 0.99 1.0</Power>
</SOPNode>
</ColorCorrection>
</ColorDecision>
But it can also contain just a reference:
<ColorDecision>
<MediaRef ref="best/project/ever/jim.0100.dpx"/>
<ColorCorrectionRef ref="xf45.x628"/>
</ColorDecision>
Class Attributes:
- members : {str: [ :class`ColorDecision` ]}
- All instanced ColorDecision are added to this member dictionary. The key is the id or reference id of the contained ColorCorrection or ColorCorrectionRef Multiple ColorDecision can , therefore for each reference id key, the members dictionary stores a list of ColorDecision instances that share that id value.
Attributes:
- cc : (ColorCorrection , ColorCorrectionRef)
- Returns the contained ColorCorrection, even if it’s a reference.
- 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 ().
Inherited from AscDescBase .
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node. Inherited from AscXMLBase .
- input_desc : (str)
- Description of the color space, format and properties of the input images. Inherited from AscColorSpaceBase .
- is_ref : (bool)
- True if contains a ColorCorrectionRef object instead of a ColorCorrection
- media_ref : (MediaRef)
- Returns the contained MediaRef or None.
- parent : (ColorDecisionList)
- The parent node that contains this node.
- set_parentage()
- Sets child ColorCorrection (or ColorCorrectionRef) and MediaRef (if present) parent attribute to point to this instance.
- viewing_desc : (str)
- Viewing device, settings and environment. Inherited from AscColorSpaceBase .
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
Public Methods:
- build_element()
- Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
- parse_xml_color_correction()
- Parses a ColorDecision ElementTree Element for a ColorCorrection Element or a ColorCorrectionRef Element.
- parse_xml_color_decision()
- Parses a ColorDecision ElementTree Element for metadata, then calls parsers for ColorCorrection and MediaRef.
- parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends any text they contain to the desc. Inherited from AscDescBase
- parse_xml_input_desc()
- Parses an ElementTree Element to find & add an InputDescription. If none is found, input_desc will remain set to None. Inherited from AscColorSpaceBase
- parse_xml_media_ref()
- Parses an ColorDecision Element for a MediaRef Element.
- parse_xml_viewing_desc()
- Parses an ElementTree Element to find & add a ViewingDescription. If none is found, viewing_desc will remain set to None. Inherited from AscColorSpaceBase
- reset_members()
- Resets the class level members list.
This class only exists to be subclassed by SatNode and SopNode and should not be used directly.
Base class for SOP and SAT nodes.
This class is meant only to be inherited by SopNode and SatNode and should not be used outside of those classes.
It inherits from both AscDescBase and AscXMLBase giving the child classes both desc and xml related functionality.
This class is also home to a private function which helps SopNode and SatNode perform type and value checks on incoming values.
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 ().
Inherited from AscDescBase .
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node. Inherited from AscXMLBase .
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
Public Methods:
- build_element()
- Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
- parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends any text they contain to the desc. Inherited 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.
Note
The above metadata preservation is not yet implemented.
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 in the python API.
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.
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node. Inherited from AscXMLBase .
- 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.
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
Public Methods:
- build_element()
- Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
- reset_members()
- Resets the class level members list.
Note
This class is meant only to be created by a ColorCorrection , 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:
- 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 ().
Inherited from AscDescBase .
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node. Inherited from AscXMLBase .
- parent : ( ColorCorrection )
- The parent ColorCorrection instance that created this instance.
- sat : (Decimal)
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 Decimal, float, int or numeric string.
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
Public Methods:
- build_element()
- Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
- parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends any text they contain to the desc. Inherited from AscDescBase
Note
This class is meant only to be created by a ColorCorrection , 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 Decimals 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:
- 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 ().
Inherited from AscDescBase .
- element : (<xml.etree.ElementTree.Element>)
- etree style Element representing the node. Inherited from AscXMLBase .
- parent : ( ColorCorrection )
- The parent ColorCorrection instance that created this instance.
- slope : (Decimal, Decimal, Decimal)
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 Decimal, float, int or numeric string.
default: (Decimal(‘1.0’), Decimal(‘1.0’), Decimal(‘1.0’))
- offset : (Decimal, Decimal, Decimal)
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 Decimal, float, int or numeric string.
default: (Decimal(‘0.0’), Decimal(‘0.0’), Decimal(‘0.0’))
- power : (Decimal, Decimal, Decimal)
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 Decimal, float, int or numeric string.
default: (Decimal(‘1.0’), Decimal(‘1.0’), Decimal(‘1.0’))
- xml : (str)
- A nicely formatted XML string representing the node. Inherited from AscXMLBase.
- xml_root : (str)
- A nicely formatted XML, ready to write to file string representing the node. Formatted as an XML root, it includes the xml version and encoding tags on the first line. Inherited from AscXMLBase.
Public Methods:
- build_element()
- Builds an ElementTree XML Element for this node and all nodes it contains. element, xml, and xml_root attributes use this to build the XML. This function is identical to calling the element attribute. Overrides inherited placeholder method from AscXMLBase .
- parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends any text they contain to the desc. Inherited from AscDescBase
Resets all the class level lists and dictionaries of cdl_convert. Calling this is the same as calling each individual reset_members method.
Resets all class level member lists and dictionaries
Checks values on ColorCorrection for sanity.
Will print a warning to stdout if any values exceed normal limits. Normal limits are defined as:
Note that depending on the desired look for a shot or sequence, it’s possible that a single ColorCorrection element might have very odd looking values and still achieve a correct look.
This is the function we use to convert ints, floats and strings to Decimal objects. We do NOT attempt to use maximum accuracy on floats passed in, as that results in extremely long values more often than not. Better to just truncate the float with a string conversion, than attempt to perfectly represent with a Decimal.
Converts an incoming value to Decimal in the best way
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.
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 .ccc file into a ColorCollection with type ‘ccc’
A ColorCorrectionCollection is just that- a collection of ColorCorrection elements. It does not contain any ColorDecision or MediaRef elements, but is free to contain as many Description elements as someone adds in.
It should also contain an InputDescription element, describing the color space and other properties of the incoming image, as well as a ViewingDescription which describes the viewing environment as well as any relevant hardware devices used to view or grade.
Parses a .cdl file into a ColorCollection with type ‘cdl’
A ColorDecicionList is just that- a list of ColorDecision elements. It does not directly contain any ColorCorrections or Media Ref, only ColorDecisions, but is free to contain as many Description elements as someone adds in.
It should also contain an InputDescription element, describing the color space and other properties of the incoming image, as well as a ViewingDescription which describes the viewing environment as well as any relevant hardware devices used to view or grade.
Passes on the file to the correct parser.
Determines & uses the correct parser to use on a CDL file
A file extension corresponding to the CDL type to convert from. If not provided, we’ll derive it from the filepath.
Should not include a ‘.’
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.
Rhythm & Hues’ implementation of the cdl format is based on a very early spec, and as such lacks the all metadata. It’s extremely unlikely that you’ll run into this format in the wild.
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
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.
This writes a very sparse cdl format that is based on a very early spec of the cdl implementation. It lacks all metadata. Unless you work at Rhythm & Hues, you probably don’t want to write a cdl that uses this format.
Writes the ColorCorrection to a space separated .cdl file