tinycio

Primitive, lightweight Python color library for PyTorch-involved projects. It implements color space conversion, tone mapping, LUT usage and creation, basic color correction and color balancing, and HDR-LDR encoding/decoding.

Getting started

  1. Recommended: set up a clean Python environment

  2. Install PyTorch as instructed here

  3. Run pip install tinycio

  4. Run tcio-setup (installs freeimage binaries; iio docs on fi)

About

  • v 0.8.2 a

As pip has a tendency to screw up PyTorch installations, torch is deliberately left out of the explicit package requirements; install it whichever way is most appropriate, if you haven’t done so already.

Note on limitations

I feel like a disclaimer is in order.

  • This package is (obviously) not suitable for realtime rendering

  • This package is generally not suitable for differentiable rendering

  • I am not a color expert and can’t guarantee scientific accuracy

This package was motivated by a frustration with the staggering complexities of digital color and put together as part of a larger project, already using PyTorch, to minimize external dependencies. In self-flattering terms, the goal here is a kind of spartan-utilitarian approach to color for image processing with some light machine learning. In less self-flattering terms, I have no idea what I’m doing. This is not meant to be a replacement for a proper color management solution.

While the code was tested within reason, some things are likely still not quite correct. For dependable color management, defer to OCIO or consider a more comprehensive and scientifically-minded Python project like Colour.

Supported color spaces (and other things treated as if they were):

  • CIE XYZ

  • CIE xyY

  • sRGB

  • Rec. 709

  • sRGB / Rec. 709 (scene-linear)

  • Rec. 2020

  • Rec. 2020 (scene-linear)

  • DCI-P3

  • DCI-P3 (scene-linear)

  • Display P3

  • ACEScg

  • ACEScc

  • ACES 2065-1

  • LMS

  • OKLAB

  • CIELAB

  • HSL

  • HSV

  • OKHSL

  • OKHSV

Supported tone mapping operators:

  • AgX / AgX punchy

  • ACEScg (fitted RRT+ODT)

  • Hable (a.k.a. Uncharted 2)

  • Reinhard (extended)

Supported LUT formats:

  • CUBE

License

MIT License on all original code - see source for details

How to

The how-to section has a brief tutorial on the library’s core functionality.

Examples

See: examples section.

Deeper dive

See: deeper dives section.

Reference

See: reference section.

Scripts

The library comes with a few bundled CLI scripts:

Sibling projects

Special thanks