## Expand description

kolor implements conversions between color spaces which use 3-component vectors.

kolor is intended for use in games or other interactive visual applications, where it can help implement correct color management and wide color gamut rendering.

## Named color spaces

Named color space definitions can be found in spaces. Some notable color spaces and models:

- sRGB / linear sRGB / BT.709
- BT.2020
- ACEScg
- ACES2065-1
- Oklab
- CIE LAB / Lch / Luv / xyY / uvV
- HSL / HSV / HSI
- ICtCp

You can also construct custom ColorSpaces from a combination of primaries, whitepoint and transform function.

## Design

kolor aims to supports all color spaces and color models which use 3-component vectors, such as RGB, LAB, XYZ, HSL and more.

In the spirit of keeping things simple, kolor uses a single type, Color, to represent a color in any supported color space.

kolor can programmatically generate an efficient conversion between any two color spaces by using the CIE XYZ color space as a “connecting space”, meaning all supported color spaces only need to support a conversion to a reference color space that is a linear transform of the CIE XYZ color space.

Transformations between linear color spaces can be implemented with a 3x3 matrix, and since 3x3 matrices are composable, these matrices can be pre-composed and applied to a color with a single multiply.

kolor recognizes that users may want to perform conversions on colors stored in types defined by the user. ColorConversion represents a conversion between two color spaces and is intended to be compatible with 3-component vectors in many math libraries.

kolor defines conversions from a source ColorSpace to a destination ColorSpace as three parts:

- if the source color space is non-linear, apply the inverse of its transform function to convert to the non-linear color space’s reference color space (which is always linear)
- a linear 3x3 transformation matrix from the source to the destination linear color space
- if the destination color space is a non-linear color space, apply its transform function

A “non-linear transform function” means any function that cannot be expressed as a linear transformation of the CIE XYZ color space. Examples include the sRGB logarithmic gamma compensation function, the Oklab transform function, and the HSL/HSV hexagonal/circular transform.

For non-linear color spaces, many transform functions are supported to convert between popular spaces, but for GPU contexts, these implementations clearly can’t be used directly. To implement data-driven conversions, you can read the required operations for transforming between spaces from a ColorConversion value and run these as appropriate. Feel free to port the implementations in details::transform to your shaders or other code.

#### Gamut-agnostic transforms

Some color models like CIELAB or HSL are intended to provide an alternate view of some linear color spaces, and need a reference color space to provide information like which white point or RGB primaries to use. To construct these color spaces, refer to associated methods on ColorSpace and use an appropriate reference color space.

## Details

kolor can calculate 3x3 conversion matrices between any linear color space defined by RGB primaries and a white point. kolor offers APIs for performing conversions directly, and for extracting the 3x3 matrix to use in a different context, for example on a GPU.

#### Generating conversion matrices between RGB color spaces

LinearColorConversion can be used
to generate conversion matrices “offline”,
in which case you probably want to use the `f64`

feature for better precision.
The precision of the derived matrices won’t be perfect, but probably good enough for games.

Conversions between all combinations of built-in primaries and whitepoints color spaces
are bundled with kolor as constants with the `color-matrices`

feature, which is enabled by default.
When a ColorConversion without a bundled pre-calculated conversion matrix is created,
it is calculated on-demand, meaning the creation will be a bit slower to create than
if there is a constant matrix available.

#### Chromatic Adaptation Transformation (CAT)

kolor implements CAT in details::cat and supports the LMS cone spaces defined in LMSConeSpace. Chromatic Adaptation Transformation means converting a linear RGB color space from one reference WhitePoint to another.

Use ColorSpace::with_whitepoint to change WhitePoint for a color space.

#### XYZ-RGB conversions

All supported RGB color spaces use the CIE XYZ color space as its reference color space. Functions in details::xyz can be used to create conversion matrices to/from an RGB color space given a set of primaries and a white point.

## no_std and glam support

kolor is using by default `std`

and `glam`

, but both can be disabled separately or together with the
folowing features:

`std` | `no_std` | |
---|---|---|

`glam` | `std-glam` | `libm-glam` |

no `glam` | `std` | `libm` |

## Modules

## Structs

- Color is a 3-component vector defined in a ColorSpace.
- ColorConversion defines an operation that maps a 3-component vector from a source ColorSpace to a destination ColorSpace.
- A color space defined in data by its Primaries, white point, and an optional invertible transform function.
- A 3x3 column major matrix.
- A 3-dimensional vector.