@call-me-sensei/toonlab 0.3.0 → 0.4.19

package/src/cloud/noise/curlNoise.js

@@ -0,0 +1,289 @@
+// Curl noise — the divergence-free vector field that advects cloud edges into
+// wisps. Displacing a sample position by an arbitrary noise vector pumps
+// density in and out of the cloud (the field has sources and sinks), so edges
+// bulge and pop. The curl of a vector potential is divergence-free by
+// construction, so advecting along it shears and folds the cloud without
+// creating or destroying any of it — the reason curl noise, not plain noise, is
+// what makes a wisp look torn from the body rather than pasted onto it.
+//
+// Potential: three decorrelated periodic Perlin FBM fields. Curl: collocated
+// central differences of those. Because the same difference stencil is used for
+// every partial, the mixed second derivatives cancel exactly and the discrete
+// divergence is zero to floating-point rounding — not just to O(h²).
+//
+// Encoding: the volume packs curl * 0.5 + 0.5 into RGB and the vector's length
+// into A, so a shader can modulate wisp strength by field energy from the same
+// fetch. Decode through decodeCurlNoise(), or take the ready-made advection
+// offset from curlNoiseOffsetNode(), rather than unpacking by hand; the scale
+// the CPU normalized by is this module's business, not the raymarcher's.
+//
+// Both channels share one normalization scale, so A is exactly the length of the
+// vector RGB decodes to. That scale comes from the probed peak *length*, not the
+// peak component: a length reaches up to sqrt(3) times its largest component, so
+// normalizing by the component peak overflowed A and clipped it.
+
+import {
+  Fn,
+  texture3D,
+  vec3,
+} from 'three/tsl';
+
+import { hashSeed } from '../../core/generation.js';
+import { hashCombine } from '../../rockgen/noise/prng.js';
+import {
+  createNoiseVolumeTexture,
+  encodeSnorm8,
+  encodeUnorm8,
+  noiseVolumeKey,
+  resolveNoiseDims,
+  warnNoiseVolumeOnce,
+} from './noiseVolume.js';
+import { createPeriodicPerlinFbm3 } from './periodicNoise3.js';
+
+/** Default resolution. Curl is a low-frequency advection field; 32³ is ample. */
+export const CURL_NOISE_DEFAULT_DIMS = 32;
+
+/**
+ * Potential-field plan. `epsilon` is the central-difference step in tile units:
+ * small enough to read as a derivative, large enough that the difference of two
+ * nearly equal FBM samples keeps its significant digits.
+ */
+export const CURL_NOISE_PLAN = Object.freeze({
+  epsilon: 1 / 256,
+  gain: 0.6,
+  lacunarity: 2,
+  octaves: 3,
+  period: 3,
+});
+
+// The normalization scale is measured on a fixed probe grid rather than on the
+// output grid, so the same seed yields the same field at every resolution — a
+// 16³ curl volume must not be a differently scaled field from the 64³ one.
+const NORMALIZATION_PROBE_DIMS = 32;
+// Headroom over the probed peak, and the reason the probe can be fixed at all: a
+// finer output grid samples points the probe never visits, so it finds higher
+// values. Measured against the 32³ probe's peak length, the true peak runs 8.5%
+// higher on a 64³ output grid and 8.8% higher on a 128³ one, and a 400k-point
+// off-lattice sweep tops out at 6.8% — so the growth flattens off well inside
+// 15%, resolveNoiseDims' 256³ ceiling included.
+const NORMALIZATION_HEADROOM = 1.15;
+
+const volumeCache = new Map();
+
+/**
+ * Builds the divergence-free field.
+ *
+ * `sample(x, y, z)` takes tile coordinates and writes the normalized curl into
+ * `out`, returning it — components land in about [-1, 1]. `curl()` returns the
+ * same vector unnormalized, which is what the divergence check needs.
+ */
+export function createCurlNoiseField({ seed = 1, plan = {} } = {}) {
+  const rootSeed = hashSeed(seed);
+  const settings = { ...CURL_NOISE_PLAN, ...plan };
+  const epsilon = Math.max(1e-5, Number(settings.epsilon) || CURL_NOISE_PLAN.epsilon);
+  const fbmOptions = {
+    // The potential is evaluated analytically at arbitrary offsets, not on the
+    // output grid, so it carries no band limit of its own. The curl's own
+    // frequency content is set by `period` and stays well inside 32³.
+    dim: Infinity,
+    gain: settings.gain,
+    lacunarity: settings.lacunarity,
+    octaves: settings.octaves,
+    period: settings.period,
+  };
+  // Three potential components, seeded apart so the curl does not degenerate
+  // toward a single axis.
+  const psi = [
+    createPeriodicPerlinFbm3(hashCombine(rootSeed, 0x9e37), fbmOptions),
+    createPeriodicPerlinFbm3(hashCombine(rootSeed, 0x85eb), fbmOptions),
+    createPeriodicPerlinFbm3(hashCombine(rootSeed, 0xc2b2), fbmOptions),
+  ];
+  const inverseStep = 1 / (2 * epsilon);
+
+  function curl(x, y, z, out) {
+    const dy3 = (psi[2].sample(x, y + epsilon, z) - psi[2].sample(x, y - epsilon, z)) * inverseStep;
+    const dz2 = (psi[1].sample(x, y, z + epsilon) - psi[1].sample(x, y, z - epsilon)) * inverseStep;
+    const dz1 = (psi[0].sample(x, y, z + epsilon) - psi[0].sample(x, y, z - epsilon)) * inverseStep;
+    const dx3 = (psi[2].sample(x + epsilon, y, z) - psi[2].sample(x - epsilon, y, z)) * inverseStep;
+    const dx2 = (psi[1].sample(x + epsilon, y, z) - psi[1].sample(x - epsilon, y, z)) * inverseStep;
+    const dy1 = (psi[0].sample(x, y + epsilon, z) - psi[0].sample(x, y - epsilon, z)) * inverseStep;
+    out.x = dy3 - dz2;
+    out.y = dz1 - dx3;
+    out.z = dx2 - dy1;
+    return out;
+  }
+
+  // Probe for the peak so the 8-bit encoding uses its range without clipping the
+  // tails. Both peaks are measured; only the length one sets the scale.
+  const probe = { x: 0, y: 0, z: 0 };
+  let componentPeak = 0;
+  let lengthPeak = 0;
+  const inverseProbe = 1 / NORMALIZATION_PROBE_DIMS;
+  for (let z = 0; z < NORMALIZATION_PROBE_DIMS; z += 1) {
+    for (let y = 0; y < NORMALIZATION_PROBE_DIMS; y += 1) {
+      for (let x = 0; x < NORMALIZATION_PROBE_DIMS; x += 1) {
+        curl((x + 0.5) * inverseProbe, (y + 0.5) * inverseProbe, (z + 0.5) * inverseProbe, probe);
+        componentPeak = Math.max(
+          componentPeak, Math.abs(probe.x), Math.abs(probe.y), Math.abs(probe.z),
+        );
+        lengthPeak = Math.max(
+          lengthPeak,
+          Math.sqrt(probe.x * probe.x + probe.y * probe.y + probe.z * probe.z),
+        );
+      }
+    }
+  }
+  // Normalize by the *length* peak, because the length is what the A channel
+  // encodes and a length runs up to sqrt(3) times its largest component. Scaling
+  // by the component peak fit RGB and overflowed A, and a clipped |curl| is no
+  // longer the length of the RGB it ships with. One shared scale keeps
+  // `a === length(decode(rgb))` exact; it costs the components about a tenth of
+  // their range, which is cheaper than an inconsistent encoding.
+  const scale = 1 / (lengthPeak * NORMALIZATION_HEADROOM || 1);
+
+  return {
+    componentPeak,
+    curl,
+    epsilon,
+    lengthPeak,
+    sample(x, y, z, out = { x: 0, y: 0, z: 0 }) {
+      curl(x, y, z, out);
+      out.x *= scale;
+      out.y *= scale;
+      out.z *= scale;
+      return out;
+    },
+    scale,
+    seed: rootSeed,
+  };
+}
+
+/**
+ * Bakes the RGBA8 curl volume. Returned separately from the texture so the
+ * divergence and tiling checks can read the numbers without a renderer.
+ */
+export function createCurlNoiseData({
+  dims = CURL_NOISE_DEFAULT_DIMS,
+  seed = 1,
+  plan = {},
+} = {}) {
+  const size = resolveNoiseDims(dims, CURL_NOISE_DEFAULT_DIMS);
+  const field = createCurlNoiseField({ plan, seed });
+  const data = new Uint8Array(size.x * size.y * size.z * 4);
+  const vector = { x: 0, y: 0, z: 0 };
+  const invX = 1 / size.x;
+  const invY = 1 / size.y;
+  const invZ = 1 / size.z;
+  let cursor = 0;
+  // Watchdog on the fixed probe grid's assumption: the output grid is free to
+  // land on a higher field value than the probe found, and if the headroom ever
+  // fails to cover that the encoders clamp silently. Report it instead.
+  let peakLength = 0;
+  let clippedTexels = 0;
+  for (let z = 0; z < size.z; z += 1) {
+    const w = (z + 0.5) * invZ;
+    for (let y = 0; y < size.y; y += 1) {
+      const v = (y + 0.5) * invY;
+      for (let x = 0; x < size.x; x += 1) {
+        const u = (x + 0.5) * invX;
+        field.sample(u, v, w, vector);
+        const length = Math.sqrt(vector.x * vector.x + vector.y * vector.y + vector.z * vector.z);
+        if (length > peakLength) peakLength = length;
+        if (length > 1) clippedTexels += 1;
+        data[cursor] = encodeSnorm8(vector.x);
+        data[cursor + 1] = encodeSnorm8(vector.y);
+        data[cursor + 2] = encodeSnorm8(vector.z);
+        data[cursor + 3] = encodeUnorm8(length);
+        cursor += 4;
+      }
+    }
+  }
+  if (clippedTexels > 0) {
+    warnNoiseVolumeOnce(
+      `curl-clip:${size.x}x${size.y}x${size.z}`,
+      `[curlNoise] |curl| peaked at ${peakLength.toFixed(3)} on the `
+      + `${size.x}x${size.y}x${size.z} output grid, above the 1.0 the A channel can hold, so `
+      + `${clippedTexels} texel(s) clipped. The ${NORMALIZATION_PROBE_DIMS}³ probe grid `
+      + 'under-estimated the field peak at this resolution.',
+    );
+  }
+
+  return {
+    clippedTexels,
+    data,
+    dims: size,
+    field,
+    peakLength,
+    seed: field.seed,
+  };
+}
+
+/** Bakes an uncached curl volume. Callers own dispose(). */
+export function createCurlNoiseVolume({
+  dims = CURL_NOISE_DEFAULT_DIMS,
+  seed = 1,
+  plan = {},
+} = {}) {
+  const baked = createCurlNoiseData({ dims, plan, seed });
+  const texture = createNoiseVolumeTexture(
+    baked.data,
+    baked.dims,
+    `ToonLabCloudCurl${baked.dims.x}x${baked.dims.y}x${baked.dims.z}`,
+  );
+  texture.userData.toonlabCloudNoise = {
+    componentPeak: baked.field.componentPeak,
+    dims: baked.dims,
+    encoding: 'rgb = curl * 0.5 + 0.5, a = |curl|',
+    kind: 'curl',
+    lengthPeak: baked.field.lengthPeak,
+    peakLength: baked.peakLength,
+    scale: baked.field.scale,
+    seed: baked.seed,
+  };
+  return texture;
+}
+
+/** Cached curl volume, keyed by resolution and seed. */
+export function getCurlNoiseVolume({
+  dims = CURL_NOISE_DEFAULT_DIMS,
+  seed = 1,
+  plan = {},
+} = {}) {
+  const size = resolveNoiseDims(dims, CURL_NOISE_DEFAULT_DIMS);
+  // The plan joins the key: a custom potential is a different field, and
+  // returning the default one for it would be a silent wrong answer.
+  const key = `${noiseVolumeKey(size, hashSeed(seed))}:${hashSeed(JSON.stringify({ ...CURL_NOISE_PLAN, ...plan }))}`;
+  const cached = volumeCache.get(key);
+  if (cached) return cached;
+  const texture = createCurlNoiseVolume({ dims: size, plan, seed });
+  volumeCache.set(key, texture);
+  return texture;
+}
+
+/** Releases every cached curl volume. */
+export function disposeCurlNoiseVolumes() {
+  for (const texture of volumeCache.values()) texture.dispose();
+  volumeCache.clear();
+}
+
+/** Decodes a packed curl texel back to a signed vector in about [-1, 1]. */
+export const decodeCurlNoise = /*@__PURE__*/ Fn(([packed]) => (
+  packed.rgb.mul(2).sub(vec3(1))
+));
+
+/**
+ * Samples a baked curl volume as an advection offset, in metres.
+ *
+ * `scale` is the world size of one tile — pass the same repeat the erosion
+ * detail uses so wisps shear at the scale they are carved at. `strength` is the
+ * offset magnitude in metres at full field energy. RepeatWrapping does the
+ * tiling, so the world position needs no fract() first.
+ */
+export function curlNoiseOffsetNode(volume, {
+  position,
+  scale,
+  strength,
+}) {
+  const packed = texture3D(volume).sample(position.div(scale));
+  return decodeCurlNoise(packed).mul(strength);
+}

package/src/cloud/noise/erosionVolume.js

@@ -0,0 +1,188 @@
+// Cloud erosion volume — the high-frequency Worley detail field that carves
+// the cloud silhouette after the base shape has decided where cloud exists.
+//
+//   R  inverted Worley FBM, low detail (2 / 4 / 8 cells)
+//   G  inverted Worley FBM, mid detail (4 / 8 / 16 cells)
+//   B  inverted Worley FBM, high detail (8 / 16 cells)
+//   A  R * 0.625 + G * 0.25 + B * 0.125, precombined
+//
+// Each RGB channel is already an overlapping FBM, matching Hillaire's published
+// TileableVolumeNoise companion implementation. The density field combines the
+// three FBMs once more, which is what gives erosion a broad support plus enough
+// fine structure to break a silhouette:
+//
+//   detail   = r * 0.625 + g * 0.25 + b * 0.125            (or just the A channel)
+//   wispy    = mix(detail, 1 - detail, saturate(heightFraction * 5))
+//   modifier = mix(detail, wispy, erosionShape)
+//   density  = remap(base, modifier * erosionStrength, 1, 0, 1)
+//
+// The A channel exists for the cheap paths — the shadow bake and the env-map
+// bake carve with one weighted band instead of three, and a fetch they already
+// have to make is cheaper than three multiplies they do not.
+//
+// The band limit here is deliberately looser than the base-shape volume's (two
+// texels per cell rather than four). A detail field's job is high-frequency
+// grain, not a resolvable silhouette, and the top rung of a 32³ detail volume
+// is where the reference-class implementations sit.
+
+import { deriveSeed, hashSeed } from '../../core/generation.js';
+import {
+  createNoiseVolumeTexture,
+  encodeUnorm8,
+  noiseVolumeKey,
+  resolveNoiseDims,
+  warnNoiseVolumeOnce,
+} from './noiseVolume.js';
+import { createWorleyLadder3 } from './periodicNoise3.js';
+
+/** Default resolution. Not tier-driven: erosion is cheap at every tier. */
+export const CLOUD_EROSION_DEFAULT_DIMS = 32;
+
+/**
+ * Seed namespace for this volume's bands.
+ *
+ * createWorleyLadder3 seeds each band by its cell count, so a frequency is the
+ * same field at every volume resolution — and, without a namespace, the same
+ * field in every *volume* that requests that count. The base-shape volume's
+ * ladder overlaps this plan at 4/8/16 cells, so the two combined fields became
+ * strongly correlated. Carving a cloud with a copy of its own erosion basis
+ * flattens the silhouette instead of tearing it, and at
+ * `shape.erosionScaleBaseMultiplier = 1.0` — the top of the spec's authoring
+ * range, where both volumes are read at the same tile coordinate — the two
+ * fields were 0.69 correlated. Namespacing the seed drops that to ~0.
+ */
+export const CLOUD_EROSION_SEED_NAMESPACE = 'cloud-erosion';
+
+/** Weights the A channel packs, and the density field's own detail FBM. */
+export const CLOUD_EROSION_DETAIL_WEIGHTS = Object.freeze([0.625, 0.25, 0.125]);
+
+/**
+ * Frequency plan in cells across one tile. Fixed in tile units so a custom
+ * resolution re-resolves the same field rather than authoring a new one.
+ */
+export const CLOUD_EROSION_PLAN = Object.freeze({
+  cells: Object.freeze([2, 4, 8, 16]),
+  jitter: 1,
+  texelsPerCell: 2,
+});
+
+const volumeCache = new Map();
+
+/**
+ * Bakes the RGBA8 erosion field. Returned separately from the texture so
+ * verification scripts can read the numbers without a renderer.
+ */
+export function createCloudErosionData({
+  dims = CLOUD_EROSION_DEFAULT_DIMS,
+  seed = 1,
+} = {}) {
+  const size = resolveNoiseDims(dims, CLOUD_EROSION_DEFAULT_DIMS);
+  const rootSeed = hashSeed(seed);
+  // The public seed is reported unchanged so a preset can round-trip it; only
+  // the field seed is namespaced.
+  const fieldSeed = deriveSeed(rootSeed, CLOUD_EROSION_SEED_NAMESPACE);
+  const bands = createWorleyLadder3(fieldSeed, CLOUD_EROSION_PLAN.cells, {
+    dim: Math.min(size.x, size.y, size.z),
+    jitter: CLOUD_EROSION_PLAN.jitter,
+    texelsPerCell: CLOUD_EROSION_PLAN.texelsPerCell,
+  });
+  // Four bands are the contract, not a preference: RGB are the overlapping
+  // FBMs [2/4/8], [4/8/16] and [8/16]. At two texels per cell a short axis of
+  // 16 band-limits the last rung and loses the finest part of G/B.
+  const distinctBands = new Set(bands).size;
+  if (distinctBands < CLOUD_EROSION_PLAN.cells.length) {
+    warnNoiseVolumeOnce(
+      `erosion-bands:${size.x}x${size.y}x${size.z}`,
+      `[erosionVolume] ${size.x}x${size.y}x${size.z} band-limits cells `
+      + `[${CLOUD_EROSION_PLAN.cells}] to [${bands.map((band) => band.cells)}], leaving `
+      + `${distinctBands} distinct band(s) of ${CLOUD_EROSION_PLAN.cells.length}: the repeated `
+      + 'channels carry identical bytes and the detail FBM loses a band. Raise the resolution to '
+      + `${CLOUD_EROSION_PLAN.cells[CLOUD_EROSION_PLAN.cells.length - 1]
+        * CLOUD_EROSION_PLAN.texelsPerCell}³ or above for all three.`,
+    );
+  }
+  const [weightR, weightG, weightB] = CLOUD_EROSION_DETAIL_WEIGHTS;
+
+  const data = new Uint8Array(size.x * size.y * size.z * 4);
+  const invX = 1 / size.x;
+  const invY = 1 / size.y;
+  const invZ = 1 / size.z;
+  let cursor = 0;
+  for (let z = 0; z < size.z; z += 1) {
+    const w = (z + 0.5) * invZ;
+    for (let y = 0; y < size.y; y += 1) {
+      const v = (y + 0.5) * invY;
+      for (let x = 0; x < size.x; x += 1) {
+        const u = (x + 0.5) * invX;
+        const w0 = 1 - bands[0].sample(u, v, w);
+        const w1 = 1 - bands[1].sample(u, v, w);
+        const w2 = 1 - bands[2].sample(u, v, w);
+        const w3 = 1 - bands[3].sample(u, v, w);
+        // Exact packing from Hillaire's reference generator. The highest
+        // channel has two usable rungs at 32^3, hence 0.75 / 0.25.
+        const low = w0 * 0.625 + w1 * 0.25 + w2 * 0.125;
+        const mid = w1 * 0.625 + w2 * 0.25 + w3 * 0.125;
+        const high = w2 * 0.75 + w3 * 0.25;
+        data[cursor] = encodeUnorm8(low);
+        data[cursor + 1] = encodeUnorm8(mid);
+        data[cursor + 2] = encodeUnorm8(high);
+        data[cursor + 3] = encodeUnorm8(low * weightR + mid * weightG + high * weightB);
+        cursor += 4;
+      }
+    }
+  }
+
+  return {
+    data,
+    dims: size,
+    distinctBands,
+    fieldSeed,
+    seed: rootSeed,
+    worleyCells: bands.map((band) => band.cells),
+  };
+}
+
+/** Bakes an uncached erosion volume. Callers own dispose(). */
+export function createCloudErosionVolume({
+  dims = CLOUD_EROSION_DEFAULT_DIMS,
+  seed = 1,
+} = {}) {
+  const baked = createCloudErosionData({ dims, seed });
+  const texture = createNoiseVolumeTexture(
+    baked.data,
+    baked.dims,
+    `ToonLabCloudErosion${baked.dims.x}x${baked.dims.y}x${baked.dims.z}`,
+  );
+  texture.userData.toonlabCloudNoise = {
+    detailWeights: CLOUD_EROSION_DETAIL_WEIGHTS,
+    dims: baked.dims,
+    distinctBands: baked.distinctBands,
+    // `seed` is the public seed, so a lab can serialize it and get this volume
+    // back; `fieldSeed` is the namespaced seed the bands were built from.
+    fieldSeed: baked.fieldSeed,
+    kind: 'erosion',
+    seed: baked.seed,
+    worleyCells: baked.worleyCells,
+  };
+  return texture;
+}
+
+/** Cached erosion volume, keyed by resolution and seed. */
+export function getCloudErosionVolume({
+  dims = CLOUD_EROSION_DEFAULT_DIMS,
+  seed = 1,
+} = {}) {
+  const size = resolveNoiseDims(dims, CLOUD_EROSION_DEFAULT_DIMS);
+  const key = noiseVolumeKey(size, hashSeed(seed));
+  const cached = volumeCache.get(key);
+  if (cached) return cached;
+  const texture = createCloudErosionVolume({ dims: size, seed });
+  volumeCache.set(key, texture);
+  return texture;
+}
+
+/** Releases every cached erosion volume. */
+export function disposeCloudErosionVolumes() {
+  for (const texture of volumeCache.values()) texture.dispose();
+  volumeCache.clear();
+}

package/src/cloud/noise/noiseVolume.js

@@ -0,0 +1,202 @@
+// The Data3DTexture contract shared by the three cloud noise volumes.
+//
+// All of them are RGBA8 tiling fields sampled trilinearly with RepeatWrapping
+// on every axis. Getting one axis wrong (wrapR defaults to ClampToEdge) puts a
+// seam in the sky that looks like a shader bug rather than a texture setting,
+// so the settings live in one place instead of three.
+
+import * as THREE from 'three';
+
+/**
+ * Reads one authored number out of untrusted input, returning `fallback` for
+ * anything absent. The single definition of "absent" for the whole noise module.
+ *
+ * `Number()` is not the guard it looks like: `Number(null)`, `Number('')`,
+ * `Number([])` and `Number(false)` are all 0 and all pass `Number.isFinite`, so
+ * a clamp downstream pins them to a range's minimum instead of falling back to a
+ * default. A preset that round-tripped through JSON carries `null` for every
+ * untouched field, so that difference is the difference between reloading a sky
+ * and authoring a new one. Numeric strings stay legal because lab inputs and URL
+ * parameters arrive as strings.
+ */
+export function resolveAuthoredNumber(value, fallback) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : fallback;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+  }
+  return fallback;
+}
+
+/**
+ * Hard floor for every noise volume, on every axis.
+ *
+ * Below 8 the band ladder has nothing left to resolve: every Worley rung
+ * band-limits onto the same cell count, so the three erosion channels come out
+ * byte-identical and what remains is not a cloud field. The floor lives here
+ * rather than in each baker because the degenerate volume still samples cleanly
+ * — nothing downstream can detect that it was handed junk.
+ */
+export const NOISE_VOLUME_MIN_DIM = 8;
+
+/** Accepts 64, [64, 32, 64] or { x, y, z } and normalizes to { x, y, z }. */
+export function resolveNoiseDims(dims, fallback = 64) {
+  const clampAxis = (value) => {
+    // An absent axis is the default, not zero: a preset that serialized `null`
+    // — or `false`, or 0 — must not deserialize into a 2³ volume.
+    const size = Math.round(resolveAuthoredNumber(value, fallback));
+    if (!(size > 0)) return fallback;
+    if (size < NOISE_VOLUME_MIN_DIM) {
+      warnNoiseVolumeOnce(
+        `noise-dim-floor:${size}`,
+        `Noise volume axis ${size} is below the ${NOISE_VOLUME_MIN_DIM}-texel floor; `
+        + `clamping to ${NOISE_VOLUME_MIN_DIM}. Below it every band collapses onto one `
+        + 'cell count and the erosion channels come out identical.',
+      );
+    }
+    return Math.min(Math.max(size, NOISE_VOLUME_MIN_DIM), 256);
+  };
+  if (Array.isArray(dims)) {
+    return {
+      x: clampAxis(dims[0]),
+      y: clampAxis(dims[1] ?? dims[0]),
+      z: clampAxis(dims[2] ?? dims[0]),
+    };
+  }
+  if (dims && typeof dims === 'object') {
+    return { x: clampAxis(dims.x), y: clampAxis(dims.y), z: clampAxis(dims.z) };
+  }
+  const size = clampAxis(dims);
+  return { x: size, y: size, z: size };
+}
+
+/** `${x}x${y}x${z}:${seed}` — the cache key every volume generator uses. */
+export function noiseVolumeKey(dims, seed) {
+  return `${dims.x}x${dims.y}x${dims.z}:${seed}`;
+}
+
+const warnedKeys = new Set();
+
+/**
+ * Reports a degenerate volume configuration once per distinct `key`.
+ *
+ * A band ladder that collapsed, a mip level that hit the resolution floor, an
+ * encoding that clipped — all of them produce a field that still *looks* like a
+ * volume, so silence is the failure mode. Deduplicated because a lab bound to a
+ * seed slider re-bakes on every drag, and a warning repeated a hundred times
+ * buries the first one. The key is the configuration, not the seed: the same
+ * resolution degenerates the same way whatever it is seeded with.
+ */
+export function warnNoiseVolumeOnce(key, message) {
+  if (warnedKeys.has(key)) return false;
+  warnedKeys.add(key);
+  console.warn(message);
+  return true;
+}
+
+/**
+ * Wraps baked RGBA8 data in a fully configured tiling 3D texture.
+ *
+ * `generateMipmaps` stays off: three.js cannot build a 3D mip chain on the
+ * WebGPU backend. Volumes that carry authored levels are configured and uploaded
+ * by configureNoiseVolumeMipChain/uploadNoiseVolumeMipChain below.
+ */
+export function createNoiseVolumeTexture(data, dims, name) {
+  const texture = new THREE.Data3DTexture(data, dims.x, dims.y, dims.z);
+  texture.name = name;
+  texture.format = THREE.RGBAFormat;
+  texture.type = THREE.UnsignedByteType;
+  texture.colorSpace = THREE.NoColorSpace;
+  texture.wrapS = THREE.RepeatWrapping;
+  texture.wrapT = THREE.RepeatWrapping;
+  texture.wrapR = THREE.RepeatWrapping;
+  texture.minFilter = THREE.LinearFilter;
+  texture.magFilter = THREE.LinearFilter;
+  texture.generateMipmaps = false;
+  texture.unpackAlignment = 1;
+  texture.needsUpdate = true;
+  return texture;
+}
+
+function volumeMipDims(dims, level) {
+  const scale = 2 ** level;
+  return {
+    x: Math.max(1, Math.floor(dims.x / scale)),
+    y: Math.max(1, Math.floor(dims.y / scale)),
+    z: Math.max(1, Math.floor(dims.z / scale)),
+  };
+}
+
+/**
+ * Gives a Data3DTexture a full authored mip pyramid. WebGPU cannot generate
+ * 3D mips through three's normal generator, so the byte levels are retained
+ * until a renderer can copy them into the allocated GPU levels.
+ */
+export function configureNoiseVolumeMipChain(texture, levels, dims) {
+  if (!texture?.isData3DTexture || !Array.isArray(levels) || levels.length < 2) {
+    return texture;
+  }
+  texture.minFilter = THREE.LinearMipMapLinearFilter;
+  texture.magFilter = THREE.LinearFilter;
+  texture.generateMipmaps = false;
+  texture.mipmaps = levels.map((unused, level) => {
+    const size = volumeMipDims(dims, level);
+    return { width: size.x, height: size.y, depth: size.z };
+  });
+  texture.userData.toonlabVolumeMipChain = {
+    dims: { ...dims },
+    levels,
+    uploadedRenderers: new WeakSet(),
+  };
+  texture.needsUpdate = true;
+  return texture;
+}
+
+/** Uploads the retained 3D mip levels once for each renderer. */
+export function uploadNoiseVolumeMipChain(renderer, texture) {
+  const chain = texture?.userData?.toonlabVolumeMipChain;
+  if (!renderer?.copyTextureToTexture || !chain || chain.uploadedRenderers.has(renderer)) {
+    return false;
+  }
+
+  const temps = [];
+  for (let level = 1; level < chain.levels.length; level += 1) {
+    const size = volumeMipDims(chain.dims, level);
+    const temp = new THREE.Data3DTexture(
+      chain.levels[level],
+      size.x,
+      size.y,
+      size.z,
+    );
+    temp.format = THREE.RGBAFormat;
+    temp.type = THREE.UnsignedByteType;
+    temp.unpackAlignment = 1;
+    temp.needsUpdate = true;
+    renderer.copyTextureToTexture(
+      temp,
+      texture,
+      new THREE.Box3(
+        new THREE.Vector3(0, 0, 0),
+        new THREE.Vector3(size.x, size.y, size.z),
+      ),
+      new THREE.Vector3(0, 0, 0),
+      0,
+      level,
+    );
+    temps.push(temp);
+  }
+  for (const temp of temps) temp.dispose();
+  chain.uploadedRenderers.add(renderer);
+  return true;
+}
+
+/** Quantizes a [0, 1] field value to a byte with round-half-up. */
+export function encodeUnorm8(value) {
+  const clamped = value < 0 ? 0 : value > 1 ? 1 : value;
+  return (clamped * 255 + 0.5) | 0;
+}
+
+/** Quantizes a [-1, 1] field value to a byte, matching a `* 2 - 1` decode. */
+export function encodeSnorm8(value) {
+  return encodeUnorm8(value * 0.5 + 0.5);
+}