@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/utils/landscapeGeometry.js

@@ -0,0 +1,126 @@
+import * as THREE from 'three';
+import { Rtin } from './rtin.js';
+const tileCache = new WeakMap();
+/** The error map depends only on the heightfield, so it is built once per
+ *  decoded heightmap and reused for every error budget. */
+export function rtinTileFor(height) {
+    const cached = tileCache.get(height);
+    if (cached)
+        return cached;
+    const tile = new Rtin(height.gridSize).createTile(height.data);
+    tileCache.set(height, tile);
+    return tile;
+}
+export function buildLandscapeGeometry(height, options) {
+    const { size, maxError } = options;
+    const chunksPerSide = Math.max(1, Math.min(16, Math.round(options.chunks)));
+    const tile = rtinTileFor(height);
+    const mesh = tile.getMesh(Math.max(0, maxError));
+    const grid = height.gridSize;
+    const tileSize = height.tileSize;
+    const vertexCount = mesh.vertices.length / 2;
+    const positions = new Float32Array(vertexCount * 3);
+    const uvs = new Float32Array(vertexCount * 2);
+    for (let i = 0; i < vertexCount; i++) {
+        const gx = mesh.vertices[i * 2];
+        const gy = mesh.vertices[i * 2 + 1];
+        const u = gx / tileSize;
+        const v = gy / tileSize;
+        positions[i * 3 + 0] = (u - 0.5) * size;
+        positions[i * 3 + 1] = 0;
+        positions[i * 3 + 2] = (v - 0.5) * size;
+        uvs[i * 2 + 0] = u;
+        uvs[i * 2 + 1] = v;
+    }
+    const position = new THREE.BufferAttribute(positions, 3);
+    const uv = new THREE.BufferAttribute(uvs, 2);
+    // Bucket triangles by the chunk their centroid falls in.
+    const buckets = Array.from({ length: chunksPerSide * chunksPerSide }, () => []);
+    const triangleCount = mesh.triangles.length / 3;
+    for (let t = 0; t < triangleCount; t++) {
+        const a = mesh.triangles[t * 3];
+        const b = mesh.triangles[t * 3 + 1];
+        const c = mesh.triangles[t * 3 + 2];
+        const cx = (mesh.vertices[a * 2] + mesh.vertices[b * 2] + mesh.vertices[c * 2]) / 3;
+        const cy = (mesh.vertices[a * 2 + 1] + mesh.vertices[b * 2 + 1] + mesh.vertices[c * 2 + 1]) / 3;
+        const ix = Math.min(chunksPerSide - 1, Math.floor((cx / tileSize) * chunksPerSide));
+        const iy = Math.min(chunksPerSide - 1, Math.floor((cy / tileSize) * chunksPerSide));
+        buckets[iy * chunksPerSide + ix].push(a, b, c);
+    }
+    const chunks = [];
+    for (const indices of buckets) {
+        if (indices.length === 0)
+            continue;
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute('position', position);
+        geometry.setAttribute('uv', uv);
+        geometry.setIndex(new THREE.BufferAttribute(new Uint32Array(indices), 1));
+        let minH01 = Infinity;
+        let maxH01 = -Infinity;
+        let minX = Infinity;
+        let maxX = -Infinity;
+        let minZ = Infinity;
+        let maxZ = -Infinity;
+        for (const index of indices) {
+            const gx = mesh.vertices[index * 2];
+            const gy = mesh.vertices[index * 2 + 1];
+            const h = height.data[gy * grid + gx];
+            if (h < minH01)
+                minH01 = h;
+            if (h > maxH01)
+                maxH01 = h;
+            const x = positions[index * 3];
+            const z = positions[index * 3 + 2];
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+        // Placeholder Y; setLandscapeBounds writes the real range once the
+        // elevation scale is known, and again whenever it changes.
+        geometry.boundingBox = new THREE.Box3(new THREE.Vector3(minX, 0, minZ), new THREE.Vector3(maxX, 1, maxZ));
+        geometry.boundingSphere = new THREE.Sphere();
+        geometry.boundingBox.getBoundingSphere(geometry.boundingSphere);
+        chunks.push({ geometry, minH01, maxH01 });
+    }
+    return {
+        chunks,
+        position,
+        uv,
+        vertexCount,
+        triangleCount,
+        size,
+        dispose() {
+            for (const chunk of chunks) {
+                // Drop the shared attributes first so disposing the geometry
+                // cannot free them once per chunk.
+                chunk.geometry.deleteAttribute('position');
+                chunk.geometry.deleteAttribute('uv');
+                chunk.geometry.dispose();
+            }
+        },
+    };
+}
+/** Rewrite the vertical extent of every chunk's bounds. Called whenever the
+ *  elevation scale or bias changes; without it a raised landscape culls against
+ *  the flat plate it was built as and disappears when the camera tilts. */
+export function setLandscapeBounds(geometry, scale, bias) {
+    for (const chunk of geometry.chunks) {
+        const box = chunk.geometry.boundingBox;
+        if (!box)
+            continue;
+        box.min.y = chunk.minH01 * scale + bias;
+        box.max.y = chunk.maxH01 * scale + bias;
+        // A degenerate box makes the sphere radius 0 and culls the chunk at
+        // grazing angles.
+        if (box.max.y - box.min.y < 1e-3)
+            box.max.y = box.min.y + 1e-3;
+        if (!chunk.geometry.boundingSphere)
+            chunk.geometry.boundingSphere = new THREE.Sphere();
+        box.getBoundingSphere(chunk.geometry.boundingSphere);
+    }
+}

package/dist/utils/landscapeHeight.d.ts

@@ -0,0 +1,44 @@
+import * as THREE from 'three';
+/**
+ * CPU height queries against a landscape.
+ *
+ * The procedural terrain has never had this — its height field exists only in
+ * the shader, so nothing can be placed *on* it programmatically (terrain doc,
+ * open item #5). A landscape gets it for nothing, because RTIN already decoded
+ * the heightmap into a `Float32Array` on the way to building the mesh.
+ *
+ * What it is for: snapping a placed object to the ground, keeping a camera above
+ * it, and later letting the water read a landscape's shoreline the way the ocean
+ * plan reads the terrain's.
+ */
+export interface LandscapeHeightField {
+    /** Normalised 0..1 samples, `gridSize * gridSize`, row-major. */
+    data: Float32Array;
+    gridSize: number;
+    tileSize: number;
+    /** World units across the tile. */
+    size: number;
+    /** World centre of the tile. */
+    origin: THREE.Vector3;
+    /** Y rotation applied to the tile, in radians. */
+    rotationY: number;
+    elevationScale: number;
+    elevationBias: number;
+}
+export declare function registerLandscapeHeightField(id: string, field: LandscapeHeightField): void;
+export declare function unregisterLandscapeHeightField(id: string): void;
+/**
+ * World height at a world XZ, or null when the point is off the tile.
+ *
+ * Bilinear against the heightmap itself rather than against the mesh, so the
+ * answer does not change when the error budget does — the mesh is an
+ * approximation of this, not the other way round.
+ */
+export declare function sampleLandscapeHeight(field: LandscapeHeightField, x: number, z: number): number | null;
+/** Highest landscape under a world XZ, across every registered landscape.
+ *  Returns null when no landscape covers the point. */
+export declare function getLandscapeHeightAt(x: number, z: number): number | null;
+/** Drop an object onto the ground, keeping its XZ. No-op when nothing is under
+ *  it, so calling this in a scene with no landscape is safe. */
+export declare function snapToLandscape(object: THREE.Object3D, offset?: number): boolean;
+//# sourceMappingURL=landscapeHeight.d.ts.map

package/dist/utils/landscapeHeight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscapeHeight.d.ts","sourceRoot":"","sources":["../../src/utils/landscapeHeight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,oBAAoB;IACjC,iEAAiE;IACjE,IAAI,EAAE,YAAY,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAA;IACrB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;CACxB;AAID,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAE1F;AAED,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgCtG;AAED;uDACuD;AACvD,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOxE;AAED;gEACgE;AAChE,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,SAAI,GAAG,OAAO,CAK3E"}

package/dist/utils/landscapeHeight.js

@@ -0,0 +1,65 @@
+const fields = new Map();
+export function registerLandscapeHeightField(id, field) {
+    fields.set(id, field);
+}
+export function unregisterLandscapeHeightField(id) {
+    fields.delete(id);
+}
+/**
+ * World height at a world XZ, or null when the point is off the tile.
+ *
+ * Bilinear against the heightmap itself rather than against the mesh, so the
+ * answer does not change when the error budget does — the mesh is an
+ * approximation of this, not the other way round.
+ */
+export function sampleLandscapeHeight(field, x, z) {
+    let dx = x - field.origin.x;
+    let dz = z - field.origin.z;
+    if (field.rotationY !== 0) {
+        const c = Math.cos(-field.rotationY);
+        const s = Math.sin(-field.rotationY);
+        const rx = dx * c - dz * s;
+        const rz = dx * s + dz * c;
+        dx = rx;
+        dz = rz;
+    }
+    const u = dx / field.size + 0.5;
+    const v = dz / field.size + 0.5;
+    if (u < 0 || u > 1 || v < 0 || v > 1)
+        return null;
+    const fx = u * field.tileSize;
+    const fy = v * field.tileSize;
+    const x0 = Math.min(field.tileSize, Math.floor(fx));
+    const y0 = Math.min(field.tileSize, Math.floor(fy));
+    const x1 = Math.min(field.gridSize - 1, x0 + 1);
+    const y1 = Math.min(field.gridSize - 1, y0 + 1);
+    const tx = fx - x0;
+    const ty = fy - y0;
+    const g = field.gridSize;
+    const h00 = field.data[y0 * g + x0];
+    const h10 = field.data[y0 * g + x1];
+    const h01 = field.data[y1 * g + x0];
+    const h11 = field.data[y1 * g + x1];
+    const h = (h00 * (1 - tx) + h10 * tx) * (1 - ty) + (h01 * (1 - tx) + h11 * tx) * ty;
+    return h * field.elevationScale + field.elevationBias + field.origin.y;
+}
+/** Highest landscape under a world XZ, across every registered landscape.
+ *  Returns null when no landscape covers the point. */
+export function getLandscapeHeightAt(x, z) {
+    let best = null;
+    for (const field of fields.values()) {
+        const h = sampleLandscapeHeight(field, x, z);
+        if (h !== null && (best === null || h > best))
+            best = h;
+    }
+    return best;
+}
+/** Drop an object onto the ground, keeping its XZ. No-op when nothing is under
+ *  it, so calling this in a scene with no landscape is safe. */
+export function snapToLandscape(object, offset = 0) {
+    const h = getLandscapeHeightAt(object.position.x, object.position.z);
+    if (h === null)
+        return false;
+    object.position.y = h + offset;
+    return true;
+}

package/dist/utils/landscapeTextures.d.ts

@@ -0,0 +1,94 @@
+import * as THREE from 'three';
+export declare function loadImage(url: string): Promise<HTMLImageElement>;
+/** Largest power of two at or below n, clamped to something RTIN can chew. */
+export declare function floorPowerOfTwo(n: number): number;
+export type HeightEncodingName = 'grayscale' | 'terrain-rgb' | 'rg16';
+export interface DecodedHeightmap {
+    /** (size+1)^2 samples, normalised to 0..1, row-major, right and bottom edges
+     *  backfilled so RTIN gets its 2^n+1 grid. */
+    data: Float32Array;
+    /** RTIN grid size — `tileSize + 1`. */
+    gridSize: number;
+    /** Heightmap resolution the grid was built from, a power of two. */
+    tileSize: number;
+    /** Source-unit range, before normalisation. Metres for terrain-rgb. */
+    min: number;
+    max: number;
+}
+/**
+ * Heightmap pixels to a normalised RTIN grid.
+ *
+ * Normalising to 0..1 here rather than baking `elevationScale` in is what lets
+ * the error map be built once: RTIN's error scales linearly with the height
+ * scale, so a change of scale is a change of error budget, not a new error map.
+ */
+export declare function decodeHeightmap(image: HTMLImageElement, encoding: HeightEncodingName): DecodedHeightmap;
+export interface TextureArrayResult {
+    texture: THREE.DataArrayTexture;
+    /** Mean colour per layer, in the array's own encoding. Used by the
+     *  variance-preserving stochastic blend, which needs the texture's mean to
+     *  restore contrast the blend would otherwise wash out. Free to compute here
+     *  because the pixels are already in hand. */
+    means: THREE.Vector3[];
+}
+/**
+ * Pack images into one `DataArrayTexture`.
+ *
+ * Every layer must be the same size, and user uploads never are, so each image
+ * is drawn into a canvas at `size` first. `alphaFrom` supplies a second image
+ * per layer whose red channel becomes the layer's alpha — used to carry each
+ * surface's height map in the normal array's spare channel rather than paying
+ * for a whole third array.
+ */
+export declare function buildTextureArray(images: (HTMLImageElement | null)[], size: number, colorSpace: THREE.ColorSpace, alphaFrom?: (HTMLImageElement | null)[], fallback?: [number, number, number, number]): TextureArrayResult;
+/** A plain 2D texture from an already-loaded image, without a round trip through
+ *  TextureLoader — the image is in the cache either way. */
+export declare function textureFromImage(image: HTMLImageElement, colorSpace: THREE.ColorSpace): THREE.Texture;
+/**
+ * Light separable binomial blur over the decoded field.
+ *
+ * This is not cosmetic. An 8-bit heightmap has 256 levels, which over 340 m of
+ * relief is a 1.33 m step — and RTIN's error metric measures exactly that step.
+ * Measured on the highlands map: a 1.7 m budget sits above the quantisation
+ * noise and returns 68k triangles (visibly polygonal), while 0.4 m sits below it
+ * and returns 1.2M, the whole grid. There is no useful setting in between,
+ * because the staircase, not the terrain, is what the metric is seeing.
+ *
+ * Smoothing first removes the staircase and gives the error map a real signal,
+ * so the budget means what it says. The smoothed field is what RTIN, the field
+ * texture and the CPU height query all use; the vertex shader keeps sampling the
+ * raw texture, where its own bicubic filter does the same job on the GPU.
+ */
+export declare function smoothHeightfield(height: DecodedHeightmap, passes?: number): DecodedHeightmap;
+export interface FieldTextureResult {
+    texture: THREE.DataTexture;
+    /** Largest absolute one-texel gradient in the field, used to unpack RG. */
+    gradScale: number;
+}
+/**
+ * The height field as something the FRAGMENT stage can read: one texture, one
+ * fetch, carrying both the surface gradient and the height.
+ *
+ *   R, G  the one-texel gradient in x and z, biased to 0..1 by `gradScale`
+ *   B     the height, 0..1
+ *
+ * ## Why this exists
+ *
+ * Because splatting and shading off the interpolated vertex height is wrong, and
+ * that is exactly what the first version did. A linearly interpolated quantity
+ * has straight iso-lines within a triangle that kink at its edges, so every
+ * splat threshold is drawn along the triangulation — big polygonal patches of
+ * flat colour — and the shading normal is faceted for the same reason. The
+ * terrain material's own comment says so: *shade against the evaluated surface,
+ * not the interpolated mesh vertex*.
+ *
+ * Sampling this in the fragment shader costs one texture fetch and makes the
+ * mesh's own resolution invisible: the ground shades and splats smoothly however
+ * coarse the triangles under it are.
+ *
+ * Eight bits per channel is enough here. The gradient is a normal map by another
+ * name, and the height only drives auto-splat band thresholds that are already
+ * noise-jittered and smoothstepped.
+ */
+export declare function buildFieldTexture(height: DecodedHeightmap): FieldTextureResult;
+//# sourceMappingURL=landscapeTextures.d.ts.map

package/dist/utils/landscapeTextures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscapeTextures.d.ts","sourceRoot":"","sources":["../../src/utils/landscapeTextures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAe9B,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAYhE;AAwBD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAA;AAErE,MAAM,WAAW,gBAAgB;IAC7B;kDAC8C;IAC9C,IAAI,EAAE,YAAY,CAAA;IAClB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,kBAAkB,GAAG,gBAAgB,CA4CvG;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,KAAK,CAAC,gBAAgB,CAAA;IAC/B;;;kDAG8C;IAC9C,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAA;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,CAAC,gBAAgB,GAAG,IAAI,CAAC,EAAE,EACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,KAAK,CAAC,UAAU,EAC5B,SAAS,CAAC,EAAE,CAAC,gBAAgB,GAAG,IAAI,CAAC,EAAE,EACvC,QAAQ,GAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAwB,GAClE,kBAAkB,CA2DpB;AAED;4DAC4D;AAC5D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,OAAO,CAUrG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,SAAI,GAAG,gBAAgB,CA2BxF;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,KAAK,CAAC,WAAW,CAAA;IAC1B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CA0C9E"}

package/dist/utils/landscapeTextures.js

@@ -0,0 +1,290 @@
+import * as THREE from 'three';
+/**
+ * Image decoding and texture-array packing for the landscape.
+ *
+ * Everything here reads pixels through a 2D canvas, which means every image must
+ * be CORS-clean: a cross-origin image served without `Access-Control-Allow-Origin`
+ * taints the canvas and `getImageData` throws. The failure is confusing when it
+ * happens — the texture itself renders fine and only the landscape fails to
+ * build — so `loadImage` sets `crossOrigin` and the callers report the origin in
+ * the error.
+ */
+const imageCache = new Map();
+export function loadImage(url) {
+    const cached = imageCache.get(url);
+    if (cached)
+        return cached;
+    const promise = new Promise((resolve, reject) => {
+        const image = new window.Image();
+        image.crossOrigin = 'anonymous';
+        image.onload = () => resolve(image);
+        image.onerror = () => reject(new Error(`landscape: failed to load ${url}`));
+        image.src = url;
+    });
+    imageCache.set(url, promise);
+    return promise;
+}
+function canvasOf(width, height) {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    if (!ctx)
+        throw new Error('landscape: no 2d context');
+    return { canvas, ctx };
+}
+function readPixels(image, size) {
+    const { ctx } = canvasOf(size, size);
+    ctx.drawImage(image, 0, 0, size, size);
+    try {
+        return ctx.getImageData(0, 0, size, size).data;
+    }
+    catch (error) {
+        throw new Error(`landscape: cannot read pixels from ${image.src} — the canvas is tainted. `
+            + 'The asset host must send Access-Control-Allow-Origin.');
+    }
+}
+/** Largest power of two at or below n, clamped to something RTIN can chew. */
+export function floorPowerOfTwo(n) {
+    return Math.max(16, Math.min(4096, 2 ** Math.floor(Math.log2(n))));
+}
+/**
+ * Heightmap pixels to a normalised RTIN grid.
+ *
+ * Normalising to 0..1 here rather than baking `elevationScale` in is what lets
+ * the error map be built once: RTIN's error scales linearly with the height
+ * scale, so a change of scale is a change of error budget, not a new error map.
+ */
+export function decodeHeightmap(image, encoding) {
+    const tileSize = floorPowerOfTwo(Math.min(image.width, image.height));
+    const gridSize = tileSize + 1;
+    const pixels = readPixels(image, tileSize);
+    const raw = new Float32Array(gridSize * gridSize);
+    let min = Infinity;
+    let max = -Infinity;
+    for (let y = 0; y < tileSize; y++) {
+        for (let x = 0; x < tileSize; x++) {
+            const k = (y * tileSize + x) * 4;
+            const r = pixels[k];
+            const g = pixels[k + 1];
+            const b = pixels[k + 2];
+            let h;
+            if (encoding === 'terrain-rgb') {
+                h = (r * 65536 + g * 256 + b) / 10 - 10000;
+            }
+            else if (encoding === 'rg16') {
+                h = (r * 256 + g) / 65535;
+            }
+            else {
+                h = r / 255;
+            }
+            raw[y * gridSize + x] = h;
+            if (h < min)
+                min = h;
+            if (h > max)
+                max = h;
+        }
+    }
+    // RTIN wants 2^n+1 samples; the last row and column are copies of their
+    // neighbours so the extra edge does not invent a cliff.
+    for (let x = 0; x < gridSize - 1; x++) {
+        raw[gridSize * (gridSize - 1) + x] = raw[gridSize * (gridSize - 2) + x];
+    }
+    for (let y = 0; y < gridSize; y++) {
+        raw[gridSize * y + gridSize - 1] = raw[gridSize * y + gridSize - 2];
+    }
+    const range = max - min;
+    if (range > 1e-9 && (encoding !== 'grayscale' || min !== 0 || max !== 1)) {
+        for (let i = 0; i < raw.length; i++)
+            raw[i] = (raw[i] - min) / range;
+    }
+    return { data: raw, gridSize, tileSize, min, max };
+}
+/**
+ * Pack images into one `DataArrayTexture`.
+ *
+ * Every layer must be the same size, and user uploads never are, so each image
+ * is drawn into a canvas at `size` first. `alphaFrom` supplies a second image
+ * per layer whose red channel becomes the layer's alpha — used to carry each
+ * surface's height map in the normal array's spare channel rather than paying
+ * for a whole third array.
+ */
+export function buildTextureArray(images, size, colorSpace, alphaFrom, fallback = [255, 255, 255, 255]) {
+    const layers = images.length;
+    const stride = size * size * 4;
+    const data = new Uint8Array(stride * layers);
+    const means = [];
+    for (let i = 0; i < layers; i++) {
+        const image = images[i];
+        const offset = i * stride;
+        let sumR = 0;
+        let sumG = 0;
+        let sumB = 0;
+        if (image) {
+            const pixels = readPixels(image, size);
+            data.set(pixels, offset);
+            for (let p = 0; p < stride; p += 4) {
+                sumR += pixels[p];
+                sumG += pixels[p + 1];
+                sumB += pixels[p + 2];
+            }
+        }
+        else {
+            for (let p = 0; p < stride; p += 4) {
+                data[offset + p] = fallback[0];
+                data[offset + p + 1] = fallback[1];
+                data[offset + p + 2] = fallback[2];
+                data[offset + p + 3] = fallback[3];
+            }
+            sumR = (fallback[0] * stride) / 4;
+            sumG = (fallback[1] * stride) / 4;
+            sumB = (fallback[2] * stride) / 4;
+        }
+        const alphaImage = alphaFrom?.[i];
+        if (alphaImage) {
+            const alpha = readPixels(alphaImage, size);
+            for (let p = 0; p < stride; p += 4)
+                data[offset + p + 3] = alpha[p];
+        }
+        else if (alphaFrom) {
+            // No height map for this layer: a flat mid height blends linearly,
+            // which is what every layer does in the reference implementation.
+            for (let p = 0; p < stride; p += 4)
+                data[offset + p + 3] = 128;
+        }
+        const texels = (size * size) || 1;
+        means.push(new THREE.Vector3(sumR / texels / 255, sumG / texels / 255, sumB / texels / 255));
+    }
+    const texture = new THREE.DataArrayTexture(data, size, size, layers);
+    texture.format = THREE.RGBAFormat;
+    texture.type = THREE.UnsignedByteType;
+    texture.colorSpace = colorSpace;
+    texture.minFilter = THREE.LinearMipMapLinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.wrapS = THREE.RepeatWrapping;
+    texture.wrapT = THREE.RepeatWrapping;
+    texture.generateMipmaps = true;
+    texture.needsUpdate = true;
+    return { texture, means };
+}
+/** A plain 2D texture from an already-loaded image, without a round trip through
+ *  TextureLoader — the image is in the cache either way. */
+export function textureFromImage(image, colorSpace) {
+    const texture = new THREE.Texture(image);
+    texture.colorSpace = colorSpace;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.minFilter = THREE.LinearMipMapLinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.generateMipmaps = true;
+    texture.needsUpdate = true;
+    return texture;
+}
+/**
+ * Light separable binomial blur over the decoded field.
+ *
+ * This is not cosmetic. An 8-bit heightmap has 256 levels, which over 340 m of
+ * relief is a 1.33 m step — and RTIN's error metric measures exactly that step.
+ * Measured on the highlands map: a 1.7 m budget sits above the quantisation
+ * noise and returns 68k triangles (visibly polygonal), while 0.4 m sits below it
+ * and returns 1.2M, the whole grid. There is no useful setting in between,
+ * because the staircase, not the terrain, is what the metric is seeing.
+ *
+ * Smoothing first removes the staircase and gives the error map a real signal,
+ * so the budget means what it says. The smoothed field is what RTIN, the field
+ * texture and the CPU height query all use; the vertex shader keeps sampling the
+ * raw texture, where its own bicubic filter does the same job on the GPU.
+ */
+export function smoothHeightfield(height, passes = 1) {
+    const { gridSize } = height;
+    let src = height.data;
+    for (let pass = 0; pass < passes; pass++) {
+        const tmp = new Float32Array(src.length);
+        const out = new Float32Array(src.length);
+        // horizontal, then vertical: [1 2 1] / 4
+        for (let y = 0; y < gridSize; y++) {
+            const row = y * gridSize;
+            for (let x = 0; x < gridSize; x++) {
+                const l = src[row + Math.max(x - 1, 0)];
+                const c = src[row + x];
+                const r = src[row + Math.min(x + 1, gridSize - 1)];
+                tmp[row + x] = (l + 2 * c + r) * 0.25;
+            }
+        }
+        for (let y = 0; y < gridSize; y++) {
+            const up = Math.max(y - 1, 0) * gridSize;
+            const dn = Math.min(y + 1, gridSize - 1) * gridSize;
+            const row = y * gridSize;
+            for (let x = 0; x < gridSize; x++) {
+                out[row + x] = (tmp[up + x] + 2 * tmp[row + x] + tmp[dn + x]) * 0.25;
+            }
+        }
+        src = out;
+    }
+    return { ...height, data: src };
+}
+/**
+ * The height field as something the FRAGMENT stage can read: one texture, one
+ * fetch, carrying both the surface gradient and the height.
+ *
+ *   R, G  the one-texel gradient in x and z, biased to 0..1 by `gradScale`
+ *   B     the height, 0..1
+ *
+ * ## Why this exists
+ *
+ * Because splatting and shading off the interpolated vertex height is wrong, and
+ * that is exactly what the first version did. A linearly interpolated quantity
+ * has straight iso-lines within a triangle that kink at its edges, so every
+ * splat threshold is drawn along the triangulation — big polygonal patches of
+ * flat colour — and the shading normal is faceted for the same reason. The
+ * terrain material's own comment says so: *shade against the evaluated surface,
+ * not the interpolated mesh vertex*.
+ *
+ * Sampling this in the fragment shader costs one texture fetch and makes the
+ * mesh's own resolution invisible: the ground shades and splats smoothly however
+ * coarse the triangles under it are.
+ *
+ * Eight bits per channel is enough here. The gradient is a normal map by another
+ * name, and the height only drives auto-splat band thresholds that are already
+ * noise-jittered and smoothstepped.
+ */
+export function buildFieldTexture(height) {
+    const { data, gridSize, tileSize } = height;
+    const size = tileSize;
+    const gx = new Float32Array(size * size);
+    const gy = new Float32Array(size * size);
+    let maxGrad = 1e-6;
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            const xl = Math.max(x - 1, 0);
+            const xr = Math.min(x + 1, size - 1);
+            const yu = Math.max(y - 1, 0);
+            const yd = Math.min(y + 1, size - 1);
+            const dx = (data[y * gridSize + xr] - data[y * gridSize + xl]) * 0.5;
+            const dy = (data[yd * gridSize + x] - data[yu * gridSize + x]) * 0.5;
+            gx[y * size + x] = dx;
+            gy[y * size + x] = dy;
+            const m = Math.max(Math.abs(dx), Math.abs(dy));
+            if (m > maxGrad)
+                maxGrad = m;
+        }
+    }
+    const pixels = new Uint8Array(size * size * 4);
+    for (let i = 0; i < size * size; i++) {
+        const x = i % size;
+        const y = (i / size) | 0;
+        pixels[i * 4 + 0] = Math.round(THREE.MathUtils.clamp(gx[i] / maxGrad * 0.5 + 0.5, 0, 1) * 255);
+        pixels[i * 4 + 1] = Math.round(THREE.MathUtils.clamp(gy[i] / maxGrad * 0.5 + 0.5, 0, 1) * 255);
+        pixels[i * 4 + 2] = Math.round(THREE.MathUtils.clamp(data[y * gridSize + x], 0, 1) * 255);
+        pixels[i * 4 + 3] = 255;
+    }
+    const texture = new THREE.DataTexture(pixels, size, size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    texture.colorSpace = THREE.NoColorSpace;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.minFilter = THREE.LinearMipMapLinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.generateMipmaps = true;
+    texture.needsUpdate = true;
+    return { texture, gradScale: maxGrad };
+}

package/dist/utils/landscapeUniforms.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from 'three';
+import type { LandscapeConfig, LandscapeQualityConfig } from '../types/landscapeConfigs';
+import type { LandscapeUniforms } from '../shaders/landscape/LandscapeMaterial';
+export interface LandscapeMapUniforms {
+    height: THREE.Texture | null;
+    heightSize: THREE.Vector2;
+    /** RG gradient + B height, sampled per fragment. */
+    field: THREE.Texture | null;
+    fieldSize: THREE.Vector2;
+    gradScale: number;
+    diffuse: THREE.DataArrayTexture | null;
+    normal: THREE.DataArrayTexture | null;
+    splat0: THREE.Texture | null;
+    splat1: THREE.Texture | null;
+    ao: THREE.Texture | null;
+    means: THREE.Vector3[];
+}
+export declare function applyLandscapeMaps(uniforms: LandscapeUniforms, maps: LandscapeMapUniforms): void;
+export declare function applyLandscapeUniforms(uniforms: LandscapeUniforms, config: LandscapeConfig, quality: LandscapeQualityConfig): void;
+//# sourceMappingURL=landscapeUniforms.d.ts.map

package/dist/utils/landscapeUniforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscapeUniforms.d.ts","sourceRoot":"","sources":["../../src/utils/landscapeUniforms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAa/E,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,KAAK,CAAC,OAAO,CAAA;IACzB,oDAAoD;IACpD,KAAK,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;IAC3B,SAAS,EAAE,KAAK,CAAC,OAAO,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAA;IACtC,MAAM,EAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAA;IACrC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;IAC5B,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;IAC5B,EAAE,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAA;CACzB;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAoBhG;AAED,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,sBAAsB,GAChC,IAAI,CAmDN"}