Skip to content

3D engine that AI agents drive

10.3 KB
Raw Blame
import { createEnvironmentMap } from './environment.js';
import { radianceForDisplayColor } from './view-transform-inverse.js';

// environment.sky { type: 'gradient' }: a sky whose colours are picked, not computed. Stops run from the horizon (at 0) to the
// zenith (at 1) by elevation angle, and an optional glow band hugs the horizon. The same colours feed the background, the
// environment map that lights the scene and the water reflection, so the three always agree. The sun, the key light and the
// haze stay as the lighting setup or the recipe set them.

export const GRADIENT_SKY_FIELDS = Object.freeze(['type', 'stops', 'horizonGlow']);
export const HORIZON_GLOW_FIELDS = Object.freeze(['color', 'width', 'intensity']);
export const MAXIMUM_GRADIENT_STOPS = 8;

const GLOW_DEFAULTS = Object.freeze({ width: 6, intensity: 1 });
// intensity multiplies the glow colour at the horizon: 1 shows the colour itself, above 1 pushes it brighter.
const GLOW_LIMITS = Object.freeze({
  width: [0.5, 45, 'the glow half width in degrees of elevation, such as 6'],
  intensity: [0, 20, 'a multiplier of the glow colour from 0 to 20, 1 shows the colour as given, such as 1.5'],
});
const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
const COLOR_EXAMPLE = 'a hex colour such as "#0e5d73"';
const MAP_WIDTH = 1024;
const MAP_HEIGHT = 513;

function checkedColor(value, field, fail) {
  if (typeof value !== 'string' || !HEX_COLOR.test(value)) {
    throw fail(field, value, COLOR_EXAMPLE);
  }
  return value.toLowerCase();
}

function resolveStops(stops, fail) {
  if (!Array.isArray(stops) || stops.length < 1 || stops.length > MAXIMUM_GRADIENT_STOPS) {
    throw fail('environment.sky.stops', stops, `a list of 1 to ${MAXIMUM_GRADIENT_STOPS} stops, such as [{ "at": 0, "color": "#1a8a9c" }, { "at": 1, "color": "#0e5d73" }]`);
  }
  let previousAt = -Infinity;
  return stops.map((stop, index) => {
    const field = `environment.sky.stops[${index}]`;
    const unknown = stop && typeof stop === 'object' ? Object.keys(stop).find(key => key !== 'at' && key !== 'color') : 'stop';
    if (unknown !== undefined) {
      throw fail(field, unknown === 'stop' ? stop : unknown, 'an object with at (0 at the horizon to 1 at the zenith) and color');
    }
    if (!Number.isFinite(stop.at) || stop.at < 0 || stop.at > 1 || stop.at <= previousAt) {
      throw fail(`${field}.at`, stop.at, 'a number from 0 (horizon) to 1 (zenith), larger than the stop before it');
    }
    previousAt = stop.at;
    return { at: stop.at, color: checkedColor(stop.color, `${field}.color`, fail) };
  });
}

function resolveHorizonGlow(glow, fail) {
  if (!glow || typeof glow !== 'object' || Array.isArray(glow)) {
    throw fail('environment.sky.horizonGlow', glow, `an object with color (${COLOR_EXAMPLE}), width and intensity`);
  }
  const unknown = Object.keys(glow).find(key => !HORIZON_GLOW_FIELDS.includes(key));
  if (unknown !== undefined) {
    throw fail('environment.sky.horizonGlow', unknown, `the fields ${HORIZON_GLOW_FIELDS.join(', ')}`);
  }
  const resolved = { color: checkedColor(glow.color, 'environment.sky.horizonGlow.color', fail) };
  for (const [field, [minimum, maximum, example]] of Object.entries(GLOW_LIMITS)) {
    const value = glow[field] ?? GLOW_DEFAULTS[field];
    if (!Number.isFinite(value) || value < minimum || value > maximum) {
      throw fail(`environment.sky.horizonGlow.${field}`, value, `a number from ${minimum} to ${maximum}, ${example}`);
    }
    resolved[field] = value;
  }
  return resolved;
}

/** Checks and normalizes a gradient sky; `fail` builds the error for a field, a value and what is accepted. */
export function resolveGradientSky(input, fail) {
  const unknown = Object.keys(input).find(key => !GRADIENT_SKY_FIELDS.includes(key));
  if (unknown !== undefined) {
    throw fail('environment.sky', unknown, `type 'gradient' with fields ${GRADIENT_SKY_FIELDS.slice(1).join(', ')}`);
  }
  const resolved = { type: 'gradient', stops: resolveStops(input.stops, fail) };
  if (input.horizonGlow !== undefined && input.horizonGlow !== null) {
    resolved.horizonGlow = resolveHorizonGlow(input.horizonGlow, fail);
  }
  return resolved;
}

function srgbChannelToLinear(channel) {
  return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
}

function linearChannelToSrgb(channel) {
  const clamped = Math.min(1, Math.max(0, channel));
  return clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * clamped ** (1 / 2.4) - 0.055;
}

export function linearColorFromHex(hex) {
  return [1, 3, 5].map(offset => srgbChannelToLinear(parseInt(hex.slice(offset, offset + 2), 16) / 255));
}

// OKLab (Ottosson): blending in it keeps lightness and hue steady between two stops, where a blend of linear radiance
// goes grey and dark in the middle and a blend of encoded values bands where the hue turns.
function oklabFromLinear([red, green, blue]) {
  const long = Math.cbrt(0.4122214708 * red + 0.5363325363 * green + 0.0514459929 * blue);
  const medium = Math.cbrt(0.2119034982 * red + 0.6806995451 * green + 0.1073969566 * blue);
  const short = Math.cbrt(0.0883024619 * red + 0.2817188376 * green + 0.6299787005 * blue);
  return [
    0.2104542553 * long + 0.793617785 * medium - 0.0040720468 * short,
    1.9779984951 * long - 2.428592205 * medium + 0.4505937099 * short,
    0.0259040371 * long + 0.7827717662 * medium - 0.808675766 * short,
  ];
}

function linearFromOklab([lightness, greenRed, blueYellow]) {
  const long = (lightness + 0.3963377774 * greenRed + 0.2158037573 * blueYellow) ** 3;
  const medium = (lightness - 0.1055613458 * greenRed - 0.0638541728 * blueYellow) ** 3;
  const short = (lightness - 0.0894841775 * greenRed - 1.291485548 * blueYellow) ** 3;
  return [
    4.0767416621 * long - 3.3077115913 * medium + 0.2309699292 * short,
    -1.2684380046 * long + 2.6097574011 * medium - 0.3413193965 * short,
    -0.0041960863 * long - 0.7034186147 * medium + 1.707614701 * short,
  ];
}

function mixOklab(from, to, share) {
  return from.map((component, index) => component + (to[index] - component) * share);
}

const oklabFromHex = hex => oklabFromLinear(linearColorFromHex(hex));
const encodedFromOklab = lab => linearFromOklab(lab).map(linearChannelToSrgb);

/**
 * The radiance that shows as the hex you asked for: the view transform and the display power turn it back into the hex,
 * so a stop reads as its colour in the frame instead of being lifted by the transform (a flat #0e5d73 under aces used to
 * show as #0c6988). The inverse assumes exposure 1 and no look or post effect on the frame, and divides by the
 * environment strength, which the background and the light both multiply back in. Under aces every hex is reachable.
 * Under agx and neutral a colour the transform cannot produce lands on the nearest one it can.
 */
export function radianceFromHex(hex, viewTransform) {
  const encoded = [1, 3, 5].map(offset => parseInt(hex.slice(offset, offset + 2), 16) / 255);
  return radianceForDisplayColor(encoded, viewTransform).radiance;
}

/** The recipe fields a gradient implies: the legacy sky colours that fog and the probe trace read, as radiance. */
export function gradientSkyFields(sky, viewTransform) {
  const horizon = radianceFromHex(sky.stops[0].color, viewTransform);
  const zenith = radianceFromHex(sky.stops[sky.stops.length - 1].color, viewTransform);
  return { skyTop: zenith, skyBottom: horizon, fogColor: horizon };
}

/** A gradient sky leaves the sun alone and only supplies the sky colours. */
export function applyGradientSky(input, environment, fail) {
  const sky = resolveGradientSky(input, fail);
  Object.assign(environment, gradientSkyFields(sky, environment.viewTransform), { sky });
}

function stopLabs(sky) {
  return sky.stops.map(stop => ({ at: stop.at, lab: oklabFromHex(stop.color) }));
}

function labAtHeight(stops, height) {
  if (height <= stops[0].at) {
    return stops[0].lab;
  }
  for (let index = 1; index < stops.length; index++) {
    if (height <= stops[index].at) {
      return mixOklab(stops[index - 1].lab, stops[index].lab, (height - stops[index - 1].at) / (stops[index].at - stops[index - 1].at));
    }
  }
  return stops[stops.length - 1].lab;
}

// The glow colour blends in over the gradient by its share, so the band keeps its hue as it brightens and never washes
// to white; `intensity` then scales the radiance of the band (1 shows the colour as given).
function radianceAtElevation(stops, glow, glowLab, elevation, viewTransform, strengthScale) {
  const base = labAtHeight(stops, Math.max(0, elevation) / 90);
  const glowShare = glow ? Math.exp(-((elevation / glow.width) ** 2)) : 0;
  const displayed = encodedFromOklab(glow ? mixOklab(base, glowLab, glowShare) : base);
  const brightness = glow ? 1 + (glow.intensity - 1) * glowShare : 1;
  return radianceForDisplayColor(displayed, viewTransform).radiance.map(channel => channel * brightness * strengthScale);
}

function buildMapData(sky, viewTransform, environmentIntensity) {
  const stops = stopLabs(sky);
  const glow = sky.horizonGlow;
  const glowLab = glow ? oklabFromHex(glow.color) : null;
  const strengthScale = environmentIntensity > 0 ? 1 / environmentIntensity : 1;
  const data = new Float32Array(MAP_WIDTH * MAP_HEIGHT * 3);
  for (let row = 0; row < MAP_HEIGHT; row++) {
    // Each row is one elevation: the gradient and the glow depend on the angle above the horizon only. The odd row count
    // puts the middle row exactly on the horizon, so the glow peak is the glow colour itself.
    const elevation = 90 - ((row + 0.5) / MAP_HEIGHT) * 180;
    const radiance = radianceAtElevation(stops, glow, glowLab, elevation, viewTransform, strengthScale);
    for (let column = 0; column < MAP_WIDTH; column++) {
      data.set(radiance, (row * MAP_WIDTH + column) * 3);
    }
  }
  return data;
}

const mapsByKey = new Map();
const MAXIMUM_CACHED_MAPS = 8;

/** The environment map of a gradient sky; the same object returns while sky, strength, rotation, background and view transform hold. */
export function createGradientSkyMap({ sky, environmentIntensity: intensity, environmentRotation: rotation, world: showBackground, viewTransform = 'aces' }) {
  const key = JSON.stringify([sky, intensity, rotation, showBackground, viewTransform]);
  if (!mapsByKey.has(key)) {
    if (mapsByKey.size >= MAXIMUM_CACHED_MAPS) {
      mapsByKey.clear();
    }
    mapsByKey.set(key, createEnvironmentMap({ width: MAP_WIDTH, height: MAP_HEIGHT, data: buildMapData(sky, viewTransform, intensity), intensity, rotation, showBackground }));
  }
  return mapsByKey.get(key);
}