@navaramap/three 0.0.0 → 0.0.2

package/src/tileTexture/TileTextureCompositor.test.ts

@@ -2,6 +2,7 @@ import { Mesh, BoxGeometry, MeshBasicMaterial } from "three";
 import { describe, expect, it, vi } from "vitest";
 
 import { TexturizedSceneByTileCoordinates } from "../scene";
+import { createTestTileHandler } from "../test-utils/engine";
 
 import { TileTextureCompositor } from "./TileTextureCompositor";
 import type { AtlasFactory, CompositeAtlas } from "./types";
@@ -47,6 +48,7 @@ function setup() {
       typeof TileTextureCompositor
     >[0]["renderer"],
     texturizedSceneByTileCoordinates: texturizedScenes,
+    mercatorY: createTestTileHandler().mercatorY,
     atlasFactory: fakeFactory,
   });
   return { compositor, renderer, texturizedScenes };
@@ -258,3 +260,108 @@ describe("TileTextureCompositor.renderVectorScenes", () => {
     expect(renderer.clear).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("TileTextureCompositor.renderRasterTiles", () => {
+  const fakeRT = (): unknown => ({ texture: { needsUpdate: false } });
+  // A bake source texture: `configureRasterBakeSource` mutates these sampler
+  // fields in place, so a plain object stands in for a three.js Texture.
+  const fakeTex = (name: string): unknown => ({
+    name,
+    colorSpace: "",
+    minFilter: 0,
+    magFilter: 0,
+    generateMipmaps: false,
+    needsUpdate: false,
+  });
+  /** The texture bound to the bake quad at each render call, in draw order. */
+  const trackDrawnMaps = (renderer: ReturnType<typeof makeRenderer>) => {
+    const maps: unknown[] = [];
+    renderer.render.mockImplementation((scene) => {
+      const quad = (scene as { children: { material: { map: unknown } }[] })
+        .children[0];
+      maps.push(quad.material.map);
+    });
+    return maps;
+  };
+
+  it("paints the no-data underlay across a heatmap target before its sources", () => {
+    const { compositor, renderer } = setup();
+    const maps = trackDrawnMaps(renderer);
+    const src = fakeTex("dem");
+
+    compositor.renderRasterTiles(
+      [
+        {
+          isElevationHeatmap: true,
+          noDataColor: [1, 2, 3],
+          sources: [
+            { texture: src as never, uvOffset: [0, 0], uvScale: [1, 1] },
+          ],
+        },
+      ],
+      [fakeRT() as never],
+    );
+
+    // First draw: the 1×1 no-data texture (decoder boundary color, opaque
+    // alpha) spanning the whole target; the DEM source then overwrites the
+    // covered region, leaving uncovered regions decoding as no-data.
+    expect(maps).toHaveLength(2);
+    const underlay = maps[0] as { image: { data: Uint8Array } };
+    expect(Array.from(underlay.image.data)).toEqual([1, 2, 3, 255]);
+    expect(maps[1]).toBe(src);
+    // The underlay is framed over the full target (identity camera window).
+    const cam = renderer.render.mock.calls[0][1] as {
+      left: number;
+      right: number;
+      bottom: number;
+      top: number;
+    };
+    expect([cam.left, cam.right, cam.bottom, cam.top]).toEqual([-1, 1, -1, 1]);
+    // Cleared once: underlay and source accumulate into the same target.
+    expect(renderer.clear).toHaveBeenCalledTimes(1);
+  });
+
+  it("draws sources coarse-first so finer tiles overwrite the ancestor", () => {
+    const { compositor, renderer } = setup();
+    const maps = trackDrawnMaps(renderer);
+    // A finer-than-terrain tile (uvScale > 1) and a coarse ancestor fallback
+    // (uvScale < 1) covering the whole rect, listed fine-first: the bake must
+    // reorder by ascending uvScale or the ancestor buries the finer tile.
+    const fine = fakeTex("fine");
+    const coarse = fakeTex("coarse");
+
+    compositor.renderRasterTiles(
+      [
+        {
+          isElevationHeatmap: false,
+          sources: [
+            { texture: fine as never, uvOffset: [0, 0], uvScale: [2, 2] },
+            {
+              texture: coarse as never,
+              uvOffset: [0, 0],
+              uvScale: [0.5, 0.5],
+            },
+          ],
+        },
+      ],
+      [fakeRT() as never],
+    );
+
+    expect(maps).toEqual([coarse, fine]);
+    expect(renderer.clear).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips a never-touched render target that has no slot (no GPU allocation)", () => {
+    const { compositor, renderer } = setup();
+
+    const rt = fakeRT();
+    compositor.renderRasterTiles([], [rt as never]);
+
+    // Render-targeting the RT would create its GL framebuffer; an empty slot
+    // whose target was never baked must not pay that cost (same invariant as
+    // the vector bake — both run through the shared bake loop).
+    expect(renderer.setRenderTarget).not.toHaveBeenCalledWith(rt);
+    expect(renderer.render).not.toHaveBeenCalled();
+    expect(renderer.clear).not.toHaveBeenCalled();
+  });
+});

package/src/tileTexture/TileTextureCompositor.ts

@@ -3,12 +3,18 @@ import {
   Color,
   DataTexture,
   GLSL3,
+  LinearFilter,
   Mesh,
+  MeshBasicMaterial,
+  NearestFilter,
+  NoBlending,
+  NoColorSpace,
   OrthographicCamera,
   PlaneGeometry,
   RGBAFormat,
   Scene,
   ShaderMaterial,
+  SRGBColorSpace,
   type Texture,
   UnsignedByteType,
   WebGLRenderTarget,
@@ -71,6 +77,10 @@ export const defaultAtlasFactory =
 export type TileTextureCompositorOptions = {
   renderer: WebGLRenderer;
   texturizedSceneByTileCoordinates: TexturizedSceneByTileCoordinates;
+  /** Rust's clamped WebMercator northing (`TileHandler.mercatorY`), handed to
+   * the core uniform mutates so the paste-side reprojection constants come
+   * from the same implementation as the Rust bake affine. */
+  mercatorY: (lat: number) => number;
   /** Atlas RT side length (defaults to 512). */
   size?: number;
   /** Test seam: replace MRT RT creation. */
@@ -89,6 +99,30 @@ type CachedMaterial = {
   placeholderTexture: Texture;
 };
 
+/** One WebMercator raster tile texture to bake into a layer's render target,
+ * framed by the Rust-resolved mercator affine (terrain `[0,1]` UV → source UV). */
+export type RasterBakeSource = {
+  texture: Texture;
+  uvOffset: [number, number];
+  uvScale: [number, number];
+};
+
+/** One baked raster layer: its overlapping WM tile textures, mosaicked into one
+ * render target. Heatmap layers carry encoded DEM, copied raw (nearest, no
+ * color conversion) so the composite decode stays valid. */
+export type RasterBakeSlot = {
+  isElevationHeatmap: boolean;
+  /**
+   * The decoder's no-data (boundary) color for heatmap slots: painted across
+   * the render target before the sources so uncovered regions decode as
+   * "no elevation" — the no-data story lives entirely in the encoded-elevation
+   * domain, keeping the alpha channel free for future RGBA encodings. Absent
+   * for color slots and for decoders with no byte-representable boundary.
+   */
+  noDataColor?: [number, number, number];
+  sources: RasterBakeSource[];
+};
+
 /**
  * Integration layer for per-tile texture composition.
  *
@@ -112,9 +146,11 @@ export class TileTextureCompositor {
    * per-tile GPU byte cost it reports to the memory ledger. */
   readonly size: number;
   private readonly texturizedScenes: TexturizedSceneByTileCoordinates;
-  // Single fixed [-1, 1] camera shared by every vector-scene bake. Ancestor
-  // fallback is resolved in Rust, so no per-tile camera transform is needed.
-  private readonly vectorCamera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+  private readonly mercatorY: (lat: number) => number;
+  // Single camera shared by every drape bake (vector and raster), re-framed
+  // per source by `frameBakeCamera`. Ancestor fallback is resolved in Rust,
+  // so no per-tile camera transform is needed.
+  private readonly bakeCamera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
 
   // Composite-pass machinery (lazily created on first use so tests that
   // don't render don't pay the allocation).
@@ -122,15 +158,43 @@ export class TileTextureCompositor {
   private readonly quadCamera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
   private readonly quadMesh: Mesh;
   private readonly materialCache = new Map<string, CachedMaterial>();
-  // Vector render targets this compositor has ever rendered to. three.js
+  // Drape render targets this compositor has ever rendered to. three.js
   // allocates a render target's GL framebuffer on first setRenderTarget, so
   // an empty slot whose target was never touched must be skipped entirely —
   // clearing it would allocate size² × 4 bytes of GPU memory for nothing.
-  private readonly touchedVectorTargets = new WeakSet<WebGLRenderTarget>();
+  private readonly touchedTargets = new WeakSet<WebGLRenderTarget>();
+
+  // Raster-bake machinery (lazily used): a textured quad drawn once per source
+  // through the same windowing camera as the vector bake. `toneMapped: false` +
+  // per-kind texture color spaces keep the bake a value-preserving copy.
+  //
+  // `transparent: true` + `blending: NoBlending` carries the source ALPHA into
+  // the render target: an opaque material (transparent=false + NormalBlending)
+  // gets three.js's `OPAQUE` define, whose shader forces `diffuseColor.a = 1.0`
+  // and destroys the tile's transparency. NoBlending keeps replace semantics —
+  // sources are disjoint WM tiles (plus a coarse-first ancestor underlay), so
+  // each draw must overwrite, not blend, and straight (r, g, b, a) texels land
+  // in the target for the composite's own alpha blend.
+  private readonly rasterBakeScene = new Scene();
+  private readonly rasterBakeMaterial = new MeshBasicMaterial({
+    toneMapped: false,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+    blending: NoBlending,
+  });
+  // 1×1 no-data underlay for baked heatmap targets, drawn through the same
+  // value-preserving bake pipeline as the sources — a texture upload is
+  // byte-exact, whereas a clear color would pass through the renderer's color
+  // management and could land one byte off (fatal for positional encodings,
+  // where the high byte weighs 65536 in decoded x). Cached per color.
+  private demNoDataTexture: DataTexture | null = null;
+  private demNoDataTextureKey = "";
 
   constructor(opts: TileTextureCompositorOptions) {
     this.renderer = opts.renderer;
     this.texturizedScenes = opts.texturizedSceneByTileCoordinates;
+    this.mercatorY = opts.mercatorY;
     this.size = opts.size ?? 512;
     this.cache = new TileTextureCache({
       size: this.size,
@@ -141,7 +205,15 @@ export class TileTextureCompositor {
     this.quadMesh = new Mesh(new PlaneGeometry(2, 2));
     this.quadScene.add(this.quadMesh);
     this.quadCamera.position.z = 1;
-    this.vectorCamera.position.z = 1;
+    this.bakeCamera.position.z = 1;
+
+    // Raster-bake quad: spans the source tile's NDC frame like a vector scene,
+    // so the same windowing camera math frames it. Shares the fullscreen quad
+    // geometry with `quadMesh` (both are static [-1, 1] planes; the windowing
+    // lives in the camera), so dispose() frees one geometry for both.
+    this.rasterBakeScene.add(
+      new Mesh(this.quadMesh.geometry, this.rasterBakeMaterial),
+    );
   }
 
   // ---------------------------------------------------------------------
@@ -204,7 +276,88 @@ export class TileTextureCompositor {
     }[],
     renderTargets: WebGLRenderTarget[],
   ): void {
-    const camera = this.vectorCamera;
+    this.bakeSlotTargets(slots, renderTargets, (slot) => {
+      for (const source of slot.sources) {
+        const scene = this.texturizedScenes.findSceneByLayerId(
+          source.tileHandle,
+          slot.layerId,
+        );
+        if (!scene || scene.removed || !scene.children.length) continue;
+        this.renderer.render(
+          scene,
+          this.frameBakeCamera(source.uvOffset, source.uvScale),
+        );
+      }
+    });
+  }
+
+  /**
+   * Bake each raster layer's overlapping WM tile textures into ONE render
+   * target (slot `i` → `renderTargets[i]`), mirroring {@link renderVectorScenes}:
+   * every source is a textured quad framed by the Rust-supplied mercator affine
+   * `uvOffset`/`uvScale`, so the render target ends up spanning the terrain
+   * tile's (Mercator-projected) extent and the composite treats the whole layer
+   * as one slot with the terrain-band reprojection — instead of one composite
+   * slot per overlapping tile, which overflowed the GPU slot budget on
+   * Geographic terrain once 3+ layers were draped.
+   *
+   * Sources are drawn coarse-first (ascending `uvScale`): an ancestor fallback
+   * covers the whole terrain rect, so painting it first lets the finer tiles
+   * overwrite it instead of being buried under coarse texels. The bake is a
+   * value-preserving copy (`toneMapped: false`; per-kind color spaces below), so
+   * heatmap DEM texels survive it bit-faithfully:
+   * - color imagery: source + target declared sRGB — decode at fetch, encode at
+   *   write, decode again at the composite fetch: the same linear values the
+   *   direct (non-baked) path produced.
+   * - elevation heatmap: everything `NoColorSpace` + nearest — raw texels, no
+   *   interpolation, so the composite's decode-then-interpolate keeps working.
+   */
+  renderRasterTiles(
+    slots: (RasterBakeSlot | undefined)[],
+    renderTargets: (WebGLRenderTarget | undefined)[],
+  ): void {
+    this.bakeSlotTargets(slots, renderTargets, (slot) => {
+      // Heatmap targets: paint the decoder's no-data color across the whole
+      // target first, so regions no source covers decode as "no elevation"
+      // (the composite renders them transparent) instead of decoding the
+      // cleared black as a height.
+      if (slot.isElevationHeatmap && slot.noDataColor) {
+        this.drawRasterBakeQuad(
+          this.demNoDataUnderlay(slot.noDataColor),
+          true,
+          [0, 0],
+          [1, 1],
+        );
+      }
+
+      // Coarse-first painter's order: a shared ancestor spans every finer
+      // source's rect, so it must not be drawn over them.
+      const sources = [...slot.sources].sort(
+        (a, b) => a.uvScale[0] - b.uvScale[0],
+      );
+      for (const source of sources) {
+        this.drawRasterBakeQuad(
+          source.texture,
+          slot.isElevationHeatmap,
+          source.uvOffset,
+          source.uvScale,
+        );
+      }
+    });
+  }
+
+  /**
+   * Shared bake loop over per-layer drape render targets (slot `i` →
+   * `renderTargets[i]`): saves/restores the renderer state, clears each live
+   * target once and lets `drawSlot` accumulate that slot's sources into it —
+   * autoClear stays off so the sources mosaic instead of overwriting one
+   * another.
+   */
+  private bakeSlotTargets<S>(
+    slots: readonly (S | undefined)[],
+    renderTargets: readonly (WebGLRenderTarget | undefined)[],
+    drawSlot: (slot: S) => void,
+  ): void {
     const prevTarget = this.renderer.getRenderTarget();
     const prevClear = this.renderer.getClearColor(PREV_CLEAR_COLOR);
     const prevClearAlpha = this.renderer.getClearAlpha();
@@ -220,35 +373,14 @@ export class TileTextureCompositor {
       // An empty slot only needs a clear when the target holds stale content
       // from a previous bake; a never-touched target has no GL storage yet
       // and must not be render-targeted (that would allocate it).
-      if (!slot && !this.touchedVectorTargets.has(renderTarget)) continue;
-      this.touchedVectorTargets.add(renderTarget);
+      if (!slot && !this.touchedTargets.has(renderTarget)) continue;
+      this.touchedTargets.add(renderTarget);
 
       this.renderer.setRenderTarget(renderTarget);
       this.renderer.setClearColor(0x000, 0);
       this.renderer.clear();
 
-      if (slot) {
-        for (const source of slot.sources) {
-          const scene = this.texturizedScenes.findSceneByLayerId(
-            source.tileHandle,
-            slot.layerId,
-          );
-          if (!scene || scene.removed || !scene.children.length) continue;
-          // Frame the terrain tile's sub-rect of this source tile from the
-          // mercator uvOffset/uvScale: meshUv ∈ [0,1] → vectorUv = uvOffset +
-          // meshUv·uvScale, source scene NDC = 2·vectorUv − 1. A source finer than
-          // the terrain tile yields a camera wider than [-1, 1], so it draws into
-          // only its sub-rect and leaves the rest of the RT transparent.
-          const [ox, oy] = source.uvOffset;
-          const [sx, sy] = source.uvScale;
-          camera.left = 2 * ox - 1;
-          camera.right = 2 * (ox + sx) - 1;
-          camera.bottom = 2 * oy - 1;
-          camera.top = 2 * (oy + sy) - 1;
-          camera.updateProjectionMatrix();
-          this.renderer.render(scene, camera);
-        }
-      }
+      if (slot) drawSlot(slot);
 
       renderTarget.texture.needsUpdate = true;
     }
@@ -258,6 +390,86 @@ export class TileTextureCompositor {
     this.renderer.setClearColor(prevClear, prevClearAlpha);
   }
 
+  /**
+   * Frame the shared bake camera on the terrain tile's sub-rect of a source
+   * from the mercator affine: meshUv ∈ [0,1] → sourceUv = uvOffset +
+   * meshUv·uvScale, source NDC = 2·sourceUv − 1. A source finer than the
+   * terrain tile yields a camera wider than [-1, 1], so it draws into only
+   * its sub-rect and leaves the rest of the render target transparent.
+   */
+  private frameBakeCamera(
+    uvOffset: [number, number],
+    uvScale: [number, number],
+  ): OrthographicCamera {
+    const [ox, oy] = uvOffset;
+    const [sx, sy] = uvScale;
+    const camera = this.bakeCamera;
+    camera.left = 2 * ox - 1;
+    camera.right = 2 * (ox + sx) - 1;
+    camera.bottom = 2 * oy - 1;
+    camera.top = 2 * (oy + sy) - 1;
+    camera.updateProjectionMatrix();
+    return camera;
+  }
+
+  /** Draw one textured quad into the current render target through the bake
+   * camera window — the value-preserving copy described on
+   * {@link renderRasterTiles}. */
+  private drawRasterBakeQuad(
+    texture: Texture,
+    isElevationHeatmap: boolean,
+    uvOffset: [number, number],
+    uvScale: [number, number],
+  ): void {
+    const material = this.rasterBakeMaterial;
+    this.configureRasterBakeSource(texture, isElevationHeatmap);
+    // First map assignment flips USE_MAP; later swaps are uniform-only.
+    if (material.map === null) material.needsUpdate = true;
+    material.map = texture;
+    this.renderer.render(
+      this.rasterBakeScene,
+      this.frameBakeCamera(uvOffset, uvScale),
+    );
+  }
+
+  /** The cached 1×1 no-data texture, (re)created when the color changes. */
+  private demNoDataUnderlay(color: [number, number, number]): DataTexture {
+    const key = color.join(",");
+    if (!this.demNoDataTexture || this.demNoDataTextureKey !== key) {
+      this.demNoDataTexture?.dispose();
+      const texture = new DataTexture(
+        new Uint8Array([...color, 255]),
+        1,
+        1,
+        RGBAFormat,
+        UnsignedByteType,
+      );
+      texture.needsUpdate = true;
+      this.demNoDataTexture = texture;
+      this.demNoDataTextureKey = key;
+    }
+    return this.demNoDataTexture;
+  }
+
+  /** Value-preserving sampler settings for a bake source texture (see
+   * {@link renderRasterTiles}); idempotent so re-bakes don't re-upload. */
+  private configureRasterBakeSource(tex: Texture, isElevationHeatmap: boolean) {
+    const colorSpace = isElevationHeatmap ? NoColorSpace : SRGBColorSpace;
+    const filter = isElevationHeatmap ? NearestFilter : LinearFilter;
+    if (
+      tex.colorSpace !== colorSpace ||
+      tex.minFilter !== filter ||
+      tex.magFilter !== filter ||
+      tex.generateMipmaps
+    ) {
+      tex.colorSpace = colorSpace;
+      tex.minFilter = filter;
+      tex.magFilter = filter;
+      tex.generateMipmaps = false;
+      tex.needsUpdate = true;
+    }
+  }
+
   // ---------------------------------------------------------------------
   // MRT composite pass
   // ---------------------------------------------------------------------
@@ -354,7 +566,7 @@ export class TileTextureCompositor {
     // uniform ownership: each active enhancer attaches its own uniform refs and
     // contributes the matching GLSL, so a new expression touches only its module.
     const chain = createCompositeLayerEnhancers(features);
-    const core = createCoreUniformMutates();
+    const core = createCoreUniformMutates(this.mercatorY);
 
     const uniforms: CompositeUniformTarget = {};
     core.attachUniforms(uniforms, numTextures, placeholderTexture);
@@ -416,6 +628,10 @@ export class TileTextureCompositor {
       m.placeholderTexture.dispose();
     }
     this.materialCache.clear();
+    // Also frees the raster-bake quad, which shares this geometry.
     this.quadMesh.geometry.dispose();
+    this.rasterBakeMaterial.dispose();
+    this.demNoDataTexture?.dispose();
+    this.demNoDataTexture = null;
   }
 }

package/src/tileTexture/__snapshots__/CompositeShader.snapshot.test.ts.snap

@@ -234,7 +234,13 @@ float interpolateDEMHeights(float h00, float h10, float h01, float h11, vec2 fra
 
   
   
-  float sampleElevationBilinear(sampler2D demTexture, vec2 uv, ivec2 texSize) {
+  
+  
+  
+  
+  
+  
+  float sampleElevationBilinear(sampler2D demTexture, vec2 uv, ivec2 texSize, out bool valid) {
     
     DEMBilinearData data = prepareDEMBilinear(texSize, uv);
 
@@ -251,7 +257,8 @@ float interpolateDEMHeights(float h00, float h10, float h01, float h11, vec2 fra
       h = interpolateDEMHeights(h00, h10, h01, h11, data.frac);
     }
 
-    if (!isValidHeight(h)) {
+    valid = isValidHeight(h);
+    if (!valid) {
       return 0.0;
     }
 
@@ -329,8 +336,9 @@ void main() {
     vec4 texColor0;
     if (uIsElevationHeatmaps[0]) {
       ivec2 demTexSize = textureSize(uTextures[0], 0);
-      float normalized_h = sampleElevationBilinear(uTextures[0], texUv0, demTexSize);
-      texColor0 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+      bool demValid0;
+      float normalized_h = sampleElevationBilinear(uTextures[0], texUv0, demTexSize, demValid0);
+      texColor0 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, demValid0 ? 1.0 : 0.0);
     } else {
       texColor0 = texture2D(uTextures[0], texUv0) * vec4(uColors[0], 1.0);
     }
@@ -397,8 +405,9 @@ void main() {
     vec4 texColor1;
     if (uIsElevationHeatmaps[1]) {
       ivec2 demTexSize = textureSize(uTextures[1], 0);
-      float normalized_h = sampleElevationBilinear(uTextures[1], texUv1, demTexSize);
-      texColor1 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+      bool demValid1;
+      float normalized_h = sampleElevationBilinear(uTextures[1], texUv1, demTexSize, demValid1);
+      texColor1 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, demValid1 ? 1.0 : 0.0);
     } else {
       texColor1 = texture2D(uTextures[1], texUv1) * vec4(uColors[1], 1.0);
     }
@@ -465,8 +474,9 @@ void main() {
     vec4 texColor2;
     if (uIsElevationHeatmaps[2]) {
       ivec2 demTexSize = textureSize(uTextures[2], 0);
-      float normalized_h = sampleElevationBilinear(uTextures[2], texUv2, demTexSize);
-      texColor2 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+      bool demValid2;
+      float normalized_h = sampleElevationBilinear(uTextures[2], texUv2, demTexSize, demValid2);
+      texColor2 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, demValid2 ? 1.0 : 0.0);
     } else {
       texColor2 = texture2D(uTextures[2], texUv2) * vec4(uColors[2], 1.0);
     }
@@ -533,8 +543,9 @@ void main() {
     vec4 texColor3;
     if (uIsElevationHeatmaps[3]) {
       ivec2 demTexSize = textureSize(uTextures[3], 0);
-      float normalized_h = sampleElevationBilinear(uTextures[3], texUv3, demTexSize);
-      texColor3 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+      bool demValid3;
+      float normalized_h = sampleElevationBilinear(uTextures[3], texUv3, demTexSize, demValid3);
+      texColor3 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, demValid3 ? 1.0 : 0.0);
     } else {
       texColor3 = texture2D(uTextures[3], texUv3) * vec4(uColors[3], 1.0);
     }
@@ -857,7 +868,13 @@ float interpolateDEMHeights(float h00, float h10, float h01, float h11, vec2 fra
 
   
   
-  float sampleElevationBilinear(sampler2D demTexture, vec2 uv, ivec2 texSize) {
+  
+  
+  
+  
+  
+  
+  float sampleElevationBilinear(sampler2D demTexture, vec2 uv, ivec2 texSize, out bool valid) {
     
     DEMBilinearData data = prepareDEMBilinear(texSize, uv);
 
@@ -874,7 +891,8 @@ float interpolateDEMHeights(float h00, float h10, float h01, float h11, vec2 fra
       h = interpolateDEMHeights(h00, h10, h01, h11, data.frac);
     }
 
-    if (!isValidHeight(h)) {
+    valid = isValidHeight(h);
+    if (!valid) {
       return 0.0;
     }
 
@@ -952,8 +970,9 @@ void main() {
     vec4 texColor0;
     if (uIsElevationHeatmaps[0]) {
       ivec2 demTexSize = textureSize(uTextures[0], 0);
-      float normalized_h = sampleElevationBilinear(uTextures[0], texUv0, demTexSize);
-      texColor0 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+      bool demValid0;
+      float normalized_h = sampleElevationBilinear(uTextures[0], texUv0, demTexSize, demValid0);
+      texColor0 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, demValid0 ? 1.0 : 0.0);
     } else {
       texColor0 = texture2D(uTextures[0], texUv0) * vec4(uColors[0], 1.0);
     }
@@ -1016,8 +1035,9 @@ void main() {
     vec4 texColor1;
     if (uIsElevationHeatmaps[1]) {
       ivec2 demTexSize = textureSize(uTextures[1], 0);
-      float normalized_h = sampleElevationBilinear(uTextures[1], texUv1, demTexSize);
-      texColor1 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+      bool demValid1;
+      float normalized_h = sampleElevationBilinear(uTextures[1], texUv1, demTexSize, demValid1);
+      texColor1 = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, demValid1 ? 1.0 : 0.0);
     } else {
       texColor1 = texture2D(uTextures[1], texUv1) * vec4(uColors[1], 1.0);
     }

package/src/tileTexture/types.ts

@@ -16,6 +16,7 @@ export type DirtyReason =
   | "material"
   | "texture-binding"
   | "vector-revision"
+  | "raster-revision"
   | "hillshade";
 
 /**
@@ -121,6 +122,12 @@ export type HillshadeCompositeLayer = CompositeLayerBase & {
 export type ElevationHeatmapCompositeLayer = CompositeLayerBase & {
   kind: "elevationHeatmap";
   opacity: number;
+  /**
+   * Same Mercator latitude reprojection band as {@link RasterCompositeLayer}:
+   * the heatmap decode samples the reprojected per-slot UV, so a DEM draped on
+   * Geographic terrain (baked or direct) remaps identically to color imagery.
+   */
+  reproject?: [number, number];
 };
 
 export type CompositeLayer =

package/src/utils/demNoDataColor.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { demNoDataColorBytes } from "./demNoDataColor";
+
+describe("demNoDataColorBytes", () => {
+  it("solves the Japan GSI boundary (2^23) to (128, 0, 0)", () => {
+    expect(demNoDataColorBytes({ x: 65536, y: 256, z: 1 }, 8388608)).toEqual([
+      128, 0, 0,
+    ]);
+  });
+
+  it("solves the Mapbox boundary (10000) to (0, 39, 16)", () => {
+    expect(demNoDataColorBytes({ x: 65536, y: 256, z: 1 }, 10000)).toEqual([
+      0, 39, 16,
+    ]);
+  });
+
+  it("solves the Terrarium boundary (0) to black", () => {
+    expect(demNoDataColorBytes({ x: 256, y: 1, z: 1 / 256 }, 0)).toEqual([
+      0, 0, 0,
+    ]);
+  });
+
+  it("keeps channel order independent of scaler magnitude order", () => {
+    // Same positional system with permuted channels: G is the coarse digit.
+    expect(demNoDataColorBytes({ x: 256, y: 65536, z: 1 }, 8388608)).toEqual([
+      0, 128, 0,
+    ]);
+  });
+
+  it("accepts a non-exact color inside the shader's no-data band", () => {
+    // 0.75 has no exact byte decomposition with unit scalers, but black
+    // decodes to 0 and |0 - 0.75| <= 1, so the shader still flags it no-data.
+    expect(demNoDataColorBytes({ x: 1, y: 1, z: 1 }, 0.75)).toEqual([0, 0, 0]);
+    // Band edge: the closest representable value is exactly 1 away
+    // ((1,0,0) decodes to 2, |2 - 3| == 1), which the shader's
+    // `abs(x - boundary) <= 1` check still classifies as no-data.
+    expect(demNoDataColorBytes({ x: 2, y: 0, z: 0 }, 3)).toEqual([1, 0, 0]);
+  });
+
+  it("returns null when no byte color decodes inside the no-data band", () => {
+    // Boundary beyond the encodable range (max dot product is 765).
+    expect(demNoDataColorBytes({ x: 1, y: 1, z: 1 }, 100000)).toBeNull();
+    // Coarse scalers leave the nearest representable value a full step away.
+    expect(demNoDataColorBytes({ x: 4, y: 0, z: 0 }, 6)).toBeNull();
+  });
+});