From 80714922c18b91b828c0749de2f666eaf3c00a32 Mon Sep 17 00:00:00 2001 From: Brad Stricherz Date: Sat, 7 Nov 2026 21:00:09 -0600 Subject: [PATCH 1/6] docs: plan for issue 15 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf --- ...1-07-issue-15-gpu-heatmap-misregistered.md | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md diff --git a/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md new file mode 100644 index 0000000..4130b40 --- /dev/null +++ b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md @@ -0,0 +1,60 @@ +# Plan: GPU heatmap is misregistered: equirectangular grid drawn as a Mercator-stretched bitmap (issue #15) + +Risk tier: High. Starts Low, raised once because the visible effect (heat lining up with airports on the rendered map) is a GPU and map-rendering result no unit test in jsdom can exercise, and once because it alters existing behavior (the shader's binning). Small diff, but rounded up per the rules. + +Domain skills: +- superpowers:test-driven-development: invoke (every change starts with a failing test). +- context7 / deck.gl docs: used in analysis (see Approach); no further invocation needed. +- vercel-react-best-practices: not applicable because no React component or hook structure changes; only a shader string and layer props change. +- dataviz: not applicable because the color ramp and opacity do not change; only where pixels land. +- frontend-design, a11y skills: not applicable because no UI, markup, or styles change. + +## Approach + +Bin in Web Mercator inside the shader and keep the BitmapLayer's current Mercator bounds `[-180, -85.051129, 180, 85.051129]` with the default image coordinate system. + +Rejected: `_imageCoordinateSystem: COORDINATE_SYSTEM.LNGLAT` with bounds `[-180, -90, 180, 90]`. In deck.gl 9.4.1 (`node_modules/@deck.gl/layers/dist/bitmap-layer/bitmap-layer.js` line 177 onward, `bitmap-layer-fragment.js` line 52) it is an underscore (experimental) prop, it reprojects per fragment while clamping latitude to +/-89.9, and the quad corners at +/-90 project to infinite Mercator Y. Whether that renders correctly in the non-interleaved MapboxOverlay is uncertain, and nothing in the repo can pin it in a unit test. Mercator binning is exact, deterministic, and testable in plain JS. + +## Acceptance criteria + +1. Heatmap hot spots line up with the airport points at all latitudes up to +/-80 (verify visually at about 0, 40, and 65 degrees N). +2. The latitude mapping the shader uses and the bounds and projection of the BitmapLayer agree, and a unit test covers that. + +Checkable form: +- 1a. For any latitude in [-80, 80], the cell row the binning maps it to, when drawn by a BitmapLayer stretched linearly in Mercator Y over the layer's bounds, covers a latitude band that contains the input latitude (unit test over a sweep, plus named reference points 0, 40, 60, 65, -33.9). +- 1b. In a real browser with a WebGPU adapter (Chromium, `--enable-unsafe-webgpu --use-webgpu-adapter=swiftshader`), screenshots with HEATMAP and AIRPORTS on at about 0N (West Africa), 40N (US mid-Atlantic), and 65N (Scandinavia or Alaska) show hot spots on the airport dots, not shifted north. +- 2a. One JS module owns the Mercator latitude limit, the grid dimensions used for rows, the lat-to-row formula, and the BitmapLayer bounds. `buildLayers` uses its bounds and sets no `_imageCoordinateSystem`. The accumulate shader's WGSL binning code is generated from that module's constants (no second hand-typed copy of 85.051129 or of the row formula). +- 2b. A unit test asserts the BitmapLayer's bounds equal the helper's bounds, that the numeric constants embedded in the generated WGSL equal the JS constants, and that the old linear `(90.0 - lat) / 180.0` mapping is gone. +- 2c. Latitudes beyond +/-85.051129 (and +/-90) clamp to the first or last row instead of producing NaN or an out-of-range row. + +## Files that change + +- `src/layers/heatmapProjection.js` (new): exports `MERCATOR_MAX_LAT = 85.051129`, `HEATMAP_GRID_W = 1024`, `HEATMAP_GRID_H = 512`, `HEATMAP_BOUNDS` (`[-180, -MERCATOR_MAX_LAT, 180, MERCATOR_MAX_LAT]`), `mercatorY(lat)` (`ln(tan(pi/4 + lat*pi/360))` with lat clamped to +/-MERCATOR_MAX_LAT), `latToRowFraction(lat)` (`(1 - mercatorY(lat) / mercatorY(MERCATOR_MAX_LAT)) / 2`, 0 at the north edge, 1 at the south edge), `latToRow(lat, gridH = HEATMAP_GRID_H)` (floor of fraction times gridH, clamped to [0, gridH-1]), `lonToCol(lon, gridW = HEATMAP_GRID_W)` (same as the current shader), and `binningWGSL()` (or a constant string) returning WGSL functions `lonToCol(lon: f32) -> u32` and `latToRow(lat: f32) -> u32` that use the same formula, with the limit, its Mercator Y, and the grid sizes interpolated from the JS values as f32 literals (always with a decimal point). +- `src/layers/heatmapProjection.test.js` (new): reference points and the agreement sweep (1a), clamping (2c), WGSL constants (2b). +- `src/hooks/useGPUHeatmap.js`: import the grid sizes and WGSL from the helper, drop the local `GRID_W`/`GRID_H` constants, call the generated `lonToCol`/`latToRow` in `ACCUMULATE_SHADER`, and export `ACCUMULATE_SHADER` so a test can inspect it. Nothing else in the hook changes. +- `src/hooks/useGPUHeatmap.test.js`: add a test that `ACCUMULATE_SHADER` contains the generated binning code and no `(90.0 - lat) / 180.0`. +- `src/layers/index.js`: `bounds: HEATMAP_BOUNDS`. +- `src/layers/index.test.js`: assert heatmap layer bounds equal `HEATMAP_BOUNDS` and `_imageCoordinateSystem` is undefined. +- `README.md`: only if a line becomes false (Phase 8 decides). + +## Order of work + +1. Red: write `heatmapProjection.test.js` and the new assertions in `index.test.js` and `useGPUHeatmap.test.js`. Run `npm test`; record the failures. +2. Green: add `heatmapProjection.js`, wire it into `index.js` and `useGPUHeatmap.js`. +3. Full gate (`npm ci`, `npm run lint`, `npm test`, `npm run build`, `npm audit --omit=dev --audit-level=high`). +4. Live drive (below), on `npm run dev` or `npm run preview`. + +## Risks + +- f32 precision in WGSL: `log(tan(...))` near 85 degrees is fine in f32; the clamp to +/-MERCATOR_MAX_LAT keeps `tan` finite. Rows are floored after clamping the fraction to [0, 1) times gridH, then clamped to gridH-1. +- Floating literal formatting: a JS integer like 1024 interpolated as `1024` is an abstract int in WGSL; emit `1024.0` style f32 literals where floats are expected to avoid type errors. The live drive proves the shader compiles. +- Cell shape: a 1024x512 grid over the square Mercator world gives cells twice as tall as wide. Kept as is to stay in scope; alignment is what the issue asks for. +- Do not touch the hook's run-once behavior, buffer lifetimes, or the COLORIZE shader. Do not touch other prior work (a11y, layout, contrast tests, benchmark, RENDER label). + +What I chose not to do: change grid resolution, change the color ramp, add zoom-scaled radius (#9), or loading and error states (#10). + +## Proof + +- Criterion 1a, 2c: `src/layers/heatmapProjection.test.js`. +- Criterion 2a, 2b: `src/layers/index.test.js` and `src/hooks/useGPUHeatmap.test.js` plus `heatmapProjection.test.js` WGSL-constant tests. +- Criterion 1b: live drive in Playwright Chromium with a SwiftShader WebGPU adapter: HEATMAP and AIRPORTS on, screenshots at about 0N (e.g. lon 0, lat 7, zoom 4), 40N (lon -76, lat 39, zoom 5), and 65N (lon 18, lat 63, zoom 4 or Alaska lon -150, lat 63), plus a numeric check in the page: for a few airports, the heat pixel's screen position (from the rendered bitmap) is within one cell of `map.project([lon, lat])`. Before-and-after screenshots at 60N or 65N show the shift is gone. From 36543fc6eb10ab9f1e817b16b33b66deb87f29ec Mon Sep 17 00:00:00 2001 From: Brad Stricherz Date: Sat, 7 Nov 2026 21:01:49 -0600 Subject: [PATCH 2/6] test: add failing tests for Mercator heatmap binning and bounds agreement (#15) The accumulate shader bins latitude linearly over [-90, 90] while the BitmapLayer stretches the image linearly in Mercator Y over +/-85.051129, so hot spots drift north away from airports. These tests pin a shared projection helper, its generated WGSL, and the layer bounds. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf --- src/hooks/useGPUHeatmap.test.js | 19 ++- src/layers/heatmapProjection.test.js | 167 +++++++++++++++++++++++++++ src/layers/index.test.js | 14 ++- 3 files changed, 197 insertions(+), 3 deletions(-) create mode 100644 src/layers/heatmapProjection.test.js diff --git a/src/hooks/useGPUHeatmap.test.js b/src/hooks/useGPUHeatmap.test.js index 11d85df..89bd666 100644 --- a/src/hooks/useGPUHeatmap.test.js +++ b/src/hooks/useGPUHeatmap.test.js @@ -1,6 +1,7 @@ import { describe, it, expect } from 'vitest' import { renderHook } from '@testing-library/react' -import { useGPUHeatmap, buildPointsData } from './useGPUHeatmap.js' +import { useGPUHeatmap, buildPointsData, ACCUMULATE_SHADER } from './useGPUHeatmap.js' +import { binningWGSL } from '../layers/heatmapProjection.js' describe('buildPointsData', () => { it('returns a Float32Array of length airportCount * 2', () => { @@ -44,4 +45,18 @@ describe('useGPUHeatmap', () => { it('does not throw when airports array is empty', () => { expect(() => renderHook(() => useGPUHeatmap([]))).not.toThrow() }) -}) \ No newline at end of file +}) +describe('ACCUMULATE_SHADER binning', () => { + it('includes the generated Mercator binning functions', () => { + expect(ACCUMULATE_SHADER).toContain(binningWGSL()) + }) + + it('bins each point with the generated lonToCol and latToRow', () => { + expect(ACCUMULATE_SHADER).toMatch(/lonToCol\(\s*lon\s*\)/) + expect(ACCUMULATE_SHADER).toMatch(/latToRow\(\s*lat\s*\)/) + }) + + it('no longer uses the linear equirectangular latitude mapping', () => { + expect(ACCUMULATE_SHADER).not.toContain('(90.0 - lat) / 180.0') + }) +}) diff --git a/src/layers/heatmapProjection.test.js b/src/layers/heatmapProjection.test.js new file mode 100644 index 0000000..0ac7a30 --- /dev/null +++ b/src/layers/heatmapProjection.test.js @@ -0,0 +1,167 @@ +import { describe, it, expect } from 'vitest' +import { + MERCATOR_MAX_LAT, + HEATMAP_GRID_W, + HEATMAP_GRID_H, + HEATMAP_BOUNDS, + mercatorY, + latToRowFraction, + latToRow, + lonToCol, + binningWGSL, +} from './heatmapProjection.js' + +// Independent reference math, written here so the test does not trust the module. +const DEG = Math.PI / 180 +const refMercY = (lat) => Math.log(Math.tan(Math.PI / 4 + (lat * DEG) / 2)) +const refInvMercY = (y) => (2 * Math.atan(Math.exp(y)) - Math.PI / 2) / DEG + +/** + * The latitude band a BitmapLayer draws image row `row` over, when the image + * is stretched linearly in Mercator Y across [south, north] (deck.gl default + * image coordinate system for a non-geospatial-reprojected bitmap). + */ +function rowBand(row, bounds, gridH) { + const yTop = refMercY(bounds[3]) + const yBottom = refMercY(bounds[1]) + const step = (yTop - yBottom) / gridH + const north = refInvMercY(yTop - row * step) + const south = refInvMercY(yTop - (row + 1) * step) + return { north, south } +} + +describe('heatmapProjection constants', () => { + it('uses the Web Mercator latitude limit', () => { + expect(MERCATOR_MAX_LAT).toBe(85.051129) + }) + + it('keeps the existing grid size', () => { + expect(HEATMAP_GRID_W).toBe(1024) + expect(HEATMAP_GRID_H).toBe(512) + }) + + it('bounds span the full Mercator world', () => { + expect(HEATMAP_BOUNDS).toEqual([-180, -MERCATOR_MAX_LAT, 180, MERCATOR_MAX_LAT]) + }) + + it('mercatorY matches the reference formula', () => { + for (const lat of [-80, -33.9, 0, 40, 65, 80]) { + expect(mercatorY(lat)).toBeCloseTo(refMercY(lat), 10) + } + }) + + it('the Mercator limit is the latitude whose Mercator Y is pi', () => { + expect(mercatorY(MERCATOR_MAX_LAT)).toBeCloseTo(Math.PI, 5) + }) +}) + +describe('latToRow agrees with a Mercator-stretched bitmap (criterion 1a)', () => { + it('equator lands on the middle rows', () => { + expect(latToRowFraction(0)).toBeCloseTo(0.5, 10) + expect(latToRow(0)).toBe(HEATMAP_GRID_H / 2) + }) + + it('reference latitudes fall inside the band their row is drawn over', () => { + for (const lat of [0, 40, 60, 65, -33.9]) { + const row = latToRow(lat) + const { north, south } = rowBand(row, HEATMAP_BOUNDS, HEATMAP_GRID_H) + expect(lat).toBeLessThanOrEqual(north + 1e-9) + expect(lat).toBeGreaterThanOrEqual(south - 1e-9) + } + }) + + it('65N maps to a row far from what the old linear mapping gave', () => { + // Old: floor((90 - 65) / 180 * 512) = 71. Under Mercator it is much nearer the top. + const oldRow = Math.floor(((90 - 65) / 180) * HEATMAP_GRID_H) + expect(oldRow).toBe(71) + expect(latToRow(65)).not.toBe(oldRow) + const { north, south } = rowBand(oldRow, HEATMAP_BOUNDS, HEATMAP_GRID_H) + // The old row is drawn north of 65N, which is the reported shift. + expect(south).toBeGreaterThan(65) + expect(north).toBeGreaterThan(65) + }) + + it('every latitude in [-80, 80] lands in the band its row is drawn over', () => { + for (let lat = -80; lat <= 80; lat += 0.05) { + const row = latToRow(lat) + const { north, south } = rowBand(row, HEATMAP_BOUNDS, HEATMAP_GRID_H) + expect(lat).toBeLessThanOrEqual(north + 1e-9) + expect(lat).toBeGreaterThanOrEqual(south - 1e-9) + } + }) + + it('rows increase monotonically southward', () => { + let prev = -1 + for (let lat = 85; lat >= -85; lat -= 0.5) { + const row = latToRow(lat) + expect(row).toBeGreaterThanOrEqual(prev) + prev = row + } + }) +}) + +describe('clamping (criterion 2c)', () => { + it('latitudes at or beyond the north limit clamp to row 0', () => { + for (const lat of [MERCATOR_MAX_LAT, 86, 89.999, 90, 120]) { + expect(latToRow(lat)).toBe(0) + } + }) + + it('latitudes at or beyond the south limit clamp to the last row', () => { + for (const lat of [-MERCATOR_MAX_LAT, -86, -90, -120]) { + expect(latToRow(lat)).toBe(HEATMAP_GRID_H - 1) + } + }) + + it('never returns NaN for extreme latitudes', () => { + for (const lat of [90, -90]) { + expect(Number.isFinite(mercatorY(lat))).toBe(true) + expect(Number.isFinite(latToRowFraction(lat))).toBe(true) + } + }) + + it('lonToCol clamps to [0, gridW - 1]', () => { + expect(lonToCol(-180)).toBe(0) + expect(lonToCol(180)).toBe(HEATMAP_GRID_W - 1) + expect(lonToCol(0)).toBe(HEATMAP_GRID_W / 2) + expect(lonToCol(-500)).toBe(0) + expect(lonToCol(500)).toBe(HEATMAP_GRID_W - 1) + }) + + it('latToRow and lonToCol honor custom grid sizes', () => { + expect(latToRow(0, 8)).toBe(4) + expect(latToRow(90, 8)).toBe(0) + expect(latToRow(-90, 8)).toBe(7) + expect(lonToCol(0, 8)).toBe(4) + }) +}) + +describe('binningWGSL (criterion 2b)', () => { + const wgsl = binningWGSL() + const floats = (wgsl.match(/-?\d+\.\d+/g) ?? []).map(Number) + + it('declares lonToCol and latToRow WGSL functions', () => { + expect(wgsl).toMatch(/fn\s+lonToCol\s*\(\s*lon\s*:\s*f32\s*\)\s*->\s*u32/) + expect(wgsl).toMatch(/fn\s+latToRow\s*\(\s*lat\s*:\s*f32\s*\)\s*->\s*u32/) + }) + + it('embeds the JS latitude limit', () => { + expect(floats).toContain(MERCATOR_MAX_LAT) + }) + + it('embeds the Mercator Y of the limit computed in JS', () => { + const target = mercatorY(MERCATOR_MAX_LAT) + expect(floats.some((v) => Math.abs(v - target) < 1e-9)).toBe(true) + }) + + it('embeds the grid sizes as f32 literals with a decimal point', () => { + expect(wgsl).toContain(`${HEATMAP_GRID_W}.0`) + expect(wgsl).toContain(`${HEATMAP_GRID_H}.0`) + }) + + it('uses a Mercator log-tan formula, not the old linear one', () => { + expect(wgsl).toMatch(/log\s*\(\s*tan\s*\(/) + expect(wgsl).not.toContain('(90.0 - lat) / 180.0') + expect(wgsl).not.toMatch(/\b90\.0\b/) + }) +}) diff --git a/src/layers/index.test.js b/src/layers/index.test.js index aa5d499..28cd432 100644 --- a/src/layers/index.test.js +++ b/src/layers/index.test.js @@ -10,6 +10,7 @@ vi.mock('@deck.gl/layers', () => ({ })) import { buildLayers } from './index.js' +import { HEATMAP_BOUNDS } from './heatmapProjection.js' const mockAirport = { lon: 10, lat: 20, name: 'Test Airport', type: 'large_airport' } const mockPort = { lon: 30, lat: 40, name: 'Test Port' } @@ -209,4 +210,15 @@ describe('buildLayers', () => { const layer = layers.find((l) => l.id === 'heatmap') expect(layer.props.bounds).toEqual([-180, -85.051129, 180, 85.051129]) }) -}) \ No newline at end of file + + it('heatmap layer bounds come from the shared projection helper', () => { + const layers = buildLayers( + { airports: false, ports: false, heatmap: true }, + { airports: [], ports: [], heatmapCanvas: mockCanvas }, + vi.fn() + ) + const layer = layers.find((l) => l.id === 'heatmap') + expect(layer.props.bounds).toEqual(HEATMAP_BOUNDS) + expect(layer.props._imageCoordinateSystem).toBeUndefined() + }) +}) From 8fdf28f96e2cbe62bbe60fbbbb750d11bcfe6080 Mon Sep 17 00:00:00 2001 From: Brad Stricherz Date: Sat, 7 Nov 2026 21:02:26 -0600 Subject: [PATCH 3/6] fix: bin GPU heatmap latitude in Web Mercator to match bitmap bounds (#15) The accumulate shader mapped latitude linearly over [-90, 90], but the BitmapLayer draws the image linearly in Mercator Y over +/-85.051129, so heat drifted north of airports at mid and high latitudes. A new heatmapProjection module owns the latitude limit, grid size, bounds, and lat-to-row formula, and generates the shader's binning WGSL from those constants so the two cannot drift apart again. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf --- src/hooks/useGPUHeatmap.js | 14 +++--- src/layers/heatmapProjection.js | 84 +++++++++++++++++++++++++++++++++ src/layers/index.js | 3 +- 3 files changed, 92 insertions(+), 9 deletions(-) create mode 100644 src/layers/heatmapProjection.js diff --git a/src/hooks/useGPUHeatmap.js b/src/hooks/useGPUHeatmap.js index 92019ee..f2d43f1 100644 --- a/src/hooks/useGPUHeatmap.js +++ b/src/hooks/useGPUHeatmap.js @@ -1,19 +1,18 @@ import { useState, useEffect, useRef } from 'react' +import { HEATMAP_GRID_W as GRID_W, HEATMAP_GRID_H as GRID_H, binningWGSL } from '../layers/heatmapProjection.js' -const GRID_W = 1024 -const GRID_H = 512 const GRID_SIZE = GRID_W * GRID_H const WORKGROUP_SIZE = 256 // ---- WGSL shaders -------------------------------------------------------- -const ACCUMULATE_SHADER = ` +export const ACCUMULATE_SHADER = ` struct Params { count: u32 } @group(0) @binding(0) var points: array>; @group(0) @binding(1) var params: Params; @group(0) @binding(2) var grid: array>; - +${binningWGSL()} @compute @workgroup_size(${WORKGROUP_SIZE}) fn main(@builtin(global_invocation_id) gid: vec3) { let i = gid.x; @@ -22,10 +21,9 @@ fn main(@builtin(global_invocation_id) gid: vec3) { let lon = points[i].x; let lat = points[i].y; - // Map lon [-180, 180] -> col [0, GRID_W-1] - let col = u32(clamp((lon + 180.0) / 360.0 * f32(${GRID_W}), 0.0, f32(${GRID_W} - 1u))); - // Map lat [-90, 90] -> row [0, GRID_H-1] (north at row 0) - let row = u32(clamp((90.0 - lat) / 180.0 * f32(${GRID_H}), 0.0, f32(${GRID_H} - 1u))); + // Bin in Web Mercator to match the BitmapLayer bounds (see heatmapProjection.js) + let col = lonToCol(lon); + let row = latToRow(lat); atomicAdd(&grid[row * ${GRID_W}u + col], 1u); } diff --git a/src/layers/heatmapProjection.js b/src/layers/heatmapProjection.js new file mode 100644 index 0000000..71bf314 --- /dev/null +++ b/src/layers/heatmapProjection.js @@ -0,0 +1,84 @@ +// Single source of truth for how the GPU heatmap grid maps to the map. +// +// The heatmap image is drawn by a deck.gl BitmapLayer over HEATMAP_BOUNDS with +// the default image coordinate system, which stretches the image linearly in +// Web Mercator Y. The accumulate shader therefore bins latitude in Mercator Y +// too, using WGSL generated from the constants below, so a point's cell is +// drawn where the point is. + +export const MERCATOR_MAX_LAT = 85.051129 +export const HEATMAP_GRID_W = 1024 +export const HEATMAP_GRID_H = 512 +export const HEATMAP_BOUNDS = [-180, -MERCATOR_MAX_LAT, 180, MERCATOR_MAX_LAT] + +const QUARTER_PI = Math.PI / 4 +const HALF_DEG_TO_RAD = Math.PI / 360 + +/** + * Web Mercator Y (in radians of the unit sphere) for a latitude in degrees, + * with latitude clamped to +/-MERCATOR_MAX_LAT so the result is always finite. + * @param {number} lat + * @returns {number} + */ +export function mercatorY(lat) { + const clamped = Math.min(Math.max(lat, -MERCATOR_MAX_LAT), MERCATOR_MAX_LAT) + return Math.log(Math.tan(QUARTER_PI + clamped * HALF_DEG_TO_RAD)) +} + +const MERCATOR_MAX_Y = mercatorY(MERCATOR_MAX_LAT) + +/** + * Fraction of the image height from the north edge (0) to the south edge (1). + * @param {number} lat + * @returns {number} + */ +export function latToRowFraction(lat) { + return (1 - mercatorY(lat) / MERCATOR_MAX_Y) / 2 +} + +/** + * @param {number} lat + * @param {number} [gridH] + * @returns {number} row in [0, gridH - 1], north at row 0 + */ +export function latToRow(lat, gridH = HEATMAP_GRID_H) { + const row = Math.floor(latToRowFraction(lat) * gridH) + return Math.min(Math.max(row, 0), gridH - 1) +} + +/** + * @param {number} lon + * @param {number} [gridW] + * @returns {number} column in [0, gridW - 1] + */ +export function lonToCol(lon, gridW = HEATMAP_GRID_W) { + const col = Math.floor(((lon + 180) / 360) * gridW) + return Math.min(Math.max(col, 0), gridW - 1) +} + +/** Format a JS number as a WGSL f32 literal (always with a decimal point). */ +function f32(value) { + return Number.isInteger(value) ? `${value}.0` : String(value) +} + +/** + * WGSL functions `lonToCol(lon: f32) -> u32` and `latToRow(lat: f32) -> u32` + * matching the JS helpers above, with every constant interpolated from JS. + * @returns {string} + */ +export function binningWGSL() { + return ` +fn lonToCol(lon: f32) -> u32 { + let c = floor((lon + 180.0) / 360.0 * ${f32(HEATMAP_GRID_W)}); + return u32(clamp(c, 0.0, ${f32(HEATMAP_GRID_W - 1)})); +} + +fn latToRow(lat: f32) -> u32 { + let clamped = clamp(lat, ${f32(-MERCATOR_MAX_LAT)}, ${f32(MERCATOR_MAX_LAT)}); + let y = log(tan(${f32(QUARTER_PI)} + clamped * ${f32(HALF_DEG_TO_RAD)})); + let fraction = (1.0 - y / ${f32(MERCATOR_MAX_Y)}) / 2.0; + let r = floor(fraction * ${f32(HEATMAP_GRID_H)}); + return u32(clamp(r, 0.0, ${f32(HEATMAP_GRID_H - 1)})); +} +` +} diff --git a/src/layers/index.js b/src/layers/index.js index ccc10bd..4c41c42 100644 --- a/src/layers/index.js +++ b/src/layers/index.js @@ -1,4 +1,5 @@ import { ScatterplotLayer, BitmapLayer } from '@deck.gl/layers' +import { HEATMAP_BOUNDS } from './heatmapProjection.js' /** * Builds the deck.gl layer array from current visibility and data state. @@ -14,7 +15,7 @@ export function buildLayers(layerVisibility, data, onFeatureClick) { layers.push( new BitmapLayer({ id: 'heatmap', - bounds: [-180, -85.051129, 180, 85.051129], + bounds: HEATMAP_BOUNDS, image: data.heatmapCanvas, opacity: 0.6, fetch: (url) => From 35f7193468395aa11e8bacfdde8083e31fe8ad0c Mon Sep 17 00:00:00 2001 From: Brad Stricherz Date: Sat, 7 Nov 2026 21:18:41 -0600 Subject: [PATCH 4/6] test: execute generated WGSL binning and compare with JS helpers (#15) The WGSL lonToCol and latToRow bodies restate the formulas in shader syntax, and no test ran them, so a broken shader formula stayed green. The new test translates the generated WGSL into JS with a strict translator that rejects unknown tokens, then checks it against the JS helpers at reference points, past the Mercator and polar limits, and over full lat and lon sweeps. The plan now records this coverage and describes the row clamping as the code does it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf --- ...1-07-issue-15-gpu-heatmap-misregistered.md | 9 +- src/layers/heatmapProjection.wgsl.test.js | 102 ++++++++++++++++++ 2 files changed, 107 insertions(+), 4 deletions(-) create mode 100644 src/layers/heatmapProjection.wgsl.test.js diff --git a/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md index 4130b40..978912b 100644 --- a/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md +++ b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md @@ -23,14 +23,15 @@ Rejected: `_imageCoordinateSystem: COORDINATE_SYSTEM.LNGLAT` with bounds `[-180, Checkable form: - 1a. For any latitude in [-80, 80], the cell row the binning maps it to, when drawn by a BitmapLayer stretched linearly in Mercator Y over the layer's bounds, covers a latitude band that contains the input latitude (unit test over a sweep, plus named reference points 0, 40, 60, 65, -33.9). - 1b. In a real browser with a WebGPU adapter (Chromium, `--enable-unsafe-webgpu --use-webgpu-adapter=swiftshader`), screenshots with HEATMAP and AIRPORTS on at about 0N (West Africa), 40N (US mid-Atlantic), and 65N (Scandinavia or Alaska) show hot spots on the airport dots, not shifted north. -- 2a. One JS module owns the Mercator latitude limit, the grid dimensions used for rows, the lat-to-row formula, and the BitmapLayer bounds. `buildLayers` uses its bounds and sets no `_imageCoordinateSystem`. The accumulate shader's WGSL binning code is generated from that module's constants (no second hand-typed copy of 85.051129 or of the row formula). -- 2b. A unit test asserts the BitmapLayer's bounds equal the helper's bounds, that the numeric constants embedded in the generated WGSL equal the JS constants, and that the old linear `(90.0 - lat) / 180.0` mapping is gone. +- 2a. One JS module owns the Mercator latitude limit, the grid dimensions used for rows, the lat-to-row formula, and the BitmapLayer bounds. `buildLayers` uses its bounds and sets no `_imageCoordinateSystem`. The accumulate shader's WGSL binning code is generated from that module's constants (no second hand-typed copy of 85.051129). The WGSL bodies do restate the row and column formulas in WGSL syntax, so a test executes the generated WGSL (2b) to prove they match the JS helpers. +- 2b. A unit test asserts the BitmapLayer's bounds equal the helper's bounds, that the numeric constants embedded in the generated WGSL equal the JS constants, and that the old linear `(90.0 - lat) / 180.0` mapping is gone. A second test translates the generated WGSL `lonToCol` and `latToRow` mechanically into JS (failing on any token it does not know) and asserts they return the same values as the JS helpers at the reference points, at and beyond +/-85.051129 and +/-90, and over sweeps of lat -85..85 and lon -180..180. - 2c. Latitudes beyond +/-85.051129 (and +/-90) clamp to the first or last row instead of producing NaN or an out-of-range row. ## Files that change - `src/layers/heatmapProjection.js` (new): exports `MERCATOR_MAX_LAT = 85.051129`, `HEATMAP_GRID_W = 1024`, `HEATMAP_GRID_H = 512`, `HEATMAP_BOUNDS` (`[-180, -MERCATOR_MAX_LAT, 180, MERCATOR_MAX_LAT]`), `mercatorY(lat)` (`ln(tan(pi/4 + lat*pi/360))` with lat clamped to +/-MERCATOR_MAX_LAT), `latToRowFraction(lat)` (`(1 - mercatorY(lat) / mercatorY(MERCATOR_MAX_LAT)) / 2`, 0 at the north edge, 1 at the south edge), `latToRow(lat, gridH = HEATMAP_GRID_H)` (floor of fraction times gridH, clamped to [0, gridH-1]), `lonToCol(lon, gridW = HEATMAP_GRID_W)` (same as the current shader), and `binningWGSL()` (or a constant string) returning WGSL functions `lonToCol(lon: f32) -> u32` and `latToRow(lat: f32) -> u32` that use the same formula, with the limit, its Mercator Y, and the grid sizes interpolated from the JS values as f32 literals (always with a decimal point). - `src/layers/heatmapProjection.test.js` (new): reference points and the agreement sweep (1a), clamping (2c), WGSL constants (2b). +- `src/layers/heatmapProjection.wgsl.test.js` (new, added after review): executes the generated WGSL binning functions via a strict WGSL-to-JS translator and compares them with the JS helpers (2b). - `src/hooks/useGPUHeatmap.js`: import the grid sizes and WGSL from the helper, drop the local `GRID_W`/`GRID_H` constants, call the generated `lonToCol`/`latToRow` in `ACCUMULATE_SHADER`, and export `ACCUMULATE_SHADER` so a test can inspect it. Nothing else in the hook changes. - `src/hooks/useGPUHeatmap.test.js`: add a test that `ACCUMULATE_SHADER` contains the generated binning code and no `(90.0 - lat) / 180.0`. - `src/layers/index.js`: `bounds: HEATMAP_BOUNDS`. @@ -46,7 +47,7 @@ Checkable form: ## Risks -- f32 precision in WGSL: `log(tan(...))` near 85 degrees is fine in f32; the clamp to +/-MERCATOR_MAX_LAT keeps `tan` finite. Rows are floored after clamping the fraction to [0, 1) times gridH, then clamped to gridH-1. +- f32 precision in WGSL: `log(tan(...))` near 85 degrees is fine in f32; the clamp to +/-MERCATOR_MAX_LAT keeps `tan` finite. The latitude is clamped to +/-MERCATOR_MAX_LAT first, so the fraction is always finite and in [0, 1]; the row is the floor of fraction times gridH, then clamped to [0, gridH-1] (this maps the south limit, fraction 1, to the last row). - Floating literal formatting: a JS integer like 1024 interpolated as `1024` is an abstract int in WGSL; emit `1024.0` style f32 literals where floats are expected to avoid type errors. The live drive proves the shader compiles. - Cell shape: a 1024x512 grid over the square Mercator world gives cells twice as tall as wide. Kept as is to stay in scope; alignment is what the issue asks for. - Do not touch the hook's run-once behavior, buffer lifetimes, or the COLORIZE shader. Do not touch other prior work (a11y, layout, contrast tests, benchmark, RENDER label). @@ -56,5 +57,5 @@ What I chose not to do: change grid resolution, change the color ramp, add zoom- ## Proof - Criterion 1a, 2c: `src/layers/heatmapProjection.test.js`. -- Criterion 2a, 2b: `src/layers/index.test.js` and `src/hooks/useGPUHeatmap.test.js` plus `heatmapProjection.test.js` WGSL-constant tests. +- Criterion 2a, 2b: `src/layers/index.test.js` and `src/hooks/useGPUHeatmap.test.js` plus `heatmapProjection.test.js` WGSL-constant tests, and `heatmapProjection.wgsl.test.js`, which executes the generated WGSL row and column formulas and compares them with the JS helpers (shown to fail when the WGSL `/ 2.0` becomes `* 2.0`, when `1.0 -` is dropped, or when `+ 180.0` is dropped). - Criterion 1b: live drive in Playwright Chromium with a SwiftShader WebGPU adapter: HEATMAP and AIRPORTS on, screenshots at about 0N (e.g. lon 0, lat 7, zoom 4), 40N (lon -76, lat 39, zoom 5), and 65N (lon 18, lat 63, zoom 4 or Alaska lon -150, lat 63), plus a numeric check in the page: for a few airports, the heat pixel's screen position (from the rendered bitmap) is within one cell of `map.project([lon, lat])`. Before-and-after screenshots at 60N or 65N show the shift is gone. diff --git a/src/layers/heatmapProjection.wgsl.test.js b/src/layers/heatmapProjection.wgsl.test.js new file mode 100644 index 0000000..9b3fba6 --- /dev/null +++ b/src/layers/heatmapProjection.wgsl.test.js @@ -0,0 +1,102 @@ +import { describe, it, expect } from 'vitest' +import { + MERCATOR_MAX_LAT, + latToRow, + lonToCol, + binningWGSL, +} from './heatmapProjection.js' + +// Executes the generated WGSL binning functions by translating them +// mechanically into JS. The translator only knows the WGSL subset the +// generator emits today; anything else throws, so a future edit to the WGSL +// cannot silently fall out of coverage. + +const BUILTINS = { + floor: Math.floor, + log: Math.log, + tan: Math.tan, + clamp: (x, lo, hi) => Math.min(Math.max(x, lo), hi), + u32: (x) => { + if (!Number.isFinite(x) || x < 0) throw new Error(`u32() of ${x} is out of range`) + return Math.trunc(x) + }, +} +const KEYWORDS = new Set(['function', 'const', 'return']) + +function translateWGSL(wgsl) { + const declared = new Set() + let src = wgsl.replace( + /\bfn\s+(\w+)\s*\(([^)]*)\)\s*->\s*(\w+)/g, + (_, name, params, ret) => { + if (ret !== 'u32') throw new Error(`unsupported return type ${ret}`) + const names = params.split(',').map((p) => { + const m = p.trim().match(/^(\w+)\s*:\s*f32$/) + if (!m) throw new Error(`unsupported parameter "${p.trim()}"`) + declared.add(m[1]) + return m[1] + }) + declared.add(name) + return `function ${name}(${names.join(', ')})` + } + ) + src = src.replace(/\blet\s+(\w+)/g, (_, name) => { + declared.add(name) + return `const ${name}` + }) + + const bad = src.match(/[^\w\s.(){}+\-*/=,;]/) + if (bad) throw new Error(`unknown character "${bad[0]}" in WGSL`) + for (const tok of src.match(/[A-Za-z_]\w*/g) ?? []) { + if (!KEYWORDS.has(tok) && !declared.has(tok) && !(tok in BUILTINS)) { + throw new Error(`unknown WGSL token "${tok}"`) + } + } + if (!declared.has('lonToCol') || !declared.has('latToRow')) { + throw new Error('WGSL is missing lonToCol or latToRow') + } + + const names = Object.keys(BUILTINS) + const factory = new Function(...names, `${src}\nreturn { lonToCol, latToRow }`) + return factory(...names.map((n) => BUILTINS[n])) +} + +describe('translateWGSL', () => { + it('throws on a WGSL token it does not know', () => { + const wgsl = 'fn latToRow(lat: f32) -> u32 { return u32(select(0.0, 1.0, lat > 0.0)); }' + expect(() => translateWGSL(wgsl)).toThrow() + }) + + it('throws on an unknown identifier', () => { + const wgsl = 'fn lonToCol(lon: f32) -> u32 { return u32(abs(lon)); }\nfn latToRow(lat: f32) -> u32 { return u32(lat); }' + expect(() => translateWGSL(wgsl)).toThrow(/abs/) + }) +}) + +describe('generated WGSL binning executes like the JS helpers', () => { + const gpu = translateWGSL(binningWGSL()) + + it('latToRow matches at reference latitudes and beyond the limits', () => { + const lats = [0, 40, 60, 65, -33.9, MERCATOR_MAX_LAT, -MERCATOR_MAX_LAT, 90, -90, 120, -120] + for (const lat of lats) { + expect(gpu.latToRow(lat), `lat ${lat}`).toBe(latToRow(lat)) + } + }) + + it('latToRow matches over a sweep of -85 to 85', () => { + for (let lat = -85; lat <= 85; lat += 0.01) { + expect(gpu.latToRow(lat)).toBe(latToRow(lat)) + } + }) + + it('lonToCol matches at reference longitudes and beyond the limits', () => { + for (const lon of [-180, -179.9, -0.0001, 0, 0.0001, 18, 151.18, 179.9, 180, -500, 500]) { + expect(gpu.lonToCol(lon), `lon ${lon}`).toBe(lonToCol(lon)) + } + }) + + it('lonToCol matches over a sweep of -180 to 180', () => { + for (let lon = -180; lon <= 180; lon += 0.01) { + expect(gpu.lonToCol(lon)).toBe(lonToCol(lon)) + } + }) +}) From 7589af68303bc826fd72d945d48033ed3dab1fc6 Mon Sep 17 00:00:00 2001 From: Brad Stricherz Date: Sat, 7 Nov 2026 21:23:01 -0600 Subject: [PATCH 5/6] test: emulate f32 in WGSL binning test and pin rejection messages (#15) In float64 the south limit gives a row fraction just under 1, so the shader's row clamp was never exercised; on the GPU, in f32, it is exactly 1 and the clamp is what keeps the row inside the grid. The translator is now a small parser that can emit f32-rounded JS, and new tests assert rows and columns stay in range, extremes land on the edge rows and columns, and sweeps stay within one cell of the JS helpers. Each translator rejection test now asserts the error for its own path. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf --- ...1-07-issue-15-gpu-heatmap-misregistered.md | 3 +- src/layers/heatmapProjection.wgsl.test.js | 286 ++++++++++++++---- 2 files changed, 234 insertions(+), 55 deletions(-) diff --git a/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md index 978912b..7d3cd8d 100644 --- a/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md +++ b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md @@ -31,7 +31,7 @@ Checkable form: - `src/layers/heatmapProjection.js` (new): exports `MERCATOR_MAX_LAT = 85.051129`, `HEATMAP_GRID_W = 1024`, `HEATMAP_GRID_H = 512`, `HEATMAP_BOUNDS` (`[-180, -MERCATOR_MAX_LAT, 180, MERCATOR_MAX_LAT]`), `mercatorY(lat)` (`ln(tan(pi/4 + lat*pi/360))` with lat clamped to +/-MERCATOR_MAX_LAT), `latToRowFraction(lat)` (`(1 - mercatorY(lat) / mercatorY(MERCATOR_MAX_LAT)) / 2`, 0 at the north edge, 1 at the south edge), `latToRow(lat, gridH = HEATMAP_GRID_H)` (floor of fraction times gridH, clamped to [0, gridH-1]), `lonToCol(lon, gridW = HEATMAP_GRID_W)` (same as the current shader), and `binningWGSL()` (or a constant string) returning WGSL functions `lonToCol(lon: f32) -> u32` and `latToRow(lat: f32) -> u32` that use the same formula, with the limit, its Mercator Y, and the grid sizes interpolated from the JS values as f32 literals (always with a decimal point). - `src/layers/heatmapProjection.test.js` (new): reference points and the agreement sweep (1a), clamping (2c), WGSL constants (2b). -- `src/layers/heatmapProjection.wgsl.test.js` (new, added after review): executes the generated WGSL binning functions via a strict WGSL-to-JS translator and compares them with the JS helpers (2b). +- `src/layers/heatmapProjection.wgsl.test.js` (new, added after review): executes the generated WGSL binning functions via a strict WGSL-to-JS translator (each rejection path asserts its own error) and compares them with the JS helpers: exactly in float64 (2b), and under f32 emulation (Math.fround on every literal, parameter, operator and builtin result) asserting rows and columns stay in the grid, extremes land on the first or last row and column, and sweeps stay within one cell of the JS helpers (2c). - `src/hooks/useGPUHeatmap.js`: import the grid sizes and WGSL from the helper, drop the local `GRID_W`/`GRID_H` constants, call the generated `lonToCol`/`latToRow` in `ACCUMULATE_SHADER`, and export `ACCUMULATE_SHADER` so a test can inspect it. Nothing else in the hook changes. - `src/hooks/useGPUHeatmap.test.js`: add a test that `ACCUMULATE_SHADER` contains the generated binning code and no `(90.0 - lat) / 180.0`. - `src/layers/index.js`: `bounds: HEATMAP_BOUNDS`. @@ -58,4 +58,5 @@ What I chose not to do: change grid resolution, change the color ramp, add zoom- - Criterion 1a, 2c: `src/layers/heatmapProjection.test.js`. - Criterion 2a, 2b: `src/layers/index.test.js` and `src/hooks/useGPUHeatmap.test.js` plus `heatmapProjection.test.js` WGSL-constant tests, and `heatmapProjection.wgsl.test.js`, which executes the generated WGSL row and column formulas and compares them with the JS helpers (shown to fail when the WGSL `/ 2.0` becomes `* 2.0`, when `1.0 -` is dropped, or when `+ 180.0` is dropped). +- Criterion 2c on the GPU path: the f32-emulated tests in `heatmapProjection.wgsl.test.js` (in f32 the fraction at -85.051129 is exactly 1 and at +85.051129 slightly negative, so the row clamp is what keeps rows in [0, 511]; shown to fail when the upper clamp becomes `512.0` or `600.0` or the lower clamp becomes `-5.0`). - Criterion 1b: live drive in Playwright Chromium with a SwiftShader WebGPU adapter: HEATMAP and AIRPORTS on, screenshots at about 0N (e.g. lon 0, lat 7, zoom 4), 40N (lon -76, lat 39, zoom 5), and 65N (lon 18, lat 63, zoom 4 or Alaska lon -150, lat 63), plus a numeric check in the page: for a few airports, the heat pixel's screen position (from the rendered bitmap) is within one cell of `map.project([lon, lat])`. Before-and-after screenshots at 60N or 65N show the shift is gone. diff --git a/src/layers/heatmapProjection.wgsl.test.js b/src/layers/heatmapProjection.wgsl.test.js index 9b3fba6..82babd2 100644 --- a/src/layers/heatmapProjection.wgsl.test.js +++ b/src/layers/heatmapProjection.wgsl.test.js @@ -1,79 +1,218 @@ import { describe, it, expect } from 'vitest' import { MERCATOR_MAX_LAT, + HEATMAP_GRID_W, + HEATMAP_GRID_H, latToRow, lonToCol, binningWGSL, } from './heatmapProjection.js' -// Executes the generated WGSL binning functions by translating them -// mechanically into JS. The translator only knows the WGSL subset the -// generator emits today; anything else throws, so a future edit to the WGSL -// cannot silently fall out of coverage. - -const BUILTINS = { - floor: Math.floor, - log: Math.log, - tan: Math.tan, - clamp: (x, lo, hi) => Math.min(Math.max(x, lo), hi), - u32: (x) => { - if (!Number.isFinite(x) || x < 0) throw new Error(`u32() of ${x} is out of range`) - return Math.trunc(x) - }, +// Executes the generated WGSL binning functions by parsing them and emitting +// JS. The parser only knows the WGSL subset the generator emits today +// (fn with f32 params returning u32, let, return, + - * /, unary minus, +// calls to floor/log/tan/clamp/u32); anything else throws, so a future edit +// to the WGSL cannot silently fall out of coverage. +// +// Two modes: +// - f64: plain JS doubles, for exact agreement with the JS helpers. +// - f32: every literal, parameter, operator result and builtin result is +// rounded with Math.fround, to emulate what the GPU computes. +// +// u32() here throws on a negative or out-of-range input instead of +// saturating, so the shader must clamp explicitly rather than rely on the +// conversion. + +const BUILTINS = new Set(['floor', 'log', 'tan', 'clamp', 'u32']) + +function tokenize(src) { + const tokens = [] + const re = /\s*(?:(\d+\.\d+|\d+)|([A-Za-z_]\w*)|(->|[(){},;:=+\-*/]))/y + let pos = 0 + while (pos < src.length) { + if (/^\s*$/.test(src.slice(pos))) break + re.lastIndex = pos + const m = re.exec(src) + if (!m) { + const ch = src.slice(pos).trimStart()[0] + throw new Error(`unknown character "${ch}" in WGSL`) + } + pos = re.lastIndex + if (m[1]) tokens.push({ t: 'num', v: m[1] }) + else if (m[2]) tokens.push({ t: 'id', v: m[2] }) + else tokens.push({ t: 'op', v: m[3] }) + } + return tokens } -const KEYWORDS = new Set(['function', 'const', 'return']) - -function translateWGSL(wgsl) { - const declared = new Set() - let src = wgsl.replace( - /\bfn\s+(\w+)\s*\(([^)]*)\)\s*->\s*(\w+)/g, - (_, name, params, ret) => { - if (ret !== 'u32') throw new Error(`unsupported return type ${ret}`) - const names = params.split(',').map((p) => { - const m = p.trim().match(/^(\w+)\s*:\s*f32$/) - if (!m) throw new Error(`unsupported parameter "${p.trim()}"`) - declared.add(m[1]) - return m[1] - }) - declared.add(name) - return `function ${name}(${names.join(', ')})` + +function compile(wgsl, mode) { + const f32 = mode === 'f32' + const F = (code) => (f32 ? `F(${code})` : code) + const toks = tokenize(wgsl) + let i = 0 + const peek = () => toks[i] + const next = () => toks[i++] + const expect_ = (v) => { + const tok = next() + if (!tok || tok.v !== v) throw new Error(`expected "${v}" but found "${tok?.v}"`) + return tok + } + const ident = () => { + const tok = next() + if (!tok || tok.t !== 'id') throw new Error(`expected identifier but found "${tok?.v}"`) + return tok.v + } + + let scope + function primary() { + const tok = next() + if (!tok) throw new Error('unexpected end of WGSL') + if (tok.t === 'num') return F(tok.v) + if (tok.v === '(') { + const e = expr() + expect_(')') + return `(${e})` } - ) - src = src.replace(/\blet\s+(\w+)/g, (_, name) => { - declared.add(name) - return `const ${name}` - }) + if (tok.t === 'id') { + if (peek()?.v === '(') { + if (!BUILTINS.has(tok.v)) throw new Error(`unknown WGSL identifier "${tok.v}"`) + next() + const args = [] + if (peek()?.v !== ')') { + args.push(expr()) + while (peek()?.v === ',') { next(); args.push(expr()) } + } + expect_(')') + const call = `B.${tok.v}(${args.join(', ')})` + return tok.v === 'u32' ? call : F(call) + } + if (!scope.has(tok.v)) throw new Error(`unknown WGSL identifier "${tok.v}"`) + return tok.v + } + throw new Error(`unexpected token "${tok.v}"`) + } + function unary() { + if (peek()?.v === '-') { next(); return F(`-${unary()}`) } + return primary() + } + function binary(sub, ops) { + let left = sub() + while (ops.includes(peek()?.v)) { + const op = next().v + left = F(`(${left} ${op} ${sub()})`) + } + return left + } + const term = () => binary(unary, ['*', '/']) + const expr = () => binary(term, ['+', '-']) - const bad = src.match(/[^\w\s.(){}+\-*/=,;]/) - if (bad) throw new Error(`unknown character "${bad[0]}" in WGSL`) - for (const tok of src.match(/[A-Za-z_]\w*/g) ?? []) { - if (!KEYWORDS.has(tok) && !declared.has(tok) && !(tok in BUILTINS)) { - throw new Error(`unknown WGSL token "${tok}"`) + const fns = {} + let out = '' + while (i < toks.length) { + const kw = ident() + if (kw !== 'fn') throw new Error(`unknown WGSL identifier "${kw}"`) + const name = ident() + scope = new Set() + expect_('(') + const params = [] + while (peek()?.v !== ')') { + const p = ident() + expect_(':') + const ty = ident() + if (ty !== 'f32') throw new Error(`unsupported parameter type ${ty}`) + params.push(p) + scope.add(p) + if (peek()?.v === ',') next() + } + expect_(')') + expect_('->') + const ret = ident() + if (ret !== 'u32') throw new Error(`unsupported return type ${ret}`) + expect_('{') + let body = params.map((p) => `${p} = ${F(p)};`).join(' ') + while (peek()?.v !== '}') { + const kw2 = ident() + if (kw2 === 'let') { + const v = ident() + expect_('=') + body += ` const ${v} = ${expr()};` + expect_(';') + scope.add(v) + } else if (kw2 === 'return') { + body += ` return ${expr()};` + expect_(';') + } else { + throw new Error(`unknown WGSL identifier "${kw2}"`) + } } + expect_('}') + out += `function ${name}(${params.join(', ')}) {${body} }\n` + fns[name] = true } - if (!declared.has('lonToCol') || !declared.has('latToRow')) { - throw new Error('WGSL is missing lonToCol or latToRow') + for (const want of ['lonToCol', 'latToRow']) { + if (!fns[want]) throw new Error(`WGSL is missing ${want}`) } - const names = Object.keys(BUILTINS) - const factory = new Function(...names, `${src}\nreturn { lonToCol, latToRow }`) - return factory(...names.map((n) => BUILTINS[n])) + const fr = f32 ? Math.fround : (x) => x + const B = { + floor: Math.floor, + log: Math.log, + tan: Math.tan, + clamp: (x, lo, hi) => Math.min(Math.max(x, lo), hi), + u32: (x) => { + if (!Number.isFinite(x) || x < 0 || x > 0xffffffff) throw new Error(`u32() of ${x} is out of range`) + return Math.trunc(x) + }, + } + return new Function('F', 'B', `${out}return { lonToCol, latToRow }`)(fr, B) } -describe('translateWGSL', () => { - it('throws on a WGSL token it does not know', () => { - const wgsl = 'fn latToRow(lat: f32) -> u32 { return u32(select(0.0, 1.0, lat > 0.0)); }' - expect(() => translateWGSL(wgsl)).toThrow() +describe('WGSL translator rejects what it does not know', () => { + const lon = 'fn lonToCol(lon: f32) -> u32 { return u32(lon); }\n' + const lat = 'fn latToRow(lat: f32) -> u32 { return u32(lat); }\n' + + it('rejects an unknown builtin call', () => { + const wgsl = lon + 'fn latToRow(lat: f32) -> u32 { return u32(select(0.0, 1.0, lat)); }' + expect(() => compile(wgsl, 'f64')).toThrow('unknown WGSL identifier "select"') + }) + + it('rejects an undeclared variable', () => { + const wgsl = lon + 'fn latToRow(lat: f32) -> u32 { return u32(lat + offset); }' + expect(() => compile(wgsl, 'f64')).toThrow('unknown WGSL identifier "offset"') + }) + + it('rejects an unknown character', () => { + const wgsl = lon + 'fn latToRow(lat: f32) -> u32 { return u32(lat % 2.0); }' + expect(() => compile(wgsl, 'f64')).toThrow('unknown character "%" in WGSL') + }) + + it('rejects an unsupported statement keyword', () => { + const wgsl = lon + 'fn latToRow(lat: f32) -> u32 { var x = lat; return u32(x); }' + expect(() => compile(wgsl, 'f64')).toThrow('unknown WGSL identifier "var"') }) - it('throws on an unknown identifier', () => { - const wgsl = 'fn lonToCol(lon: f32) -> u32 { return u32(abs(lon)); }\nfn latToRow(lat: f32) -> u32 { return u32(lat); }' - expect(() => translateWGSL(wgsl)).toThrow(/abs/) + it('rejects an unsupported parameter type', () => { + const wgsl = lon + 'fn latToRow(lat: i32) -> u32 { return u32(lat); }' + expect(() => compile(wgsl, 'f64')).toThrow('unsupported parameter type i32') + }) + + it('rejects an unsupported return type', () => { + const wgsl = lon + 'fn latToRow(lat: f32) -> f32 { return lat; }' + expect(() => compile(wgsl, 'f64')).toThrow('unsupported return type f32') + }) + + it('rejects WGSL missing one of the two functions', () => { + expect(() => compile(lon, 'f64')).toThrow('WGSL is missing latToRow') + expect(() => compile(lat, 'f64')).toThrow('WGSL is missing lonToCol') + }) + + it('accepts the minimal valid pair', () => { + expect(compile(lon + lat, 'f64').latToRow(3.7)).toBe(3) }) }) -describe('generated WGSL binning executes like the JS helpers', () => { - const gpu = translateWGSL(binningWGSL()) +describe('generated WGSL binning in float64 matches the JS helpers exactly', () => { + const gpu = compile(binningWGSL(), 'f64') it('latToRow matches at reference latitudes and beyond the limits', () => { const lats = [0, 40, 60, 65, -33.9, MERCATOR_MAX_LAT, -MERCATOR_MAX_LAT, 90, -90, 120, -120] @@ -100,3 +239,42 @@ describe('generated WGSL binning executes like the JS helpers', () => { } }) }) + +describe('generated WGSL binning under f32 emulation stays in the grid (criterion 2c)', () => { + const gpu = compile(binningWGSL(), 'f32') + + it('north extremes land exactly on row 0', () => { + for (const lat of [MERCATOR_MAX_LAT, 90, 120]) { + expect(gpu.latToRow(lat), `lat ${lat}`).toBe(0) + } + }) + + it('south extremes land exactly on the last row', () => { + for (const lat of [-MERCATOR_MAX_LAT, -90, -120]) { + expect(gpu.latToRow(lat), `lat ${lat}`).toBe(HEATMAP_GRID_H - 1) + } + }) + + it('longitude extremes land exactly on the first and last column', () => { + for (const lon of [-180, -500]) expect(gpu.lonToCol(lon), `lon ${lon}`).toBe(0) + for (const lon of [180, 500]) expect(gpu.lonToCol(lon), `lon ${lon}`).toBe(HEATMAP_GRID_W - 1) + }) + + it('latToRow is in range and within one row of the JS helper over -90 to 90', () => { + for (let lat = -90; lat <= 90; lat += 0.01) { + const r = gpu.latToRow(lat) + expect(r).toBeGreaterThanOrEqual(0) + expect(r).toBeLessThanOrEqual(HEATMAP_GRID_H - 1) + expect(Math.abs(r - latToRow(lat))).toBeLessThanOrEqual(1) + } + }) + + it('lonToCol is in range and within one column of the JS helper over -180 to 180', () => { + for (let lon = -180; lon <= 180; lon += 0.01) { + const c = gpu.lonToCol(lon) + expect(c).toBeGreaterThanOrEqual(0) + expect(c).toBeLessThanOrEqual(HEATMAP_GRID_W - 1) + expect(Math.abs(c - lonToCol(lon))).toBeLessThanOrEqual(1) + } + }) +}) From d71050146d8a88a848789b31f045aea4af9252c4 Mon Sep 17 00:00:00 2001 From: Brad Stricherz Date: Sat, 7 Nov 2026 21:41:41 -0600 Subject: [PATCH 6/6] docs: align issue 15 plan with the WGSL translator test (#15) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf --- docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md index 7d3cd8d..01967fa 100644 --- a/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md +++ b/docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md @@ -24,14 +24,14 @@ Checkable form: - 1a. For any latitude in [-80, 80], the cell row the binning maps it to, when drawn by a BitmapLayer stretched linearly in Mercator Y over the layer's bounds, covers a latitude band that contains the input latitude (unit test over a sweep, plus named reference points 0, 40, 60, 65, -33.9). - 1b. In a real browser with a WebGPU adapter (Chromium, `--enable-unsafe-webgpu --use-webgpu-adapter=swiftshader`), screenshots with HEATMAP and AIRPORTS on at about 0N (West Africa), 40N (US mid-Atlantic), and 65N (Scandinavia or Alaska) show hot spots on the airport dots, not shifted north. - 2a. One JS module owns the Mercator latitude limit, the grid dimensions used for rows, the lat-to-row formula, and the BitmapLayer bounds. `buildLayers` uses its bounds and sets no `_imageCoordinateSystem`. The accumulate shader's WGSL binning code is generated from that module's constants (no second hand-typed copy of 85.051129). The WGSL bodies do restate the row and column formulas in WGSL syntax, so a test executes the generated WGSL (2b) to prove they match the JS helpers. -- 2b. A unit test asserts the BitmapLayer's bounds equal the helper's bounds, that the numeric constants embedded in the generated WGSL equal the JS constants, and that the old linear `(90.0 - lat) / 180.0` mapping is gone. A second test translates the generated WGSL `lonToCol` and `latToRow` mechanically into JS (failing on any token it does not know) and asserts they return the same values as the JS helpers at the reference points, at and beyond +/-85.051129 and +/-90, and over sweeps of lat -85..85 and lon -180..180. +- 2b. A unit test asserts the BitmapLayer's bounds equal the helper's bounds, that the numeric constants embedded in the generated WGSL equal the JS constants, and that the old linear `(90.0 - lat) / 180.0` mapping is gone. A second test translates the generated WGSL `lonToCol` and `latToRow` mechanically into JS (failing on any identifier, character, parameter type or return type it does not know; numeric literals are read as floats, which holds because the generator emits every literal with a decimal point) and asserts they return the same values as the JS helpers at the reference points, at and beyond +/-85.051129 and +/-90, and over sweeps of lat -85..85 and lon -180..180. - 2c. Latitudes beyond +/-85.051129 (and +/-90) clamp to the first or last row instead of producing NaN or an out-of-range row. ## Files that change - `src/layers/heatmapProjection.js` (new): exports `MERCATOR_MAX_LAT = 85.051129`, `HEATMAP_GRID_W = 1024`, `HEATMAP_GRID_H = 512`, `HEATMAP_BOUNDS` (`[-180, -MERCATOR_MAX_LAT, 180, MERCATOR_MAX_LAT]`), `mercatorY(lat)` (`ln(tan(pi/4 + lat*pi/360))` with lat clamped to +/-MERCATOR_MAX_LAT), `latToRowFraction(lat)` (`(1 - mercatorY(lat) / mercatorY(MERCATOR_MAX_LAT)) / 2`, 0 at the north edge, 1 at the south edge), `latToRow(lat, gridH = HEATMAP_GRID_H)` (floor of fraction times gridH, clamped to [0, gridH-1]), `lonToCol(lon, gridW = HEATMAP_GRID_W)` (same as the current shader), and `binningWGSL()` (or a constant string) returning WGSL functions `lonToCol(lon: f32) -> u32` and `latToRow(lat: f32) -> u32` that use the same formula, with the limit, its Mercator Y, and the grid sizes interpolated from the JS values as f32 literals (always with a decimal point). - `src/layers/heatmapProjection.test.js` (new): reference points and the agreement sweep (1a), clamping (2c), WGSL constants (2b). -- `src/layers/heatmapProjection.wgsl.test.js` (new, added after review): executes the generated WGSL binning functions via a strict WGSL-to-JS translator (each rejection path asserts its own error) and compares them with the JS helpers: exactly in float64 (2b), and under f32 emulation (Math.fround on every literal, parameter, operator and builtin result) asserting rows and columns stay in the grid, extremes land on the first or last row and column, and sweeps stay within one cell of the JS helpers (2c). +- `src/layers/heatmapProjection.wgsl.test.js` (new, added after review): executes the generated WGSL binning functions via a strict WGSL-to-JS translator (each rejection test pins the error message of the path it names) and compares them with the JS helpers: exactly in float64 (2b), and under f32 emulation (Math.fround on every literal, parameter, operator and builtin result) asserting rows and columns stay in the grid, extremes land on the first or last row and column, and sweeps stay within one cell of the JS helpers (2c). - `src/hooks/useGPUHeatmap.js`: import the grid sizes and WGSL from the helper, drop the local `GRID_W`/`GRID_H` constants, call the generated `lonToCol`/`latToRow` in `ACCUMULATE_SHADER`, and export `ACCUMULATE_SHADER` so a test can inspect it. Nothing else in the hook changes. - `src/hooks/useGPUHeatmap.test.js`: add a test that `ACCUMULATE_SHADER` contains the generated binning code and no `(90.0 - lat) / 180.0`. - `src/layers/index.js`: `bounds: HEATMAP_BOUNDS`.