Wacton.Unicolour 2.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Wacton.Unicolour --version 2.1.0
NuGet\Install-Package Wacton.Unicolour -Version 2.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Wacton.Unicolour" Version="2.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Wacton.Unicolour --version 2.1.0
#r "nuget: Wacton.Unicolour, 2.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Wacton.Unicolour as a Cake Addin
#addin nuget:?package=Wacton.Unicolour&version=2.1.0

// Install Wacton.Unicolour as a Cake Tool
#tool nuget:?package=Wacton.Unicolour&version=2.1.0

Unicolour

pipeline status coverage report tests passed NuGet

Unicolour is a set of utilities for working with colour:

  • Colour space conversion
  • Colour interpolation
  • Colour comparison

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

Unicolour can be used to calculate colour difference via:

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

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 ⚡

Colour space Construction Access Interpolation
RGB (Hex) Unicolour.FromHex() .Hex .InterpolateRgb()
RGB (0-255) Unicolour.FromRgb255() .Rgb.Byte255 .InterpolateRgb()
RGB Unicolour.FromRgb() .Rgb .InterpolateRgb()
HSB/HSV Unicolour.FromHsb() .Hsb .InterpolateHsb()
HSL Unicolour.FromHsl() .Hsl .InterpolateHsl()
HWB Unicolour.FromHwb() .Hwb .InterpolateHwb()
CIEXYZ Unicolour.FromXyz() .Xyz .InterpolateXyz()
CIExyY Unicolour.FromXyy() .Xyy .InterpolateXyy()
CIELAB Unicolour.FromLab() .Lab .InterpolateLab()
CIELChab Unicolour.FromLchab() .Lchab .InterpolateLchab()
CIELUV Unicolour.FromLuv() .Luv .InterpolateLuv()
CIELChuv Unicolour.FromLchuv() .Lchuv .InterpolateLchuv()
HSLuv Unicolour.FromHsluv() .Hsluv .InterpolateHsluv()
HPLuv Unicolour.FromHpluv() .Hpluv .InterpolateHpluv()
ICTCP Unicolour.FromIctcp() .Ictcp .InterpolateIctcp()
Jzazbz Unicolour.FromJzazbz() .Jzazbz .InterpolateJzazbz()
JzCzhz Unicolour.FromJzczhz() .Jzczhz .InterpolateJzczhz()
Oklab Unicolour.FromOklab() .Oklab .InterpolateOklab()
Oklch Unicolour.FromOklch() .Oklch .InterpolateOklch()

How to use 🎨

  1. Install the package from NuGet
dotnet add package Wacton.Unicolour
  1. Create a Unicolour from values:
using Wacton.Unicolour;
...
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);
  1. Get representation of 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;
  1. 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);
  1. 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);

See also the example code, which uses Unicolour to generate gradients through different colour spaces: Gradients generate from Unicolour

Advanced configuration 💡

A Configuration parameter can be used to change 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);

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

var srgbConfig = new Configuration(RgbConfiguration.StandardRgb, XyzConfiguration.D65);
var displayP3Config = new Configuration(RgbConfiguration.DisplayP3, XyzConfiguration.D65);
var rec202Config = new Configuration(RgbConfiguration.Rec2020, XyzConfiguration.D65);

// pure green in standard RGB
var unicolourSrgb = Unicolour.FromRgb(config, 0, 1, 0);                         // RGB = (0.00, 1.00, 0.00)
var unicolourDisplayP3 = unicolourSrgb.ConvertToConfiguration(displayP3Config); // RGB = (0.46, 0.99, 0.30)
var unicolourRec2020 = unicolourDisplayP3.ConvertToConfiguration(rec202Config); // RGB = (0.57, 0.96, 0.27)

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

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Wacton.Unicolour:

Package Downloads
VL.Interpolator

Powerfull binary search set of nodes for vl, to interpolate any kind of type.

Wacton.Unicolour.Datasets

Datasets for use with 🌈 Wacton.Unicolour

VL.Unicolour

Unicolour for VL

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
4.4.0 467 5/9/2024
4.3.0 391 4/17/2024
4.2.0 582 3/24/2024
4.1.0 592 2/13/2024
4.0.0 379 1/27/2024
3.0.0 1,068 11/5/2023
2.5.0 482 10/22/2023
2.4.0 314 10/7/2023
2.3.0 169 9/24/2023
2.2.0 3,241 6/9/2023
2.1.0 356 4/24/2023
2.0.0 266 2/27/2023
1.11.0 298 1/21/2023
1.10.0 288 1/16/2023
1.9.0 309 1/4/2023
1.8.0 294 12/10/2022
1.7.0 431 8/6/2022
1.6.2 428 5/5/2022
1.6.1 401 5/5/2022
1.6.0 404 5/5/2022
1.5.0 412 4/30/2022
1.4.0 408 4/16/2022
1.3.0 412 4/5/2022
1.2.0 406 3/28/2022
1.1.1 387 3/21/2022
1.1.0 399 3/21/2022
1.0.0 437 2/8/2022
1.0.0-alpha.3 134 2/1/2022
1.0.0-alpha.2 135 1/24/2022
1.0.0-alpha.1 129 1/24/2022

Enable conversion between configurations