Verify color conversion parity, fix a bunch of issues

Author: PollRobots

docs/color.md

@@ -21,7 +21,7 @@ relatively high smoothing factor), the color evenly blends as the shapes blend.
 
 This tool processes color internally within the shader in the CIE XYZ
 colorspace. This is makes the math that operates on color values easier in the
-shader pipeline, because the color values are in a perceptually uniform space,
+shader pipeline, because the color values are in a linear space,
 but it can be harder to reason about them.
 
 To demonstrate this, the following example colors a cube with a blend of red →
@@ -61,12 +61,81 @@ second values according to the third value, which clamped between 0 and 1. The
 box in the example has been positioned to ensure that the x-coordinate is 0 on
 the left hand edge and 1 on the right hand edge.
 
+## Supported Color Spaces
+
+### sRGB
+
+[sRGB](https://en.wikipedia.org/wiki/sRGB) is the standard color space used for
+web presentation. The three color channels represent red, green, and blue, and
+have ranges from 0→1. Every rgb value where each channel is between 0 and 1 is
+displayable. The other colorspaces can represent colors outside of these bounds,
+some of which would be considered visible, but cannot be represented on screen,
+and others are outside the gamut of human vision.
+
+### CIE XYZ
+
+[CIE 1931 XYZ](https://en.wikipedia.org/wiki/CIEXYZ) is the color space used
+internally in the shader. Colors are converted to sRGB only at the final stage
+of setting the pixel value. The three color values X, Y, Z can have ranges from 0 -> (0.950489, 1, 1.08884) respectively. These limits are derived from the
+D65 standard illuminant. Any color in the XYZ color space that is within these
+bounds can be considered ‘visible‛, but not all of those colors will be
+displayable.
+
+### CIE L\*a\*b\*
+
+[CIE L\*a\*b\*](https://en.wikipedia.org/wiki/CIELAB_color_space) is an
+approximately perceptually uniform color space derived from CIE XYZ.
+
+- The L\* (L-star) value is a lightness value between 0–black, and
+  100–white.
+- The a\* value represents a green↔red axis, with negative values adding green,
+  and positive values adding red.
+- The b\* value represents a blue↔yellow axis, with negative values adding blue,
+  and positive values adding yellow.
+
+The a\* and b\* values aren't formally bounded, but useful values are typically
+between ±150
+
+### CIE L\*C\*h
+
+[CIE
+L\*C\*h°](https://en.wikipedia.org/wiki/CIELAB_color_space#Cylindrical_model) is
+a transformation of the CIE L\*a\*b\* color space into cylindrical polar
+coordinates.
+
+- The L\* value has the same interpretation as in LAB space, lightness between 0–black and 100–white.
+- C\* is the length of the vector <a\*, b\*>, and represents chromaticity
+- h° is an angle in degrees, where 0°&ndash;red, 90°&ndash;yellow,
+  180°&ndash;green, 270°&ndash;blue. Note that this is similar to, but
+  not the same as the H value in HSL or HSV color models.
+
+```example
+#|start-interactive-values
+  view.z = 0.3
+  c = 75 [0:100:1]
+  l = 50 [0:100:1]
+end-interactive-values|#
+
+(union
+  (color (saturate-xyz (lch-xyz #<:l :c 0>))
+    (sphere #<-3 1 0> 1))
+  (color (saturate-xyz (lch-xyz #<:l :c 90>))
+    (sphere #<-1 1 0> 1))
+  (color (saturate-xyz (lch-xyz #<:l :c 180>))
+    (sphere #<1 1 0> 1))
+  (color (saturate-xyz (lch-xyz #<:l :c 270>))
+    (sphere #<3 1 0> 1)))
+```
+
+This shows four spheres each with the same lightness and chrominance values at
+the four cardinal color directions in the L\*C\*h° color space.
+
 ## Conversion Functions
 
 This tool processes color internally within the shader in the CIE XYZ
-colorspace. This is makes the math that operates on color values easier in the
-shader pipeline, because the color values are in a perceptually uniform space,
-but it is harder to reason about them.
+color space. This is makes the math that operates on color values easier in the
+shader pipeline, because the color values are in a linear space, but it is
+harder to reason about them.
 
 The following conversion functions are provided which can make manipulating colors easier.
 
@@ -85,8 +154,8 @@ Or to adjust the hue by a fixed value without changing saturation or lightness
 (lch-xyz (+ (xyz-lch a) #<0 0 20>))
 ```
 
-This converts to the CIE LCH colorspace (via CIE LAB) (where the H is a hue value in degrees),
-adds 20° and then converts back.
+This converts to the CIE LCH color space (via CIE LAB) (where the H is a hue
+value in degrees), adds 20° and then converts back.
 
 ![RGB → XYZ](rgb-xyz.doc)
 ![XYZ → RGB](xyz-rgb.doc)

docs/faq.md

@@ -89,6 +89,10 @@ The code editing font is Nikita Prokopov's "[Fira
 Code](https://github.com/tonsky/FiraCode)" as packaged by
 [fontsource](https://npmjs.com/@fontsource-variable/fira-code)
 
+The evaluation time color space conversions were derived from the
+[colorspaces.js](https://github.com/boronine/colorspaces.js) library by Alexei
+Boronine.
+
 # Acknowledgments
 
 It is pretty much impossible to play with SDFs without recognizing the contribution that Inigo Quillez has made in this space.

src/app.tsx

@@ -315,12 +315,9 @@ export const App: React.FC = () => {
                 fontVariantLigatures: "discretionary-ligatures",
               }}
             >
-              <pre style={{ fontFamily: "unset", whiteSpace: "pre-wrap" }}>
-                {generated}
-              </pre>
+              <pre style={{ whiteSpace: "pre-wrap" }}>{generated}</pre>
               <pre
                 style={{
-                  fontFamily: "unset",
                   whiteSpace: "pre-wrap",
                   color: currTheme.red,
                 }}

src/builtins.ts

@@ -1435,7 +1435,7 @@ const kBuiltins: Internal[] = [
       const vec = coerce(args[0], "vec");
       return {
         type: "vec",
-        code: `clamp(vec3<f32>(0), kReferenceD65 * 0.01, ${vec.code})`,
+        code: `clamp(vec3<f32>(0), kReferenceD65, ${vec.code})`,
       };
     },
     docs: [
@@ -1520,8 +1520,9 @@ const kBuiltins: Internal[] = [
     },
     docs: [
       "(**rgb-xyz** *rgb*)",
-      "Converts the *rgb* vector representing a color in sRgb space, into a vector " +
-        "representing the same color in CIE 1931 XYZ color space, using the D65 reference illuminant",
+      "Converts the *rgb* vector representing a color in sRgb space, into a " +
+        "vector representing the same color in CIE 1931 XYZ color space, using " +
+        "the D65 reference illuminant",
     ],
     insertText: "rgb-xyz ${1:rgb}",
   },
@@ -1544,8 +1545,9 @@ const kBuiltins: Internal[] = [
     },
     docs: [
       "(**xyz-rgb** *xyz*)",
-      "Converts the *xyz* vector representing a color in CIE 1931 XYZ color space, into a vector " +
-        "representing the same color in sRgb color space, using the D65 reference illuminant",
+      "Converts the *xyz* vector representing a color in CIE 1931 XYZ color " +
+        "space, into a vector representing the same color in sRgb color space, " +
+        "using the D65 reference illuminant",
     ],
     insertText: "xyz-rgb ${1:xyz}",
   },
@@ -1629,7 +1631,7 @@ const kBuiltins: Internal[] = [
       requireArity("lch-lab", 1, args);
       requireVector("lch-lab", 0, args[0]);
       const lch = args[0].value as Vector;
-      const lab = make_color("CIEXYZ", [lch.x, lch.y, lch.z]).as(
+      const lab = make_color("CIELCH", [lch.x, lch.y, lch.z]).as(
         "CIELAB"
       ) as ColorTuple;
 
@@ -1718,7 +1720,7 @@ const kLambdas: MacroDef[] = [
         "space, into a vector representing the same color in CIE 1931 XYZ color " +
         "space, using the D65 reference illuminant",
     ],
-    insertText: "lch-xyz ${1:xyz}",
+    insertText: "lch-xyz ${1:lch}",
   },
   {
     name: "step",

src/colorspaces.ts

@@ -259,8 +259,8 @@ const polar_to_scalar = (tuple: ColorValue): ColorValue => {
   const _C = tuple[1];
   const _h = tuple[2];
   const _h_rad = (_h / 360) * 2 * Math.PI;
-  const var1 = Math.cos(_h_rad) * _C;
-  const var2 = Math.sin(_h_rad) * _C;
+  const var1 = Math.sin(_h_rad) * _C;
+  const var2 = Math.cos(_h_rad) * _C;
   return [_L, var1, var2];
 };
 conv["CIELCH"]["CIELAB"] = polar_to_scalar;

src/sdf/colors.wgsl

@@ -1,85 +1,107 @@
 const kRgbToXyzMat = mat3x3<f32>(
-  vec3<f32>(0.4124, 0.2126, 0.0193),
-  vec3<f32>(0.3576, 0.7152, 0.1192),
-  vec3<f32>(0.1805, 0.0722, 0.9505));
+    vec3<f32>(0.4124, 0.2126, 0.0193),
+    vec3<f32>(0.3576, 0.7152, 0.1192),
+    vec3<f32>(0.1805, 0.0722, 0.9505)
+);
 
 fn colRgbToXyz(rgb: vec3<f32>) -> vec3<f32> {
-  return kRgbToXyzMat * rgb;
+    return kRgbToXyzMat * rgb;
 }
 
 fn colSRgbToXyz(sRgb: vec3<f32>) -> vec3<f32> {
-  var rgb = select(sRgb / 12.92,
-               pow((sRgb + 0.055) / 1.055, vec3<f32>(2.4)),
-               sRgb > vec3<f32>(0.04045));
-  return kRgbToXyzMat * rgb;
+    var rgb = select(sRgb / 12.92,
+        pow((sRgb + 0.055) / 1.055, vec3<f32>(2.4)),
+        sRgb > vec3<f32>(0.04045));
+    return kRgbToXyzMat * rgb;
 }
 
 const kXyzToRgbMat = mat3x3<f32>(
-  vec3<f32>(3.2046, -0.9689, 0.0577),
-  vec3<f32>(-1.5372, 1.8758, -0.2040),
-  vec3<f32>(-0.4986, 0.0415, 1.0570));
+    vec3<f32>(3.2046, -0.9689, 0.0577),
+    vec3<f32>(-1.5372, 1.8758, -0.2040),
+    vec3<f32>(-0.4986, 0.0415, 1.0570)
+);
 
 fn colXyzToSRgb(xyz: vec3<f32>) -> vec3<f32> {
-  var rgb = kXyzToRgbMat * xyz;
+    var rgb = kXyzToRgbMat * xyz;
 
-  rgb = select(rgb * 12.92,
-               1.055 * (pow(rgb, vec3<f32>(1/2.4)) - 0.055),
-               rgb > vec3<f32>(0.0031308));
+    rgb = select(rgb * 12.92,
+        1.055 * (pow(rgb, vec3<f32>(1 / 2.4)) - 0.055),
+        rgb > vec3<f32>(0.0031308));
 
-  return rgb;
+    return rgb;
 }
 
-const kReferenceD65 = vec3<f32>(95.0489, 100, 108.884);
+const kReferenceD65 = vec3<f32>(0.950489, 1, 1.08884);
+
+
+// matrix
+// ┌                     ┐
+// │ 0    116   0    -16 │
+// │ 500 -500   0     0  │
+// │ 0    200  -200   0  │
+// └                     ┘
+
 
 const kXyzToLabMat = mat4x3<f32>(
-  vec3<f32>(0, 500, 0),
-  vec3<f32>(116, -500, 200),
-  vec3<f32>(0, 0, -200),
-  vec3<f32>(-16, 0, 0));
+    vec3<f32>(0, 500, 0),
+    vec3<f32>(116, -500, 200),
+    vec3<f32>(0, 0, -200),
+    vec3<f32>(-16, 0, 0)
+);
 
 fn colXyzToCIELab(xyz: vec3<f32>) -> vec3<f32> {
-  var s = xyz / kReferenceD65;
+    var s = xyz / kReferenceD65;
 
-  const d3 = (6.0 * 6.0 * 6.0) / (29.0 * 29.0 * 29.0);
-  const i3d2 = (29.0 * 29.0) / (6.0 * 6.0 * 3);
+    const d3 = (6.0 * 6.0 * 6.0) / (29.0 * 29.0 * 29.0);
+    const i3d2 = (29.0 * 29.0) / (6.0 * 6.0 * 3);
 
-  s = select(s * i3d2 + vec3<f32>(4.0/29.0),
-             pow(s, vec3<f32>(1/3)),
-             s > vec3<f32>(d3));
+    s = select(s * i3d2 + vec3<f32>(4.0 / 29.0),
+        pow(s, vec3<f32>(1.0 / 3.0)),
+        s > vec3<f32>(d3));
 
-  return kXyzToLabMat * vec4<f32>(s, 1);
+    return kXyzToLabMat * vec4<f32>(s, 1);
 }
 
+// matrix
+// ┌                           ┐
+// │ 1/116  1/500 0     16/116 │
+// │ 1/116  0     0     16/116 │
+// │ 1/116  0    -1/200 16/116 │
+// └                           ┘
 const kLabToXyzMat = mat4x3<f32>(
-  vec3<f32>(1.0/116.0),
-  vec3<f32>(1.0/500.0, 0, 0),
-  vec3<f32>(0, 0, -1.0/200.0),
-  vec3<f32>(16.0/116.0));
+    vec3<f32>(1.0 / 116.0, 1.0 / 116.0, 1.0 / 116.0),
+    vec3<f32>(1.0 / 500.0, 0, 0),
+    vec3<f32>(0, 0, -1.0 / 200.0),
+    vec3<f32>(16.0 / 116.0, 16.0 / 116.0, 16.0 / 116.0)
+);
 
 fn colCIELabToXyz(lab: vec3<f32>) -> vec3<f32> {
-  var xyz = kLabToXyzMat * vec4<f32>(lab, 1);
+    var xyz = kLabToXyzMat * vec4<f32>(lab, 1);
 
-  const d = vec3<f32>(6.0/29.0);
-  const t3d2 = vec3<f32>((3.0 * 6.0 * 6.0) / (29.0 * 29.0));
+    // δ = 6/29 24/116
+    const d = vec3<f32>(6.0 / 29.0);
+    // 3δ²
+    const t3d2 = vec3<f32>((3.0 * 6.0 * 6.0) / (29.0 * 29.0));
 
-  xyz = select(t3d2 * (xyz - vec3<f32>(4.0/29.0)),
-               xyz * xyz * xyz,
-               xyz > d);
+    xyz = select(t3d2 * (xyz - vec3<f32>(4.0 / 29.0)), // t ≤ δ → 3δ²(t - 4/29)
+        xyz * xyz * xyz, // t > δ → t³
+        xyz > d);
 
-  return xyz * kReferenceD65;
+    return xyz * kReferenceD65;
 }
 
 fn colCIELabToLch(lab: vec3<f32>) -> vec3<f32> {
-  var h = degrees(atan2(lab.z, lab.y));
-  h = select(h + 360, h, h >= 0);
-
-  return vec3<f32>(
-    lab.x,
-    length(lab.yz),
-    h);
+    var h = degrees(atan2(lab.z, lab.y));
+    h = select(h + 360, h, h >= 0);
+
+    return vec3<f32>(
+        lab.x,
+        length(lab.yz),
+        h
+    );
 }
 
 fn colCIELchToLab(lch: vec3<f32>) -> vec3<f32> {
-  var h = radians(lch.z);
-  return vec3<f32>(lch.x, lch.y * cos(h), lch.y * sin(h));
+    var h = radians(lch.z);
+    return vec3<f32>(lch.x, lch.y * sin(h), lch.y * cos(h));
 }

src/sdf/map.wgsl

@@ -1,6 +1,6 @@
 fn map(p: vec3<f32>) -> vec4<f32> {
-  var k: f32 = 0;
-  var col = kReferenceD65 * 0.01;
-  var res4 = vec4<f32>(0);
+    var k: f32 = 0;
+    var col = kReferenceD65;
+    var res4 = vec4<f32>(0);
   //MAP-CODE//
 }