webgpu-sonar

GPU-accelerated multibeam sonar rendering, phase correlation, and mosaic stitching in the browser via WebGPU.

Install

npm install webgpu-sonar

Requirements

• A browser with WebGPU support
• A palette texture URL (512x18 RGBA PNG with 9 colour palettes)

Usage

All GPU classes follow the same pattern: async create() factory, instance methods for processing, and destroy() for cleanup.

Render a sonar ping (polar view)

import { MultibeamRenderer } from "webgpu-sonar";

const renderer = await MultibeamRenderer.create(canvas, paletteUrl);
renderer.render(ping, { palette: 0 });
renderer.destroy();

Render a Cartesian reprojection

import { CartesianReprojector } from "webgpu-sonar";

const reprojector = await CartesianReprojector.create(canvas, paletteUrl);
reprojector.render(ping, 0);
reprojector.destroy();

Phase correlation (translation estimation)

import { PhaseCorrelator } from "webgpu-sonar";

const correlator = await PhaseCorrelator.create();
const result = await correlator.correlate(pingA, pingB);
// result.dx, result.dy, result.peak
correlator.destroy();

Real-time mosaic pipeline

import {
  MosaicCompositor,
  PhaseCorrelator,
  PolarPhaseCorrelator,
  RealtimeMosaicPipeline,
} from "webgpu-sonar";

const compositor = await MosaicCompositor.create(canvas, paletteUrl);
const translation = await PhaseCorrelator.create();
const rotation = await PolarPhaseCorrelator.create();   // optional
const pipeline = new RealtimeMosaicPipeline(compositor, translation, {
  rotationCorrelator: rotation,   // omit/null for translation-only mode
  minPeak: 0.05,                  // minimum correlation peak (default: 0.05)
  maxDisplacement: 25,            // hard cap on displacement in pixels (default: 25)
  consistencyFactor: 3,           // adaptive threshold = factor × median (default: 3)
});

for (const ping of pings) {
  await pipeline.processPing(ping);
  pipeline.render(0); // palette index
}

// Export timing data
const csv = pipeline.exportCSV();

React components

import { MultibeamPing, MultibeamCartesian, MultibeamMosaic } from "webgpu-sonar/react";

<MultibeamPing ping={ping} paletteUrl={paletteUrl} palette={0} />
<MultibeamCartesian ping={ping} paletteUrl={paletteUrl} palette={0} />
<MultibeamMosaic pings={pings} paletteUrl={paletteUrl} palette={0} />

React is an optional peer dependency and only required when importing from webgpu-sonar/react.

Input format

All processing stages accept a SonarPing object:

interface SonarPing {
  numberOfBeams: number;
  numberOfRanges: number;
  bearings: ArrayLike<number>; // bearing angles in degrees, one per beam
  pingData: ArrayLike<number>; // row-major intensity data, values 0-255
  range: number; // sonar range in metres
}

ArrayLike<number> accepts both standard arrays and typed arrays (e.g. Uint8Array, Float32Array) without copying.

Core exports

| Class | Description | | ------------------------ | ----------------------------------------------------------------- | | MultibeamRenderer | Polar-coordinate sonar visualisation | | CartesianReprojector | Polar-to-Cartesian reprojection (512x512) | | MosaicCompositor | Feathered blending into 2048x2048 mosaic | | PhaseCorrelator | Translation estimation via Cartesian-domain phase correlation | | PolarPhaseCorrelator | Rotation estimation via polar-domain phase correlation | | RealtimeMosaicPipeline | Orchestrates correlation, outlier rejection, and compositing | | FFT2D | Radix-2 2D FFT in WGSL (512x512) |

License

MIT