Metadata-Version: 2.5
Name: mucolor
Version: 0.1.0
Summary: Minimal pure-python colorimetry: gamuts, transfer functions and colorspace conversion with no dependencies.
Project-URL: Source, https://github.com/jedypod/mucolor
Author-email: Jed Smith <jed.coma316@passmail.net>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# mucolor

**μcolor**, "micro color". The "mu" is the Greek letter μ, the SI symbol for micro: one
millionth. The name is the goal: the colorimetry a pipeline needs, made as small as it can be.

Minimal pure-python colorimetry calculations, transfer functions and colorspace conversions. 

Convert stimuli between camera, working and display colorspaces. Pure Python, one file,
no dependencies.

## Install

mucolor is a single file. Either copy `mucolor.py` next to your own code, or install it
from this folder:

```
pip install .
```

## Quick start

```python
import mucolor as mc

# Convert one RGB triplet: (red, green, blue), from colorspace, to colorspace
mc.convert((0.41, 0.41, 0.41), 'sony-sgamut3-slog3', 'acescg')
# -> (0.179, 0.179, 0.179)
```

An RGB triplet is a tuple of three numbers: `(red, green, blue)`. The result is a tuple too.

## Colorspace names

Every colorspace has a long name, a short name and an alias. You can use any of them, and
upper or lower case does not matter. These all result in the same colorspace conversion:

```python
rgb = (0.41, 0.41, 0.41)

mc.convert(rgb, 'Sony - S-Gamut3 - S-Log3', 'acescg')
mc.convert(rgb, 'sony-sgamut3-slog3', 'acescg')
mc.convert(rgb, 'sg3lg3', 'acescg')
```

The [full list](#colorspaces) is at the end of this page. To list them from Python:

```python
for cs in mc.colorspaces():
    print(cs.shortname, '|', cs.name)
```

If you misspell a name, the error suggests close matches:

```
KeyError: "unknown colorspace 'slog3', did you mean 'smlg', 'sg3ln'?"
```

## Converting many stimuli

`convert` looks up both colorspaces every time you call it. To convert a lot of stimuli
between the same two colorspaces, make a converter once and reuse it:

```python
slog3_to_acescg = mc.converter('sony-sgamut3-slog3', 'acescg')

slog3_to_acescg((0.41, 0.41, 0.41))   # -> (0.179, 0.179, 0.179)
slog3_to_acescg((0.6, 0.5, 0.4))      # -> (1.107, 0.434, 0.160)
```

For bigger challenges, use [numpy](#numpy-arrays) which is much faster to process.

## Transfer functions on their own

A transfer function turns linear signal into code values and back. Each one has two methods:

- `encode`: linear signal -> code value
- `decode`: code value -> linear signal

They work on one number at a time, not an RGB triplet:

```python
mc.sony_slog3.encode(0.18)    # -> 0.411  (18% grey in S-Log3)
mc.sony_slog3.decode(0.41)    # -> 0.179
```

## Matrices

`matrix` gives the 3x3 matrix between the linear versions of two colorspaces, as a tuple of
three rows:

```python
mc.matrix('p3d65-lin', 'rec709-lin')
# -> ((1.2249, -0.2249, 0.0), (-0.0421, 1.0421, 0.0), (-0.0196, -0.0786, 1.0983))
```

## numpy arrays

The functions above work on one RGB triplet at a time, which is slow for large jobs such as
baking a LUT or converting an image. If you have [numpy](https://numpy.org) installed,
add `np=True` to work on whole arrays at once:

```python
import numpy as np
import mucolor as mc

rgb = np.array([   # two RGB triplets
    [0.41, 0.41, 0.41],
    [0.6, 0.5, 0.4],
])
mc.convert(rgb, 'sony-sgamut3-slog3', 'acescg', np=True)
# -> array([[0.179, 0.179, 0.179],
#           [1.107, 0.434, 0.160]])
```

`np=True` works the same way everywhere:

```python
f = mc.converter('sony-sgamut3-slog3', 'acescg', np=True)
f(rgb)

mc.sony_slog3.decode(np.array([0.1, 0.41, 0.6]), np=True)
# -> array([0.0011, 0.179, 1.037])
```

Things to know:

- The array can have any shape, as long as the last axis holds the three channels: a list
  of RGB triplets `(n, 3)`, an image `(height, width, 3)`, or a LUT grid `(n, n, n, 3)`.
- You always get a new array back. Your input array is never changed.
- numpy is only needed when you use `np=True`. Without numpy installed, everything else
  still works.
- A value a curve cannot handle, such as a negative number into a pure log curve, gives
  `nan` and a numpy warning. Without `np=True` the same value raises an error.

### Example: bake a 3D LUT to a .cube file

```python
import numpy as np
import mucolor as mc

size = 33

# A grid of every input RGB triplet. In a .cube file red changes fastest, then green, then blue.
steps = np.linspace(0.0, 1.0, size)
b, g, r = np.meshgrid(steps, steps, steps, indexing='ij')
grid = np.stack([r, g, b], axis=-1)    # shape (33, 33, 33, 3)

lut = mc.convert(grid, 'arri-wg4-logc4', 'davinci-wg-ilog', np=True)

with open('logc4_to_davinci.cube', 'w') as file:
    file.write(f'LUT_3D_SIZE {size}\n')
    for red, green, blue in lut.reshape(-1, 3):
        file.write(f'{red:.6f} {green:.6f} {blue:.6f}\n')
```

## Conventions

- **Linear signal**: scene-linear 0.18 is 18% grey. For display colorspaces, linear 1.0 is
  100 nits, including `pq` and `hlg`.
- **No "tone mapping"**: mucolor converts colorimetry exactly. Converting a camera log
  image straight to a display colorspace gives values above 1.0 for bright areas, the
  same as a plain colorspace conversion in other software. It is not a viewing transform.
- **Chromatic adaptation**: when two colorspaces have different white points, mucolor
  adapts between them with CAT02. Pass `cat='bradford'` to use Bradford, or `cat=None`
  for none: `mc.convert((0.18, 0.18, 0.18), 'aces', 'rec709-lin', cat='bradford')`.
- **Gamuts** are flat tuples of xy chromaticities: `(rx, ry, gx, gy, bx, by, wx, wy)`.
  `mc.matrix` and `mc.npm` accept these as well as colorspace names.

## Colorspaces

The short name is shown. `encoding` tells you what kind of values the colorspace holds.

| Short name | Name | Encoding |
|---|---|---|
| `xyz-d65` | XYZ D65 | scene-linear |
| `xyz-e` | XYZ E | scene-linear |
| `aces` | ACES 2065-1 | scene-linear |
| `acescg` | ACEScg | scene-linear |
| `acescct` | ACEScct | log |
| `jplog2` | JPLog2 | log |
| `filmlight-egamut-lin` | Filmlight - E-Gamut - Linear | scene-linear |
| `filmlight-egamut-tlog` | Filmlight - E-Gamut - T-Log | log |
| `filmlight-egamut2-lin` | Filmlight - E-Gamut2 - Linear | scene-linear |
| `filmlight-egamut2-tlog` | Filmlight - E-Gamut2 - T-Log | log |
| `filmlight-egamut2-tloge` | Filmlight - E-Gamut2 - T-LogE | log |
| `davinci-wg-lin` | DaVinci - WideGamut - Linear | scene-linear |
| `davinci-wg-ilog` | DaVinci - WideGamut - Intermediate Log | log |
| `arri-wg3-lin` | Arri - WideGamut3 - Linear | scene-linear |
| `arri-wg3-logc3` | Arri - WideGamut3 - LogC3 | log |
| `arri-wg4-lin` | Arri - WideGamut4 - Linear | scene-linear |
| `arri-wg4-logc4` | Arri - WideGamut4 - LogC4 | log |
| `blackmagic-wg-lin` | Blackmagic - WideGamut - Linear | scene-linear |
| `blackmagic-wg-gen5log` | Blackmagic - WideGamut - Gen5 Log | log |
| `canon-cgamut-lin` | Canon - C-Gamut - Linear | scene-linear |
| `canon-cgamut-clog2` | Canon - C-Gamut - C-Log2 | log |
| `canon-cgamut-clog3` | Canon - C-Gamut - C-Log3 | log |
| `dji-dgamut-lin` | DJI - D-Gamut - Linear | scene-linear |
| `dji-dgamut-dlog` | DJI - D-Gamut - D-Log | log |
| `fuji-fgamut-lin` | Fujifilm - F-Gamut - Linear | scene-linear |
| `fuji-fgamut-flog` | Fujifilm - F-Gamut - F-Log | log |
| `fuji-fgamut-flog2` | Fujifilm - F-Gamut - F-Log2 | log |
| `fuji-fgamutc-lin` | Fujifilm - F-GamutC - Linear | scene-linear |
| `fuji-fgamutc-flog2` | Fujifilm - F-GamutC - F-Log2 | log |
| `cineon` | Kodak Cineon | log |
| `gopro-rec709-protune` | GoPro - Rec.709 - Protune | log |
| `leica-rec2020-lin` | Leica - Rec.2020 - Linear | scene-linear |
| `leica-rec2020-llog` | Leica - Rec.2020 - L-Log | log |
| `nikon-rec2020-lin` | Nikon - Rec.2020 - Linear | scene-linear |
| `nikon-rec2020-nlog` | Nikon - Rec.2020 - N-Log | log |
| `apple-rec2020-lin` | Apple - Rec.2020 - Linear | scene-linear |
| `apple-rec2020-alog` | Apple - Rec.2020 - Apple-Log | log |
| `samsung-rec2020-lin` | Samsung - Rec.2020 - Linear | scene-linear |
| `samsung-rec2020-slog` | Samsung - Rec.2020 - Samsung-Log | log |
| `xiaomi-rec2020-lin` | Xiaomi - Rec.2020 - Linear | scene-linear |
| `xiaomi-rec2020-xlog` | Xiaomi - Rec.2020 - Xiaomi-Log | log |
| `panasonic-vgamut-lin` | Panasonic - V-Gamut - Linear | scene-linear |
| `panasonic-vgamut-vlog` | Panasonic - V-Gamut - V-Log | log |
| `red-wg-lin` | Red - WideGamutRGB - Linear | scene-linear |
| `red-wg-log3g10` | Red - WideGamutRGB - Log3G10 | log |
| `sony-sgamut3-lin` | Sony - S-Gamut3 - Linear | scene-linear |
| `sony-sgamut3-slog3` | Sony - S-Gamut3 - S-Log3 | log |
| `sony-sgamut3cine-lin` | Sony - S-Gamut3.Cine - Linear | scene-linear |
| `sony-sgamut3cine-slog3` | Sony - S-Gamut3.Cine - S-Log3 | log |
| `sony-venice-sgamut3-lin` | Sony - Venice S-Gamut3 - Linear | scene-linear |
| `sony-venice-sgamut3-slog3` | Sony - Venice S-Gamut3 - S-Log3 | log |
| `sony-venice-sgamut3cine-lin` | Sony - Venice S-Gamut3.Cine - Linear | scene-linear |
| `sony-venice-sgamut3cine-slog3` | Sony - Venice S-Gamut3.Cine - S-Log3 | log |
| `rec709-lin` | Rec.709 - Linear | scene-linear |
| `rec2020-lin` | Rec.2020 - Linear | scene-linear |
| `p3d65-lin` | P3D65 - Linear | scene-linear |
| `rec1886` | Rec.1886 | sdr-video |
| `srgb-display` | sRGB Display | sdr-video |
| `srgb-encoding` | sRGB Encoding | sdr-video |
| `dci-p3d65` | DCIP3 D65 | sdr-video |
| `display-p3` | Display P3 | sdr-video |
| `rec2100-pq` | Rec2100 PQ | hdr-video |
| `rec2100-hlg` | Rec2100 HLG | hdr-video |

## How the curves are defined

Most camera log curves are a `Log`: a natural log curve with an optional piecewise linear toe.

```
y = gain*ln(x + offset) + bias     x >  toe
y = slope*(x - toe) + y0           x <= toe
```

The linear toe always meets the log segment at the same value (C0 continuity). Its slope
is the one the whitepaper publishes, which is not always the slope of the log segment at
the join.

**Why the slope is kept.** Several curves are designed with a kink at the join: the linear
segment is steeper than the log segment there (S-Log3 by 27%, F-Log 4.7%, F-Log2 3.7%,
L-Log 1.3%, D-Log 1.2%). Forcing matching slopes (C1 continuity) would move every code
value in the toe away from what the camera records. A kink does no harm: the curve still
rises everywhere, so it decodes exactly. If you build a `Log` without a `slope`, it uses
the slope of the log segment.

**Why the join value is not kept.** Some whitepapers publish the linear segment's offset
as a separate constant, and with the rounded published values the two segments do not quite
meet: there is a small step at the join. With a step, decode cannot exactly undo encode
near the join, because code values inside the step belong to neither segment. F-Log shows
this in its own whitepaper: the linear segment ends at 0.100639, but its decode formula
switches segments at 0.100538. mucolor derives the offset so the segments meet, and in
the toe it differs from the whitepaper by the size of the step:

| Curve | Step at the join |
|---|---|
| Leica L-Log | 9.0e-4 (about 0.9 of a 10-bit code value) |
| Fujifilm F-Log | 1.0e-4 |
| DJI D-Log | 2.0e-6 |
| Panasonic V-Log | 3.1e-7 |
| ARRI LogC3 | 2.5e-7 |
| Fujifilm F-Log2 | 3.6e-8 |

Above the join, every curve matches its whitepaper to floating point precision. Below it,
the difference is a constant offset of exactly the step. `tests/test_external.py` lists the
tolerance used for each curve.

Each curve is built from the constants and formula of its whitepaper, so it can be
checked against the source:

```python
# ARRI LogC3 EI800
#   y = c*log10(a*x + b) + d     x >  cut
#   y = e*x + f                  x <= cut
cut, a, b, c, d, e, f = 0.010591, 5.555556, 0.052272, 0.247190, 0.385537, 5.367655, 0.092809
arri_logc3 = Log.from_base(10, c, a, b, d, toe=cut, slope=e)
```

Display curves are a `Power` with the same optional toe. Curves that fit neither form are
a `Curve` of two functions.

## Tests

```
python -m unittest discover -s tests
```

`tests/test_external.py` compares every colorspace it can against
[colour-science](https://www.colour-science.org) and the OCIO built-in ACES studio config.
It is skipped unless those packages are installed (OCIO 2.6 or newer):

```
pip install colour-science opencolorio
python -m unittest discover -s tests
```
