Skip to content

Commit

Permalink
Remove experimental label on ray trace GMA and update some doc wording
Browse files Browse the repository at this point in the history
- Update changelog.
- Remove experimental label on ray trace GMA.
- Better phrasing in some doc sections of gamut mapping and add more
  details.
  • Loading branch information
facelessuser committed Aug 5, 2024
1 parent 577a4d9 commit fdfd7bf
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 24 deletions.
16 changes: 9 additions & 7 deletions docs/src/markdown/about/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,15 @@
## 3.4

- **NEW**: Officially support Python 3.13.
- **BREAK**: Experimental `raytrace` gamut mapping method now uses OkLCh by default instead of CIELab (D65).
- **BREAK**: Pre-configured `oklch-raytrace` and `lch-raytrace` variants of the experimental `raytrace` gamut mapping
method have been removed, but users can still specify other perceptual spaces if desired via the `pspace` parameter.
Documentation has been added so users can create their own variants with the their desired pre-configured perceptual
color space and make it the default if they prefer.
- **BREAK**: Remove deprecated `lab` parameter from experimental `raytrace` gamut mapping method. Users should use
`pspace` instead.
- **BREAK**: Finalize the `raytrace` gamut mapping algorithm implementation and remove experimental label.

- Remove deprecated `lab` parameter from experimental `raytrace` gamut mapping method. Users should use
`pspace` instead.
- The `raytrace` gamut mapping method now uses OkLCh by default instead of CIELCh (D65).
- Pre-configured `oklch-raytrace` and `lch-raytrace` variants of the experimental `raytrace` gamut mapping
method have been removed. OkLCh is the default now and users can still specify CIELCh and other perceptual
spaces if desired via the `pspace` parameter. Additionally, documentation has been added so users can easily
recreate the aforementioned pre-configured methods themselves or their own desired variants.

## 3.3.1

Expand Down
40 changes: 23 additions & 17 deletions docs/src/markdown/gamut.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,10 @@ MINDE chroma reduction is an approach that reduces the chroma in a perceptual co
gamut of a targeted color space. As the exact point at which the color will be in gamut is unknown, the chroma is
reduced using bisection. The color is compared periodically to the the clipped version of the current iteration to see
if the ∆E distance between them is below the "just noticeable difference" (JND) defined for the color space. If the
color is close enough to the clipped version, the clipped version is returned.
color is close enough to the clipped version, the clipped version is returned. Because MINDE is used in conjunction
with chroma reduction, a closer color can be found while reducing the chroma preventing too much chroma reduction in
some cases which is particularly useful for some color spaces that have undesirable geometry in certain regions, such as
CIELCh.

Preserving lightness in this way is useful when creating tones or mixing and interpolating colors, but desiring to
preserve their lightness for contrast. It also does a fairly accurate job at approaching the gamut surface. If the JND
Expand All @@ -260,13 +263,13 @@ Computationally, MINDE Chroma Reduction is slower to compute than clipping due t
to get close enough to the gamut surface, but it generally provides good results, far surpassing naive clipping.

It should be noted that most color spaces that have a defined gamut are tied to specific RGB gamuts. And when they are
gamut mapped, they are done so in those RGB spaces. For instance HSL, which represents the sRGB gamut in a cylindrical
gamut mapped, they are done so in those RGB spaces. For instance, HSL which represents the sRGB gamut in a cylindrical
form will be gamut mapped in sRGB (though simple clipping may be done directly in HSL).

There are a few color spaces/models that do not have a clearly defined gamuts. One such case is HPLuv, which is only
defined as a cylindrical color space that represent only a subset of the sRGB color space. Additionally Okhsl and Okhsv
are two cylindrical color spaces based on the perceptual Oklab color space that are meant to target the sRGB gamut, but
are only a loose approximation which actually can slightly clip the sRGB gamut while simultaneously containing a few
are only a loose approximation which can actually slightly clip the sRGB gamut while simultaneously containing a few
colors that exceed the sRGB gamut. ColorAide will not automatically associate these color spaces with an RGB gamut. In
the case of HPLuv, there is no specifically defined RGB gamut, and in the case of Okhsl and Okhsv, sRGB is the closest,
but does not precisely represent the colors in Okhsl and Okhsv.
Expand All @@ -280,11 +283,13 @@ Steps([c.fit('srgb', method='oklch-chroma') for c in Color.steps(['oklch(90% 0.4
```

Lastly, all MINDE Chroma Reduction methods allow the setting of the JND. The default is usually specific to the
perceptual space being used, but it should be noted that while a lower JND will give you a theoretically better value,
some color spaces have quirks due to their unique geometric shape. Consider the color `#!color color(display-p3 1 1 0)`.
If we were to gamut map it in LCh with a very low JND, we can see that the odd shape of LCh can cause us to get a very
desaturated color. By using the default JND of 2 for LCh, the fuzziness of the MINDE will catch the more saturated
yellow. This isn't a problem in OkLCh, but it has its own quirks as well.
perceptual space being used, but it should be noted that while a lower JND will give you a closer value to the gamut
while holding lightness and hue constant, some color spaces have quirks due to their unique geometric shape. Consider
the color `#!color color(display-p3 1 1 0)`. If we were to gamut map it in CIELCh with a very low JND, we can see that
the odd shape of CIELCh in the yellow region can cause us to get a very desaturated color. By using the default JND of 2
for CIELCh, the MINDE logic will catch the more saturated yellow before it reduces chroma all the way to the gamut
surface. Such geometric quirks aren't present in all color spaces, so a space like OkLCh likely benefits less from this
logic.

/// tab | JND 0
![JND 0](images/jnd-0.png)
Expand Down Expand Up @@ -376,6 +381,8 @@ c = Color('hct', [325, 24, 50])
tones = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 100]
Steps([c.clone().set('tone', tone).convert('srgb').to_string(hex=True, fit={'method': 'raytrace', 'pspace': 'hct'}) for tone in tones])
```

If more accuracy in HCT's atypical achromatic region is desired, the MINDE approach is available.
///

Much like the other LCh chroma reduction algorithms, HCT Chroma performs gamut mapping exactly like
Expand Down Expand Up @@ -418,16 +425,15 @@ Color.register([HCT(), DEHCT(), HCTChroma()])

### Ray Tracing Chroma Reduction

/// warning | Experimental Gamut Mapping
///

/// New | New in 3.4
The default perceptual space is now OkLCh. Additionally, the `oklch-raytrace` and `lch-raytrace` variants have been
removed. Please see [Ray Tracing Chroma Reduction in Any Perceptual Space](#ray-tracing-chroma-reduction-in-any-perceptual-space)
to learn how to use different perceptual spaces and even create your own `lch-raytrace` or `oklch-raytrace` variants.
Also reference [Force Ray Trace Default Perceptual Space](#force-ray-trace-default-perceptual-space) to learn how to set
the default ray trace perceptual space to your desired space or even how to force your custom approach as the default
for all gamut mapping.
The default perceptual space is now OkLCh.

Please see [Ray Tracing Chroma Reduction in Any Perceptual Space](#ray-tracing-chroma-reduction-in-any-perceptual-space)
to learn how to use different perceptual spaces.

See [Force Ray Trace Default Perceptual Space](#force-ray-trace-default-perceptual-space) to learn how to set the
default ray trace perceptual space to your desired space or even how to force your custom approach as the default for
all gamut mapping.
///

ColorAide has developed an experimental chroma reduction technique that employs ray tracing. This approach specifically
Expand Down

0 comments on commit fdfd7bf

Please sign in to comment.