MAPS3D-2082: Debug 3D Model Footprints in GL JS (internal-9681)

GitOrigin-RevId: a919932c8eea91b685cb1c9de54e8c026edfb5ba

Author: aleksproger

3d-style/data/model.ts

@@ -133,6 +133,12 @@ export type ModelNode = {
     anchor: vec2;
     hidden: boolean;
     isGeometryBloom: boolean;
+    footprintDebugMesh?: {
+        vertexBuffer: VertexBuffer;
+        indexBuffer: IndexBuffer;
+        segments: SegmentVector;
+        color: Color;
+    };
 };
 
 export const ModelTraits = {
@@ -496,6 +502,11 @@ export function destroyBuffers(node: ModelNode) {
             }
         }
     }
+    if (node.footprintDebugMesh) {
+        node.footprintDebugMesh.vertexBuffer.destroy();
+        node.footprintDebugMesh.indexBuffer.destroy();
+        node.footprintDebugMesh.segments.destroy();
+    }
     if (node.children) {
         for (const child of node.children) {
             destroyBuffers(child);

3d-style/render/draw_model.ts

@@ -9,7 +9,7 @@ import {mat4, quat, vec3, vec4} from 'gl-matrix';
 import {getMetersPerPixelAtLatitude, mercatorZfromAltitude, tileToMeter} from '../../src/geo/mercator_coordinate';
 import TextureSlots from './texture_slots';
 import {convertModelMatrixForGlobe} from '../util/model_util';
-import {clamp, warnOnce} from '../../src/util/util';
+import {clamp, warnOnce, esgtsaHash} from '../../src/util/util';
 import assert from 'assert';
 import {DEMSampler} from '../../src/terrain/elevation';
 import {Aabb} from '../../src/util/primitives';
@@ -21,6 +21,11 @@ import {pointInFootprint} from '../../3d-style/source/replacement_source';
 import Point from '@mapbox/point-geometry';
 import LngLat from '../../src/geo/lng_lat';
 import {tileToLngLat} from '../style/style_layer/model_style_layer';
+import SegmentVector from '../../src/data/segment';
+import {PosArray, TriangleIndexArray} from '../../src/data/array_types';
+import posAttributes from '../../src/data/pos_attributes';
+import {debugUniformValues} from '../../src/render/program/debug_program';
+import Color from '../../src/style-spec/util/color';
 
 import type Program from '../../src/render/program';
 import type Transform from '../../src/geo/transform';
@@ -57,6 +62,8 @@ type SortedMesh = {
     modelOpacity: number;
     materialOverride?: MaterialOverride;
     modelColor?: [number, number, number, number];
+    node: ModelNode;
+    modelMatrix: mat4;
 };
 
 type SortedNode = {
@@ -313,15 +320,15 @@ function prepareMeshes(painter: Painter, node: ModelNode, modelMatrix: mat4, pro
             if (materialOverride && materialOverride.opacity <= 0) continue;
 
             if (mesh.material.alphaMode !== 'BLEND') {
-                const opaqueMesh: SortedMesh = {mesh, depth: 0.0, modelIndex, worldViewProjection, nodeModelMatrix, isLightMesh, materialOverride, modelOpacity, modelColor: modelColorMix};
+                const opaqueMesh: SortedMesh = {mesh, depth: 0.0, modelIndex, worldViewProjection, nodeModelMatrix, isLightMesh, materialOverride, modelOpacity, modelColor: modelColorMix, node, modelMatrix};
                 opaqueMeshes.push(opaqueMesh);
                 continue;
             }
 
             const centroidPos = vec3.transformMat4([], mesh.centroid, worldViewProjection);
             // Filter meshes behind the camera if in perspective mode
             if (!transform.isOrthographic && centroidPos[2] <= 0.0) continue;
-            const transparentMesh: SortedMesh = {mesh, depth: centroidPos[2], modelIndex, worldViewProjection, nodeModelMatrix, isLightMesh, materialOverride, modelOpacity, modelColor: modelColorMix};
+            const transparentMesh: SortedMesh = {mesh, depth: centroidPos[2], modelIndex, worldViewProjection, nodeModelMatrix, isLightMesh, materialOverride, modelOpacity, modelColor: modelColorMix, node, modelMatrix};
             transparentMeshes.push(transparentMesh);
         }
     }
@@ -347,6 +354,82 @@ function drawShadowCaster(mesh: Mesh, matrix: mat4, painter: Painter, layer: Mod
         undefined, undefined);
 }
 
+function getOrCreateFootprintMesh(painter: Painter, node: ModelNode) {
+    if (node.footprintDebugMesh) return node.footprintDebugMesh;
+    if (!node.footprint) return null;
+
+    const context = painter.context;
+    const vertices = node.footprint.vertices;
+    const indices = node.footprint.indices;
+
+    const vertexArray = new PosArray();
+    vertexArray.reserve(vertices.length);
+    for (const v of vertices) {
+        vertexArray.emplaceBack(v.x, v.y);
+    }
+
+    const indexArray = new TriangleIndexArray();
+    indexArray.reserve(indices.length);
+    for (let i = 0; i < indices.length; i += 3) {
+        indexArray.emplaceBack(indices[i], indices[i + 1], indices[i + 2]);
+    }
+
+    const vertexBuffer = context.createVertexBuffer(vertexArray, posAttributes.members);
+    const indexBuffer = context.createIndexBuffer(indexArray);
+    const segments = SegmentVector.simpleSegment(0, 0, vertices.length, indices.length);
+
+    // Generate a deterministic color based on the node ID or name
+    const idStr = node.id || node.name || 'footprint';
+    let seed: number;
+
+    const numericId = parseInt(idStr, 10);
+    if (!isNaN(numericId)) {
+        seed = numericId;
+    } else {
+        seed = stringHash(idStr);
+    }
+
+    const r = esgtsaHash(seed);
+    const g = esgtsaHash(seed + 1);
+    const b = esgtsaHash(seed + 2);
+
+    node.footprintDebugMesh = {
+        vertexBuffer,
+        indexBuffer,
+        segments,
+        color: new Color(r, g, b, 0.5)
+    };
+
+    return node.footprintDebugMesh;
+}
+
+function stringHash(str: string): number {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = (((hash << 5) - hash) + str.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+
+function drawFootprint(painter: Painter, layer: ModelStyleLayer, node: ModelNode, mvpMatrix: mat4) {
+    const mesh = getOrCreateFootprintMesh(painter, node);
+    if (!mesh) return;
+
+    const context = painter.context;
+    const gl = context.gl;
+
+    const program = painter.getOrCreateProgram('debug');
+
+    const color = mesh.color;
+    const depthMode = DepthMode.disabled;
+    // We bind the empty (transparent) texture to ensure no overlay is drawn.
+    context.activeTexture.set(gl.TEXTURE0);
+    painter.emptyTexture.bind(gl.LINEAR, gl.CLAMP_TO_EDGE);
+    program.draw(painter, gl.TRIANGLES, depthMode, StencilMode.disabled, ColorMode.alphaBlended, CullFaceMode.disabled,
+        debugUniformValues(mvpMatrix, color.toPremultipliedRenderColor(null)), '$debug',
+        mesh.vertexBuffer, mesh.indexBuffer, mesh.segments);
+}
+
 // Evaluate feature state for node names
 function evaluateFeatureStateForNodeOverrides(layer: ModelStyleLayer, featureId: string | number, featureState: FeatureState, featureProperties: Record<string, unknown>, nodeNamesToEvaluate: string[], nodeOverrides: ModelNodeOverrides) {
     for (const nodeId of nodeNamesToEvaluate) {
@@ -523,6 +606,35 @@ function drawModels(painter: Painter, sourceCache: SourceCache, layer: ModelStyl
         return;
     }
 
+    if (painter._debugParams.show3DModelFootprints) {
+        const proj = painter.transform.projMatrix;
+        const footprints = new Map<string, {node: ModelNode, mvp: mat4}>();
+
+        const addFootprint = (node: ModelNode, matrix: mat4) => {
+            if (node.footprint) {
+                const id = node.id || node.name || 'footprint';
+                if (!footprints.has(id)) {
+                    const mvp = mat4.multiply([] as unknown as mat4, proj, matrix);
+                    footprints.set(id, {node, mvp});
+                }
+            }
+        };
+
+        for (const opaqueMesh of opaqueMeshes) {
+            addFootprint(opaqueMesh.node, opaqueMesh.modelMatrix);
+        }
+        for (const transparentMesh of transparentMeshes) {
+            addFootprint(transparentMesh.node, transparentMesh.modelMatrix);
+        }
+
+        const sortedIds = Array.from(footprints.keys()).sort();
+
+        for (const id of sortedIds) {
+            const {node, mvp} = footprints.get(id);
+            drawFootprint(painter, layer, node, mvp);
+        }
+    }
+
     drawSortedMeshes(painter, layer, transparentMeshes, opaqueMeshes, modelParametersVector);
 
     cleanup();
@@ -981,6 +1093,9 @@ function drawBatchedModels(painter: Painter, source: SourceCache, layer: ModelSt
 
     const stats = layer.getLayerRenderingStats();
     const drawTiles = function () {
+        // Keyed by ID to deduplicate footprints across tiles
+        const footprints = new Map<string, {node: ModelNode, mvp: mat4}>();
+
         let start, end, step;
         // When front cutoff is enabled the tiles are iterated in back to front order
         if (frontCutoffEnabled) {
@@ -1136,6 +1251,13 @@ function drawBatchedModels(painter: Painter, source: SourceCache, layer: ModelSt
                 const nodeInfo = sortedNode.nodeInfo;
                 const node = nodeInfo.node;
 
+                if (painter._debugParams.show3DModelFootprints && node.footprint) {
+                    const id = node.id || node.name || 'footprint';
+                    if (!footprints.has(id)) {
+                        footprints.set(id, {node, mvp: sortedNode.wvpForTile});
+                    }
+                }
+
                 let lightingMatrix = mat4.multiply([], zScaleMatrix, sortedNode.tileModelMatrix);
                 mat4.multiply(lightingMatrix, negCameraPosMatrix, lightingMatrix);
                 const normalMatrix = mat4.invert([], lightingMatrix);
@@ -1274,6 +1396,14 @@ function drawBatchedModels(painter: Painter, source: SourceCache, layer: ModelSt
                 }
             }
         }
+
+        if (painter._debugParams.show3DModelFootprints && footprints.size > 0) {
+            const sortedIds = Array.from(footprints.keys()).sort();
+            for (const id of sortedIds) {
+                const {node, mvp} = footprints.get(id);
+                drawFootprint(painter, layer, node, mvp);
+            }
+        }
     };
 
     // Evaluate bucket and prepare for rendering

src/render/draw_raster_particle.ts

@@ -27,7 +27,7 @@ import {mercatorXfromLng, mercatorYfromLat} from '../geo/mercator_coordinate';
 import rasterFade from './raster_fade';
 import assert from 'assert';
 import {RGBAImage} from '../util/image';
-import {smoothstep} from '../util/util';
+import {smoothstep, esgtsaHash} from '../util/util';
 import {GLOBE_ZOOM_THRESHOLD_MAX} from '../geo/projection/globe_constants';
 
 import type Transform from '../geo/transform';
@@ -58,20 +58,12 @@ function drawRasterParticle(painter: Painter, sourceCache: SourceCache, layer: R
 function createPositionRGBAData(textureDimension: number): Uint8Array {
     const numParticles = textureDimension * textureDimension;
     const RGBAPositions = new Uint8Array(4 * numParticles);
-    // Hash function from https://www.shadertoy.com/view/XlGcRh
-    const esgtsa = function (s: number): number {
-        s |= 0;
-        s = Math.imul(s ^ 2747636419, 2654435769);
-        s = Math.imul(s ^ (s >>> 16), 2654435769);
-        s = Math.imul(s ^ (s >>> 16), 2654435769);
-        return (s >>> 0) / 4294967296;
-    };
     // Pack random positions in [0, 1] into RGBA pixels. Matches the GLSL
     // `pack_pos_to_rgba` behavior.
     const invScale = 1.0 / RASTER_PARTICLE_POS_SCALE;
     for (let i = 0; i < numParticles; i++) {
-        const x = invScale * (esgtsa(2 * i + 0) + RASTER_PARTICLE_POS_OFFSET);
-        const y = invScale * (esgtsa(2 * i + 1) + RASTER_PARTICLE_POS_OFFSET);
+        const x = invScale * (esgtsaHash(2 * i + 0) + RASTER_PARTICLE_POS_OFFSET);
+        const y = invScale * (esgtsaHash(2 * i + 1) + RASTER_PARTICLE_POS_OFFSET);
 
         const rx = x;
         const ry = (x * 255.0) % 1;

src/render/painter.ts

@@ -250,6 +250,7 @@ class Painter {
         continousRedraw: boolean;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         enabledLayers: any;
+        show3DModelFootprints: boolean;
     };
 
     _timeStamp: number;
@@ -294,6 +295,7 @@ class Painter {
             showTerrainProxyTiles: false,
             fpsWindow: 30,
             continousRedraw: false,
+            show3DModelFootprints: false,
             enabledLayers: {
             }
         };
@@ -308,6 +310,9 @@ class Painter {
         DevTools.addParameter(this._debugParams, 'showTerrainProxyTiles', 'Terrain', {}, () => {
             this.style.map.triggerRepaint();
         });
+        DevTools.addParameter(this._debugParams, 'show3DModelFootprints', 'Debug', {}, () => {
+            this.style.map.triggerRepaint();
+        });
         DevTools.addParameter(this._debugParams, 'forceEnablePrecipitation', 'Precipitation');
         DevTools.addParameter(this._debugParams, 'fpsWindow', 'FPS', {min: 1, max: 100, step: 1});
         DevTools.addBinding(this._debugParams, 'continousRedraw', 'FPS', {

src/util/util.ts

@@ -898,4 +898,16 @@ export function easeIn(x: number) {
     return x * x * x * x * x;
 }
 
+/**
+ * Hash function from https://www.shadertoy.com/view/XlGcRh
+ * Matches gl-native's esgtsaHash in mbgl/util/random.hpp
+ */
+export function esgtsaHash(s: number): number {
+    s = s >>> 0; // Ensure unsigned 32-bit integer
+    s = Math.imul(s ^ 2747636419, 2654435769) >>> 0;
+    s = Math.imul(s ^ (s >>> 16), 2654435769) >>> 0;
+    s = Math.imul(s ^ (s >>> 16), 2654435769) >>> 0;
+    return s / 4294967296;
+}
+
 export {deepEqual};