@omi-io/color-gamut 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# `@omi-io/color-gamut`
+
+Gamut queries and mapping for RGB display gamuts (`sRGB`, `Display P3`,
+`Rec.2020`, …): is a color displayable, what is the closest displayable
+fallback, and how much chroma survives at a given lightness and hue.
+
+Conversions in `@omi-io/color-convert` never clamp — out-of-gamut input
+yields out-of-gamut RGB. This package is the explicit opt-in layer on top:
+the CSS Color 4 `css-gamut-map` algorithm (what browsers do for
+`color(srgb …)` fallback, and what oklch.com shows as "closest fallback by
+chroma"), a naive clip, and slider-bound helpers.
+
+## Installation
+
+```bash
+yarn add @omi-io/color-gamut
+```
+
+## Example — sRGB fallback for an out-of-gamut Oklch color
+
+```ts
+import { unsafeAsOklch } from "@omi-io/color-models";
+import { isOklchInGamut, mapToGamut, clipToGamut } from "@omi-io/color-gamut";
+
+const vivid = unsafeAsOklch([0.35, 0.35, 150] as const);
+
+isOklchInGamut(vivid, "sRGB"); // false — not displayable as-is
+
+// CSS Color 4 gamut mapping (default strategy "css"):
+mapToGamut(vivid, "sRGB"); // ~[0.3590, 0.1140, 144.68] — closest fallback
+clipToGamut(vivid, "sRGB"); // encoded sRGB of the naive per-channel clamp
+```
+
+## API
+
+| Export | Signature | What it does |
+| --- | --- | --- |
+| `isInGamut` | `(rgb, space?) => boolean` | Channels of an encoded-RGB tuple (already in `space`) inside `[0, 1] ± GAMUT_EPSILON` |
+| `isOklchInGamut` | `(oklch, space?) => boolean` | `oklchToRgb(…, space)` then the same channel check |
+| `mapToGamut` | `(oklch, space?, strategy?) => Oklch` | Nearest displayable color; strategies `"css"` (default, CSS Color 4), `"clip"`, `"cusp"` (reserved, throws) |
+| `clipToGamut` | `(oklch, space?) => RGB` | Naive per-channel clamp, encoded in `space` — ready to render |
+| `maxChromaForLh` | `(L, h, space?) => number` | Largest displayable Oklch chroma at fixed lightness/hue (chroma slider bound) |
+| `deltaEOK` | `(a: Oklab, b: Oklab) => number` | Euclidean distance in Oklab — the metric `css-gamut-map` requires (JND `0.02`) |
+| `GAMUT_EPSILON` | `1e-6` | Boundary tolerance for encoded channels |
+
+`space` is any D65 `RGBColorspaceId` and defaults to `"sRGB"`; non-D65
+spaces (ACES/ACEScg) throw in the underlying Oklch conversions.
+
+The `"css"` strategy is verified against colorjs.io (the CSS Color 4
+reference implementation): max deviation on a 90-point grid is under
+`0.0014` per sRGB channel. Note the spec returns the *clipped* converged
+candidate, so the mapped result may differ from the input by up to the JND
+(`0.02` deltaEOK) in lightness and hue as well, not only in chroma.

package/dist/cjs/index.cjs

@@ -0,0 +1 @@
+"use strict";var I=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var S=Object.getOwnPropertyNames;var M=Object.prototype.hasOwnProperty;var N=(r,o)=>{for(var t in o)I(r,t,{get:o[t],enumerable:!0})},L=(r,o,t,n)=>{if(o&&typeof o=="object"||typeof o=="function")for(let e of S(o))!M.call(r,e)&&e!==t&&I(r,e,{get:()=>o[e],enumerable:!(n=A(o,e))||n.enumerable});return r};var _=r=>L(I({},"__esModule",{value:!0}),r);var D={};N(D,{GAMUT_EPSILON:()=>l,clipToGamut:()=>p,deltaEOK:()=>u,isInGamut:()=>R,isOklchInGamut:()=>c,mapToGamut:()=>T,maxChromaForLh:()=>g});module.exports=_(D);function u(r,o){return Math.hypot(r[0]-o[0],r[1]-o[1],r[2]-o[2])}var k=require("@omi-io/color-core"),y=require("@omi-io/color-convert"),l=1e-6;function R(r,o=k.DEFAULTS.rgbColorspace){return r[0]>=-l&&r[0]<=1+l&&r[1]>=-l&&r[1]<=1+l&&r[2]>=-l&&r[2]<=1+l}function c(r,o=k.DEFAULTS.rgbColorspace){return R((0,y.oklchToRgb)(r,o),o)}var s=require("@omi-io/color-core"),m=require("@omi-io/color-convert"),O=require("@omi-io/color-models");var d=.02,b=1e-4;function p(r,o=s.DEFAULTS.rgbColorspace){let t=(0,m.oklchToRgb)(r,o);return[(0,s.clampUnit)(t[0]),(0,s.clampUnit)(t[1]),(0,s.clampUnit)(t[2])]}function U(r,o){let[t,n,e]=r;if(t>=1)return(0,O.unsafeAsOklch)([1,0,0]);if(t<=0)return(0,O.unsafeAsOklch)([0,0,0]);if(c(r,o))return r;let i=0,C=n,E=!0,a=r,f=p(a,o);if(u((0,m.rgbToOklab)(f,o),(0,m.oklchToOklab)(a))<d)return(0,m.rgbToOklch)(f,o);for(;C-i>b;){let G=(i+C)/2;if(a=(0,O.unsafeAsOklch)([t,G,e]),E&&c(a,o)){i=G;continue}f=p(a,o);let x=u((0,m.rgbToOklab)(f,o),(0,m.oklchToOklab)(a));if(x<d){if(d-x<b)break;E=!1,i=G}else C=G}return(0,m.rgbToOklch)(p(a,o),o)}function T(r,o=s.DEFAULTS.rgbColorspace,t="css"){switch(t){case"css":return U(r,o);case"clip":return(0,m.rgbToOklch)(p(r,o),o);case"cusp":throw new Error('mapToGamut strategy "cusp" is not implemented')}}var B=require("@omi-io/color-core"),h=require("@omi-io/color-models");var w=.5,F=1e-7;function g(r,o,t=B.DEFAULTS.rgbColorspace){if(!c((0,h.unsafeAsOklch)([r,0,o]),t))return 0;let n=0,e=w;if(c((0,h.unsafeAsOklch)([r,e,o]),t))return e;for(;e-n>F;){let i=(n+e)/2;c((0,h.unsafeAsOklch)([r,i,o]),t)?n=i:e=i}return n}

package/dist/esm/index.js

@@ -0,0 +1 @@
+function u(r,o){return Math.hypot(r[0]-o[0],r[1]-o[1],r[2]-o[2])}import{DEFAULTS as d}from"@omi-io/color-core";import{oklchToRgb as B}from"@omi-io/color-convert";var i=1e-6;function E(r,o=d.rgbColorspace){return r[0]>=-i&&r[0]<=1+i&&r[1]>=-i&&r[1]<=1+i&&r[2]>=-i&&r[2]<=1+i}function m(r,o=d.rgbColorspace){return E(B(r,o),o)}import{clampUnit as G,DEFAULTS as T}from"@omi-io/color-core";import{oklchToOklab as x,oklchToRgb as g,rgbToOklab as y,rgbToOklch as C}from"@omi-io/color-convert";import{unsafeAsOklch as O}from"@omi-io/color-models";var h=.02,b=1e-4;function a(r,o=T.rgbColorspace){let t=g(r,o);return[G(t[0]),G(t[1]),G(t[2])]}function A(r,o){let[t,l,n]=r;if(t>=1)return O([1,0,0]);if(t<=0)return O([0,0,0]);if(m(r,o))return r;let e=0,f=l,k=!0,c=r,s=a(c,o);if(u(y(s,o),x(c))<h)return C(s,o);for(;f-e>b;){let p=(e+f)/2;if(c=O([t,p,n]),k&&m(c,o)){e=p;continue}s=a(c,o);let R=u(y(s,o),x(c));if(R<h){if(h-R<b)break;k=!1,e=p}else f=p}return C(a(c,o),o)}function S(r,o=T.rgbColorspace,t="css"){switch(t){case"css":return A(r,o);case"clip":return C(a(r,o),o);case"cusp":throw new Error('mapToGamut strategy "cusp" is not implemented')}}import{DEFAULTS as M}from"@omi-io/color-core";import{unsafeAsOklch as I}from"@omi-io/color-models";var N=.5,L=1e-7;function _(r,o,t=M.rgbColorspace){if(!m(I([r,0,o]),t))return 0;let l=0,n=N;if(m(I([r,n,o]),t))return n;for(;n-l>L;){let e=(l+n)/2;m(I([r,e,o]),t)?l=e:n=e}return l}export{i as GAMUT_EPSILON,a as clipToGamut,u as deltaEOK,E as isInGamut,m as isOklchInGamut,S as mapToGamut,_ as maxChromaForLh};

package/dist/types/delta-e-ok.d.ts

@@ -0,0 +1,2 @@
+import type { Oklab } from "@omi-io/color-models";
+export declare function deltaEOK(a: Oklab, b: Oklab): number;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { deltaEOK } from "./delta-e-ok";
+export { GAMUT_EPSILON, isInGamut, isOklchInGamut } from "./is-in-gamut";
+export { clipToGamut, mapToGamut, type GamutMapStrategy } from "./map-to-gamut";
+export { maxChromaForLh } from "./max-chroma";

package/dist/types/is-in-gamut.d.ts

@@ -0,0 +1,5 @@
+import type { RGB, RGBColorspaceId } from "@omi-io/color-core/types";
+import type { Oklch } from "@omi-io/color-models";
+export declare const GAMUT_EPSILON = 0.000001;
+export declare function isInGamut(rgb: RGB, _space?: RGBColorspaceId): boolean;
+export declare function isOklchInGamut(oklch: Oklch, space?: RGBColorspaceId): boolean;

package/dist/types/map-to-gamut.d.ts

@@ -0,0 +1,5 @@
+import type { RGB, RGBColorspaceId } from "@omi-io/color-core/types";
+import { type Oklch } from "@omi-io/color-models";
+export type GamutMapStrategy = "css" | "clip" | "cusp";
+export declare function clipToGamut(oklch: Oklch, space?: RGBColorspaceId): RGB;
+export declare function mapToGamut(oklch: Oklch, space?: RGBColorspaceId, strategy?: GamutMapStrategy): Oklch;

package/dist/types/max-chroma.d.ts

@@ -0,0 +1,2 @@
+import type { RGBColorspaceId } from "@omi-io/color-core/types";
+export declare function maxChromaForLh(L: number, h: number, space?: RGBColorspaceId): number;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@omi-io/color-gamut",
+  "scopeCommitName": "@:gamut",
+  "version": "0.1.0",
+  "description": "Gamut queries and mapping for RGB display gamuts: in-gamut checks, CSS Color 4 gamut mapping, naive clipping, max chroma per (L, h), and the deltaEOK metric.",
+  "keywords": [
+    "color",
+    "gamut",
+    "gamut-mapping",
+    "css-color-4",
+    "oklch",
+    "oklab",
+    "delta-e",
+    "srgb",
+    "display-p3",
+    "rec2020",
+    "wide-gamut",
+    "colorimetry"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a-omi-io/color.git",
+    "directory": "packages/color-gamut"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "types": "./dist/types/index.d.ts",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "scripts": {
+    "clean": "omi-io-pkg clean",
+    "build": "yarn clean && omi-io-pkg build && tsc && omi-io-pkg alias",
+    "test": "jest",
+    "lint": "eslint ./src",
+    "tsc-check": "tsc --noEmit --emitDeclarationOnly false"
+  },
+  "dependencies": {
+    "@omi-io/color-convert": "^0.2.0",
+    "@omi-io/color-core": "^0.1.0",
+    "@omi-io/color-models": "^0.2.0"
+  },
+  "devDependencies": {
+    "@omi-io/pkg-scripts": "v2.5.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.11.30",
+    "eslint": "^8.57.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.0.5",
+    "typescript": "~5.4.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ]
+}