Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

7.7 KB
Raw Blame
/**
 * Sprites — dynamic chroma-key selection (issue #2896, phase 2).
 *
 * The source pipeline hardcoded magenta because its one character wore green;
 * per the #2895 decision the key is now picked per character from a FIXED set
 * of three standard keys, by hue distance from the character's own palette
 * (a green-clothed character keys on magenta; a pink one keys on green/blue).
 *
 * Pure module — palette extraction (sharp) lives in normalize.js; this file
 * is just color math so it stays unit-testable and safe to import anywhere.
 */

export const CHROMA_KEYS = [
  { hex: '#FF00FF', name: 'magenta', hue: 300 },
  { hex: '#00FF00', name: 'green', hue: 120 },
  { hex: '#0000FF', name: 'blue', hue: 240 },
];

export const CHROMA_KEY_HEXES = CHROMA_KEYS.map((k) => k.hex);

// Magenta — the source pipeline's only key; the fallback wherever no key has
// been selected yet (pre-lock generation, legacy imports).
export const DEFAULT_CHROMA_KEY = CHROMA_KEYS[0].hex;

// Below this hue separation (degrees) between the chosen key and the nearest
// significant palette color, keying will likely eat character pixels — the
// selection still returns the best key but carries a warning.
export const MIN_HUE_SEPARATION = 60;

export function hexToRgb(hex) {
  const m = /^#?([0-9a-fA-F]{6})$/.exec(typeof hex === 'string' ? hex : '');
  if (!m) throw new Error(`Invalid hex color: ${hex}`);
  const n = parseInt(m[1], 16);
  return { r: (n >> 16) & 0xff, g: (n >> 8) & 0xff, b: n & 0xff };
}

export function rgbToHsv(r, g, b) {
  const rn = r / 255; const gn = g / 255; const bn = b / 255;
  const max = Math.max(rn, gn, bn);
  const min = Math.min(rn, gn, bn);
  const delta = max - min;
  let h = 0;
  if (delta > 0) {
    if (max === rn) h = 60 * (((gn - bn) / delta) % 6);
    else if (max === gn) h = 60 * ((bn - rn) / delta + 2);
    else h = 60 * ((rn - gn) / delta + 4);
    if (h < 0) h += 360;
  }
  return { h, s: max === 0 ? 0 : delta / max, v: max };
}

export function hueDistance(a, b) {
  const d = Math.abs(a - b) % 360;
  return d > 180 ? 360 - d : d;
}

/**
 * Pick the key whose hue is farthest from every significant color in the
 * character's palette.
 *
 * `palette` is `[{ r, g, b, count }]` (see extractForegroundPalette). Colors
 * below the saturation/value floors are ignored — near-grays and near-blacks
 * have no meaningful hue and never conflict with a saturated key; colors
 * below `minCountFrac` of the total are single-pixel noise.
 *
 * Returns `{ hex, name, minHueDistance, warning }` — never null; a fully
 * achromatic palette conflicts with nothing, so the first key (magenta, the
 * legacy default) wins with distance Infinity.
 */
function significantHues(palette, { minCountFrac = 0.005, minSaturation = 0.25, minValue = 0.15 } = {}) {
  const entries = Array.isArray(palette) ? palette : [];
  const total = entries.reduce((sum, e) => sum + (e.count || 0), 0);
  return entries
    .map((e) => ({ ...rgbToHsv(e.r, e.g, e.b), count: e.count || 0 }))
    .filter((c) => c.count >= total * minCountFrac && c.s >= minSaturation && c.v >= minValue);
}

/**
 * Warn when the character's surviving palette sits close in hue to the key
 * it was GENERATED on: the normalize mask has already discarded any pixel
 * within the luma threshold of that key, so near-key palette colors imply
 * exact-key details (a magenta garment on the magenta default) may have been
 * silently clipped from the immutable locked artifact. Returns a warning
 * string or null.
 */
export function keyProximityWarning(palette, keyHex, { role = 'generation', ...opts } = {}) {
  const { r, g, b } = hexToRgb(keyHex);
  const keyHue = rgbToHsv(r, g, b).h;
  const significant = significantHues(palette, opts);
  if (!significant.length) return null;
  const minDist = Math.min(...significant.map((c) => hueDistance(keyHue, c.h)));
  if (minDist >= MIN_HUE_SEPARATION) return null;
  // `selected` = the key the artifact will be COMPOSITED onto (runtime keying
  // would clip character pixels); `generation` = the key it was RENDERED on
  // (exact-key details are already gone from the mask).
  return role === 'selected'
    ? `Character palette sits within ${Math.round(minDist)}° of the selected key ${keyHex} — runtime keying on it would clip character pixels; pick a different key before locking`
    : `Character palette sits within ${Math.round(minDist)}° of the generation key ${keyHex} — exact-key details may have been clipped by the mask; consider pinning a different key and regenerating before locking`;
}

/**
 * Split a key color into its saturated ("high", 255) and dark ("low", 0)
 * channel indices — the structure every key-parameterized un-key/despill
 * formula in walkPostprocess.js is written against. The source pipeline
 * hardcoded magenta (highs r+b, low g); the three standard keys are all
 * pure-channel colors, so highs/lows fully describe them:
 *   magenta → highs [0,2], lows [1]
 *   green   → highs [1],   lows [0,2]
 *   blue    → highs [2],   lows [0,1]
 * Channel indices are 0=r, 1=g, 2=b into an RGB(A) pixel.
 */
export function keyChannelSplit(hex) {
  const { r, g, b } = hexToRgb(hex);
  const values = [r, g, b];
  const highs = [];
  const lows = [];
  values.forEach((v, i) => (v >= 128 ? highs : lows).push(i));
  if (!highs.length || !lows.length) throw new Error(`Not a usable chroma key: ${hex}`);
  return { rgb: values, highs, lows };
}

/**
 * How key-like a pixel is: min(high channels) − max(low channels).
 * Positive = the pixel leans toward the key color. For magenta this is the
 * source pipeline's `min(r,b) − g` exactly.
 */
export function keyness(pixel, split) {
  let minHigh = 255;
  for (const h of split.highs) minHigh = Math.min(minHigh, pixel[h]);
  let maxLow = 0;
  for (const l of split.lows) maxLow = Math.max(maxLow, pixel[l]);
  return minHigh - maxLow;
}

/**
 * Build the per-pixel background-key "share" sampler for a key: the fraction of
 * a pixel that is the key color, reversing anti-aliased source-over-key
 * compositing. Measured as the min over the key's (high, low) channel pairs of
 * (pixel[high] − pixel[low]) / (key[high] − key[low]), clamped to [0, 1] — a
 * pure-key pixel scores 1, a pixel unlike the key scores 0, an anti-aliased
 * blend lands in between (the exact weight of the key still contaminating it).
 *
 * `keyRgb` is the key as `[r, g, b]` (a nominal key OR a measured border key);
 * `split` is its keyChannelSplit. The returned sampler reads channels from
 * `arr` at `base + channelIndex`, so one factory serves both a 3-element pixel
 * array (`base` 0) and a flat RGB/RGBA buffer (`base` = pixelIndex * channels).
 * The (high, low) pairs and their spans are precomputed once per key so the
 * hot per-pixel path only does the reads, subtracts, and min.
 */
export function keyShareFn(keyRgb, split) {
  const pairs = [];
  for (const h of split.highs) {
    for (const l of split.lows) pairs.push([h, l, Math.max(1, keyRgb[h] - keyRgb[l])]);
  }
  return (arr, base = 0) => {
    let s = Infinity;
    for (const [h, l, span] of pairs) {
      const v = (arr[base + h] - arr[base + l]) / span;
      if (v < s) s = v;
    }
    return s < 0 ? 0 : s > 1 ? 1 : s;
  };
}

export function pickChromaKey(palette, opts = {}) {
  const significant = significantHues(palette, opts);

  let best = null;
  for (const key of CHROMA_KEYS) {
    const minDist = significant.length
      ? Math.min(...significant.map((c) => hueDistance(key.hue, c.h)))
      : Infinity;
    if (!best || minDist > best.minHueDistance) {
      best = { hex: key.hex, name: key.name, minHueDistance: minDist };
    }
  }
  return {
    ...best,
    warning: best.minHueDistance < MIN_HUE_SEPARATION
      ? `Closest palette hue is within ${Math.round(best.minHueDistance)}° of the ${best.name} key — keying may clip character pixels`
      : null,
  };
}