From 4841fcfc69a3383febf88f3f508ca3f5c45ef22d Mon Sep 17 00:00:00 2001
From: MM20 <15646950+MM2-0@users.noreply.github.com>
Date: Wed, 28 Jun 2023 18:57:37 +0200
Subject: [PATCH] Update material-color-utilities
---
.../src/main/java/blend/Blend.java | 121 +++++++++---------
.../src/main/java/hct/Cam16.java | 22 +++-
.../src/main/java/hct/Hct.java | 30 +++++
.../src/main/java/hct/ViewingConditions.java | 30 +++--
.../src/main/java/palettes/TonalPalette.java | 81 +++++++++++-
.../src/main/java/utils/ColorUtils.java | 15 +++
6 files changed, 221 insertions(+), 78 deletions(-)
diff --git a/libs/material-color-utilities/src/main/java/blend/Blend.java b/libs/material-color-utilities/src/main/java/blend/Blend.java
index 39642db4..545e2ff1 100644
--- a/libs/material-color-utilities/src/main/java/blend/Blend.java
+++ b/libs/material-color-utilities/src/main/java/blend/Blend.java
@@ -25,66 +25,67 @@ import utils.MathUtils;
/** Functions for blending in HCT and CAM16. */
public class Blend {
- private Blend() {}
+ private Blend() {}
- /**
- * Blend the design color's HCT hue towards the key color's HCT hue, in a way that leaves the
- * original color recognizable and recognizably shifted towards the key color.
- *
- * @param designColor ARGB representation of an arbitrary color.
- * @param sourceColor ARGB representation of the main theme color.
- * @return The design color with a hue shifted towards the system's color, a slightly
- * warmer/cooler variant of the design color's hue.
- */
- public static int harmonize(int designColor, int sourceColor) {
- Hct fromHct = Hct.fromInt(designColor);
- Hct toHct = Hct.fromInt(sourceColor);
- double differenceDegrees = MathUtils.differenceDegrees(fromHct.getHue(), toHct.getHue());
- double rotationDegrees = Math.min(differenceDegrees * 0.5, 15.0);
- double outputHue =
- MathUtils.sanitizeDegreesDouble(
- fromHct.getHue()
- + rotationDegrees * MathUtils.rotationDirection(fromHct.getHue(), toHct.getHue()));
- return Hct.from(outputHue, fromHct.getChroma(), fromHct.getTone()).toInt();
- }
+ /**
+ * Blend the design color's HCT hue towards the key color's HCT hue, in a way that leaves the
+ * original color recognizable and recognizably shifted towards the key color.
+ *
+ * @param designColor ARGB representation of an arbitrary color.
+ * @param sourceColor ARGB representation of the main theme color.
+ * @return The design color with a hue shifted towards the system's color, a slightly
+ * warmer/cooler variant of the design color's hue.
+ */
+ public static int harmonize(int designColor, int sourceColor) {
+ Hct fromHct = Hct.fromInt(designColor);
+ Hct toHct = Hct.fromInt(sourceColor);
+ double differenceDegrees = MathUtils.differenceDegrees(fromHct.getHue(), toHct.getHue());
+ double rotationDegrees = Math.min(differenceDegrees * 0.5, 15.0);
+ double outputHue =
+ MathUtils.sanitizeDegreesDouble(
+ fromHct.getHue()
+ + rotationDegrees * MathUtils.rotationDirection(fromHct.getHue(), toHct.getHue()));
+ return Hct.from(outputHue, fromHct.getChroma(), fromHct.getTone()).toInt();
+ }
- /**
- * Blends hue from one color into another. The chroma and tone of the original color are
- * maintained.
- *
- * @param from ARGB representation of color
- * @param to ARGB representation of color
- * @param amount how much blending to perform; 0.0 >= and <= 1.0
- * @return from, with a hue blended towards to. Chroma and tone are constant.
- */
- public static int hctHue(int from, int to, double amount) {
- int ucs = cam16Ucs(from, to, amount);
- Cam16 ucsCam = Cam16.fromInt(ucs);
- Cam16 fromCam = Cam16.fromInt(from);
- Hct blended = Hct.from(ucsCam.getHue(), fromCam.getChroma(), ColorUtils.lstarFromArgb(from));
- return blended.toInt();
- }
+ /**
+ * Blends hue from one color into another. The chroma and tone of the original color are
+ * maintained.
+ *
+ * @param from ARGB representation of color
+ * @param to ARGB representation of color
+ * @param amount how much blending to perform; 0.0 >= and <= 1.0
+ * @return from, with a hue blended towards to. Chroma and tone are constant.
+ */
+ public static int hctHue(int from, int to, double amount) {
+ int ucs = cam16Ucs(from, to, amount);
+ Cam16 ucsCam = Cam16.fromInt(ucs);
+ Cam16 fromCam = Cam16.fromInt(from);
+ Hct blended = Hct.from(ucsCam.getHue(), fromCam.getChroma(), ColorUtils.lstarFromArgb(from));
+ return blended.toInt();
+ }
+
+ /**
+ * Blend in CAM16-UCS space.
+ *
+ * @param from ARGB representation of color
+ * @param to ARGB representation of color
+ * @param amount how much blending to perform; 0.0 >= and <= 1.0
+ * @return from, blended towards to. Hue, chroma, and tone will change.
+ */
+ public static int cam16Ucs(int from, int to, double amount) {
+ Cam16 fromCam = Cam16.fromInt(from);
+ Cam16 toCam = Cam16.fromInt(to);
+ double fromJ = fromCam.getJstar();
+ double fromA = fromCam.getAstar();
+ double fromB = fromCam.getBstar();
+ double toJ = toCam.getJstar();
+ double toA = toCam.getAstar();
+ double toB = toCam.getBstar();
+ double jstar = fromJ + (toJ - fromJ) * amount;
+ double astar = fromA + (toA - fromA) * amount;
+ double bstar = fromB + (toB - fromB) * amount;
+ return Cam16.fromUcs(jstar, astar, bstar).toInt();
+ }
+}
- /**
- * Blend in CAM16-UCS space.
- *
- * @param from ARGB representation of color
- * @param to ARGB representation of color
- * @param amount how much blending to perform; 0.0 >= and <= 1.0
- * @return from, blended towards to. Hue, chroma, and tone will change.
- */
- public static int cam16Ucs(int from, int to, double amount) {
- Cam16 fromCam = Cam16.fromInt(from);
- Cam16 toCam = Cam16.fromInt(to);
- double fromJ = fromCam.getJstar();
- double fromA = fromCam.getAstar();
- double fromB = fromCam.getBstar();
- double toJ = toCam.getJstar();
- double toA = toCam.getAstar();
- double toB = toCam.getBstar();
- double jstar = fromJ + (toJ - fromJ) * amount;
- double astar = fromA + (toA - fromA) * amount;
- double bstar = fromB + (toB - fromB) * amount;
- return Cam16.fromUcs(jstar, astar, bstar).toInt();
- }
-}
\ No newline at end of file
diff --git a/libs/material-color-utilities/src/main/java/hct/Cam16.java b/libs/material-color-utilities/src/main/java/hct/Cam16.java
index 9dfdb09e..9b6fb1fb 100644
--- a/libs/material-color-utilities/src/main/java/hct/Cam16.java
+++ b/libs/material-color-utilities/src/main/java/hct/Cam16.java
@@ -63,6 +63,9 @@ public final class Cam16 {
private final double astar;
private final double bstar;
+ // Avoid allocations during conversion by pre-allocating an array.
+ private final double[] tempArray = new double[] {0.0, 0.0, 0.0};
+
/**
* CAM16 instances also have coordinates in the CAM16-UCS space, called J*, a*, b*, or jstar,
* astar, bstar in code. CAM16-UCS is included in the CAM16 specification, and is used to measure
@@ -207,6 +210,11 @@ public final class Cam16 {
double y = 0.2126 * redL + 0.7152 * greenL + 0.0722 * blueL;
double z = 0.01932141 * redL + 0.11916382 * greenL + 0.95034478 * blueL;
+ return fromXyzInViewingConditions(x, y, z, viewingConditions);
+ }
+
+ static Cam16 fromXyzInViewingConditions(
+ double x, double y, double z, ViewingConditions viewingConditions) {
// Transform XYZ to 'cone'/'rgb' responses
double[][] matrix = XYZ_TO_CAM16RGB;
double rT = (x * matrix[0][0]) + (y * matrix[0][1]) + (z * matrix[0][2]);
@@ -371,6 +379,11 @@ public final class Cam16 {
* @return ARGB representation of color
*/
int viewed(ViewingConditions viewingConditions) {
+ double[] xyz = xyzInViewingConditions(viewingConditions, tempArray);
+ return ColorUtils.argbFromXyz(xyz[0], xyz[1], xyz[2]);
+ }
+
+ double[] xyzInViewingConditions(ViewingConditions viewingConditions, double[] returnArray) {
double alpha =
(getChroma() == 0.0 || getJ() == 0.0) ? 0.0 : getChroma() / Math.sqrt(getJ() / 100.0);
@@ -414,6 +427,13 @@ public final class Cam16 {
double y = (rF * matrix[1][0]) + (gF * matrix[1][1]) + (bF * matrix[1][2]);
double z = (rF * matrix[2][0]) + (gF * matrix[2][1]) + (bF * matrix[2][2]);
- return ColorUtils.argbFromXyz(x, y, z);
+ if (returnArray != null) {
+ returnArray[0] = x;
+ returnArray[1] = y;
+ returnArray[2] = z;
+ return returnArray;
+ } else {
+ return new double[] {x, y, z};
+ }
}
}
diff --git a/libs/material-color-utilities/src/main/java/hct/Hct.java b/libs/material-color-utilities/src/main/java/hct/Hct.java
index 4bcdb781..93806b9b 100644
--- a/libs/material-color-utilities/src/main/java/hct/Hct.java
+++ b/libs/material-color-utilities/src/main/java/hct/Hct.java
@@ -117,6 +117,36 @@ public final class Hct {
setInternalState(HctSolver.solveToInt(hue, chroma, newTone));
}
+ /**
+ * Translate a color into different ViewingConditions.
+ *
+ * Colors change appearance. They look different with lights on versus off, the same color, as
+ * in hex code, on white looks different when on black. This is called color relativity, most
+ * famously explicated by Josef Albers in Interaction of Color.
+ *
+ *
In color science, color appearance models can account for this and calculate the appearance
+ * of a color in different settings. HCT is based on CAM16, a color appearance model, and uses it
+ * to make these calculations.
+ *
+ *
See ViewingConditions.make for parameters affecting color appearance.
+ */
+ public Hct inViewingConditions(ViewingConditions vc) {
+ // 1. Use CAM16 to find XYZ coordinates of color in specified VC.
+ Cam16 cam16 = Cam16.fromInt(toInt());
+ double[] viewedInVc = cam16.xyzInViewingConditions(vc, null);
+
+ // 2. Create CAM16 of those XYZ coordinates in default VC.
+ Cam16 recastInVc =
+ Cam16.fromXyzInViewingConditions(
+ viewedInVc[0], viewedInVc[1], viewedInVc[2], ViewingConditions.DEFAULT);
+
+ // 3. Create HCT from:
+ // - CAM16 using default VC with XYZ coordinates in specified VC.
+ // - L* converted from Y in XYZ coordinates in specified VC.
+ return Hct.from(
+ recastInVc.getHue(), recastInVc.getChroma(), ColorUtils.lstarFromY(viewedInVc[1]));
+ }
+
private void setInternalState(int argb) {
this.argb = argb;
Cam16 cam = Cam16.fromInt(argb);
diff --git a/libs/material-color-utilities/src/main/java/hct/ViewingConditions.java b/libs/material-color-utilities/src/main/java/hct/ViewingConditions.java
index 93a3a6bb..3e452de0 100644
--- a/libs/material-color-utilities/src/main/java/hct/ViewingConditions.java
+++ b/libs/material-color-utilities/src/main/java/hct/ViewingConditions.java
@@ -33,16 +33,7 @@ import utils.MathUtils;
public final class ViewingConditions {
/** sRGB-like viewing conditions. */
public static final ViewingConditions DEFAULT =
- ViewingConditions.make(
- new double[] {
- ColorUtils.whitePointD65()[0],
- ColorUtils.whitePointD65()[1],
- ColorUtils.whitePointD65()[2]
- },
- (200.0 / Math.PI * ColorUtils.yFromLstar(50.0) / 100.f),
- 50.0,
- 2.0,
- false);
+ ViewingConditions.defaultWithBackgroundLstar(50.0);
private final double aw;
private final double nbb;
@@ -113,12 +104,15 @@ public final class ViewingConditions {
* such as knowing an apple is still red in green light. default = false, the eye does not
* perform this process on self-luminous objects like displays.
*/
- static ViewingConditions make(
+ public static ViewingConditions make(
double[] whitePoint,
double adaptingLuminance,
double backgroundLstar,
double surround,
boolean discountingIlluminant) {
+ // A background of pure black is non-physical and leads to infinities that represent the idea
+ // that any color viewed in pure black can't be seen.
+ backgroundLstar = Math.max(0.1, backgroundLstar);
// Transform white point XYZ to 'cone'/'rgb' responses
double[][] matrix = Cam16.XYZ_TO_CAM16RGB;
double[] xyz = whitePoint;
@@ -166,6 +160,20 @@ public final class ViewingConditions {
return new ViewingConditions(n, aw, nbb, ncb, c, nc, rgbD, fl, Math.pow(fl, 0.25), z);
}
+ /**
+ * Create sRGB-like viewing conditions with a custom background lstar.
+ *
+ *
Default viewing conditions have a lstar of 50, midgray.
+ */
+ public static ViewingConditions defaultWithBackgroundLstar(double lstar) {
+ return ViewingConditions.make(
+ ColorUtils.whitePointD65(),
+ (200.0 / Math.PI * ColorUtils.yFromLstar(50.0) / 100.f),
+ lstar,
+ 2.0,
+ false);
+ }
+
/**
* Parameters are intermediate values of the CAM16 conversion process. Their names are shorthand
* for technical color science terminology, this class would not benefit from documenting them
diff --git a/libs/material-color-utilities/src/main/java/palettes/TonalPalette.java b/libs/material-color-utilities/src/main/java/palettes/TonalPalette.java
index fdcdd2de..3347c78e 100644
--- a/libs/material-color-utilities/src/main/java/palettes/TonalPalette.java
+++ b/libs/material-color-utilities/src/main/java/palettes/TonalPalette.java
@@ -25,6 +25,7 @@ import java.util.Map;
*/
public final class TonalPalette {
Map cache;
+ Hct keyColor;
double hue;
double chroma;
@@ -34,9 +35,18 @@ public final class TonalPalette {
* @param argb ARGB representation of a color
* @return Tones matching that color's hue and chroma.
*/
- public static final TonalPalette fromInt(int argb) {
- Hct hct = Hct.fromInt(argb);
- return TonalPalette.fromHueAndChroma(hct.getHue(), hct.getChroma());
+ public static TonalPalette fromInt(int argb) {
+ return fromHct(Hct.fromInt(argb));
+ }
+
+ /**
+ * Create tones using a HCT color.
+ *
+ * @param hct HCT representation of a color.
+ * @return Tones matching that color's hue and chroma.
+ */
+ public static TonalPalette fromHct(Hct hct) {
+ return new TonalPalette(hct.getHue(), hct.getChroma(), hct);
}
/**
@@ -46,14 +56,53 @@ public final class TonalPalette {
* @param chroma HCT chroma
* @return Tones matching hue and chroma.
*/
- public static final TonalPalette fromHueAndChroma(double hue, double chroma) {
- return new TonalPalette(hue, chroma);
+ public static TonalPalette fromHueAndChroma(double hue, double chroma) {
+ return new TonalPalette(hue, chroma, createKeyColor(hue, chroma));
}
- private TonalPalette(double hue, double chroma) {
+ private TonalPalette(double hue, double chroma, Hct keyColor) {
cache = new HashMap<>();
this.hue = hue;
this.chroma = chroma;
+ this.keyColor = keyColor;
+ }
+
+ /** The key color is the first tone, starting from T50, matching the given hue and chroma. */
+ private static Hct createKeyColor(double hue, double chroma) {
+ double startTone = 50.0;
+ Hct smallestDeltaHct = Hct.from(hue, chroma, startTone);
+ double smallestDelta = Math.abs(smallestDeltaHct.getChroma() - chroma);
+ // Starting from T50, check T+/-delta to see if they match the requested
+ // chroma.
+ //
+ // Starts from T50 because T50 has the most chroma available, on
+ // average. Thus it is most likely to have a direct answer and minimize
+ // iteration.
+ for (double delta = 1.0; delta < 50.0; delta += 1.0) {
+ // Termination condition rounding instead of minimizing delta to avoid
+ // case where requested chroma is 16.51, and the closest chroma is 16.49.
+ // Error is minimized, but when rounded and displayed, requested chroma
+ // is 17, key color's chroma is 16.
+ if (Math.round(chroma) == Math.round(smallestDeltaHct.getChroma())) {
+ return smallestDeltaHct;
+ }
+
+ final Hct hctAdd = Hct.from(hue, chroma, startTone + delta);
+ final double hctAddDelta = Math.abs(hctAdd.getChroma() - chroma);
+ if (hctAddDelta < smallestDelta) {
+ smallestDelta = hctAddDelta;
+ smallestDeltaHct = hctAdd;
+ }
+
+ final Hct hctSubtract = Hct.from(hue, chroma, startTone - delta);
+ final double hctSubtractDelta = Math.abs(hctSubtract.getChroma() - chroma);
+ if (hctSubtractDelta < smallestDelta) {
+ smallestDelta = hctSubtractDelta;
+ smallestDeltaHct = hctSubtract;
+ }
+ }
+
+ return smallestDeltaHct;
}
/**
@@ -72,4 +121,24 @@ public final class TonalPalette {
}
return color;
}
+
+ /** Given a tone, use hue and chroma of palette to create a color, and return it as HCT. */
+ public Hct getHct(double tone) {
+ return Hct.from(this.hue, this.chroma, tone);
+ }
+
+ /** The chroma of the Tonal Palette, in HCT. Ranges from 0 to ~130 (for sRGB gamut). */
+ public double getChroma() {
+ return this.chroma;
+ }
+
+ /** The hue of the Tonal Palette, in HCT. Ranges from 0 to 360. */
+ public double getHue() {
+ return this.hue;
+ }
+
+ /** The key color is the first tone, starting from T50, that matches the palette's chroma. */
+ public Hct getKeyColor() {
+ return this.keyColor;
+ }
}
diff --git a/libs/material-color-utilities/src/main/java/utils/ColorUtils.java b/libs/material-color-utilities/src/main/java/utils/ColorUtils.java
index bada576e..27430ad8 100644
--- a/libs/material-color-utilities/src/main/java/utils/ColorUtils.java
+++ b/libs/material-color-utilities/src/main/java/utils/ColorUtils.java
@@ -187,6 +187,21 @@ public class ColorUtils {
return 100.0 * labInvf((lstar + 16.0) / 116.0);
}
+ /**
+ * Converts a Y value to an L* value.
+ *
+ * L* in L*a*b* and Y in XYZ measure the same quantity, luminance.
+ *
+ *
L* measures perceptual luminance, a linear scale. Y in XYZ measures relative luminance, a
+ * logarithmic scale.
+ *
+ * @param y Y in XYZ
+ * @return L* in L*a*b*
+ */
+ public static double lstarFromY(double y) {
+ return labF(y / 100.0) * 116.0 - 16.0;
+ }
+
/**
* Linearizes an RGB component.
*