Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
feat(layers): add 3D density surface display to heatmaps (#3957)
Igor Dykhta02054d98e445
diff --git a/docs/user-guides/c-types-of-layers/i-heatmap.md b/docs/user-guides/c-types-of-layers/i-heatmap.mdindex 91d20c191..855d68330 100644--- a/docs/user-guides/c-types-of-layers/i-heatmap.md+++ b/docs/user-guides/c-types-of-layers/i-heatmap.md@@ -4,4 +4,17 @@Heatmap layers describe the intensity of data at geographical points through a colored overlap. The intensity can be weighted by a numerical field.+## 3D Surface++Turn on the toggle in the **3D Surface** group at the end of the heatmap settings, then tilt the map to see density as a continuous raised surface. The toggle is off by default, keeping the map in 2D. All surface options are in the collapsible group; click its header to expand or collapse them.++The surface uses the same data, weights, aggregation, radius, color range, intensity, and filters as the flat heatmap. Height represents density, not terrain elevation. The surface grid matches the allocated density texture resolution: normally 512 × 512 cells (513 × 513 vertices).++- **Maximum height (m)** sets the height limit in meters (default 1,000). Density is normalized against the maximum in the current heatmap texture, so other peaks are proportional. Intensity affects colors and opacity only. Zooming can reshape peaks as density is recomputed, but does not change the height limit.+- **Surface shading** uses scene lighting to make slopes easier to see. With **Light & Shadow** enabled, the surface responds to the sun and ambient-light settings and casts and receives shadows.+- **Surface contours** overlays lines at regular density intervals, independent of intensity.+- **Contour step** appears when contours are enabled and controls the density interval between lines, from 0.01 to 100 (default 0.1). Smaller steps show more lines; larger steps reduce clutter when zoomed out. The slider keeps fine control over intervals from 0.01 to 1.++Surface settings are saved with the map and retained when switching back to Flat. Surface mode works on both the flat map and globe.+[Back to table of contents](../README.md)diff --git a/src/components/src/side-panel/layer-panel/layer-configurator.tsx b/src/components/src/side-panel/layer-panel/layer-configurator.tsxindex f4777c7bd..0d01df7e4 100644--- a/src/components/src/side-panel/layer-panel/layer-configurator.tsx+++ b/src/components/src/side-panel/layer-panel/layer-configurator.tsx@@ -759,6 +759,33 @@ export default function LayerConfiguratorFactory(/></SidePanelSection></LayerConfigGroup>+ {/* 3D Surface */}+ <LayerConfigGroup+ {...layer.visConfigSettings.surfaceEnabled}+ {...visConfiguratorProps}+ collapsible+ >+ <ConfigGroupCollapsibleContent>+ <VisConfigSlider+ {...layer.visConfigSettings.surfaceHeight}+ {...visConfiguratorProps}+ />+ <VisConfigSwitch+ {...layer.visConfigSettings.surfaceLighting}+ {...visConfiguratorProps}+ />+ <VisConfigSwitch+ {...layer.visConfigSettings.surfaceContours}+ {...visConfiguratorProps}+ />+ {visConfig.surfaceContours ? (+ <VisConfigSlider+ {...layer.visConfigSettings.surfaceContourStep}+ {...visConfiguratorProps}+ />+ ) : null}+ </ConfigGroupCollapsibleContent>+ </LayerConfigGroup></StyledLayerVisualConfigurator>);}diff --git a/src/deckgl-types.d.ts b/src/deckgl-types.d.tsindex 7dc51aa56..b656342e9 100644--- a/src/deckgl-types.d.ts+++ b/src/deckgl-types.d.ts@@ -28,7 +28,14 @@ declare module '@deck.gl/core' {export {AmbientLight} from '@deck.gl/core/dist/effects/lighting/ambient-light';export {default as _SunLight} from '@deck.gl/core/dist/effects/lighting/sun-light';export {COORDINATE_SYSTEM, OPERATION, UNIT} from '@deck.gl/core/dist/lib/constants';- export {color, picking, project, project32, shadow} from '@deck.gl/core/dist/shaderlib/index';+ export {+ color,+ picking,+ project,+ project32,+ phongMaterial,+ shadow+ } from '@deck.gl/core/dist/shaderlib/index';export {default as Attribute} from '@deck.gl/core/dist/lib/attribute/attribute';export {default as AttributeManager} from '@deck.gl/core/dist/lib/attribute/attribute-manager';export {default as Tesselator} from '@deck.gl/core/dist/utils/tesselator';diff --git a/src/layers/src/heatmap-layer/deck-heatmap-layer.ts b/src/layers/src/heatmap-layer/deck-heatmap-layer.tsindex fc568abcd..b4d599bf7 100644--- a/src/layers/src/heatmap-layer/deck-heatmap-layer.ts+++ b/src/layers/src/heatmap-layer/deck-heatmap-layer.ts@@ -2,9 +2,16 @@// Copyright contributors to the kepler.gl projectimport {HeatmapLayer as DeckGLHeatmapLayer} from '@deck.gl/aggregation-layers';-import {Layer, WebMercatorViewport, project32, COORDINATE_SYSTEM} from '@deck.gl/core';+import {+ Layer,+ WebMercatorViewport,+ project32,+ phongMaterial,+ COORDINATE_SYSTEM+} from '@deck.gl/core';import {Model} from '@luma.gl/engine';import {editShader, insertBefore} from '@kepler.gl/deckgl-layers';+import {createHeatmapSurfaceMesh} from './density-surface-mesh';/*** Custom deck.gl HeatmapLayer subclass that patches GPU shaders@@ -97,30 +104,36 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {...DeckGLHeatmapLayer.defaultProps,// kepler.gl extensions to support globe modeglobeMode: false,+ surface: false,+ surfaceHeight: 1000,+ surfaceLighting: true,+ surfaceContours: false,+ surfaceContourStep: 0.1,// [minLng, minLat, maxLng, maxLat] of the data, used to frame the density texture in globe modedensityBounds: null};- // Cached fixed density viewport (keyed by bounds) so we don't rebuild it on- // every update/render. Not stored in layer state to avoid setState-in-render.+ // Viewports can be rebuilt from persistent density bounds on replacement+ // instances. Cache them locally to avoid rebuilding within an update/render.private _densityViewport: WebMercatorViewport | null = null;private _densityViewportKey: string | null = null;+ private _referenceViewport: WebMercatorViewport | null = null;+ private _referenceViewportKey: string | null = null;// Cached globe render mesh, so its identity stays stable across frames (only// rebuilt when the density bounds or the globe resolution change).private _globeMesh: HeatmapMesh | null = null;private _globeMeshKey: string | null = null;-- // World bounds [w, s, e, n] the density texture is currently framed to. In- // globe mode this is normally the data bounds, but when the camera is zoomed- // in far enough that the visible area sits fully inside the data, we frame the- // density texture around the *visible* area to improve level-of-detail.- private _densityBounds: [number, number, number, number] | null = null;- // Quantized key of `_densityBounds`, so small camera moves don't re-frame.- private _densityBoundsFrameKey: string | null = null;- // Cached reference viewport framing the full data bounds (for radius scaling).- private _referenceViewport: WebMercatorViewport | null = null;- private _referenceViewportKey: string | null = null;+ // deck.gl transfers state between replacement instances. Preserve density+ // framing, mode transitions, and the expensive surface mesh across updates.+ // Mesh cache writes are direct to avoid scheduling an update while rendering.+ declare state: DeckGLHeatmapLayer['state'] & {+ surfaceMeshCache?: {key: string; mesh: HeatmapMesh | null};+ // Bounds follow the visible area when zoomed inside the data extent.+ densityBounds?: [number, number, number, number] | null;+ densityBoundsFrameKey?: string | null;+ wasGlobeHeatmap?: boolean;+ };_createWeightsTransform(shaders: any) {if (shaders.fs?.includes('gaussianKDE')) {@@ -150,12 +163,13 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {const result = super.getShaders(shaders);if (result.fs?.includes('outTexture.r / max(1.0, outTexture.a)')) {- // Max-weights fragment shader: force max value to 1.0+ // Preserve the SUM maximum in blue for surface heights. Red and green+ // retain the existing SUM and MEAN color normalization for both modes.result.fs = insertBefore(result.fs,'fs','fragColor.g = outTexture.r / max(1.0, outTexture.a);',- 'fragColor.r = 1.0;\n '+ 'fragColor.b = outTexture.r;\n fragColor.r = 1.0;\n ');if (result.modules) {result.modules = result.modules.filter((m: any) => (m?.name || m) !== 'layer');@@ -308,15 +322,15 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {}/**- * Build (and cache) the WebMercator viewport that frames `_densityBounds`.+ * Build (and cache) the WebMercator viewport that frames the density bounds.** This viewport is completely independent of the current globe camera* *projection* — it is always a plain WebMercator frame — but the region it- * covers (`_densityBounds`) follows the camera for level-of-detail (see+ * covers follows the camera for level-of-detail (see* `_computeDensityBounds`). It drives the offscreen density texture render.*/_getDensityViewport(): WebMercatorViewport | null {- const bounds = this._densityBounds || (this.props as any).densityBounds;+ const bounds = this.state.densityBounds || (this.props as any).densityBounds;if (!bounds || bounds.length !== 4) {return null;}@@ -391,10 +405,6 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {return [q(w, stepX), q(s, stepY), q(e, stepX), q(n, stepY)].map(v => v.toFixed(4)).join(',');}- // Tracks whether the previous update ran in globe mode, so we can detect the- // globe→2D (and 2D→globe) transition and reset stale density framing state.- private _wasGlobeHeatmap = false;-updateState(opts: any) {const {globeMode, densityBounds} = this.props as any;@@ -408,11 +418,11 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {// in the wrong place (and stays wrong while panning). Clear the cached// framing + our globe caches so the 2D path rebuilds from scratch.const isGlobeNow = Boolean(globeMode && densityBounds);- const leftGlobe = this._wasGlobeHeatmap && !isGlobeNow;+ const leftGlobe = this.state.wasGlobeHeatmap && !isGlobeNow;if (leftGlobe) {this._resetGlobeState();}- this._wasGlobeHeatmap = isGlobeNow;+ this.state.wasGlobeHeatmap = isGlobeNow;if (!globeMode || !densityBounds) {super.updateState(opts);@@ -441,9 +451,9 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {const nextBounds = this._computeDensityBounds(globeViewport);if (nextBounds) {const nextKey = this._densityBoundsKey(nextBounds);- if (nextKey !== this._densityBoundsFrameKey) {- this._densityBounds = nextBounds;- this._densityBoundsFrameKey = nextKey;+ if (nextKey !== this.state.densityBoundsFrameKey) {+ this.state.densityBounds = nextBounds;+ this.state.densityBoundsFrameKey = nextKey;// Invalidate the cached mercator viewport so it is rebuilt for the new// frame, and force the base layer to recompute its density bounds +// regenerate the weightmap (it would otherwise keep the old, coarser@@ -451,6 +461,9 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {this._densityViewport = null;this._densityViewportKey = null;(this.state as any).worldBounds = null;+ // A display-only update can arrive without a viewport change. Once+ // bounds are cleared, deck.gl must rebuild them before rendering.+ opts = {...opts, changeFlags: {...opts.changeFlags, viewportChanged: true}};}}@@ -518,8 +531,8 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {_resetGlobeState() {this._densityViewport = null;this._densityViewportKey = null;- this._densityBounds = null;- this._densityBoundsFrameKey = null;+ this.state.densityBounds = null;+ this.state.densityBoundsFrameKey = null;this._referenceViewport = null;this._referenceViewportKey = null;this._globeMesh = null;@@ -699,7 +712,11 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {}renderLayers(): any {- if (!this._isGlobeHeatmap()) {+ const globe = this._isGlobeHeatmap();+ const {surface, surfaceHeight, surfaceLighting, surfaceContours, surfaceContourStep} = this+ .props as any;+ if (!globe && !surface) {+ this.state.surfaceMeshCache = undefined;return super.renderLayers();}@@ -709,7 +726,8 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {colorTexture,colorDomain,worldBounds,- normalizedCommonBounds+ normalizedCommonBounds,+ textureSize} = this.state as any;const {updateTriggers, intensity, threshold, aggregation} = this.props as any;@@ -723,7 +741,7 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {return null;}- const densityViewport = this._getDensityViewport();+ const densityViewport = globe ? this._getDensityViewport() : this.context.viewport;if (!densityViewport) {return null;}@@ -738,16 +756,48 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {// non-linear Web Mercator latitude mapping of the density texture.const resolution = this.context.viewport.resolution;const meshKey = `${worldBounds.join(',')}|${resolution}`;- if (this._globeMeshKey !== meshKey || !this._globeMesh) {- this._globeMesh = createGlobeHeatmapMesh(- worldBounds as [number, number, number, number],- normalizedCommonBounds as [number, number, number, number],- densityViewport,- resolution- );- this._globeMeshKey = meshKey;+ let mesh: HeatmapMesh | null;+ if (surface) {+ const longitude = globe+ ? undefined+ : (this.context.viewport as WebMercatorViewport).longitude;+ const worldCopy =+ typeof longitude === 'number' && Number.isFinite(longitude)+ ? Math.round((longitude - (worldBounds[0] + worldBounds[2]) / 2) / 360)+ : 0;+ const surfaceKey = `${meshKey}|${normalizedCommonBounds.join(+ ','+ )}|${worldCopy}|${textureSize}`;+ if (this.state.surfaceMeshCache?.key !== surfaceKey) {+ this.state.surfaceMeshCache = {+ key: surfaceKey,+ mesh: createHeatmapSurfaceMesh(+ worldBounds,+ normalizedCommonBounds,+ densityViewport as WebMercatorViewport,+ textureSize,+ longitude+ )+ };+ }+ mesh = this.state.surfaceMeshCache.mesh;+ } else {+ // Release the denser surface grid when returning to a flat globe heatmap.+ this.state.surfaceMeshCache = undefined;+ if (this._globeMeshKey !== meshKey || !this._globeMesh) {+ this._globeMesh = createGlobeHeatmapMesh(+ worldBounds as [number, number, number, number],+ normalizedCommonBounds as [number, number, number, number],+ densityViewport as WebMercatorViewport,+ resolution+ );+ this._globeMeshKey = meshKey;+ }+ mesh = this._globeMesh;+ }+ if (!mesh) {+ return null;}- const mesh = this._globeMesh;const GlobeTriangleLayerClass = this.getSubLayerClass('globe-triangle',@@ -756,7 +806,7 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {return new GlobeTriangleLayerClass(this.getSubLayerProps({- id: 'globe-triangle-layer',+ id: surface ? 'density-surface-layer' : 'globe-triangle-layer',updateTriggers}),{@@ -769,7 +819,21 @@ export default class KeplerHeatmapLayer extends DeckGLHeatmapLayer {weightsTexture,intensity,threshold,- colorDomain+ colorDomain,+ surfaceHeight: surface ? surfaceHeight : 0,+ surfaceLighting: surface && surfaceLighting,+ shadowEnabled: Boolean(surface && surfaceLighting),+ surfaceContours: surface && surfaceContours,+ surfaceContourStep,+ ...(surface+ ? {+ parameters: {+ ...this.props.parameters,+ depthWriteEnabled: true,+ depthCompare: 'less-equal'+ }+ }+ : {})});}@@ -887,14 +951,17 @@ const globeTriangleVs = `\#version 300 es#define SHADER_NAME globe-heatmap-triangle-layer-vertex-shaderuniform sampler2D maxTexture;+uniform sampler2D weightsTexture;in vec3 positions;in vec3 positions64Low;in vec2 texCoords;out vec2 vTexCoords;out float vIntensityMin;out float vIntensityMax;+out vec3 vCommonPosition;+out vec3 vCameraPosition;+out float vDensity;void main(void) {- gl_Position = project_position_to_clipspace(positions, positions64Low, vec3(0.0));vTexCoords = texCoords;vec4 maxTexture = texture(maxTexture, vec2(0.5));float maxValue = triangle.aggregationMode < 0.5 ? maxTexture.r : maxTexture.g;@@ -903,8 +970,33 @@ void main(void) {maxValue = triangle.colorDomain[1];minValue = triangle.colorDomain[0];}- vIntensityMax = triangle.intensity / maxValue;- vIntensityMin = triangle.intensity / minValue;+ vIntensityMax = maxValue > 0.0 ? triangle.intensity / maxValue : 0.0;+ vIntensityMin = minValue > 0.0 ? triangle.intensity / minValue : 0.0;+ vec4 weights = texture(weightsTexture, texCoords);+ float weight = weights.r;+ if (triangle.aggregationMode > 0.5) {+ weight /= max(1.0, weights.a);+ }+ // Contours use density units, independent of color intensity and domain.+ vDensity = max(0.0, weight);+ if (isnan(vDensity) || isinf(vDensity)) {+ vDensity = 0.0;+ }+ // Normalize against the actual density maximum, not the color scale.+ float maxDensity = triangle.aggregationMode < 0.5 ? maxTexture.b : maxTexture.g;+ float height = maxDensity > 0.0+ ? clamp(vDensity / maxDensity, 0.0, 1.0) * triangle.surfaceHeight+ : 0.0;+ vec3 position = positions;+ position.z += height;+ geometry.worldPosition = position;+ geometry.uv = texCoords;+ gl_Position = project_position_to_clipspace(position, positions64Low, vec3(0.0), geometry.position);+ vCommonPosition = geometry.position.xyz;+ vCameraPosition = project.cameraPosition;+ if (triangle.surfaceLighting > 0.5) {+ DECKGL_FILTER_GL_POSITION(gl_Position, geometry);+ }}`;@@ -917,11 +1009,18 @@ uniform sampler2D colorTexture;in vec2 vTexCoords;in float vIntensityMin;in float vIntensityMax;+in vec3 vCommonPosition;+in vec3 vCameraPosition;+in float vDensity;out vec4 fragColor;vec4 getLinearColor(float value) {float factor = clamp(value * vIntensityMax, 0., 1.);vec4 color = texture(colorTexture, vec2(factor, 0.5));- color.a *= min(value * vIntensityMin, 1.0);+ // A zero threshold gives every positive density full opacity, unless+ // intensity is zero. Avoid division by zero without flooring valid minima.+ color.a *= vIntensityMin > 0.0+ ? min(value * vIntensityMin, 1.0)+ : (triangle.intensity > 0.0 ? 1.0 : 0.0);return color;}void main(void) {@@ -935,7 +1034,26 @@ void main(void) {}vec4 linearColor = getLinearColor(weight);linearColor.a *= layer.opacity;+ if (triangle.surfaceLighting > 0.5) {+ vec3 normal = cross(dFdx(vCommonPosition), dFdy(vCommonPosition));+ float normalLength = length(normal);+ normal = normalLength > 0.0 ? normal / normalLength : vec3(0.0, 0.0, 1.0);+ normal = gl_FrontFacing ? normal : -normal;+ linearColor.rgb = lighting_getLightColor(+ linearColor.rgb, vCameraPosition, vCommonPosition, normal+ );+ }+ if (triangle.surfaceContours > 0.5) {+ float level = vDensity / max(triangle.surfaceContourStep, 0.0001);+ float distanceToLine = abs(fract(level + 0.5) - 0.5);+ float line = 1.0 - smoothstep(0.5, 1.5, distanceToLine / max(fwidth(level), 0.0001));+ linearColor.rgb = mix(linearColor.rgb, vec3(1.0), line * 0.35);+ }fragColor = linearColor;+ if (triangle.surfaceLighting > 0.5) {+ geometry.uv = vTexCoords;+ DECKGL_FILTER_COLOR(fragColor, geometry);+ }}`;@@ -945,6 +1063,10 @@ layout(std140) uniform triangleUniforms {vec2 colorDomain;float intensity;float threshold;+ float surfaceHeight;+ float surfaceLighting;+ float surfaceContours;+ float surfaceContourStep;} triangle;`;@@ -956,7 +1078,11 @@ const globeTriangleUniforms = {aggregationMode: 'f32',colorDomain: 'vec2<f32>',intensity: 'f32',- threshold: 'f32'+ threshold: 'f32',+ surfaceHeight: 'f32',+ surfaceLighting: 'f32',+ surfaceContours: 'f32',+ surfaceContourStep: 'f32'}} as any;@@ -981,7 +1107,7 @@ class GlobeHeatmapTriangleLayer extends Layer<any> {return super.getShaders({vs: globeTriangleVs,fs: globeTriangleFs,- modules: [project32, globeTriangleUniforms]+ modules: [project32, phongMaterial, globeTriangleUniforms]});}@@ -1049,7 +1175,8 @@ class GlobeHeatmapTriangleLayer extends Layer<any> {id: this.props.id,bufferLayout: this.getAttributeManager()?.getBufferLayouts(),topology: 'triangle-list',- isInstanced: false+ isInstanced: false,+ vertexCount: this.props.mesh?.vertexCount || 0});}@@ -1062,7 +1189,11 @@ class GlobeHeatmapTriangleLayer extends Layer<any> {threshold,colorTexture,maxTexture,- weightsTexture+ weightsTexture,+ surfaceHeight,+ surfaceLighting,+ surfaceContours,+ surfaceContourStep} = this.props;if (!model || !weightsTexture || !colorTexture || !maxTexture) {return;@@ -1073,6 +1204,10 @@ class GlobeHeatmapTriangleLayer extends Layer<any> {colorDomain,intensity,threshold,+ surfaceHeight: surfaceHeight || 0,+ surfaceLighting: surfaceLighting ? 1 : 0,+ surfaceContours: surfaceContours ? 1 : 0,+ surfaceContourStep,// Textures are not declared in `uniformTypes`, so they are treated as// bindings and bound to the matching sampler uniforms by name.colorTexture,diff --git a/src/layers/src/heatmap-layer/density-surface-mesh.ts b/src/layers/src/heatmap-layer/density-surface-mesh.tsnew file mode 100644index 000000000..d57feec7e--- /dev/null+++ b/src/layers/src/heatmap-layer/density-surface-mesh.ts@@ -0,0 +1,72 @@+// SPDX-License-Identifier: MIT+// Copyright contributors to the kepler.gl project++import type {WebMercatorViewport} from '@deck.gl/core';++type Bounds = [number, number, number, number];++/** A bounded, uniformly sampled density texture grid. Heights stay on the GPU. */+export function createHeatmapSurfaceMesh(+ worldBounds: Bounds,+ commonBounds: Bounds,+ viewport: WebMercatorViewport,+ textureSize: number,+ longitude?: number+) {+ if (+ !worldBounds?.every(Number.isFinite) ||+ !commonBounds?.every(Number.isFinite) ||+ worldBounds.length !== 4 ||+ commonBounds.length !== 4 ||+ !Number.isSafeInteger(textureSize) ||+ textureSize < 1+ ) {+ return null;+ }+ const [west, south, east, north] = worldBounds;+ const [xMin, yMin, xMax, yMax] = commonBounds;+ // Keep unwrapped longitudes: a viewport panned past the antimeridian can+ // legitimately produce a density texture entirely outside [-180, 180].+ const center = (west + east) / 2;+ const w = Math.max(west, center - 180);+ const e = Math.min(east, center + 180);+ const s = Math.max(-85.051129, south);+ const n = Math.min(85.051129, north);+ if (e <= w || n <= s || xMax <= xMin || yMax <= yMin) {+ return null;+ }++ // Sampling in Mercator space keeps vertex spacing aligned with the texture,+ // including high latitudes. Match the allocated density texture with one+ // grid cell per texel, so GPU texture limits also determine mesh resolution.+ const lower = viewport.projectPosition([w, s, 0]);+ const upper = viewport.projectPosition([e, n, 0]);+ const segments = textureSize;+ const side = segments + 1;+ const positions = new Float64Array(side * side * 3);+ const texCoords = new Float32Array(side * side * 2);+ const indices = new Uint32Array(segments * segments * 6);+ const shift =+ typeof longitude === 'number' && Number.isFinite(longitude)+ ? Math.round((longitude - (w + e) / 2) / 360) * 360+ : 0;+ let vertex = 0;+ let index = 0;+ for (let v = 0; v <= segments; v++) {+ const y = lower[1] + (upper[1] - lower[1]) * (v / segments);+ for (let u = 0; u <= segments; u++, vertex++) {+ const x = lower[0] + (upper[0] - lower[0]) * (u / segments);+ const [lng, lat] = viewport.unprojectPosition([x, y, 0]);+ positions.set([lng + shift, lat, 0], vertex * 3);+ texCoords.set([(x - xMin) / (xMax - xMin), (y - yMin) / (yMax - yMin)], vertex * 2);+ if (u < segments && v < segments) {+ indices.set(+ [vertex, vertex + 1, vertex + side, vertex + 1, vertex + side + 1, vertex + side],+ index+ );+ index += 6;+ }+ }+ }+ return {positions, texCoords, indices, vertexCount: indices.length};+}diff --git a/src/layers/src/heatmap-layer/heatmap-layer.ts b/src/layers/src/heatmap-layer/heatmap-layer.tsindex e38c584a2..bb7ef13fd 100644--- a/src/layers/src/heatmap-layer/heatmap-layer.ts+++ b/src/layers/src/heatmap-layer/heatmap-layer.ts@@ -23,6 +23,7 @@ import {ColorRange,VisConfigColorRange,VisConfigNumber,+ VisConfigBoolean,VisConfigSelection,HexColor,RGBColor,@@ -58,6 +59,11 @@ export type HeatmapLayerVisConfigSettings = {intensity: VisConfigNumber;threshold: VisConfigNumber;aggregation: VisConfigSelection;+ surfaceEnabled: VisConfigBoolean;+ surfaceHeight: VisConfigNumber;+ surfaceLighting: VisConfigBoolean;+ surfaceContours: VisConfigBoolean;+ surfaceContourStep: VisConfigNumber;};export type HeatmapLayerColumnsConfig = {@@ -79,6 +85,11 @@ export type HeatmapLayerVisConfig = {intensity: number;threshold: number;aggregation: string;+ surfaceEnabled: boolean;+ surfaceHeight: number;+ surfaceLighting: boolean;+ surfaceContours: boolean;+ surfaceContourStep: number;};export type HeatmapLayerVisualChannelConfig = LayerWeightConfig &@@ -153,7 +164,54 @@ export const heatmapVisConfigs: {intensity: VisConfigNumber;threshold: VisConfigNumber;aggregation: VisConfigSelection;+ surfaceEnabled: VisConfigBoolean;+ surfaceHeight: VisConfigNumber;+ surfaceLighting: VisConfigBoolean;+ surfaceContours: VisConfigBoolean;+ surfaceContourStep: VisConfigNumber;} = {+ surfaceEnabled: {+ type: 'boolean',+ defaultValue: false,+ label: 'layerVisConfigs.heatmap.surface',+ property: 'surfaceEnabled'+ } as VisConfigBoolean,+ surfaceHeight: {+ type: 'number',+ defaultValue: 1000,+ label: 'layerVisConfigs.heatmap.surfaceHeight',+ description: 'layerVisConfigs.heatmap.surfaceHeightDescription',+ property: 'surfaceHeight',+ isRanged: false,+ range: [0, 100000],+ step: 10,+ focusRange: [0, 5000],+ focusWeight: 0.7+ } as VisConfigNumber,+ surfaceLighting: {+ type: 'boolean',+ defaultValue: true,+ label: 'layerVisConfigs.heatmap.surfaceLighting',+ property: 'surfaceLighting'+ } as VisConfigBoolean,+ surfaceContours: {+ type: 'boolean',+ defaultValue: false,+ label: 'layerVisConfigs.heatmap.surfaceContours',+ property: 'surfaceContours'+ } as VisConfigBoolean,+ surfaceContourStep: {+ type: 'number',+ defaultValue: 0.1,+ label: 'layerVisConfigs.heatmap.surfaceContourStep',+ description: 'layerVisConfigs.heatmap.surfaceContourStepDescription',+ property: 'surfaceContourStep',+ isRanged: false,+ range: [0.01, 100],+ step: 0.01,+ focusRange: [0.01, 1],+ focusWeight: 0.5+ } as VisConfigNumber,opacity: 'opacity',colorRange: 'colorRange',radius: 'heatmapRadius',@@ -287,7 +345,12 @@ class HeatmapLayer extends Layer {'radius','intensity','threshold',- 'aggregation'+ 'aggregation',+ 'surfaceEnabled',+ 'surfaceHeight',+ 'surfaceLighting',+ 'surfaceContours',+ 'surfaceContourStep'];}@@ -672,6 +735,16 @@ class HeatmapLayer extends Layer {colorRange,weightsTextureSize: 512,debounceTimeout: 0,+ surface: visConfig.surfaceEnabled,+ surfaceHeight: Number.isFinite(visConfig.surfaceHeight)+ ? Math.max(0, visConfig.surfaceHeight)+ : 1000,+ surfaceLighting: visConfig.surfaceLighting !== false,+ surfaceContours: Boolean(visConfig.surfaceContours),+ surfaceContourStep:+ Number.isFinite(visConfig.surfaceContourStep) && visConfig.surfaceContourStep > 0+ ? visConfig.surfaceContourStep+ : 0.1,// globe-mode extensionsglobeMode,densityBounds: densityBounds && densityBounds.length === 4 ? densityBounds : nulldiff --git a/src/localization/src/translations/en.ts b/src/localization/src/translations/en.tsindex 40e064597..49c77aee5 100644--- a/src/localization/src/translations/en.ts+++ b/src/localization/src/translations/en.ts@@ -219,6 +219,17 @@ export default {colorAggregation: 'Color Aggregation',heightAggregation: 'Height Aggregation',weightAggregation: 'Weight Aggregation',+ heatmap: {+ surface: '3D Surface',+ surfaceHeight: 'Maximum height (m)',+ surfaceHeightDescription:+ 'Maximum surface height in meters, independent of intensity. Tilt the map to see the surface. Height represents density, not terrain elevation.',+ surfaceLighting: 'Surface shading',+ surfaceContours: 'Surface contours',+ surfaceContourStep: 'Contour step',+ surfaceContourStepDescription:+ 'Density interval between contour lines. Smaller values show more lines.'+ },resolutionRange: 'Resolution range',sizeScale: 'Size Scale',worldUnitSize: 'World Unit Size',diff --git a/src/reducers/src/vis-state-merger.ts b/src/reducers/src/vis-state-merger.tsindex dd32b1423..39d9dcd63 100644--- a/src/reducers/src/vis-state-merger.ts+++ b/src/reducers/src/vis-state-merger.ts@@ -1394,7 +1394,9 @@ export function validateLayerWithData(visConfig,textLabel,// Tile properties may be absent from dataset metadata; retain the saved name.- ...(type === LAYER_TYPES.vectorTile && typeof savedLayer.config.uniqueIdField === 'string'+ ...(type === LAYER_TYPES.vectorTile &&+ 'uniqueIdField' in savedLayer.config &&+ typeof savedLayer.config.uniqueIdField === 'string'? {uniqueIdField: savedLayer.config.uniqueIdField}: {})});diff --git a/test/browser/components/side-panel/layer-configurator-test.js b/test/browser/components/side-panel/layer-configurator-test.jsindex 30ccc172e..df665a5d5 100644--- a/test/browser/components/side-panel/layer-configurator-test.js+++ b/test/browser/components/side-panel/layer-configurator-test.js@@ -1303,3 +1303,120 @@ test('Components -> LayerConfigurator -> zarr variable selector changes the varit.end();});++test('Components -> LayerConfigurator -> collapsed Heatmap surface toggle group', t => {+ const layer = new KeplerGlLayers.HeatmapLayer({id: 'surface-controls', dataId: testCsvDataId});+ const changed = sinon.spy();+ function Editor() {+ const [, setVersion] = React.useState(0);+ return (+ <IntlWrapper>+ <LayerConfigurator+ {...defaultProps}+ layer={layer}+ updateLayerVisConfig={value => {+ changed(value);+ layer.updateLayerVisConfig(value);+ setVersion(v => v + 1);+ }}+ />+ </IntlWrapper>+ );+ }+ const view = renderWithTheme(<Editor />);+ const group = view.getByText('3D Surface').closest('.layer-config-group');+ const header = group.querySelector('.layer-config-group__header');+ const toggle = within(header).getByRole('checkbox');+ const content = group.querySelector('.layer-config-group__content');+ const options = content.querySelector('.layer-config-group__content__collapsible');+ try {+ t.equal(group, group.parentElement.lastElementChild, '3D Surface is the last settings group');+ t.notOk(view.queryByText('Contour step'), 'contour step is hidden until contours are enabled');+ t.notOk(toggle.checked, '3D Surface is off by default');+ t.equal(layer.config.visConfig.surfaceEnabled, false, 'default display remains 2D');+ t.ok(group.classList.contains('collapsed'), 'surface group starts collapsed');+ t.ok(content.classList.contains('disabled'), 'surface options are disabled while 2D');+ t.ok(+ options.contains(view.getByText('Maximum height (m)')),+ 'height is inside the collapsible options'+ );+ t.ok(+ options.contains(view.getByText('Surface shading')),+ 'shading is inside the collapsible options'+ );+ t.ok(+ options.contains(view.getByText('Surface contours')),+ 'contours are inside the collapsible options'+ );++ fireEvent.click(toggle);+ t.ok(toggle.checked, 'toggle enables 3D Surface');+ t.deepEqual(+ changed.lastCall.args[0],+ {surfaceEnabled: true},+ 'enabling emits the boolean setting directly'+ );+ t.notOk(content.classList.contains('disabled'), 'enabled surface options can be edited');+ t.notOk(group.classList.contains('collapsed'), 'enabling expands the surface options');++ const calls = changed.callCount;+ fireEvent.click(header);+ t.ok(group.classList.contains('collapsed'), 'header can collapse all surface options');+ t.equal(changed.callCount, calls, 'collapsing does not change the selected display mode');+ fireEvent.click(header);+ t.notOk(group.classList.contains('collapsed'), 'header can expand the options again');++ const heightInput = Array.from(options.querySelectorAll('.kg-range-slider__input')).find(+ input => input.value === '1000'+ );+ fireEvent.change(heightInput, {target: {value: '2500'}});+ fireEvent.blur(heightInput);+ t.deepEqual(changed.lastCall.args[0], {surfaceHeight: 2500}, 'height edits update the surface');+ fireEvent.click(options.querySelector('#surface-controls-surfaceLighting-switch'));+ t.deepEqual(changed.lastCall.args[0], {surfaceLighting: false}, 'shading can be disabled');+ fireEvent.click(options.querySelector('#surface-controls-surfaceContours-switch'));+ t.deepEqual(changed.lastCall.args[0], {surfaceContours: true}, 'contours can be enabled');+ t.ok(options.contains(view.getByText('Contour step')), 'contour step is in the surface group');+ const contourInput = Array.from(options.querySelectorAll('.kg-range-slider__input')).find(+ input => input.value === '0.1'+ );+ for (const step of [0.01, 0.2, 5, 100]) {+ fireEvent.change(contourInput, {target: {value: String(step)}});+ fireEvent.blur(contourInput);+ t.deepEqual(+ changed.lastCall.args[0],+ {surfaceContourStep: step},+ `contour step ${step} can be selected without clamping`+ );+ }+ fireEvent.click(options.querySelector('#surface-controls-surfaceContours-switch'));+ t.notOk(view.queryByText('Contour step'), 'disabling contours hides their step control');+ fireEvent.click(options.querySelector('#surface-controls-surfaceContours-switch'));+ t.equal(layer.config.visConfig.surfaceContourStep, 100, 'reenabling contours retains the step');+ fireEvent.click(toggle);+ t.notOk(toggle.checked, 'toggle returns to 2D');+ t.deepEqual(changed.lastCall.args[0], {surfaceEnabled: false}, 'disabling stores false');+ t.ok(content.classList.contains('disabled'), '2D disables the surface options again');+ fireEvent.click(toggle);+ t.equal(layer.config.visConfig.surfaceHeight, 2500, 'switching modes retains surface settings');+ t.equal(layer.config.visConfig.surfaceContourStep, 100, 'switching modes retains contour step');+ } finally {+ view.unmount();+ }+ const restored = renderWithTheme(<Editor />);+ try {+ const restoredGroup = restored.getByText('3D Surface').closest('.layer-config-group');+ t.ok(+ within(restoredGroup.querySelector('.layer-config-group__header')).getByRole('checkbox')+ .checked,+ 'saved Surface mode restores an enabled toggle'+ );+ t.ok(+ restoredGroup.classList.contains('collapsed'),+ 'reopened surface settings start collapsed'+ );+ } finally {+ restored.unmount();+ t.end();+ }+});diff --git a/test/browser/layer-tests/heatmap-layer-specs.js b/test/browser/layer-tests/heatmap-layer-specs.jsindex 082f63adb..07f791e34 100644--- a/test/browser/layer-tests/heatmap-layer-specs.js+++ b/test/browser/layer-tests/heatmap-layer-specs.js@@ -2,6 +2,7 @@// Copyright contributors to the kepler.gl projectimport test from 'tape';+import sinon from 'sinon';import {testCreateCases,testFormatLayerDataCases,@@ -23,10 +24,21 @@ import {visStateReducer,validateLayerWithData} from '@kepler.gl/reducers';-import {LayerManager, MapView} from '@deck.gl/core';+import {+ AmbientLight,+ LayerManager,+ MapView,+ WebMercatorViewport,+ _GlobeView,+ _SunLight as SunLight,+ getShaderAssembler+} from '@deck.gl/core';+import {visStateSchemaV1} from '@kepler.gl/schemas';+import KeplerHeatmapLayer from '../../../src/layers/src/heatmap-layer/deck-heatmap-layer';+import {createHeatmapSurfaceMesh} from '../../../src/layers/src/heatmap-layer/density-surface-mesh';+import CustomDeckLightingEffect from '../../../src/effects/src/custom-deck-lighting-effect';import {device} from '@deck.gl/test-utils';import {convertGeometryToWKB} from '@loaders.gl/gis';-import KeplerHeatmapLayer from '../../../src/layers/src/heatmap-layer/deck-heatmap-layer';const {HeatmapLayer, PointLayer} = KeplerGlLayers;@@ -199,6 +211,12 @@ test('#HeatmapLayer -> contructor', t => {},test: layer => {t.equal(layer.config.visConfig.radius, 20, 'Heatmap default radius should be 20');+ t.equal(layer.config.visConfig.surfaceEnabled, false, 'existing maps default to 2D');+ t.equal(+ layer.config.visConfig.surfaceContourStep,+ 0.1,+ 'default contour spacing is preserved'+ );t.ok(layer.visConfigSettings.radius.range[0] > 0,'heatmap radius should have a positive minimum'@@ -855,6 +873,9 @@ test('#Aggregation layers -> reducer filters at the domain minimum', t => {});};+ state.layers+ .find(layer => layer.type === 'heatmap')+ .updateLayerVisConfig({surfaceEnabled: true});check('no filter', 3);apply(VisStateActions.addFilter('first'));apply(VisStateActions.setFilter(0, 'name', 'value'));@@ -899,3 +920,798 @@ test('#Aggregation layers -> reducer filters at the domain minimum', t => {}t.end();});++test('#HeatmapLayer -> surface settings survive saving and loading', t => {+ const layer = validateLayerWithData(+ preparedDataset,+ {type: 'heatmap', config: {dataId, columns}},+ LayerClasses+ );+ t.equal(layer.config.visConfig.surfaceEnabled, false, 'a missing surface flag defaults to 2D');+ const surfaceConfig = {+ surfaceEnabled: true,+ surfaceHeight: 2500,+ surfaceLighting: false,+ surfaceContours: true,+ surfaceContourStep: 100+ };+ layer.updateLayerVisConfig(surfaceConfig);+ const saved = visStateSchemaV1.save({+ ...INITIAL_VIS_STATE,+ layers: [layer],+ layerOrder: [layer.id]+ }).visState;+ t.equal(+ saved.layers[0].config.visConfig.surfaceEnabled,+ true,+ 'saves the enabled flag as a boolean'+ );+ t.notOk('heatmapMode' in saved.layers[0].config.visConfig, 'does not save the old mode enum');+ const loaded = visStateSchemaV1.load(JSON.parse(JSON.stringify(saved))).visState;+ const restored = validateLayerWithData(preparedDataset, loaded.layers[0], LayerClasses);+ for (const [key, value] of Object.entries(surfaceConfig)) {+ t.equal(restored.config.visConfig[key], value, `restores ${key}`);+ }+ const data = restored.formatLayerData({[dataId]: preparedDataset});+ const render = (zoom = INITIAL_MAP_STATE.zoom) =>+ restored.renderLayer({data, mapState: {...INITIAL_MAP_STATE, zoom}, visible: true})[0];+ t.ok(render().props.surface, 'selects the surface renderer');+ t.equal(render().props.surfaceHeight, 2500, 'passes the selected maximum height');+ for (const zoom of [0, 10, 18]) {+ for (const intensity of [0.1, 2]) {+ restored.updateLayerVisConfig({intensity});+ const surface = render(zoom);+ t.equal(surface.props.surfaceHeight, 2500, 'zoom and intensity preserve maximum height');+ restored.updateLayerVisConfig({surfaceEnabled: false});+ const flat = render(zoom);+ for (const property of ['intensity', 'radiusPixels', 'threshold', 'colorRange']) {+ t.deepEqual(surface.props[property], flat.props[property], `preserves flat ${property}`);+ }+ restored.updateLayerVisConfig({surfaceEnabled: true});+ }+ }+ t.equal(+ render().props.surfaceContourStep,+ 100,+ 'passes large saved contour steps to the renderer'+ );+ for (const step of [undefined, 0, -0.1, Number.NaN, Infinity]) {+ restored.updateLayerVisConfig({surfaceContourStep: step});+ t.equal(+ render().props.surfaceContourStep,+ 0.1,+ 'missing or invalid contour step has a positive fallback'+ );+ }+ restored.updateLayerVisConfig({surfaceHeight: Number.NaN});+ t.equal(render().props.surfaceHeight, 1000, 'invalid height has a finite fallback');+ restored.updateLayerVisConfig({surfaceHeight: -20});+ t.equal(render().props.surfaceHeight, 0, 'negative height cannot invert the surface');+ restored.updateLayerVisConfig({surfaceEnabled: false});+ t.equal(render().props.surface, false, 'false selects the 2D renderer');+ t.equal(render().props.data, data.data, 'display changes reuse the filtered data');+ const disabledSaved = visStateSchemaV1.save({+ ...INITIAL_VIS_STATE,+ layers: [restored],+ layerOrder: [restored.id]+ }).visState;+ t.equal(+ disabledSaved.layers[0].config.visConfig.surfaceEnabled,+ false,+ 'saves the disabled flag as a boolean'+ );+ const disabledLoaded = visStateSchemaV1.load(JSON.parse(JSON.stringify(disabledSaved))).visState;+ t.equal(+ validateLayerWithData(preparedDataset, disabledLoaded.layers[0], LayerClasses).config.visConfig+ .surfaceEnabled,+ false,+ 'restores the disabled flag'+ );+ t.end();+});++test('#HeatmapLayer -> surface grid follows density geography and world copies', t => {+ const viewport = new WebMercatorViewport({longitude: 10, latitude: 65, zoom: 5});+ const bounds = [8, 60, 12, 70];+ const lower = viewport.projectPosition([8, 60, 0]);+ const upper = viewport.projectPosition([12, 70, 0]);+ const commonBounds = [lower[0], lower[1], upper[0], upper[1]];+ const textureSize = 512;+ const side = textureSize + 1;+ const mesh = createHeatmapSurfaceMesh(bounds, commonBounds, viewport, textureSize, 10);+ const shifted = createHeatmapSurfaceMesh(bounds, commonBounds, viewport, textureSize, 370);+ t.equal(+ mesh.positions.length,+ side * side * 3,+ 'surface grid matches the density texture resolution'+ );+ t.equal(+ mesh.vertexCount,+ textureSize * textureSize * 6,+ 'each density texel has two surface triangles'+ );+ for (const size of [128, 256]) {+ const resized = createHeatmapSurfaceMesh(bounds, commonBounds, viewport, size, 10);+ t.equal(resized.positions.length, (size + 1) ** 2 * 3, `matches a ${size}-pixel texture`);+ t.equal(resized.vertexCount, size * size * 6, `triangle count follows a ${size}-pixel texture`);+ }+ t.equal(mesh.vertexCount, mesh.indices.length, 'all triangles are drawn');+ t.ok(+ mesh.indices.every(i => i < mesh.positions.length / 3),+ 'all indices address valid vertices'+ );+ t.deepEqual(shifted.texCoords, mesh.texCoords, 'world wrapping preserves density samples');+ for (const i of [0, textureSize, (side * side - 1) / 2, side * side - 1]) {+ const position = Array.from(mesh.positions.slice(i * 3, i * 3 + 3));+ const projected = viewport.projectPosition(position);+ t.ok(+ Math.abs(mesh.texCoords[i * 2] - (projected[0] - lower[0]) / (upper[0] - lower[0])) < 1e-6,+ 'longitude matches its density sample'+ );+ t.ok(+ Math.abs(mesh.texCoords[i * 2 + 1] - (projected[1] - lower[1]) / (upper[1] - lower[1])) <+ 1e-6,+ 'latitude matches its density sample'+ );+ t.equal(+ shifted.positions[i * 3] - mesh.positions[i * 3],+ 360,+ 'renders in the nearest world copy'+ );+ }+ const wrappedBounds = [181, 60, 185, 70];+ const wrappedLower = viewport.projectPosition([181, 60, 0]);+ const wrappedUpper = viewport.projectPosition([185, 70, 0]);+ const wrapped = createHeatmapSurfaceMesh(+ wrappedBounds,+ [wrappedLower[0], wrappedLower[1], wrappedUpper[0], wrappedUpper[1]],+ viewport,+ textureSize,+ 183+ );+ t.ok(wrapped, 'a density texture beyond the antimeridian still renders');+ t.ok(Math.abs(wrapped.positions[0] - 181) < 1e-6, 'keeps unwrapped texture geography');+ t.deepEqual(+ Array.from(wrapped.texCoords.slice(0, 2)),+ [0, 0],+ 'samples its original density texture'+ );+ for (const invalid of [[], [0, 0, 0, 1], [0, 0, 1, 0], [0, 0, NaN, 1]]) {+ t.equal(+ createHeatmapSurfaceMesh(invalid, commonBounds, viewport, textureSize),+ null,+ 'empty or invalid geography produces no surface'+ );+ }+ t.equal(+ createHeatmapSurfaceMesh(bounds, [0, 0, 0, 0], viewport, textureSize),+ null,+ 'invalid density texture bounds produce no surface'+ );+ for (const size of [undefined, 0, -1, 1.5, NaN, Infinity]) {+ t.equal(+ createHeatmapSurfaceMesh(bounds, commonBounds, viewport, size),+ null,+ 'missing or invalid texture size produces no surface'+ );+ }+ t.end();+});++test('#HeatmapLayer -> regular rendering survives surface and effect toggles on map and globe', t => {+ for (const globe of [false, true]) {+ const viewport = new (globe ? _GlobeView : MapView)().makeViewport({+ width: 800,+ height: 600,+ viewState: {longitude: -122.4, latitude: 37.75, zoom: 10, pitch: 45}+ });+ const manager = new LayerManager(device, {viewport});+ const effect = new CustomDeckLightingEffect({+ sunLight: new SunLight({timestamp: Date.UTC(2026, 5, 1, 19), _shadow: true})+ });+ const effectContext = {+ device,+ deck: {+ _addDefaultShaderModule: module => manager.addDefaultShaderModule(module),+ _removeDefaultShaderModule: module => manager.removeDefaultShaderModule(module)+ }+ };+ let layer = new KeplerHeatmapLayer({+ id: `heatmap-surface-${globe}`,+ data: [+ [-122.42, 37.74],+ [-122.4, 37.76]+ ],+ getPosition: d => d,+ getWeight: 1,+ intensity: 0.7,+ threshold: 0.2,+ opacity: 0.6,+ radiusPixels: 30,+ parameters: {depthWriteEnabled: false, depthCompare: 'always'},+ weightsTextureSize: 128,+ debounceTimeout: 0,+ globeMode: globe,+ densityBounds: [-122.42, 37.74, -122.4, 37.76]+ });+ try {+ t.equal(layer.props.surface, false, 'missing surface settings select the regular heatmap');+ for (const aggregation of ['SUM', 'MEAN']) {+ layer = layer.clone({aggregation});+ testRenderDeckLayer(t, 'regular heatmap before effect', [layer], {layerManager: manager});+ const regular = layer.getSubLayers()[0];+ const regularVertexCount = regular.state.model.vertexCount;+ const worldBounds = layer.state.worldBounds;+ const commonBounds = layer.state.normalizedCommonBounds;+ const assertRegularRendering = () => {+ const current = layer.getSubLayers()[0];+ t.equal(current.constructor, regular.constructor, 'uses the regular renderer');+ t.equal(current.state.model.vertexCount, regularVertexCount, 'retains regular geometry');+ t.deepEqual(layer.state.worldBounds, worldBounds, 'retains the density frame');+ t.deepEqual(+ layer.state.normalizedCommonBounds,+ commonBounds,+ 'retains density texture mapping'+ );+ for (const property of [+ 'aggregationMode',+ 'intensity',+ 'threshold',+ 'opacity',+ 'colorDomain',+ 'parameters'+ ]) {+ t.deepEqual(+ current.props[property],+ regular.props[property],+ `preserves regular ${property}`+ );+ }+ for (const property of ['weightsTexture', 'maxTexture', 'colorTexture']) {+ t.equal(+ current.props[property],+ regular.props[property],+ `preserves regular ${property}`+ );+ t.notOk(current.props[property].destroyed, `${property} is still usable`);+ }+ t.notOk(current.props.surfaceHeight, 'regular heatmap has no height displacement');+ t.notOk(current.props.surfaceLighting, 'regular heatmap has no surface lighting');+ t.notOk(current.props.surfaceContours, 'regular heatmap has no surface contours');+ };+ effect.setup(effectContext);+ testRenderDeckLayer(t, 'regular heatmap with effect', [layer], {layerManager: manager});+ assertRegularRendering();++ layer = layer.clone({+ surface: true,+ surfaceHeight: 1800,+ surfaceContours: true,+ surfaceContourStep: 0.2,+ aggregation+ });+ testRenderDeckLayer(t, 'heatmap surface', [layer], {layerManager: manager});+ const surface = layer.getSubLayers()[0];+ t.ok(surface, 'creates the density surface');+ const textureSize = layer.state.textureSize;+ t.equal(+ surface.props.mesh.positions.length,+ (textureSize + 1) ** 2 * 3,+ 'renderer matches the allocated density texture resolution'+ );+ t.equal(+ surface.props.mesh.vertexCount,+ textureSize * textureSize * 6,+ 'renderer uses two triangles per density texel'+ );+ t.equal(surface.props.surfaceHeight, 1800, 'height is available to the GPU renderer');+ t.equal(+ surface.props.surfaceContourStep,+ 0.2,+ 'contour step is available to the GPU renderer'+ );+ t.equal(+ surface.props.aggregationMode,+ aggregation === 'SUM' ? 0 : 1,+ 'uses the heatmap aggregation'+ );+ const mesh = surface.props.mesh;+ layer = layer.clone({surfaceHeight: 2500, surfaceContourStep: 0.05});+ testRenderDeckLayer(t, 'rescaled surface', [layer], {layerManager: manager});+ t.equal(+ layer.getSubLayers()[0].props.mesh,+ mesh,+ 'height and contour edits reuse surface geometry'+ );+ t.equal(+ layer.getSubLayers()[0].props.surfaceContourStep,+ 0.05,+ 'contour spacing can be updated'+ );+ const weights = layer.state.weightsTexture;+ layer = layer.clone({surface: false});+ testRenderDeckLayer(t, 'flat heatmap', [layer], {layerManager: manager});+ t.equal(layer.state.weightsTexture, weights, 'Flat and Surface share density resources');+ t.notOk(layer.getSubLayers()[0].props.surfaceHeight, 'Flat does not displace density');+ assertRegularRendering();+ effect.cleanup(effectContext);+ testRenderDeckLayer(t, 'regular heatmap after removing effect', [layer], {+ layerManager: manager+ });+ assertRegularRendering();+ }+ for (const surface of [false, true]) {+ layer = layer.clone({surface, data: []});+ testRenderDeckLayer(t, 'empty filtered heatmap', [layer], {layerManager: manager});+ t.equal(layer.props.data.length, 0, 'both display modes support an empty filtered dataset');+ }+ } finally {+ effect.cleanup(effectContext);+ manager.finalize();+ }+ }+ t.end();+});++test('#HeatmapLayer -> surface responds to Light & Shadow on map and globe', t => {+ getShaderAssembler('glsl');+ for (const globe of [false, true]) {+ const viewport = new (globe ? _GlobeView : MapView)().makeViewport({+ width: 800,+ height: 600,+ viewState: {longitude: -122.4, latitude: 37.75, zoom: 10, pitch: 45}+ });+ const manager = new LayerManager(device, {viewport});+ const ambientLight = new AmbientLight({color: [255, 255, 255], intensity: 0.2});+ const sunLight = new SunLight({+ timestamp: Date.UTC(2026, 5, 1, 19),+ intensity: 1,+ _shadow: true+ });+ const effect = new CustomDeckLightingEffect({ambientLight, sunLight});+ const effectContext = {+ device,+ deck: {+ _addDefaultShaderModule: module => manager.addDefaultShaderModule(module),+ _removeDefaultShaderModule: module => manager.removeDefaultShaderModule(module)+ }+ };+ let layer = new KeplerHeatmapLayer({+ id: `heatmap-lighting-${globe}`,+ data: [[-122.4, 37.75]],+ getPosition: d => d,+ weightsTextureSize: 128,+ debounceTimeout: 0,+ globeMode: globe,+ densityBounds: [-122.42, 37.74, -122.4, 37.76],+ surface: true+ });+ try {+ testRenderDeckLayer(t, 'surface before lighting effect', [layer], {layerManager: manager});+ const mesh = layer.getSubLayers()[0].props.mesh;+ const initialModel = layer.getSubLayers()[0].state.model;+ effect.setup(effectContext);+ // NullDevice leaves framebuffer attachments uninitialized. Populate its+ // JS texture views so the real shadow pass can run without a GPU.+ for (const pass of effect.shadowPasses) {+ if (!pass.fbo.colorAttachments.length) {+ pass.fbo.autoCreateAttachmentTextures();+ }+ }+ testRenderDeckLayer(t, 'surface with lighting effect', [layer], {layerManager: manager});+ const surface = layer.getSubLayers()[0];+ const {model} = surface.state;+ t.notEqual(model, initialModel, 'adding the effect rebuilds the shader model');+ t.equal(+ model.vertexCount,+ mesh.vertexCount,+ 'the rebuilt model retains all surface triangles'+ );+ t.equal(surface.props.mesh, mesh, 'adding lighting reuses the density geometry');+ const {vs, fs} = surface.getShaders();+ t.ok(+ vs.includes('DECKGL_FILTER_GL_POSITION(gl_Position, geometry)'),+ 'displaced geometry uses the shadow projection hook'+ );+ t.ok(fs.includes('lighting_getLightColor('), 'surface colors use scene lighting');+ t.ok(+ fs.includes('DECKGL_FILTER_COLOR(fragColor, geometry)'),+ 'surface colors use shadow encoding and receiving hooks'+ );+ t.ok(+ model.vs.includes('shadow_setVertexPosition(geometry.position, position)'),+ 'the active Kepler shadow module is assembled'+ );++ const applyLighting = () => {+ surface.setShaderModuleProps(effect.getShaderModuleProps(surface, {project: {viewport}}));+ return model.shaderInputs.getUniformValues();+ };+ const initialLighting = applyLighting().lighting;+ t.deepEqual(+ initialLighting.ambientColor,+ [0.2, 0.2, 0.2],+ 'ambient intensity reaches the renderer'+ );+ t.equal(initialLighting.directionalLightCount, 1, 'the renderer uses the scene sun');+ sunLight.timestamp += 6 * 60 * 60 * 1000;+ sunLight.color = [255, 0, 0];+ sunLight.intensity = 0.5;+ ambientLight.intensity = 0.4;+ const changedLighting = applyLighting().lighting;+ t.deepEqual(+ changedLighting.ambientColor,+ [0.4, 0.4, 0.4],+ 'ambient changes update the renderer'+ );+ t.deepEqual(+ changedLighting.lights[0].color,+ [0.5, 0, 0],+ 'sun color and intensity update the renderer'+ );+ t.notDeepEqual(+ changedLighting.lights[0].direction,+ initialLighting.lights[0].direction,+ 'time changes update the sun direction'+ );++ const draw = sinon.spy(model, 'draw');+ try {+ effect.preRender({+ layers: manager.getLayers(),+ viewports: [viewport],+ onViewportActive: manager.activateViewport+ });+ t.ok(draw.called, 'the shaded surface draws into the shadow pass');+ t.equal(+ model.shaderInputs.getUniformValues().shadow.drawShadowMap,+ true,+ 'the shadow pass encodes depth'+ );+ t.equal(+ applyLighting().shadow.useShadowMap,+ true,+ 'the color pass receives the shadow map'+ );+ } finally {+ draw.restore();+ }++ layer = layer.clone({surfaceLighting: false});+ testRenderDeckLayer(t, 'unshaded surface', [layer], {layerManager: manager});+ t.equal(+ layer.getSubLayers()[0].props.shadowEnabled,+ false,+ 'disabling shading excludes the surface from shadow casting'+ );+ effect.cleanup(effectContext);+ testRenderDeckLayer(t, 'surface after removing lighting effect', [layer], {+ layerManager: manager+ });+ t.equal(+ layer.getSubLayers()[0].state.model.vertexCount,+ mesh.vertexCount,+ 'removing the effect preserves the surface triangles'+ );+ } finally {+ effect.cleanup(effectContext);+ manager.finalize();+ }+ }+ t.end();+});++test('#HeatmapLayer -> globe display edits preserve density aggregation', t => {+ const viewState = {longitude: -122.4, latitude: 37.75, zoom: 8};+ const viewport = new _GlobeView().makeViewport({width: 800, height: 600, viewState});+ const manager = new LayerManager(device, {viewport});+ const props = {+ id: 'globe-density-cache',+ data: [+ [-122.42, 37.74],+ [-122.4, 37.76]+ ],+ getPosition: d => d,+ getWeight: 1,+ weightsTextureSize: 128,+ debounceTimeout: 0,+ globeMode: true,+ surface: true,+ densityBounds: [-123, 37, -122, 38]+ };+ let layer = new KeplerHeatmapLayer(props);+ testRenderDeckLayer(t, 'globe density cache', [layer], {layerManager: manager});+ const aggregate = sinon.spy(KeplerHeatmapLayer.prototype, '_updateWeightmap');+ try {+ const weights = layer.state.weightsTexture;+ for (const change of [+ {surfaceHeight: 2000},+ {surfaceLighting: false},+ {surfaceContours: true},+ {surfaceContourStep: 0.2},+ {surface: false},+ {surface: true}+ ]) {+ layer = layer.clone(change);+ testRenderDeckLayer(t, 'display-only edit', [layer], {layerManager: manager});+ t.equal(aggregate.callCount, 0, 'display edits do not aggregate the data again');+ t.equal(layer.state.weightsTexture, weights, 'display edits retain the density texture');+ }+ layer = layer.clone({densityBounds: [-124, 36, -121, 39]});+ testRenderDeckLayer(t, 'changed density frame', [layer], {layerManager: manager});+ t.ok(aggregate.called, 'changing density bounds recomputes density');+ const boundsBeforeZoom = layer.state.worldBounds;+ const radiusBeforeZoom = layer._getRadiusScale();+ const callsBeforeZoom = aggregate.callCount;+ manager.activateViewport(+ new _GlobeView().makeViewport({+ width: 800,+ height: 600,+ viewState: {...viewState, zoom: 12}+ })+ );+ layer = layer.clone({surfaceHeight: 3000});+ testRenderDeckLayer(t, 'zoomed density frame', [layer], {layerManager: manager});+ t.ok(+ aggregate.callCount > callsBeforeZoom,+ 'zooming into a different density frame recomputes density'+ );+ const zoomedBounds = layer.state.worldBounds;+ const zoomedTextureBounds = layer.state.normalizedCommonBounds;+ const zoomedRadiusScale = layer._getRadiusScale();+ const callsAfterZoom = aggregate.callCount;+ t.ok(zoomedRadiusScale > 1, 'the tighter density frame scales the heatmap radius');++ layer = layer.clone({surfaceLighting: true});+ testRenderDeckLayer(t, 'display edit after zoom', [layer], {layerManager: manager});+ t.equal(aggregate.callCount, callsAfterZoom, 'a zoomed display edit reuses aggregation');+ t.deepEqual(layer.state.worldBounds, zoomedBounds, 'replacement retains the zoomed frame');+ t.deepEqual(+ layer.state.normalizedCommonBounds,+ zoomedTextureBounds,+ 'replacement retains the density texture mapping'+ );+ t.equal(+ layer._getRadiusScale(),+ zoomedRadiusScale,+ 'rebuilt viewports preserve radius scaling after replacement'+ );++ // Update the same instance so existing viewport caches must be invalidated.+ manager.activateViewport(viewport);+ layer.activateViewport(viewport);+ testRenderDeckLayer(t, 'zoom out with cached viewports', [layer], {layerManager: manager});+ t.ok(aggregate.callCount > callsAfterZoom, 'zooming out recomputes density');+ t.deepEqual(+ layer.state.worldBounds,+ boundsBeforeZoom,+ 'zooming out restores the density frame'+ );+ t.equal(layer._getRadiusScale(), radiusBeforeZoom, 'zooming out restores radius scaling');++ const flatViewport = new MapView().makeViewport({width: 800, height: 600, viewState});+ manager.activateViewport(flatViewport);+ layer.activateViewport(flatViewport);+ layer = layer.clone({globeMode: false});+ const fresh = new KeplerHeatmapLayer({...props, id: 'fresh-flat-density', globeMode: false});+ testRenderDeckLayer(t, 'globe to map', [layer, fresh], {layerManager: manager});+ t.deepEqual(+ layer.state.worldBounds,+ fresh.state.worldBounds,+ 'leaving globe restores the live map frame'+ );+ t.deepEqual(+ layer.state.normalizedCommonBounds,+ fresh.state.normalizedCommonBounds,+ 'leaving globe clears stale texture coordinates'+ );+ } finally {+ aggregate.restore();+ manager.finalize();+ }+ t.end();+});++test('#HeatmapLayer -> surface normalization preserves small positive densities', t => {+ const viewport = new MapView().makeViewport({+ width: 800,+ height: 600,+ viewState: {longitude: -122.4, latitude: 37.75, zoom: 10}+ });+ const manager = new LayerManager(device, {viewport});+ const layer = new KeplerHeatmapLayer({+ id: 'surface-normalization',+ data: [[-122.4, 37.75]],+ getPosition: d => d,+ surface: true,+ weightsTextureSize: 128,+ debounceTimeout: 0+ });+ try {+ testRenderDeckLayer(t, 'surface normalization', [layer], {layerManager: manager});+ const {vs, fs} = layer.getSubLayers()[0].getShaders();+ // Execute the renderer's JS-compatible scalar GLSL arithmetic in this+ // headless test, rather than duplicating its normalization in a CPU helper.+ const normalization = vs.slice(vs.indexOf('float maxValue ='), vs.indexOf('vec4 weights ='));+ const evaluate = new Function(+ 'triangle',+ 'maxTexture',+ 'max',+ `+ let vIntensityMax, vIntensityMin;+ ${normalization.replace(/\bfloat\b/g, 'let')}+ return {vIntensityMax, vIntensityMin};+ `+ );+ const alphaExpression = fs.match(/color\.a \*= ([\s\S]*?);/)[1];+ const alpha = new Function(+ 'value',+ 'vIntensityMin',+ 'triangle',+ 'min',+ `return ${alphaExpression};`+ );+ for (const aggregationMode of [0, 1]) {+ for (const customDomain of [false, true]) {+ const maximum = 5e-7;+ const minimum = 5e-9;+ const triangle = {+ aggregationMode,+ intensity: 1,+ threshold: minimum / maximum,+ colorDomain: customDomain ? [minimum, maximum] : [0, 0]+ };+ const maxTexture = aggregationMode === 0 ? {r: maximum, g: 1} : {r: 1, g: maximum};+ const {vIntensityMax, vIntensityMin} = evaluate(triangle, maxTexture, Math.max);+ t.equal(maximum * vIntensityMax, 1, 'small positive peaks reach the full color scale');+ t.equal(+ alpha(minimum / 2, vIntensityMin, triangle, Math.min),+ 0.5,+ 'small positive minima preserve the opacity ramp'+ );+ t.equal(+ alpha(minimum, vIntensityMin, triangle, Math.min),+ 1,+ 'density at the minimum is fully opaque'+ );+ }+ }+ const triangle = {aggregationMode: 0, intensity: 1, threshold: 0, colorDomain: [0, 0]};+ const zero = evaluate(triangle, {r: 0, g: 0}, Math.max);+ t.equal(zero.vIntensityMax, 0, 'empty density has a finite zero color scale');+ t.equal(zero.vIntensityMin, 0, 'zero threshold avoids division by zero');+ t.equal(+ alpha(5e-10, zero.vIntensityMin, triangle, Math.min),+ 1,+ 'zero threshold keeps positive density opaque'+ );+ const disabled = evaluate({...triangle, intensity: 0}, {r: 5e-7, g: 0}, Math.max);+ t.equal(+ alpha(5e-10, disabled.vIntensityMin, {...triangle, intensity: 0}, Math.min),+ 0,+ 'zero intensity remains transparent'+ );+ } finally {+ manager.finalize();+ }+ t.end();+});++test('#HeatmapLayer -> maximum surface height is independent of color settings', t => {+ const viewport = new MapView().makeViewport({+ width: 800,+ height: 600,+ viewState: {longitude: -122.4, latitude: 37.75, zoom: 10}+ });+ const manager = new LayerManager(device, {viewport});+ const layer = new KeplerHeatmapLayer({+ id: 'surface-maximum-height',+ data: [[-122.4, 37.75]],+ getPosition: d => d,+ surface: true,+ weightsTextureSize: 128,+ debounceTimeout: 0+ });+ try {+ testRenderDeckLayer(t, 'surface maximum height', [layer], {layerManager: manager});+ // Run the actual max-reduction fragment arithmetic. MAX blending reduces+ // channels independently; red/green must keep their regular color values.+ const maxModel = layer.state.maxWeightTransform.model;+ const maxBody = maxModel.fs.match(/void main\(\)\s*\{([\s\S]*?)\}/)[1];+ const evaluateMax = new Function(+ 'outTexture',+ 'max',+ `let fragColor;+ ${maxBody.replace('fragColor = outTexture;', 'fragColor = {...outTexture};')}+ return fragColor;`+ );+ const texels = [+ {r: 8, g: 0, b: 0, a: 4},+ {r: 6, g: 0, b: 0, a: 2},+ {r: 0, g: 0, b: 0, a: 0}+ ];+ const reduced = texels.map(texel => evaluateMax(texel, Math.max));+ const maxTexture = Object.fromEntries(+ ['r', 'g', 'b', 'a'].map(channel => [channel, Math.max(...reduced.map(v => v[channel]))])+ );+ t.equal(maxTexture.r, 1, 'regular SUM colors retain the fixed maximum of one');+ t.equal(maxTexture.g, 3, 'regular MEAN colors retain the actual mean maximum');+ t.equal(maxTexture.b, 8, 'surface retains the actual SUM maximum separately');++ // Like the color-normalization test, execute the renderer's scalar GLSL+ // because NullDevice does not run shaders. Include the weight aggregation.+ const {vs} = layer.getSubLayers()[0].getShaders();+ const heightBody = vs.slice(vs.indexOf('float weight ='), vs.indexOf('vec3 position ='));+ const evaluateHeight = new Function(+ 'triangle',+ 'maxTexture',+ 'weights',+ 'max',+ 'clamp',+ 'isnan',+ 'isinf',+ `let vDensity;+ ${heightBody.replace(/\bfloat\b/g, 'let')}+ return {height, density: vDensity};`+ );+ const height = (triangle, maximum, weights) =>+ evaluateHeight(+ triangle,+ maximum,+ weights,+ Math.max,+ (value, low, high) => Math.min(high, Math.max(low, value)),+ Number.isNaN,+ value => Math.abs(value) === Infinity+ );+ for (const aggregationMode of [0, 1]) {+ const peak = aggregationMode === 0 ? texels[0] : texels[1];+ const maximum = aggregationMode === 0 ? maxTexture.b : maxTexture.g;+ const settings = {aggregationMode, surfaceHeight: 2500};+ for (const intensity of [0, 0.1, 1, 20]) {+ for (const colorDomain of [+ [0, 0],+ [0.2, 100]+ ]) {+ const triangle = {...settings, intensity, colorDomain, threshold: 0.9};+ t.equal(height(triangle, maxTexture, peak).height, 2500, 'peak reaches maximum meters');+ const half = height(triangle, maxTexture, {...peak, r: peak.r / 2});+ t.equal(half.height, 1250, 'half density retains proportional height');+ t.equal(half.density, maximum / 2, 'contour density is independent of color settings');+ }+ }+ t.equal(+ height({...settings, surfaceHeight: 0}, maxTexture, peak).height,+ 0,+ 'zero maximum height flattens the surface'+ );+ t.equal(+ height(settings, maxTexture, {...peak, r: peak.r * 2}).height,+ 2500,+ 'height never exceeds the configured maximum'+ );+ for (const density of [5e-9, 5e-7, 100]) {+ t.equal(+ height(settings, {r: 1, g: density, b: density}, {r: density, a: 1}).height,+ 2500,+ 'recomputed density maxima retain the same meter height, including tiny densities'+ );+ }+ for (const invalid of [0, -1, NaN, Infinity]) {+ t.equal(+ height(settings, maxTexture, {r: invalid, a: 1}).height,+ 0,+ 'empty or invalid density has zero height'+ );+ t.equal(+ height(settings, {r: 1, g: invalid, b: invalid}, peak).height,+ 0,+ 'empty or invalid maximum has zero height'+ );+ }+ }+ } finally {+ manager.finalize();+ }+ t.end();+});