WebGL streamline visualizer

A library for visualizing streamlines with moving particles, powered by WebGL. The visualizer can be run with velocity fields from any source, but has a MapLibre map layer that fetches WMS data from a FEWS WMS service.

This library uses WebGL to propagate particles along the streamlines of a velocity field and visualize their tracks. Both the propagation and the visualization is powered by the user's GPU, allowing the visualization to run with thousands of particles at high FPS, even on mobile phones.

Usage with MapLibre and FEWS WMS

This library has been primarily developed for use with MapLibre and FEWS Web Mapping Service.

It can be added to an existing MapLibre map with:

// Create new animated streamlines layer based on options.
const layer = new WMSStreamlineLayer('streamlines', options)

// Add the layer to the MapLibre map.
map.addLayer(layer)

// Initialise the streamlines by a.o. fetching a velocity field.
await layer.initialise()

Refer to examples/maplibre_basic.ts for the full example.

Examples

A hosted version of some of the examples can be found on the GitHub Pages.

Standalone usage

The core of the WebGL streamline visualizer can also be used standalone, for example for integrating with your map library or velocity field source of choice.

Refer to examples/vortex.ts for a full example that uses the visualizer without a map library and generates velocity data with TypeScript function.

StreamlineVisualiserOptions

interface StreamlineVisualiserOptions {
  style: StreamlineStyle
  particleSize: number
  speedFactor: number
  fadeAmountPerSecond: number
  maxDisplacement: number
  maxAge: number
  growthRate?: number
  speedExponent?: number
  particleColor?: string
  spriteUrl?: URL
  trailParticleOptions?: TrailParticleOptions

  /** Opacity of the particle overlay (0–1). Used by LightParticlesOnMagnitude
   *  and DarkParticlesOnMagnitude styles. Default: 1 */
  particleOverlayOpacity?: number

  /** Alpha threshold for edge detection at data/nodata boundaries.
   *  Controls how aggressively edges are clipped when the velocity texture
   *  uses an alpha validity mask. Lower values show more of the interpolated
   *  edge (less corner rounding), higher values clip more aggressively.
   *  Range: 0–1. Default: 0.5 */
  edgeThreshold?: number
}

Key methods

• setScaling(scaling) — sets the bounding box scaling for positioning the data within the viewport. When the data doesn't fill the viewport, the visualizer automatically compensates particle size and speed so they appear consistent on screen regardless of the data-to-viewport ratio.

• renderFrame(dt) — advances particles by dt seconds and renders the full composite (particle trails + magnitude shading) to the default framebuffer.

• renderCopy() — re-draws the final composite pass with the current scaling without advancing particles. Use this to render world copies at different offsets: call setScaling() with the shifted bbox, then renderCopy(). Must be called after renderFrame() in the same frame.

For developers

Install dependencies and initialize Playwright:

npm install
npx playwright install

Run a development server for the demo pages, listening for changes in the source:

npm run dev

Run the linter on the library and examples:

npm run lint

Run a production build of the library:

npm run build

To build and view the examples run (note you may have to adapt base to '/' in the examples config )

npm run build:examples
npm run preview

Run all tests, listening for change in the source:

npm run test