Skip to content

Commit ca0295b

Browse files
waactonwaacton
committed
Merge branch 'v6' into 'main'
Prepare version 6.0 See merge request Wacton/Unicolour!87
2 parents 935e068 + 1ef5516 commit ca0295b

18 files changed

+773
-297
lines changed

‎README.md‎

Lines changed: 91 additions & 27 deletions
Large diffs are not rendered by default.

‎Unicolour.Datasets/Unicolour.Datasets.csproj‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88
<ImplicitUsings>enable</ImplicitUsings>
99
<Nullable>enable</Nullable>
1010
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
11-
<Version>3.0.0</Version>
11+
<Version>3.0.1</Version>
1212
<Authors>William Acton</Authors>
1313
<Description>Datasets for use with 🌈 Wacton.Unicolour</Description>
1414
<Copyright>William Acton</Copyright>
1515
<PackageProjectUrl>https://github.com/waacton/Unicolour</PackageProjectUrl>
1616
<RepositoryUrl>https://github.com/waacton/Unicolour</RepositoryUrl>
1717
<PackageTags>unicolour colour color colour-data color-data colour-dataset color-dataset colormap colormaps colourmap colourmaps color-palette colour-palette pigments paints</PackageTags>
18-
<PackageReleaseNotes>Add Artist Paint Spectral Database pigment dataset</PackageReleaseNotes>
18+
<PackageReleaseNotes>Support Unicolour v6</PackageReleaseNotes>
1919
<PackageIcon>Resources\Unicolour.Datasets.png</PackageIcon>
2020
<PackageLicenseFile>LICENSE</PackageLicenseFile>
2121
<PackageReadmeFile>README_UnicolourDatasets_nuget.md</PackageReadmeFile>

‎Unicolour.Experimental/Unicolour.Experimental.csproj‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88
<ImplicitUsings>enable</ImplicitUsings>
99
<Nullable>enable</Nullable>
1010
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
11-
<Version>1.0.0</Version>
11+
<Version>1.0.1</Version>
1212
<Authors>William Acton</Authors>
1313
<Description>Experimental additions to 🌈 Wacton.Unicolour</Description>
1414
<Copyright>William Acton</Copyright>
1515
<PackageProjectUrl>https://github.com/waacton/Unicolour</PackageProjectUrl>
1616
<RepositoryUrl>https://github.com/waacton/Unicolour</RepositoryUrl>
1717
<PackageTags>unicolour colour color pigments pigment-mixing pigment-generation kubelka-munk reflectance reflectance-curves spectral.js paints paint-mixing</PackageTags>
18-
<PackageReleaseNotes>Add pigment generation and Spectral.js implementation</PackageReleaseNotes>
18+
<PackageReleaseNotes>Support Unicolour v6</PackageReleaseNotes>
1919
<PackageIcon>Resources\Unicolour.Experimental.png</PackageIcon>
2020
<PackageLicenseFile>LICENSE</PackageLicenseFile>
2121
<PackageReadmeFile>README_UnicolourExperimental_nuget.md</PackageReadmeFile>

‎Unicolour.Readme/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
[![GitLab](https://badgen.net/static/gitlab/source/ff1493?icon=gitlab)](https://gitlab.com/Wacton/Unicolour)
44
[![NuGet](https://badgen.net/nuget/v/Wacton.Unicolour?icon)](https://www.nuget.org/packages/Wacton.Unicolour/)
55
[![pipeline status](https://gitlab.com/Wacton/Unicolour/badges/main/pipeline.svg)](https://gitlab.com/Wacton/Unicolour/-/commits/main)
6-
[![tests passed](https://badgen.net/static/tests/223,269/green/)](https://gitlab.com/Wacton/Unicolour/-/pipelines)
6+
[![tests passed](https://badgen.net/static/tests/223,239/green/)](https://gitlab.com/Wacton/Unicolour/-/pipelines)
77
[![coverage report](https://gitlab.com/Wacton/Unicolour/badges/main/coverage.svg)](https://gitlab.com/Wacton/Unicolour/-/pipelines)
88

99
Unicolour is the most comprehensive .NET library for working with colour:
@@ -519,15 +519,15 @@ Every line of code is tested, and any defect is [Unicolour's responsibility](htt
519519
## 💡 Configuration
520520
The `Configuration` parameter can be used to define the context of the colour.
521521

522-
Example configuration with predefined
522+
Example configuration with predefined
523523
- Rec. 2020 RGB
524524
- Illuminant D50 (2° observer) XYZ
525525
```c#
526526
Configuration config = new(RgbConfiguration.Rec2020, XyzConfiguration.D50);
527527
Unicolour colour = new(config, ColourSpace.Rgb255, 204, 64, 132);
528528
```
529529

530-
Example configuration with manually defined
530+
Example configuration with manually defined
531531
- Wide-gamut RGB
532532
- Illuminant C (10° observer) XYZ, using Von Kries method for white point adaptation
533533
```c#

‎Unicolour.Readme/README_Unicolour_nuget.md‎

Lines changed: 80 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,13 @@
33
[![GitLab](https://badgen.net/static/gitlab/source/ff1493?icon=gitlab)](https://gitlab.com/Wacton/Unicolour)
44
[![NuGet](https://badgen.net/nuget/v/Wacton.Unicolour?icon)](https://www.nuget.org/packages/Wacton.Unicolour/)
55
[![pipeline status](https://gitlab.com/Wacton/Unicolour/badges/main/pipeline.svg)](https://gitlab.com/Wacton/Unicolour/-/commits/main)
6-
[![tests passed](https://badgen.net/static/tests/217,476/green/)](https://gitlab.com/Wacton/Unicolour/-/pipelines)
6+
[![tests passed](https://badgen.net/static/tests/223,239/green/)](https://gitlab.com/Wacton/Unicolour/-/pipelines)
77
[![coverage report](https://gitlab.com/Wacton/Unicolour/badges/main/coverage.svg)](https://gitlab.com/Wacton/Unicolour/-/pipelines)
88

99
Unicolour is the most comprehensive .NET library for working with colour:
1010
- Colour space conversion
1111
- Colour mixing / colour interpolation
12+
- Colour blending
1213
- Colour difference / colour distance
1314
- Colour gamut mapping
1415
- Colour chromaticity
@@ -34,7 +35,7 @@ See a [live demo in the browser](https://unicolour.wacton.xyz/colour-picker/)
3435
8. 🥽 [Experimental](https://github.com/waacton/Unicolour#-experimental)
3536

3637
## 🧭 Overview
37-
A `Unicolour` encapsulates a single colour and its representation across [30+ colour spaces](https://github.com/waacton/Unicolour#convert-between-colour-spaces).
38+
A `Unicolour` encapsulates a single colour and its representation across [35+ colour spaces](https://github.com/waacton/Unicolour#convert-between-colour-spaces).
3839
It can be used to [mix and compare colours](https://github.com/waacton/Unicolour#mix-colours), and offers [many useful features](https://github.com/waacton/Unicolour#-features) for working with colour.
3940

4041
> **Supported colour spaces**
@@ -45,7 +46,7 @@ It can be used to [mix and compare colours](https://github.com/waacton/Unicolour
4546
> YPbPr · YCbCr&nbsp;/&nbsp;YUV&nbsp;_(digital)_ · YCgCo · YUV&nbsp;_(PAL)_ · YIQ&nbsp;_(NTSC)_ · YDbDr&nbsp;_(SECAM)_ ·
4647
> TSL · XYB ·
4748
> IPT · ICTCP · Jzazbz · JzCzhz ·
48-
> Oklab · Oklch · Okhsv · Okhsl · Okhwb ·
49+
> Oklab · Oklch · Okhsv · Okhsl · Okhwb · Oklrab · Oklrch ·
4950
> CIECAM02 · CAM16 ·
5051
> HCT ·
5152
> CMYK [?](https://github.com/waacton/Unicolour#use-icc-profiles-for-cmyk-conversion)
@@ -171,6 +172,8 @@ var (l, c, h) = colour.Oklch;
171172
| Okhsv | `ColourSpace.Okhsv` | `.Okhsv` |
172173
| Okhsl | `ColourSpace.Okhsl` | `.Okhsl` |
173174
| Okhwb | `ColourSpace.Okhwb` | `.Okhwb` |
175+
| Oklrab | `ColourSpace.Oklrab` | `.Oklrab` |
176+
| Oklrch | `ColourSpace.Oklrch` | `.Oklrch` |
174177
| CIECAM02 | `ColourSpace.Cam02` | `.Cam02` |
175178
| CAM16 | `ColourSpace.Cam16` | `.Cam16` |
176179
| HCT | `ColourSpace.Hct` | `.Hct` |
@@ -195,6 +198,34 @@ var palette = red.Palette(blue, ColourSpace.Hsl, 10, HueSpan.Longer);
195198
| Increasing | `HueSpan.Increasing` |
196199
| Decreasing | `HueSpan.Decreasing` |
197200
201+
### Blend colours
202+
Two colours can be blended as though they are layered elements. Compositing is performed using the source-over operator.
203+
```cs
204+
var blue = new Unicolour(ColourSpace.Rgb, 240, 1.0, 1.0, alpha: 0.5);
205+
var red = new Unicolour(ColourSpace.Rgb, 1.0, 0.0, 0.0);
206+
var purple = blue.Blend(red, BlendMode.Normal);
207+
var pink = blue.Blend(red, BlendMode.Screen);
208+
```
209+
210+
| Blend&nbsp;mode | Enum |
211+
|-------------------|--------------------------|
212+
| Normal | `BlendMode.Normal` |
213+
| Multiply | `BlendMode.Multiply` |
214+
| Screen | `BlendMode.Screen` |
215+
| Overlay | `BlendMode.Overlay` |
216+
| Darken | `BlendMode.Darken` |
217+
| Lighten | `BlendMode.Lighten` |
218+
| Colour&nbsp;Dodge | `BlendMode.ColourDodge` |
219+
| Colour&nbsp;Burn | `BlendMode.ColourBurn` |
220+
| Hard&nbsp;Light | `BlendMode.HardLight` |
221+
| Soft&nbsp;Light | `BlendMode.SoftLight` |
222+
| Difference | `BlendMode.Difference` |
223+
| Exclusion | `BlendMode.Exclusion` |
224+
| Hue | `BlendMode.Hue` |
225+
| Saturation | `BlendMode.Saturation` |
226+
| Colour | `BlendMode.Colour` |
227+
| Luminosity | `BlendMode.Luminosity` |
228+
198229
### Compare colours
199230
Two methods of comparing colours are available: contrast and difference.
200231
Difference is calculated according to a specific delta E (ΔE) metric.
@@ -220,19 +251,23 @@ var difference = red.Difference(blue, DeltaE.Cie76);
220251
| ΔECAM02 | `DeltaE.Cam02` |
221252
| ΔECAM16 | `DeltaE.Cam16` |
222253
223-
### Map colour into RGB gamut
254+
### Map colour into gamut
224255
Colours that cannot be displayed with the [configured RGB model](https://github.com/waacton/Unicolour#rgbconfiguration) can be mapped to the closest in-gamut RGB colour.
225-
The gamut mapping algorithm conforms to CSS specifications.
256+
Mapping to Pointer's gamut will return the closest real surface colour of the same lightness and hue.
226257
```cs
227-
var outOfGamut = new Unicolour(ColourSpace.Rgb, -0.51, 1.02, -0.31);
228-
var inGamut = outOfGamut.MapToRgbGamut();
258+
var veryRed = new Unicolour(ColourSpace.Rgb, 1.25, -0.39, -0.14);
259+
var isInRgb = veryRed.IsInRgbGamut;
260+
var normalRed = veryRed.MapToRgbGamut();
261+
262+
var isInPointer = veryRed.IsInPointerGamut;
263+
var surfaceRed = veryRed.MapToPointerGamut();
229264
```
230265
231-
| Gamut mapping method | Enum |
232-
|---------------------------------------------------------------------------------------------------------|---------------------------------|
233-
| RGB&nbsp;clipping | `GamutMap.RgbClipping` |
234-
| Oklch&nbsp;chroma&nbsp;reduction&nbsp;(CSS&nbsp;specification)&nbsp;👈&nbsp;_default_ | `GamutMap.OklchChromaReduction` |
235-
| [WXY&nbsp;purity&nbsp;reduction](https://unicolour.wacton.xyz/wxy-colour-space#%EF%B8%8F-gamut-mapping) | `GamutMap.WxyPurityReduction ` |
266+
| RGB&nbsp;gamut&nbsp;mapping&nbsp;method | Enum |
267+
|----------------------------------------------------------------------------------------------------------|---------------------------------|
268+
| RGB&nbsp;clipping | `GamutMap.RgbClipping` |
269+
| Oklch&nbsp;chroma&nbsp;reduction&nbsp;(CSS&nbsp;specification)&nbsp;👈&nbsp;_default_ | `GamutMap.OklchChromaReduction` |
270+
| [WXY&nbsp;purity&nbsp;reduction](https://unicolour.wacton.xyz/wxy-colour-space#%EF%B8%8F-gamut-mapping) | `GamutMap.WxyPurityReduction ` |
236271
237272
### Simulate colour vision deficiency
238273
Colour vision deficiency (CVD) or colour blindness can be simulated, conveying how a particular colour might be perceived.
@@ -371,13 +406,17 @@ Every line of code is tested, and any defect is [Unicolour's responsibility](htt
371406
## 💡 Configuration
372407
The `Configuration` parameter can be used to define the context of the colour.
373408
374-
Example configuration with predefined Rec. 2020 RGB & illuminant D50 (2° observer) XYZ:
409+
Example configuration with predefined
410+
- Rec. 2020 RGB
411+
- Illuminant D50 (2° observer) XYZ
375412
```cs
376413
Configuration config = new(RgbConfiguration.Rec2020, XyzConfiguration.D50);
377414
Unicolour colour = new(config, ColourSpace.Rgb255, 204, 64, 132);
378415
```
379416
380-
Example configuration with manually defined wide-gamut RGB & illuminant C (10° observer) XYZ:
417+
Example configuration with manually defined
418+
- Wide-gamut RGB
419+
- Illuminant C (10° observer) XYZ, using Von Kries method for white point adaptation
381420
```cs
382421
var rgbConfig = new RgbConfiguration(
383422
chromaticityR: new(0.7347, 0.2653),
@@ -388,7 +427,7 @@ var rgbConfig = new RgbConfiguration(
388427
toLinear: value => Math.Pow(value, 2.19921875)
389428
);
390429
391-
var xyzConfig = new XyzConfiguration(Illuminant.C, Observer.Degree10);
430+
var xyzConfig = new XyzConfiguration(Illuminant.C, Observer.Degree10, Adaptation.VonKries);
392431
393432
var config = new Configuration(rgbConfig, xyzConfig);
394433
var colour = new Unicolour(config, ColourSpace.Rgb255, 202, 97, 143);
@@ -405,6 +444,8 @@ Defines the RGB model, often used to specify a wider gamut than standard RGB (sR
405444
| sRGB&nbsp;👈&nbsp;_default_ | `.StandardRgb` |
406445
| Display&nbsp;P3 | `.DisplayP3` |
407446
| Rec.&nbsp;2020 | `.Rec2020` |
447+
| Rec.&nbsp;2100&nbsp;PQ | `.Rec2100Pq` |
448+
| Rec.&nbsp;2100&nbsp;HLG | `.Rec2100Hlg` |
408449
| A98 | `.A98` |
409450
| ProPhoto | `.ProPhoto` |
410451
| ACES&nbsp;2065-1 | `.Aces20651` |
@@ -432,7 +473,8 @@ Defines the RGB model, often used to specify a wider gamut than standard RGB (sR
432473
433474
### `XyzConfiguration`
434475
Defines the XYZ white point (which is also [inherited by colour spaces that do not need a specific configuration](https://github.com/waacton/Unicolour#white-points)),
435-
as well as the observer to use for temperature calculations.
476+
the observer to use when colour matching functions (CMFs) are required,
477+
and the chromatic adaptation matrix to use for any white point adaptation (the Bradford method will be used if unspecified).
436478
437479
| Predefined | Property |
438480
|----------------------------------------------------|-----------|
@@ -442,6 +484,7 @@ as well as the observer to use for temperature calculations.
442484
- Parameters
443485
- Reference white point or illuminant
444486
- Observer
487+
- Chromatic adaptation matrix
445488
446489
### `YbrConfiguration`
447490
Defines the constants, scaling, and offsets required to convert to YPbPr and YCbCr.
@@ -472,6 +515,24 @@ The predefined sRGB configuration refers to an ambient illumination of 64 lux un
472515
- Adapting luminance
473516
- Background luminance
474517
518+
### `DynamicRange`
519+
Defines luminance values used when evaluating
520+
perceptual quantizer (PQ) transfer functions (ICTCP · Jzazbz · JzCzhz · Rec. 2100 PQ RGB)
521+
and hybrid log-gamma (HLG) transfer functions (Rec. 2100 HLG RGB).
522+
523+
| Predefined | Property |
524+
|----------------------------|-------------|
525+
| SDR | `.Standard` |
526+
| HDR&nbsp;👈&nbsp;_default_ | `.High` |
527+
528+
The predefined HDR configuration has a white luminance of 203 cd/m² at 75% HLG, and a minimum luminance of 0 cd/m² (no black lift).
529+
530+
- Parameters
531+
- White luminance
532+
- Maximum luminance
533+
- Minimum luminance
534+
- HLG % white level
535+
475536
### `IccConfiguration`
476537
Defines the ICC profile and rendering intent, typically used for accurate CMYK conversion.
477538
@@ -486,21 +547,18 @@ Some commonly used profiles can be found in the [ICC profile registry](https://w
486547
- ICC profile (`.icc` file)
487548
- Rendering intent
488549
489-
### `IctcpScalar` & `JzazbzScalar`
490-
There is ambiguity and no clear consensus about how XYZ values should be scaled before calculating ICTCP and Jzazbz.
491-
These scalars can be changed to match the behaviour of other implementations if needed.
492-
493550
### White points
494551
All colour spaces are impacted by the reference white point.
495552
Unicolour applies different reference white points to different sets of colour spaces, as shown in the table below.
496-
When a [conversion to or from XYZ space](https://github.com/waacton/Unicolour#convert-between-colour-spaces) involves a change in white point, a chromatic adaptation transform (CAT) is performed using the Bradford method.
553+
When a [conversion to or from XYZ space](https://github.com/waacton/Unicolour#convert-between-colour-spaces) involves a change in white point, a chromatic adaptation transform (CAT) is performed.
554+
The default chromatic adaptation is the Bradford method but [this can be customised](https://github.com/waacton/Unicolour#xyzconfiguration).
497555
498556
| White&nbsp;point&nbsp;configuration | Affected&nbsp;colour&nbsp;spaces |
499557
|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
500558
| `RgbConfiguration` | RGB · Linear&nbsp;RGB · HSB&nbsp;/&nbsp;HSV · HSL · HWB · HSI · YPbPr · YCbCr&nbsp;/&nbsp;YUV&nbsp;_(digital)_ · YCgCo · YUV&nbsp;_(PAL)_ · YIQ&nbsp;_(NTSC)_ · YDbDr&nbsp;_(SECAM)_ · TSL · XYB |
501559
| `XyzConfiguration` | CIEXYZ · CIExyY · WXY · CIELAB · CIELChab · CIELUV · CIELChuv · HSLuv · HPLuv |
502560
| `CamConfiguration` | CIECAM02 · CAM16 |
503-
| None (always D65/2°) | IPT · ICTCP · Jzazbz · JzCzhz · Okhsv · Okhsl · Okhwb · HCT |
561+
| None (always D65/2°) | IPT · ICTCP · Jzazbz · JzCzhz · Okhsv · Okhsl · Okhwb · Oklrab · Oklrch · HCT |
504562
505563
### Convert between configurations
506564
A `Unicolour` can be converted to a different configuration,
@@ -622,7 +680,6 @@ See the [live demo](https://unicolour.wacton.xyz/colour-picker/)!
622680
|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
623681
| _Web application for picking colours in any colour space_ |
624682
625-
626683
### Unity
627684
Example code to create 3D visualisations of colour spaces using 🎮 [Unity](https://unity.com/)
628685
can be seen in the [Example.Unity](https://github.com/waacton/Unicolour/tree/main/Example.Unity) project.

0 commit comments

Comments
 (0)