API Reference¶
Classes¶
- The class structure of
cdl_convert
mirrors the element structure of the - XML schema for
ccc
,cdl
andcc
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.
AscColorSpaceBase¶
Classes that deal with input and viewer colorspace can subclass from this class
to get the input_desc
and viewing_desc
attributes.
-
class
cdl_convert.base.
AscColorSpaceBase
¶ 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 toNone
. - parse_xml_viewing_desc()
- Parses an ElementTree Element to find & add a ViewingDescription.
If none is found,
viewing_desc
will remain set toNone
.
AscDescBase¶
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.
-
class
cdl_convert.base.
AscDescBase
¶ 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
.
AscXMLBase¶
-
class
cdl_convert.base.
AscXMLBase
¶ 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.
ColorCollection¶
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
.
-
class
cdl_convert.collection.
ColorCollection
(input_file=None)¶ 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 theColorCorrection
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
orcdl
, 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 aColorDecision
, to the respective attribute list, eithercolor_corrections
orcolor_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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
.Here on
ColorCollection
, this is a pointer tobuild_element_ccc()
orbuild_element_cdl()
depending on which type theColorCollection
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 newColorCollection
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 fromAscDescBase
- parse_xml_input_desc()
- Parses an ElementTree Element to find & add an InputDescription.
If none is found,
input_desc
will remain set toNone
. Inherited fromAscColorSpaceBase
- parse_xml_viewing_desc()
- Parses an ElementTree Element to find & add a ViewingDescription.
If none is found,
viewing_desc
will remain set toNone
. Inherited fromAscColorSpaceBase
- reset_members()
- Resets the class level members list.
- set_parentage()
- Sets all child
ColorCorrection
andColorDecision
parent
attribute to point to this instance. - set_to_ccc()
- Switches the
type
of this collection to export accc
style xml collection by default. - set_to_cdl()
- Switches the
type
of this collection to export acdl
style xml collection by default.
ColorCorrection¶
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.
If the id
does match an already created id
and HALT_ON_ERROR
is
not set, the id
assignment will go forward, appending the duplicate
number to the back of the id
. So the 2nd instance of ‘sh100cc’ will
become ‘sh100cc001’.
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.
-
class
cdl_convert.correction.
ColorCorrection
(id, input_file=None)¶ 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 theColorCorrection
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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
. - 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 fromAscDescBase
- parse_xml_input_desc()
- Parses an ElementTree Element to find & add an InputDescription.
If none is found,
input_desc
will remain set toNone
. Inherited fromAscColorSpaceBase
- parse_xml_viewing_desc()
- Parses an ElementTree Element to find & add a ViewingDescription.
If none is found,
viewing_desc
will remain set toNone
. Inherited fromAscColorSpaceBase
- reset_members()
- Resets the class level members list.
ColorCorrectionRef¶
-
class
cdl_convert.decision.
ColorCorrectionRef
(id)¶ Reference marker to a full color correction
This is a fairly basic class that simply contains a reference to a full
ColorCorrection
. Theid
attribute must match theid
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 (likeccc
), attempting to write an empty reference will result in aValueError
(ifHALT_ON_ERROR
is set toTrue
, or simply skip past the reference entirely.Class Attributes:
- members : {str: [:class`ColorCorrectionRef` ]}
- All instanced
ColorCorrectionRef
are added to this member dictionary. MultipleColorCorrectionRef
can share the same reference id, therefore for each reference id key, the members dictionary stores a list ofColorCorrectionRef
instances that share thatid
value.
Attributes:
- cc : (
ColorCorrection
) - If the stored reference resolves to an existing
ColorCorrection
, this attribute will return that node using theresolve_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. IfHALT_ON_ERROR
is set toTrue
, will raise aValueError
if set to aColorCorrection
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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
. - 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 toTrue
, resolving a bad reference will raise aValueError
exception. If not set, it will simply return None.Otherwise (if the
id
attribute matches a knownColorCorrection
id
, theColorCorrection
will be returned.
ColorDecision¶
ColorDecision’s are normally found only within ColorCorrection
but
this limitation of the ASC CDL schema is not enforced by cdl_convert.
-
class
cdl_convert.decision.
ColorDecision
(color_correct=None, media=None)¶ Contains a media ref and a ColorCorrection or reference to CC.
This class is a simple container to link a
ColorCorrection
(orColorCorrectionRef
) with aMediaRef
. TheMediaRef
is optional, the ColorCorrection is not. The ColorCorrection does not need to be provided at initialization time however, asColorDecision
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 containedColorCorrection
orColorCorrectionRef
MultipleColorDecision
can , therefore for each reference id key, the members dictionary stores a list ofColorDecision
instances that share thatid
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 aColorCorrection
- media_ref : (
MediaRef
) - Returns the contained
MediaRef
or None. - parent : (
ColorDecisionList
) - The parent node that contains this node.
- set_parentage()
- Sets child
ColorCorrection
(orColorCorrectionRef
) andMediaRef
(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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
. - 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 fromAscDescBase
- parse_xml_input_desc()
- Parses an ElementTree Element to find & add an InputDescription.
If none is found,
input_desc
will remain set toNone
. Inherited fromAscColorSpaceBase
- 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 toNone
. Inherited fromAscColorSpaceBase
- reset_members()
- Resets the class level members list.
ColorNodeBase¶
This class only exists to be subclassed by SatNode
and SopNode
and should not be used directly.
-
class
cdl_convert.base.
ColorNodeBase
¶ Base class for SOP and SAT nodes.
This class is meant only to be inherited by
SopNode
andSatNode
and should not be used outside of those classes.It inherits from both
AscDescBase
andAscXMLBase
giving the child classes bothdesc
andxml
related functionality.This class is also home to a private function which helps
SopNode
andSatNode
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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
. - parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends
any text they contain to the
desc
. Inherited fromAscDescBase
MediaRef¶
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.
-
class
cdl_convert.decision.
MediaRef
(ref_uri, parent=None)¶ 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 optionalparent
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 aColorDecision
, and in fact the CDL specification states that no other container is allowed to contain aMediaRef
. 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 multipleMediaRef
point to the same reference URI, the value returned is a list ofMediaRef
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 thisMediaRef
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 aColorDecision
, 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 toref
. - 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 todirectory
. - 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 ifref
points to a directory. To get a list of all image sequences found, useseqs
.Only if a reference was given to us already in the form of
%d
padding willseq
andseqs
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. Ifref
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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
. - reset_members()
- Resets the class level members list.
- members : {str: [
SatNode¶
Note
This class is meant only to be created by a ColorCorrection
,
and thus has the required arg of parent
when instantiating it.
-
class
cdl_convert.correction.
SatNode
(parent)¶ 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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
. - parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends
any text they contain to the
desc
. Inherited fromAscDescBase
SopNode¶
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]
.
-
class
cdl_convert.correction.
SopNode
(parent)¶ 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
, andxml_root
attributes use this to build the XML. This function is identical to calling theelement
attribute. Overrides inherited placeholder method fromAscXMLBase
. - parse_xml_descs()
- Parses an ElementTree Element for any Description tags and appends
any text they contain to the
desc
. Inherited fromAscDescBase
General Functions¶
Reset All¶
Resets all the class level lists and dictionaries of cdl_convert. Calling this
is the same as calling each individual reset_members
method.
-
cdl_convert.
reset_all
()¶ Resets all class level member lists and dictionaries
Sanity Check¶
-
cdl_convert.utils.
sanity_check
(colcor)¶ Checks values on
ColorCorrection
for sanity.- Args:
- colcor : (
ColorCorrection
) - The
ColorCorrection
to check for sane values.
- colcor : (
- Returns:
- (bool)
- Returns True if all values are sane.
- Raises:
- N/A
Will print a warning to stdout if any values exceed normal limits. Normal limits are defined as:
- For Slope, Power and Saturation:
- Any value over 3 or under 0.1
- For Offset:
- Any value over 1 or under -1
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.
To Decimal¶
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.
-
cdl_convert.utils.
to_decimal
(value, name='Value')¶ Converts an incoming value to Decimal in the best way
- Args:
- value : (Decimal|str|float|int)
- Any numeric value to be checked.
- name=’Value’ : (str)
- The type of value being checked: slope, offset, etc.
- Returns:
- (Decimal)
- If value passes all tests, returns value as Decimal.
- Raises:
- TypeError:
- If value given is not a number.
- ValueError:
- If given a value that isn’t an allowed type.
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 ale¶
-
cdl_convert.parse.
parse_ale
(input_file)¶ Parses an Avid Log Exchange (ALE) file for CDLs
- Args:
- input_file : (str)
- The filepath to the ALE EDL
- Returns:
- (
ColorCollection
) - A collection that contains all found ColorCorrections
- (
- Raises:
- N/A
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.
Parse cc¶
-
cdl_convert.parse.
parse_cc
(input_file)¶ Parses a .cc file for ASC CDL information
- Args:
- input_file : (str|<ElementTree.Element>)
- The filepath to the CC or the
ElementTree.Element
object.
- Returns:
- (
ColorCorrection
) - The
ColorCorrection
described within.
- (
- Raises:
- ValueError:
- Bad XML formatting can raise ValueError is missing required elements.
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.
Parse ccc¶
-
cdl_convert.parse.
parse_ccc
(input_file)¶ Parses a .ccc file into a
ColorCollection
with type ‘ccc’- Args:
- input_file : (str)
- The filepath to the CCC.
- Returns:
- (
ColorCollection
) - A collection of all the found
ColorCorrection
as well as any metadata within the XML
- (
- Raises:
- ValueError:
- Bad XML formatting can raise ValueError is missing required elements.
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.
Parse cdl¶
-
cdl_convert.parse.
parse_cdl
(input_file)¶ Parses a .cdl file into a
ColorCollection
with type ‘cdl’- Args:
- input_file : (str)
- The filepath to the CDL.
- Returns:
- (
ColorCollection
) - A collection of all the found
ColorDecisions
as well as any metadata within the XML
- (
- Raises:
- ValueError:
- Bad XML formatting can raise ValueError is missing required elements.
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.
Parse cmx¶
-
cdl_convert.parse.
parse_cmx
(input_file)¶ Parses a CMX EDL file for ASC CDL information.
- Args:
- input_file : (str)
- The filepath to the CMX EDL
- Returns:
- (
ColorCollection
) - A collection that contains all the ColorCorrection objects found within this EDL
- (
- Raises:
- N/A
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
Parse file¶
Passes on the file to the correct parser.
-
cdl_convert.parse.
parse_file
(filepath, filetype=None)¶ Determines & uses the correct parser to use on a CDL file
- Args:
- filepath : (str)
- The filepath to the file. Must exist.
- filetype=None : (str)
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 ‘.’
- Raises:
- N/A
- Returns:
ColorCorrection
orColorCollection
- Depending on the type of input file, this function will
either return a single
ColorCorrection
or a fullColorCollection
, containing one or moreColorCorrection
orColorDecision
Parse flex¶
-
cdl_convert.parse.
parse_flex
(input_file)¶ Parses a DaVinci FLEx telecine EDL for ASC CDL information.
- Args:
- input_file : (str)
- The filepath to the FLEx EDL
- Returns:
- (
ColorCollection
) - A collection that contains all the ColorCorrection objects found within this EDL
- (
- Raises:
- N/A
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.
Parse Rhythm & Hues cdl¶
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.
-
cdl_convert.parse.
parse_rnh_cdl
(input_file)¶ Parses a space separated .cdl file for ASC CDL information.
- Args:
- input_file : (str)
- The filepath to the CDL
- Returns:
- (
ColorCorrection
) - The single ColorCorrection object retrieved from the beta CDL
- (
- Raises:
- N/A
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
Write Functions¶
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.
Write Rhythm & Hues cdl¶
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.
-
cdl_convert.write.
write_rnh_cdl
(cdl)¶ Writes the ColorCorrection to a space separated .cdl file