All Colors (Allc)

A fast TypeScript package for color management.

Installation

bun i allc

...or use your favourite package manager.

Spaces and Models

CIE 1931 XYZ
CIE 1931 xyY
Linear RGB / RGB / HSL / HSV / HSI / Y'UV SDTV / Y'UV HDTV / YDbDr / YIQ 1953 / YIQ FCC
- sRGB
- DCI P3 (uses CIE Illuminant D63)
- DCI P3 "D60 sim" (uses CIE Illuminant D60)
- Display P3
- Adobe RGB
- ProPhoto RGB (uses CIE Illuminant D50)
- Rec. 2020
- NTSC (1953) (uses CIE Illuminant C)
- SMPTE C (1987)
LAB / LCH
- Oklab
- CIELAB

Guarantees (!)

This package does not allocate! Yes, you heard that right. Conversions do not allocate any objects. The only things which can be allocated are instances of the color class, which the user does. This is why Allc is so fast.
This package does not throw. In fact, it does not even error in any way.
This package is side-effect-free.
This package is fully tree-shakable.
This package is (runtime) dependency-free. There are still some dev-dependencies used in the compilation (e.g., TypeScript).
This package is written solely in TypeScript and uses no // @ts-ignore.

Planned Support

Rec. 2100 support
HWB color model support
D50 support

If you would like to implement one of these features, feel free to submit a PR :)

Building This Package

To build this package, bun run build or use your favourite JavaScript runtime. The output files will be in the ./dist directory.

Other JavaScript Color Packages

License

This repository is MIT-licensed. You can find a copy of the license here.

Package Usage Overview

Allc provides many levels of granularity when it comes to color management.

If you want to quickly convert from one color space to another, you should use the Color class.
If you want to convert colors manually, you should use the color conversion functions in allc/conversions.

Package API Structure Overview

Allc has five main entries:

`allc`

This is the main package entry. It contains the Color class and color space types.

`allc/conversions`

This entry contains color conversion functions in the format to<TARGET><COMPONENT>From<SOURCE> with

<TARGET> being the target (there are many options, docs TODO, let your IDE help you for now);
<COMPONENT> being the target component (like R, Y, or L), depending on the target; and
<SOURCE> being the source (there are many options, docs TODO, let your IDE help you for now).

[!TIP] Many color spaces can be converted to and from CIE 1931 XYZ.

[!TIP] To convert from CIE 1931 XYZ to Oklab and vice versa, you have to do the following:

Convert from the source to LMS (or LMS' respectively)

Apply the component transfer function

Convert from LMS' (or LMS respectively) to the target

This entry also contains component transfer functions in the format to<TARGET>ComponentFrom<SOURCE>Component. These functions are component invariant.

[!TIP] To convert from and to linear RGB, you have to use a component transfer function.

This entry also contains conversion functions in the format to<TARGET>From<SOURCE>. But these are only a few.

`allc/matrices`

This entry contains matrix values for color space/model conversion in the format MATRIX_<TARGET>_FROM_<SOURCE>_<ROW_INDEX>_<COLUMN_INDEX> with

<TARGET> being the target,
<SOURCE> being the source,
<ROW_INDEX> being the matrix row index for the value (0, 1, or 2), and
<COLUMN_INDEX> being the matrix column index for the value (0, 1, or 2).

`allc/distances`

This entry contains color distance functions. A general Euclidean distance function is not provided, as it can be easily replicated with Math.hypot(...components). Instead, the functions in this entry should be used where possible because they are more accurate and sensical.

`allc/primaries`

This entry contains constants for RGB primaries of all supported RGB color spaces. These are in the format PRIMARY_<SPACE>_<COMPONENT>_<X_OR_Y> with

<SPACE> being either
- SRGB (sRGB),
- ADOBE_RGB (Adobe RGB),
- DISPLAY_P3 (Display P3),
- REC_2020 (Rec. 2020), or
- PROPHOTO_RGB (ProPhoto RGB);
CHANNEL being either
- RED,
- GREEN, or
- BLUE; and
X_OR_Y being either x or y, the CIE 1931 xy parameters. Y is not provided, you can calculate that by converting red, green, or blue in the RGB color space to CIE 1931 XYZ.

`allc/illuminants`

This entry contains constants for CIE standard illuminants. Every standard illuminant constant has the format:

CIE_ILLUMINANT_<TYPE>_<DEGREES>_<X_OR_Y> or CIE_ILLUMINANT_<TYPE>_KELVIN

with

<TYPE> being either
- A,
- B,
- C,
- D50,
- D55,
- D65,
- D75,
- D93,
- E,
- F<1..=12>,
- FL3_<1..=15>,
- HP<1..=5>,
- LED_B<1..=5>,
- LED_BH1,
- RED_RGB1,
- LED_V1,
- LED_V2,
- ID50, or
- ID65;
<DEGREES> being either
- 2d (CIE 2° standard observer) or
- 10d (CIE 10° standard observer) (some illuminants have no 10° standard observer values); and
<X_OR_Y> being either x or y, the CIE 1931 xyY values (every illuminant has Y=1).

CIE defines the CCT, (real) kelvin values, for each illuminant, and Allc uses them ALTHOUGH they are only approximations. For example, the CIE standard illuminant D65 was originally defined with a CCT of 6500K. But since then the Planck constant and others have changed (they became more accurate).

So to preserve the legacy xy of the illuminant, the illuminants' CCTs were redefined with a factor. If you want to compute the new values yourself, Allc provides the function illuminantDKelvinToRealKelvin(...) that does that.

Allc exposes two more functions, illuminantDyFromX(...) and illuminantDxFromRealKelvin(...), that you can use to calculate the exact xy values for a D-series illuminant.

Additionally, Allc provides PLANCK_CONSTANT, SPEED_OF_LIGHT, BOLTZMANN_CONSTANT, and SECOND_RADIATION_CONSTANT ( derived from the previous three).

A Note On Precision

Every library out there does color conversion differently because they use different matrices and constants. Here is a non-exhaustive list of matrix usage.

Allc uses the defined illuminant and primaries xy values to generate the conversion matrices for RGB color spaces at machine-precision level. The code for that is here.

Détail du package

allc

readme