Skip to main content

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

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:

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 is at the end of this page. To list them from 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:

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 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:

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:

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 installed, add np=True to work on whole arrays at once:

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:

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

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:

# 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 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

Metadata

Release files for mucolor 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mucolor 0.1.0
File Size Uploaded Provenance Actions
mucolor-0.1.0.tar.gz 17.2 kB Without provenance Details for mucolor-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mucolor 0.1.0
File Interpreter ABI Platform Actions
mucolor-0.1.0-py3-none-any.whl Python 3 none any Details for mucolor-0.1.0-py3-none-any.whl

Total release size: 35.1 kB

Release files / mucolor-0.1.0.tar.gz

Download URL mucolor-0.1.0.tar.gz
Size 17.2 kB
Tags Source
SHA-256 checksum
How to use checksums
3c360e04fa8bbee94b54b436de696c3ebbc24043fa0b37aa4198d2b1441b56c4
BLAKE2b-256 checksum
How to use checksums
e11123eeb789e5123ef910668a0477d66b2ba60a2af8e5dbe65f00e5edacf906
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.23

Release files / mucolor-0.1.0-py3-none-any.whl

Download URL mucolor-0.1.0-py3-none-any.whl
Size 17.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9ec3d17b2448d4a69da94c0cfe1a95d44aaa2e786d3cc59a681882b493030f17
BLAKE2b-256 checksum
How to use checksums
379c61d99ac0496b48d28f7f177f65693d3301c05a4ec9e2ef582b33051d96cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.23

Security for mucolor 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page