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 valuedecode: 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
nanand a numpy warning. Withoutnp=Truethe 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
pqandhlg. - 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, orcat=Nonefor 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.matrixandmc.npmaccept 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.