/cdl_convert

Converts between common ASC Color Decision List (CDL) formats

Primary LanguagePythonOtherNOASSERTION

CDL Convert

PyPI VersionBuild StatusCoverage StatusCode Health

Introduction

cdl_convert converts between common ASC CDL formats. The American Society of Cinematographers Color Decision List (ASC CDL, or CDL for short) is a schema to simplify the process of interchanging color data between various programs and facilities.

The ASC has defined schemas for including the 10 basic numbers in 5 different formats:

  • Avid Log Exchange (ALE)
  • Film Log EDL Exchange (FLEx)
  • CMX EDL
  • XML Color Correction (cc)
  • XML Color Correction Collection (ccc)
  • XML Color Decision List (cdl)

Unofficial Formats:

  • OCIOCDLTransform, a Foundry Nuke node
  • Space separated CDL, a Rhythm & Hues internal cdl format

It is the purpose of cdl_convert to convert ASC CDL information between these basic formats to further facilitate the ease of exchange of color data within the Film and TV industries.

cdl_convert supports parsing ALE, FLEx, CC, CCC, CDL CMX EDL and RCDL. We can write out CC, CCC, CDL and RCDL.

cdl_convert is not associated with the American Society of Cinematographers

Usage

Most likely you'll use cdl_convert as a script, instead of a python package itself (indeed, even the name is formatted more like a script (with an underscore) than the more common all lowercase of python modules.

For usage as a python module, see the module documentation.

Script Usage

If you just want to convert to a .cc XML file, the only required argument is an input file, like so::

$ cdl_convert ./di_v001.flex

You can override the default .cc output, or provide multiple outputs with the -o flag.:

$ cdl_convert ./di_v001.flex -o cc,cdl

Changelog

New in version 0.9.2:

  • Fixed a bug where ALE's with blank lines would not convert correctly.
  • Fixed a bug that was preventing cdl_convert from being correctly installed in Python 2.6
  • Fixed continuous integration testing.
  • No longer officially supporting Python 3.2, as I've had to remove it from our CI builds. It should still work just fine though, but we won't be running CI against it.

New in version 0.9:

  • Added ability to parse CMX EDLs
  • Fixed a script bug where a collection format containing color decisions will not have those color decisions exported as individual color corrections.
  • Fixed a bug where we weren't reading line endings correctly in certain situations.
  • Added a cdl_convert.py stub file to the package root level, which will allow running of the cdl_convert script without installation. Due to relative imports in the python code, it was no longer possible to call cdl_convert/cdl_convert.py directly.
  • The script, when run directly from cdl_convert.py, will now write errors to stderror correctly, and exit with a status of 1.

New in version 0.8:

  • Added --single flag. When provided with an output collection format, each color correction in the input will be exported to it's own collection.
  • Giving a ColorCorrection a non-duplicate ID now works unless the --halt flag is given. This means that incoming collections that contain duplicate IDs will not fail out.

New in version 0.7.1:

  • Fixed bug where ALE's without 'Scan Filename' fields could not parse correctly.

New in version 0.7:

The biggest change in 0.7 is the addition of collection format support. .ccc, Color Correction Collections, can now be parsed and written. .cdl, Color Decision Lists, can now be parsed and written. .ale and .flex files now return a collection.

  • New script flags:
    • Adds --check flag to script, which checks all parsed ColorCorrects for sane values, and prints warnings to shell
    • Adds -d, --destination flag to the script, which allows user to specify the output directory converted files will be written to.
    • Adds --no-ouput flag to the script, which goes through the entire conversion process but doesn't actually write anything to disk. Useful for troubleshooting, especially when combined with --check
    • Adds --halt flag to the script, which halts on errors that can be resolved safely (such as negative slope or power values)
  • Renames ColorCollectionBase to ColorCollection , since it will be used directly by both ccc and cdl.
  • Adds parse_ccc which returns a ColorCollection .
  • Adds write_ccc which writes a ColorCollection as a ccc file.
  • Adds parse_cdl which returns a ColorCollection .
  • Adds write_cdl which returns a ColorCollection as a cdl file.
  • ColorCollection is now a fully functional container class, with many attributes and methods.
  • Added ColorDecision , which stores either a ColorCorrection or ColorCorrectionRef , and an optional MediaRef
  • Added ColorCorrectionRef , which stores a reference to a ColorCorrection
  • Added parent attribute to ColorCorrection .
  • Calling sop_node or sat_node on a ColorCorrection before attempting to set a SOP or Sat power now works.
  • ColorCorrection cdl_file init argument renamed to input_file, which is now optional and able to be set after init.
  • parse_cc and parse_rnh_cdl now only yield a single ColorCorrection , not a single member list.
  • Added dev-requirements.txt (contains mock)
  • All determine_dest methods now take a second directory argument, which determines the output directory.
  • Adds sanity_check function which prints values which might be unusual to stdout.
  • parse_cdl and write_cdl renamed to parse_rnh_cdl and write_rnh_cdl respectively.
  • member_reset methods:
    • ColorCorrection now has a reset_members method, which resets the class level member's dictionary.
    • MediaRef also has a reset_members method, as does ColorCollection
    • reset_all function calls all of the above reset_members methods at once.
  • Renamed cdl_file argument:
    • parse_cc cdl_file arg renamed to input_file and now accepts a either a raw string or an ElementTree Element as input_file.
    • parse_rnh_cdl cdl_file arg renamed to input_file.
    • parse_ale edl_file arg renamed to input_file.
    • parse_flex edl_file arg renamed to input_file.
  • Python Structure Refactoring
    • Moved HALT_ON_ERROR into the config module, which should now be referenced and set by importing the entire config module, and referencing or setting config.HALT_ON_ERROR
    • Script functionality remains in cdl_convert.cdl_convert, but everything else has been moved out.
    • AscColorSpaceBase , AscDescBase , AscXMLBase and ColorNodeBase now live under cdl_convert.base
    • ColorCollection now lives in cdl_convert.collection
    • ColorCorrection , SatNode and SopNode now live under cdl_convert.correction
    • ColorDecision , ColorCorrectionRef and MediaRef now live under cdl_convert.decision
    • All parse functions now live under cdl_convert.parse
    • All write functions now live under cdl_convert.write
    • sanity_check now live under cdl_convert.utils
    • reset_all now lives under the main module

Installation

Installing is as simple as using pip::

$ pip install cdl_convert

If you don't want to bother with a pip style install, you can alternatively grab the entire cdl_convert directory, then set up a shortcut to call cdl_convert/cdl_convert.py

GitHub, Bug Reporting and Support

At cdl_convert's GitHub page you can browse the code and the history of the project.

Builds can be downloaded from the GitHub page or the PyPI repository entry.

The issues page on GitHub is the best place to report bugs or request support, and while cdl_convert is distributed with no warranty of any kind, issues will be read and helped if able.

Frequently Asked Questions

  • What versions of Python does cdl_convert support?

    cdl_convert works in Python 2.6 through 3.4 and PyPy. A full test suite runs continuous integration through Travis-ci.org, coverage through coveralls.io, and code quality checked with landscape.io. Code is pep 8 compliant, with docstrings following google code docstring standards.

  • Why don't you support format X?

    I either haven't had time to build a parser for the format yet, or I might even be unaware it exists. Perhaps you should drop by the issues page and create a request for the format? If creating a request for a format it helps immensely to have a sample of that format.

  • Why the underscore?

    cdl_convert started as a simple script to convert from one format to another. As such, it wasn't named with the standards that one would usually use for a python module. By the time the project became big enough, was on PyPI, etc, it was too spread out on the web, in too many places to make changing easy. In the end, I opted to keep it. At some point, cdl_convert might migrate into a larger, more generic film & tv python module, which will be named properly.

Contributing

Samples

Please, please, please submit samples of the following formats:

  • FLEx
  • ALE
  • CMX
  • CCC

These are complex formats, and seeing real world samples helps write tests that ensure correct parsing of real world EDLs and CDLs. If you don't even see a format of CDL listed that you know exists, open an issue at the github issues page asking for parse/write support for the format, and include a sample.

Squashing Bugs

Take a look at the issues page and if you see something that you think you can bang out, leave a comment saying you're going to take it on. While many issues are already assigned to the principal authors, just because it's assigned doesn't mean any work has begun.

Submitting Code

Before generating a pull request, make sure to run the test suite::

$ python setup.py test

If the tests fail, note which tests are failing, how they would have been affected by your code. Always assume you broke something rather than that the tests are 'wrong.' If you know you didn't break something, and the tests are simply reporting out of date results based on your changes, change the tests.

If your code fails the tests (Travis-ci.org checks all pull requests when you create them) it will be rejected. If the code style doesn't follow PEP-8, it's not going to be a high priority for integration.

When submitting, you'll be asked to waive copyright to your submitted code to the listed authors. This is so we can keep a tight handle on the code and change the license for future releases if needed.

License

The MIT License (MIT)

cdl_convert
Copyright (c) 2015 Sean Wallitsch
http://github.com/shidarin/cdl_convert/

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.