Add Color.Material and :material_pbr sort strategy for mixed finishes

Author: kipcole9

lib/color/material.ex

@@ -0,0 +1,253 @@
+defmodule Color.Material do
+  @moduledoc """
+  A physically-based-rendering (PBR) material wrapper around a
+  base colour.
+
+  `%Color.SRGB{}` describes a colour stimulus. `%Color.Material{}`
+  describes a *surface* — a colour plus the appearance parameters
+  (metallic, roughness, clearcoat) that determine whether the
+  surface reads as plastic, painted metal, glossy varnish, or
+  matte ceramic. Two materials can share the same base colour yet
+  look entirely different because of how light interacts with
+  them.
+
+  The parameter set deliberately matches the Disney Principled
+  BSDF / glTF 2.0 `pbrMetallicRoughness` convention so values
+  from those sources can be imported directly.
+
+  ## Why this exists
+
+  When you sort a palette that mixes plastic swatches with
+  polished-metal swatches, any single-axis colour sort puts
+  identical base colours next to each other regardless of
+  finish — a red plastic and a red-anodized aluminium end up
+  visually adjacent even though users file them into different
+  mental categories. `Color.Palette.Sort`'s `:material_pbr`
+  strategy consumes this struct and produces an ordering that
+  respects the metallic-vs-dielectric cliff first, then colour,
+  then gloss.
+
+  ## Parameters
+
+  * `:base_color` — a `%Color.SRGB{}` struct. The "albedo" for
+    dielectrics or the "specular colour" for metals.
+
+  * `:metallic` — `0.0`–`1.0`. `0.0` is a pure dielectric
+    (plastic, paint, wood, skin); `1.0` is a pure conductor
+    (gold, copper, aluminium). Values in between model partial
+    metallic coatings such as metallic automotive paint.
+
+  * `:roughness` — `0.0`–`1.0`. `0.0` is a perfect mirror;
+    `1.0` is a fully diffuse (Lambertian) surface.
+
+  * `:clearcoat` — `0.0`–`1.0`. Strength of an optional
+    dielectric varnish layer on top. Defaults to `0.0`
+    (no clearcoat).
+
+  * `:clearcoat_roughness` — `0.0`–`1.0`. Roughness of the
+    clearcoat layer. Ignored when `:clearcoat` is `0.0`.
+    Defaults to `0.03` (near-mirror, matching automotive paint).
+
+  * `:name` — optional string label stored with the material.
+
+  ## Example
+
+      iex> {:ok, red} = Color.new("#ff0000")
+      iex> mat = Color.Material.new(red, metallic: 0.0, roughness: 0.85, name: "Matte Red PC")
+      iex> mat.name
+      "Matte Red PC"
+      iex> mat.metallic
+      0.0
+
+  """
+
+  @default_metallic 0.0
+  @default_roughness 0.5
+  @default_clearcoat 0.0
+  @default_clearcoat_roughness 0.03
+
+  @valid_keys [:metallic, :roughness, :clearcoat, :clearcoat_roughness, :name]
+
+  defstruct [
+    :base_color,
+    :name,
+    metallic: @default_metallic,
+    roughness: @default_roughness,
+    clearcoat: @default_clearcoat,
+    clearcoat_roughness: @default_clearcoat_roughness
+  ]
+
+  @type t :: %__MODULE__{
+          base_color: Color.SRGB.t(),
+          metallic: float(),
+          roughness: float(),
+          clearcoat: float(),
+          clearcoat_roughness: float(),
+          name: binary() | nil
+        }
+
+  @doc """
+  Builds a `%Color.Material{}` struct.
+
+  ### Arguments
+
+  * `color_input` is anything accepted by `Color.new/1` — a hex
+    string, a CSS named colour, an `%Color.SRGB{}` struct, an
+    Oklch struct, etc. The input is normalised to `%Color.SRGB{}`
+    and stored in `:base_color`.
+
+  ### Options
+
+  * `:metallic` is the metallic parameter in `[0.0, 1.0]`.
+    Default `0.0` (dielectric).
+
+  * `:roughness` is the roughness parameter in `[0.0, 1.0]`.
+    Default `0.5`.
+
+  * `:clearcoat` is the clearcoat strength in `[0.0, 1.0]`.
+    Default `0.0`.
+
+  * `:clearcoat_roughness` is the clearcoat roughness in
+    `[0.0, 1.0]`. Default `0.03`.
+
+  * `:name` is an optional string label.
+
+  ### Returns
+
+  * A `%Color.Material{}` struct.
+
+  ### Examples
+
+      iex> mat = Color.Material.new("#c0c0c0", metallic: 1.0, roughness: 0.2)
+      iex> mat.metallic
+      1.0
+      iex> mat.roughness
+      0.2
+
+      iex> mat = Color.Material.new("red")
+      iex> Color.to_hex(mat.base_color)
+      "#ff0000"
+      iex> mat.metallic
+      0.0
+
+  """
+  @spec new(Color.input(), keyword()) :: t()
+  def new(color_input, options \\ []) do
+    options = validate_options!(options)
+
+    {:ok, srgb} = Color.new(color_input)
+
+    %__MODULE__{
+      base_color: srgb,
+      metallic: Keyword.fetch!(options, :metallic),
+      roughness: Keyword.fetch!(options, :roughness),
+      clearcoat: Keyword.fetch!(options, :clearcoat),
+      clearcoat_roughness: Keyword.fetch!(options, :clearcoat_roughness),
+      name: Keyword.get(options, :name)
+    }
+  end
+
+  @doc """
+  Returns the underlying base colour.
+
+  ### Arguments
+
+  * `material` is a `%Color.Material{}` struct.
+
+  ### Returns
+
+  * A `%Color.SRGB{}` struct.
+
+  ### Examples
+
+      iex> mat = Color.Material.new("#ff0000")
+      iex> Color.to_hex(Color.Material.base_color(mat))
+      "#ff0000"
+
+  """
+  @spec base_color(t()) :: Color.SRGB.t()
+  def base_color(%__MODULE__{base_color: color}), do: color
+
+  @doc """
+  Returns a tuple suitable for tuple-based sorting.
+
+  The tuple is `{metallic_bucket, hue, lightness, roughness}`
+  where `metallic_bucket` is `0` for dielectrics and `1` for
+  metals, computed from `metallic >= threshold`.
+
+  Used by `Color.Palette.Sort`'s `:material_pbr` strategy and
+  exposed so third parties can compose their own sort keys.
+
+  ### Arguments
+
+  * `material` is a `%Color.Material{}` struct.
+
+  ### Options
+
+  * `:metallic_threshold` is the cutoff between dielectric and
+    metallic buckets, in `(0.0, 1.0]`. Default `0.5`.
+
+  ### Returns
+
+  * A `{integer, float, float, float}` tuple.
+
+  ### Examples
+
+      iex> mat = Color.Material.new("#c0c0c0", metallic: 1.0, roughness: 0.2)
+      iex> {bucket, _h, _l, rough} = Color.Material.to_pbr_tuple(mat)
+      iex> bucket
+      1
+      iex> rough
+      0.2
+
+  """
+  @spec to_pbr_tuple(t(), keyword()) ::
+          {non_neg_integer(), float(), float(), float()}
+  def to_pbr_tuple(%__MODULE__{} = material, options \\ []) do
+    threshold = Keyword.get(options, :metallic_threshold, 0.5)
+
+    {:ok, oklch} = Color.convert(material.base_color, Color.Oklch)
+
+    bucket = if material.metallic >= threshold, do: 1, else: 0
+    h = oklch.h || 0.0
+    l = oklch.l || 0.0
+
+    {bucket, h, l, material.roughness}
+  end
+
+  # ---- options validation -------------------------------------------------
+
+  defp validate_options!(options) do
+    Enum.each(Keyword.keys(options), fn key ->
+      unless key in @valid_keys do
+        raise Color.PaletteError,
+          reason: :unknown_option,
+          detail: "#{inspect(key)} (valid options: #{inspect(@valid_keys)})"
+      end
+    end)
+
+    options =
+      options
+      |> Keyword.put_new(:metallic, @default_metallic)
+      |> Keyword.put_new(:roughness, @default_roughness)
+      |> Keyword.put_new(:clearcoat, @default_clearcoat)
+      |> Keyword.put_new(:clearcoat_roughness, @default_clearcoat_roughness)
+
+    check_unit_float!(options, :metallic)
+    check_unit_float!(options, :roughness)
+    check_unit_float!(options, :clearcoat)
+    check_unit_float!(options, :clearcoat_roughness)
+
+    options
+  end
+
+  defp check_unit_float!(options, key) do
+    value = Keyword.fetch!(options, key)
+
+    unless is_number(value) and value >= 0.0 and value <= 1.0 do
+      raise Color.PaletteError,
+        reason: :"invalid_#{key}",
+        detail: "#{inspect(key)} must be a number in [0.0, 1.0]"
+    end
+  end
+end

lib/color/palette.ex

@@ -31,8 +31,12 @@ defmodule Color.Palette do
 
   * `sort/2` — orders an arbitrary list of colours into a
     perceptually-sensible sequence (rainbow, stepped-hue grid,
-    or lightness ramp). Useful when you have a heterogeneous
-    bag of swatches and need a human-readable layout.
+    lightness ramp, or material-aware PBR order). Useful when
+    you have a heterogeneous bag of swatches and need a
+    human-readable layout. When the input mixes
+    `%Color.Material{}` structs (plastic, metal, ceramic), the
+    `:material_pbr` strategy splits dielectrics from metals
+    before colour-sorting each bucket.
 
   ## Working space