diff --git a/apps/mobile/lib/color-space.ts b/apps/mobile/lib/color-space.ts new file mode 100644 index 0000000..dd1d96a --- /dev/null +++ b/apps/mobile/lib/color-space.ts @@ -0,0 +1,32 @@ +type Color = [number, number, number] + +/** Convert sRGB byte values to Oklab without quantizing intermediate colors. */ +export function toOklab(rgb: Color): Color { + const [r, g, b] = rgb.map((byte) => { + const v = byte / 255 + return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 + }) + const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b) + const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b) + const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b) + return [ + 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, + 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, + 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s, + ] +} + +/** Map an Oklab color back into the display's sRGB gamut. */ +export function fromOklab([L, a, b]: Color): Color { + const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3 + const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3 + const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3 + return [ + 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, + -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, + -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s, + ].map((v) => { + const encoded = v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055 + return Math.round(Math.max(0, Math.min(1, encoded)) * 255) + }) as Color +} diff --git a/apps/mobile/lib/cover-palette.compare.cjs b/apps/mobile/lib/cover-palette.compare.cjs new file mode 100644 index 0000000..9b0b230 --- /dev/null +++ b/apps/mobile/lib/cover-palette.compare.cjs @@ -0,0 +1,50 @@ +// Measurement targets belong here and in the fixture, never in palette derivation. +const fs = require("node:fs") +const ts = require("typescript") +const references = require("./cover-palette.references.json") +function load(name) { + const exports = {} + const code = ts.transpileModule( + fs.readFileSync(`${__dirname}/${name}.ts`, "utf8"), + { + compilerOptions: { + module: ts.ModuleKind.CommonJS, + target: ts.ScriptTarget.ES2022, + }, + } + ).outputText + new Function("exports", "require", code)(exports, (name) => + load(name.replace("./", "")) + ) + return exports +} +const { deriveCoverPalette } = load("cover-palette") +const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)) +const measurements = references.map( + ({ label, swatches, expectedBackground }) => { + const actual = deriveCoverPalette(swatches).background + const errors = rgb(actual).map((v, i) => + Math.abs(v - rgb(expectedBackground)[i]) + ) + return { + label, + expectedBackground, + actual, + maxChannelError: Math.max(...errors), + squaredError: errors.reduce((s, v) => s + v * v, 0), + } + } +) +console.table(measurements.map(({ squaredError, ...row }) => row)) +console.log( + "RGB RMSE:", + Math.sqrt( + measurements.reduce((s, r) => s + r.squaredError, 0) / + (measurements.length * 3) + ) +) +if ( + process.argv.includes("--exact") && + measurements.some((row) => row.maxChannelError !== 0) +) + process.exitCode = 1 diff --git a/apps/mobile/lib/cover-palette.references.json b/apps/mobile/lib/cover-palette.references.json new file mode 100644 index 0000000..1710d20 --- /dev/null +++ b/apps/mobile/lib/cover-palette.references.json @@ -0,0 +1,92 @@ +[ + { + "label": "wicked-soundtrack", + "swatches": { + "background": "#4f4e33", + "average": "#74664d", + "dominantFraction": 0.184814453125, + "darkFraction": 0.195556640625 + }, + "expectedBackground": "#1a1c0e" + }, + { + "label": "wicked-broadway", + "swatches": { + "background": "#030605", + "average": "#74786c", + "dominantFraction": 0.423828125, + "darkFraction": 0.43798828125 + }, + "expectedBackground": "#111111" + }, + { + "label": "prince-of-egypt", + "swatches": { + "background": "#16101f", + "average": "#584546", + "dominantFraction": 0.585693359375, + "darkFraction": 0.587158203125 + }, + "expectedBackground": "#191718" + }, + { + "label": "civilization-vi", + "swatches": { + "background": "#ccaf90", + "average": "#b79e80", + "dominantFraction": 0.20703125, + "darkFraction": 0.001220703125 + }, + "expectedBackground": "#3f280c" + }, + { + "label": "ramblin-rover", + "swatches": { + "background": "#457522", + "average": "#548133", + "dominantFraction": 0.7802734375, + "darkFraction": 0 + }, + "expectedBackground": "#0e3900" + }, + { + "label": "cavalry", + "swatches": { + "background": "#0d131f", + "average": "#404954", + "dominantFraction": 0.317138671875, + "darkFraction": 0.38623046875 + }, + "expectedBackground": "#151d2f" + }, + { + "label": "city-of-angels", + "swatches": { + "background": "#1895cb", + "average": "#6c7c8b", + "dominantFraction": 0.241943359375, + "darkFraction": 0.075927734375 + }, + "expectedBackground": "#003262" + }, + { + "label": "we-the-kings", + "swatches": { + "background": "#ab3a33", + "average": "#923b32", + "dominantFraction": 0.577880859375, + "darkFraction": 0.16552734375 + }, + "expectedBackground": "#52170d" + }, + { + "label": "counter-strike-2", + "swatches": { + "background": "#060404", + "average": "#786757", + "dominantFraction": 0.35693359375, + "darkFraction": 0.390625 + }, + "expectedBackground": "#251211" + } +] diff --git a/apps/mobile/lib/cover-palette.test.cjs b/apps/mobile/lib/cover-palette.test.cjs new file mode 100644 index 0000000..15b9bd5 --- /dev/null +++ b/apps/mobile/lib/cover-palette.test.cjs @@ -0,0 +1,54 @@ +const { test } = require("node:test") +const assert = require("node:assert/strict") +const fs = require("node:fs") +const ts = require("typescript") +function load(name) { + const exports = {} + new Function( + "exports", + "require", + ts.transpileModule(fs.readFileSync(`${__dirname}/${name}.ts`, "utf8"), { + compilerOptions: { + module: ts.ModuleKind.CommonJS, + target: ts.ScriptTarget.ES2022, + }, + }).outputText + )(exports, (name) => load(name.replace("./", ""))) + return exports +} +const { deriveCoverPalette } = load("cover-palette") +const { toOklab, fromOklab } = load("color-space") + +test("sRGB and Oklab conversions round trip across the display gamut", () => { + for (const r of [0, 16, 64, 128, 192, 255]) + for (const g of [0, 16, 64, 128, 192, 255]) + for (const b of [0, 16, 64, 128, 192, 255]) + assert.deepEqual(fromOklab(toOklab([r, g, b])), [r, g, b]) +}) +test("near-black neutral artwork does not amplify arbitrary channel noise", () => { + for (const background of ["#000000", "#030605", "#050303"]) { + const palette = deriveCoverPalette({ background, average: "#747474" }) + assert.equal(palette.background, "#111111") + assert.equal(palette.foreground, "#FFFFFF") + } +}) +test("a conflicting shadow hue is muted while coherent dark blue retains its color", () => { + const shadow = deriveCoverPalette({ + background: "#16101f", + average: "#584546", + dominantFraction: 0.59, + darkFraction: 0.59, + }) + const blue = deriveCoverPalette({ + background: "#0d131f", + average: "#404954", + dominantFraction: 0.32, + darkFraction: 0.39, + }) + const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)) + const shadowRgb = rgb(shadow.background), + blueRgb = rgb(blue.background) + assert.ok(Math.max(...shadowRgb) - Math.min(...shadowRgb) <= 4) + assert.ok(blueRgb[2] - blueRgb[0] > 15) + assert.equal(deriveCoverPalette({ background: "invalid" }), null) +}) diff --git a/apps/mobile/lib/cover-palette.ts b/apps/mobile/lib/cover-palette.ts index 3e0840e..543376d 100644 --- a/apps/mobile/lib/cover-palette.ts +++ b/apps/mobile/lib/cover-palette.ts @@ -1,4 +1,5 @@ import type { ThemeColors } from "@/lib/theme" +import { toOklab, fromOklab } from "./color-space" /** * Colors for a screen tinted by its cover art, modeled on Apple Music's @@ -26,7 +27,6 @@ export type CoverSwatches = { } type Rgb = [number, number, number] -type Hsl = { h: number; s: number; l: number } export function themeCoverPalette( theme: ThemeColors, @@ -45,99 +45,81 @@ export function themeCoverPalette( } } -/** - * Artwork pages use a dark, hue-matched canvas with neutral primary controls. - * Saturated covers stay deep; muted covers retain the lighter, subtly tinted - * canvas in the references: yellow #3E2B00, muted green #2A3028, and - * deep magenta #370C18. - */ +/** Dark artwork canvas derived from region coverage and perceptual color. */ export function deriveCoverPalette( swatches: CoverSwatches ): CoverPalette | null { const source = parseHex(swatches.background) if (!source) return null - const sampled = toHsl(source) - // Yellow loses its green cast when shaded to the warm amber in the reference. - const muted = Math.max(0, 1 - sampled.s / 0.35) - const warmHue = - sampled.h >= 45 && sampled.h <= 75 ? 42 + (sampled.h - 53) * 0.5 : sampled.h - // Deep magenta shadows need a burgundy canvas rather than near-black. - // Blend by hue and shadow depth so bright covers keep their own treatment. - const berry = - Math.max(0, 1 - Math.abs(sampled.h - 320) / 40) * - Math.min(1, Math.max(0, (0.12 - sampled.l) / 0.08)) - const h = warmHue - 16 * muted + 23.25 * berry - const s = Math.min(1, sampled.s * (1.2 + 2.7 * muted)) * (1 - 0.36 * berry) - const shadedLightness = Math.min(sampled.l, (31 + 14 * muted) / 255) - const l = shadedLightness * (1 - berry) + (33.5 / 255) * berry - const background = fromHsl({ h, s, l }) - const secondary = fromHsl({ - h: h - 2.5 + 8 * muted + 3 * berry, - s: s * (0.34 + 0.06 * muted + 0.024 * berry), - l: (174.5 - 2.5 * muted - 13.5 * berry) / 255, - }) + const average = swatches.average + ? (parseHex(swatches.average) ?? source) + : source + const [lightness, a, b] = toOklab(source) + const [, averageA, averageB] = toOklab(average) + const chroma = Math.hypot(a, b) + const averageChroma = Math.hypot(averageA, averageB) + const shadow = clamp((0.4 - lightness) / 0.3) + const coverage = clamp(swatches.dominantFraction ?? 1) + const darkCoverage = clamp(swatches.darkFraction ?? 0) + // Luminance alone makes bright, muted artwork too light and dark blue art + // almost black. Chroma and a bounded shadow lift retain both kinds of cover. + let canvasLightness = Math.max( + 0.17, + Math.min(0.4, 0.11 + 0.21 * lightness + 0.58 * chroma + 0.08 * shadow) + ) + let canvasChroma = Math.min(chroma * (1 + shadow), canvasLightness * 0.39) + + // A dark region whose hue conflicts with the whole image is often a shadow, + // rather than a reliable saturated background. Do not amplify that tint. + const disagreement = Math.max( + 0, + 1 - + (a * averageA + b * averageB) / Math.max(chroma * averageChroma, 1e-8) - + 0.3 + ) + canvasChroma *= Math.exp(-20 * shadow * disagreement) + canvasChroma *= Math.max( + 0, + 1 - 2.5 * darkCoverage * (1 - coverage) * (1 - shadow) + ) + + // Near-black RGB values carry unstable hue. Use the image's overall chroma + // to distinguish neutral artwork from a dark region in a colorful image. + const neutral = shadow * clamp((0.02 - chroma) / 0.02) + canvasChroma = + canvasChroma * (1 - neutral) + + Math.max(0, averageChroma - 0.02) * 3.5 * neutral + canvasLightness = + canvasLightness * (1 - neutral) + + (0.177 + Math.max(0, averageChroma - 0.02) * 2) * neutral + if (chroma < 0.01 && averageChroma < 0.025) { + canvasLightness = toOklab([17, 17, 17])[0] + canvasChroma = 0 + } + const direction = chroma > 0 ? canvasChroma / chroma : 0 + const background = fromOklab([canvasLightness, a * direction, b * direction]) + const mixWhite = (amount: number) => + toHex( + background.map((channel) => + Math.round(channel + (255 - channel) * amount) + ) as Rgb + ) return { background: toHex(background), foreground: "#FFFFFF", - secondaryForeground: toHex(secondary), + secondaryForeground: mixWhite(0.55), accent: "#FFFFFF", accentForeground: toHex(background), accentText: "#FFFFFF", - surface: toHex( - fromHsl({ - h: h - 0.9 + 3 * berry, - s: s * (0.6 + 0.1 * muted), - l: l + (19 - muted) / 255, - }) - ), - divider: toHex( - fromHsl({ - h, - s: s * (0.48 + 0.1 * muted + 0.025 * berry), - l: l + 33 / 255, - }) - ), + surface: mixWhite(0.08), + divider: mixWhite(0.12), isDark: true, } } -function toHsl([red, green, blue]: Rgb): Hsl { - const [r, g, b] = [red, green, blue].map((channel) => channel / 255) - const max = Math.max(r, g, b) - const min = Math.min(r, g, b) - const delta = max - min - const l = (max + min) / 2 - if (delta === 0) return { h: 0, s: 0, l } - const sector = - max === r - ? (g - b) / delta - : max === g - ? (b - r) / delta + 2 - : (r - g) / delta + 4 - return { - h: (sector * 60 + 360) % 360, - s: delta / (1 - Math.abs(2 * l - 1)), - l, - } -} - -function fromHsl({ h, s, l }: Hsl): Rgb { - const hue = (((h % 360) + 360) % 360) / 60 - const chroma = (1 - Math.abs(2 * l - 1)) * s - const x = chroma * (1 - Math.abs((hue % 2) - 1)) - const sectors = [ - [chroma, x, 0], - [x, chroma, 0], - [0, chroma, x], - [0, x, chroma], - [x, 0, chroma], - [chroma, 0, x], - ] - const offset = l - chroma / 2 - return sectors[Math.floor(hue)].map((channel) => - Math.round((channel + offset) * 255) - ) as Rgb +function clamp(value: number) { + return Math.max(0, Math.min(1, value)) } function parseHex(hex: string): Rgb | null {