Wacton.Unicolour 2.3.0

Unicolour

Unicolour is a set of utilities for working with colour:

• Colour space conversion
• Colour interpolation
• Colour comparison
• Colour properties

A Unicolour encapsulates a single colour and its representation across different colour spaces. It supports:

• RGB
• HSB/HSV
• HSL
• HWB
• CIEXYZ
• CIExyY
• CIELAB
• CIELChab
• CIELUV
• CIELChuv
• HSLuv
• HPLuv
• ICTCP
• Jzazbz
• JzCzhz
• Oklab
• Oklch
• CIECAM02
• CAM16

This diagram summarises how colour space conversions are implemented in Unicolour. Arrows indicate forward transformations from one space to another. For each forward transformation there is a corresponding reverse transformation. XYZ is considered the root colour space.

The following colour properties are available on each Unicolour:

• Hex representation
• Relative luminance
• Temperature (CCT and Duv)

Unicolour can be used to calculate colour difference via:

• ΔE76 (CIE76)
• ΔE94 (CIE94)
• ΔE00 (CIEDE2000)
• ΔEITP
• ΔEz
• ΔEHyAB
• ΔEOK
• ΔECAM02
• ΔECAM16

Unicolour uses sRGB as the default RGB model and standard illuminant D65 (2° observer) as the default white point of the XYZ colour space. These can be overridden using the Configuration parameter.

This library was initially written for personal projects since existing libraries had complex APIs or missing features. The goal of this library is to be accurate, intuitive, and easy to use. Although performance is not a priority, conversions are only calculated once — when first evaluated (either on access or as part of an intermediate conversion step) the result is stored for future use. It is also extensively tested, including comparisons against known colour values and other .NET libraries.

Targets .NET Standard 2.0 for use in .NET 5.0+, .NET Core 2.0+ and .NET Framework 4.6.1+ applications.

Quickstart ⚡

How to use 🌈

1. Install the package from NuGet

dotnet add package Wacton.Unicolour

2. Import the package:

using Wacton.Unicolour;

3. Create a Unicolour from values:

var unicolour = Unicolour.FromHex("#FF1493");
var unicolour = Unicolour.FromRgb255(255, 20, 147);
var unicolour = Unicolour.FromRgb(1.0, 0.08, 0.58);
var unicolour = Unicolour.FromHsb(327.6, 0.922, 1.0);
var unicolour = Unicolour.FromHsl(327.6, 1.0, 0.539);
var unicolour = Unicolour.FromHwb(327.6, 0.078, 0.0);
var unicolour = Unicolour.FromXyz(0.4676, 0.2387, 0.2974);
var unicolour = Unicolour.FromXyy(0.4658, 0.2378, 0.2387);
var unicolour = Unicolour.FromLab(55.96, 84.54, -5.7);
var unicolour = Unicolour.FromLchab(55.96, 84.73, 356.1);
var unicolour = Unicolour.FromLuv(55.96, 131.47, -24.35);
var unicolour = Unicolour.FromLchuv(55.96, 133.71, 349.5);
var unicolour = Unicolour.FromHsluv(349.5, 100, 56);
var unicolour = Unicolour.FromHpluv(349.5, 303.2, 56);
var unicolour = Unicolour.FromIctcp(0.38, 0.12, 0.19);
var unicolour = Unicolour.FromJzazbz(0.106, 0.107, 0.005);
var unicolour = Unicolour.FromJzczhz(0.106, 0.107, 2.6);
var unicolour = Unicolour.FromOklab(0.65, 0.26, -0.01);
var unicolour = Unicolour.FromOklch(0.65, 0.26, 356.9);
var unicolour = Unicolour.FromCam02(62.86, 40.81, -1.18);
var unicolour = Unicolour.FromCam16(62.47, 42.60, -1.36);

4. Get representations of a colour in different colour spaces:

var rgb = unicolour.Rgb;
var hsb = unicolour.Hsb;
var hsl = unicolour.Hsl;
var hwb = unicolour.Hwb;
var xyz = unicolour.Xyz;
var xyy = unicolour.Xyy;
var lab = unicolour.Lab;
var lchab = unicolour.Lchab;
var luv = unicolour.Luv;
var lchuv = unicolour.Lchuv;
var hsluv = unicolour.Hsluv;
var hpluv = unicolour.Hpluv;
var ictcp = unicolour.Ictcp;
var jzazbz = unicolour.Jzazbz;
var jzczhz = unicolour.Jzczhz;
var oklab = unicolour.Oklab;
var oklch = unicolour.Oklch;
var cam02 = unicolour.Cam02;
var cam16 = unicolour.Cam16;

5. Get properties of a colour

var hex = unicolour.Hex;
var relativeLuminance = unicolour.RelativeLuminance;
var temperature = unicolour.Temperature;

6. Interpolate between colours:

var interpolated = unicolour1.InterpolateRgb(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateHsb(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateHsl(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateHwb(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateXyz(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateXyy(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateLab(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateLchab(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateLuv(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateLchuv(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateHsluv(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateHpluv(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateIctcp(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateJzazbz(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateJzczhz(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateOklab(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateOklch(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateCam02(unicolour2, 0.5);
var interpolated = unicolour1.InterpolateCam16(unicolour2, 0.5);

7. Compare colours:

var contrast = unicolour1.Contrast(unicolour2);
var difference = unicolour1.DeltaE76(unicolour2);
var difference = unicolour1.DeltaE94(unicolour2);
var difference = unicolour1.DeltaE00(unicolour2);
var difference = unicolour1.DeltaEItp(unicolour2);
var difference = unicolour1.DeltaEz(unicolour2);
var difference = unicolour1.DeltaEHyab(unicolour2);
var difference = unicolour1.DeltaEOk(unicolour2);
var difference = unicolour1.DeltaECam02(unicolour2);
var difference = unicolour1.DeltaECam16(unicolour2);

See also:

Example code that uses Unicolour to generate gradients through different colour spaces

Console application that uses Unicolour to show colour information for a given hex value

Advanced configuration 💡

A Configuration parameter can be used to customise the RGB model (e.g. Display P3, Rec. 2020) and the white point of the XYZ colour space (e.g. D50 reference white used by ICC profiles).

• RGB configuration requires red, green, and blue chromaticity coordinates, the reference white point, and the companding functions. Default configuration for sRGB, Display P3, and Rec. 2020 is provided.

• XYZ configuration only requires the reference white point. Default configuration for D65 and D50 (2° observer) is provided.

// built-in configuration for Rec. 2020 RGB + D65 XYZ
var config = new Configuration(RgbConfiguration.Rec2020, XyzConfiguration.D65);
var unicolour = Unicolour.FromRgb255(config, 255, 20, 147);

// manual configuration for wide-gamut RGB
var rgbConfig = new RgbConfiguration(
    chromaticityR: new(0.7347, 0.2653),
    chromaticityG: new(0.1152, 0.8264),
    chromaticityB: new(0.1566, 0.0177),
    whitePoint: WhitePoint.From(Illuminant.D50),
    fromLinear: value => Companding.Gamma(value, 2.2),
    toLinear: value => Companding.InverseGamma(value, 2.2)
);

// manual configuration for equal-energy (10° observer) XYZ
var xyzConfig = new XyzConfiguration(
    whitePoint: WhitePoint.From(Illuminant.E, Observer.Supplementary10)
);

var config = new Configuration(rgbConfig, xyzConfig);
var unicolour = Unicolour.FromRgb255(config, 255, 20, 147);

Configuration is also available for CAM02 & CAM16 viewing conditions, ICTCP scalar, and Jzazbz scalar.

A Unicolour can be converted to a different configuration, which enables conversions between different RGB and XYZ models.

// pure sRGB green
var srgbConfig = new Configuration(RgbConfiguration.StandardRgb);
var unicolourSrgb = Unicolour.FromRgb(srgbConfig, 0, 1, 0);                         
Console.WriteLine(unicolourSrgb.Rgb); // 0.00 1.00 0.00

// pure sRGB green -> Display P3
var displayP3Config = new Configuration(RgbConfiguration.DisplayP3);
var unicolourDisplayP3 = unicolourSrgb.ConvertToConfiguration(displayP3Config); 
Console.WriteLine(unicolourDisplayP3.Rgb); // 0.46 0.99 0.30

// pure sRGB green -> Rec. 2020
var rec202Config = new Configuration(RgbConfiguration.Rec2020);
var unicolourRec2020 = unicolourDisplayP3.ConvertToConfiguration(rec202Config);
Console.WriteLine(unicolourRec2020.Rgb); // 0.57 0.96 0.27

Wacton.Unicolour is licensed under the MIT License, copyright © 2022-2023 William Acton.