Add :chroma_ceiling option and expose :gamut in tonal visualizer

Author: kipcole9

lib/color/palette.ex

@@ -72,7 +72,16 @@ defmodule Color.Palette do
     matching how human vision perceives lightness. Default `false`.
 
   * `:gamut` is the working space to gamut-map each stop into,
-    default `:SRGB`.
+    default `:SRGB`. Widening the gamut (for example `:P3_D65` or
+    `:Rec2020`) gives non-seed stops more chroma headroom and
+    produces a smoother ramp for saturated seeds, at the cost of
+    colours that may not display accurately on sRGB-only monitors.
+
+  * `:chroma_ceiling` is a float in `(0.0, 1.0]` that caps each
+    stop's chroma at `ceiling × max_chroma(L, H, gamut)`. The
+    default `1.0` lets stops hug the gamut boundary. Lowering it
+    (for example `0.85`) produces a more muted, evenly
+    saturated-looking ramp.
 
   * `:name` is an optional string label stored on the struct.
 

lib/color/palette/tonal.ex

@@ -30,12 +30,23 @@ defmodule Color.Palette.Tonal do
      human vision perceives lightness — a phenomenon known as the
      Hunt effect — and gives the scale a more natural feel.
 
-  5. **Snap to seed**. Find the generated stop whose lightness is
+  5. **Cap to a fraction of the gamut envelope**. When
+     `:chroma_ceiling` is below `1.0`, cap each stop's chroma at
+     `ceiling × max_chroma(L, H, gamut)`. This produces a more
+     muted ramp that sits strictly inside the gamut boundary
+     instead of hugging it. At the default `1.0` this step is a
+     no-op.
+
+  6. **Snap to seed**. Find the generated stop whose lightness is
      closest to the seed's lightness and replace it with the seed
      itself. The `:seed_stop` field on the resulting struct
-     records which stop received the seed.
+     records which stop received the seed. Note that when
+     `:chroma_ceiling` is below `1.0` and the seed sits near the
+     gamut boundary, the seed will be visibly more saturated than
+     its capped neighbours — pick a wider `:gamut` instead if you
+     want a smoother ramp without muting the seed.
 
-  6. **Gamut-map** each stop into the requested working space
+  7. **Gamut-map** each stop into the requested working space
      (default `:SRGB`) using the CSS Color 4 Oklch binary-search
      algorithm provided by `Color.Gamut.to_gamut/3`.
 
@@ -51,11 +62,11 @@ defmodule Color.Palette.Tonal do
 
       iex> palette = Color.Palette.Tonal.new("#3b82f6")
       iex> Map.fetch!(palette.stops, 50) |> Color.to_hex()
-      "#f4f9ff"
+      "#f5f9ff"
 
       iex> palette = Color.Palette.Tonal.new("#3b82f6")
       iex> Map.fetch!(palette.stops, 950) |> Color.to_hex()
-      "#000825"
+      "#000827"
 
   """
 
@@ -123,13 +134,21 @@ defmodule Color.Palette.Tonal do
     dark_anchor = Keyword.fetch!(options, :dark_anchor)
     hue_drift? = Keyword.fetch!(options, :hue_drift)
     gamut = Keyword.fetch!(options, :gamut)
+    chroma_ceiling = Keyword.fetch!(options, :chroma_ceiling)
 
     base_h = seed_oklch.h || 0.0
     base_c = seed_oklch.c || 0.0
 
     seed_l = seed_oklch.l || 0.5
     num_stops = length(stops)
 
+    # Normalise the chroma ceiling so the damping curve passes
+    # through the seed's chroma at the seed's lightness. Without
+    # this, generated neighbours are damped by sin(π · L) while the
+    # seed itself keeps its raw chroma, leaving the seed visibly
+    # more saturated than its neighbours.
+    peak_c = peak_chroma(base_c, seed_l)
+
     # First pass: find which stop the seed would snap to, and
     # compute the curve lightness at that position.
     snap_index = nearest_index(stops, light_anchor, dark_anchor, seed_l)
@@ -165,9 +184,16 @@ defmodule Color.Palette.Tonal do
               lerp(seed_l, dark_anchor, t)
           end
 
-        c = base_c * chroma_damping(l)
+        curve_c = peak_c * chroma_damping(l)
         h = if hue_drift?, do: drift_hue(base_h, position), else: base_h
 
+        c =
+          if chroma_ceiling < 1.0 do
+            min(curve_c, chroma_ceiling * max_chroma_at(l, h, gamut))
+          else
+            curve_c
+          end
+
         oklch = %Color.Oklch{l: l, c: c, h: h, alpha: seed_srgb.alpha}
         {:ok, mapped} = Color.Gamut.to_gamut(oklch, gamut)
         {label, mapped, l}
@@ -475,6 +501,38 @@ defmodule Color.Palette.Tonal do
   # and dark shades don't blow past the sRGB gamut.
   defp chroma_damping(l), do: :math.sin(:math.pi() * clamp01(l))
 
+  # Solve for the pre-damping chroma ceiling that makes
+  # `peak_c · chroma_damping(seed_l) = seed_c`. Floor the divisor
+  # so seeds with extreme lightness don't blow peak_c up to
+  # unreasonable values.
+  @min_seed_damping 0.05
+  defp peak_chroma(base_c, seed_l) do
+    damping = chroma_damping(seed_l)
+    if damping > @min_seed_damping, do: base_c / damping, else: base_c
+  end
+
+  # Binary-search for the maximum chroma that is in gamut at the
+  # given lightness and hue, for the given working space. Used
+  # only when :chroma_ceiling is below 1.0.
+  @max_chroma_search_upper 0.5
+  @max_chroma_search_iters 25
+  defp max_chroma_at(l, h, gamut) do
+    do_max_chroma_search(l, h, gamut, 0.0, @max_chroma_search_upper, @max_chroma_search_iters)
+  end
+
+  defp do_max_chroma_search(_l, _h, _gamut, lo, _hi, 0), do: lo
+
+  defp do_max_chroma_search(l, h, gamut, lo, hi, iters) do
+    mid = (lo + hi) / 2
+    test = %Color.Oklch{l: l, c: mid, h: h, alpha: 1.0}
+
+    if Color.Gamut.in_gamut?(test, gamut) do
+      do_max_chroma_search(l, h, gamut, mid, hi, iters - 1)
+    else
+      do_max_chroma_search(l, h, gamut, lo, mid, iters - 1)
+    end
+  end
+
   # Drift hue toward yellow at the light end and toward blue at
   # the dark end. The drift amount is small (a few degrees) and
   # scales with distance from the midpoint.
@@ -527,7 +585,15 @@ defmodule Color.Palette.Tonal do
 
   # ---- options validation -------------------------------------------------
 
-  @valid_keys [:stops, :light_anchor, :dark_anchor, :hue_drift, :gamut, :name]
+  @valid_keys [
+    :stops,
+    :light_anchor,
+    :dark_anchor,
+    :hue_drift,
+    :gamut,
+    :chroma_ceiling,
+    :name
+  ]
 
   defp validate_options!(options) do
     Enum.each(Keyword.keys(options), fn key ->
@@ -545,6 +611,7 @@ defmodule Color.Palette.Tonal do
       |> Keyword.put_new(:dark_anchor, @default_dark_anchor)
       |> Keyword.put_new(:hue_drift, false)
       |> Keyword.put_new(:gamut, :SRGB)
+      |> Keyword.put_new(:chroma_ceiling, 1.0)
 
     stops = Keyword.fetch!(options, :stops)
 
@@ -589,6 +656,14 @@ defmodule Color.Palette.Tonal do
         detail: ":light_anchor (#{light}) must be greater than :dark_anchor (#{dark})"
     end
 
+    ceiling = Keyword.fetch!(options, :chroma_ceiling)
+
+    unless is_number(ceiling) and ceiling > 0.0 and ceiling <= 1.0 do
+      raise Color.PaletteError,
+        reason: :invalid_chroma_ceiling,
+        detail: ":chroma_ceiling must be a number in (0.0, 1.0]"
+    end
+
     options
   end
 end

lib/color/palette/visualizer.ex

@@ -138,6 +138,8 @@ defmodule Color.Palette.Visualizer do
       %{
         seed: resolve_seed(params, "#3b82f6"),
         hue_drift: truthy?(Map.get(params, "hue_drift")),
+        gamut: gamut_atom(Map.get(params, "gamut")) || :SRGB,
+        chroma_ceiling: number_default(Map.get(params, "chroma_ceiling"), 1.0),
         name: Map.get(params, "name") |> blank_default(nil)
       }
     end

lib/color/palette/visualizer/tonal_view.ex

@@ -4,14 +4,24 @@ defmodule Color.Palette.Visualizer.TonalView do
   alias Color.Palette.Tonal
   alias Color.Palette.Visualizer.Render
 
+  @gamut_options [
+    {:SRGB, "sRGB"},
+    {:P3_D65, "P3 (D65)"},
+    {:Rec2020, "Rec2020"},
+    {:Adobe, "Adobe RGB"},
+    {:ProPhoto, "ProPhoto"}
+  ]
+
   def render(params, base) do
     seed = Map.get(params, :seed, "#3b82f6")
     hue_drift? = Map.get(params, :hue_drift, false)
+    gamut = Map.get(params, :gamut, :SRGB)
+    chroma_ceiling = Map.get(params, :chroma_ceiling, 1.0)
     name = Map.get(params, :name)
     error = Map.get(params, :error)
 
     body =
-      case build(seed, hue_drift?, name) do
+      case build(seed, hue_drift?, gamut, chroma_ceiling, name) do
         {:ok, palette} -> success_body(palette)
         {:error, message} -> ["<div class=\"vz-error\">", Render.escape(message), "</div>"]
       end
@@ -23,16 +33,39 @@ defmodule Color.Palette.Visualizer.TonalView do
       body: body,
       error: error,
       base: base,
-      extra_fields: [
-        "<label><input type=\"checkbox\" name=\"hue_drift\" value=\"1\"",
-        if(hue_drift?, do: " checked", else: ""),
-        "> hue drift</label>"
-      ]
+      extra_fields: extra_fields(hue_drift?, gamut, chroma_ceiling)
     )
   end
 
-  defp build(seed, hue_drift?, name) do
-    options = [hue_drift: hue_drift?]
+  defp extra_fields(hue_drift?, gamut, chroma_ceiling) do
+    [
+      "<label>gamut <select name=\"gamut\">",
+      Enum.map(@gamut_options, fn {atom, label} ->
+        selected = if atom == gamut, do: " selected", else: ""
+        ["<option value=\"", Atom.to_string(atom), "\"", selected, ">", label, "</option>"]
+      end),
+      "</select></label>",
+      "<label>chroma ceiling <input type=\"number\" name=\"chroma_ceiling\"",
+      " min=\"0.1\" max=\"1.0\" step=\"0.05\" value=\"",
+      format_ceiling(chroma_ceiling),
+      "\"></label>",
+      "<label><input type=\"checkbox\" name=\"hue_drift\" value=\"1\"",
+      if(hue_drift?, do: " checked", else: ""),
+      "> hue drift</label>"
+    ]
+  end
+
+  defp format_ceiling(value) when is_float(value), do: :erlang.float_to_binary(value, decimals: 2)
+  defp format_ceiling(value) when is_integer(value), do: Integer.to_string(value)
+  defp format_ceiling(value), do: to_string(value)
+
+  defp build(seed, hue_drift?, gamut, chroma_ceiling, name) do
+    options = [
+      hue_drift: hue_drift?,
+      gamut: gamut,
+      chroma_ceiling: chroma_ceiling
+    ]
+
     options = if name, do: [{:name, name} | options], else: options
     {:ok, Tonal.new(seed, options)}
   rescue