fix(mobile): derive dark palettes from artwork measurements

This commit is contained in:
joshuafhiggins committed 2026-11-09 13:07:53 -05:00 Verified
1 parent 75bb562d27
commit 0c1aa736bf
6 files changed
+296 -78

No files matched your search

+8
View File
@@ -70,3 +70,11 @@ Changes to the iOS sampler require a native rebuild. Bump the palette cache
version in `hooks/use-cover-palette.ts` when changing extraction so persisted
swatches are recomputed. Run the clustering checks with
`node --test apps/mobile/lib/color-histogram.test.cjs` from the repository root.
Palette derivation uses the sampled region and image measurements in Oklab,
with shared lightness/chroma calibration and shadow neutralization. Reference
colors live only in `lib/cover-palette.references.json`; runtime code does not
import them. Run `node apps/mobile/lib/cover-palette.compare.cjs` for per-reference
background errors, or add `--exact` to fail unless every background matches.
The reference measurement set currently covers the iOS extractor. It is not a
claim that the full UI or Android quantizer matches Apple Music exactly.
+32
View File
@@ -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
}
+50
View File
@@ -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
@@ -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"
}
]
+54
View File
@@ -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)
})
+60 -78
View File
@@ -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 {