OpenWeather Maps SDK v0.0.0 docs
API Reference

@openweather/maps-gl

The WebGL renderer — custom MapLibre layers for scalar colorization, particle advection, wave glyphs, and contour extraction. Peer-depends on maplibre-gl ≥ 5. See Architecture — Low-level technology for the WebGL1/2 shader strategy and the two particle update engines.

ScalarFlow

The main plugin class — one instance manages a map's scalar/particle/waves layers together:

import { ScalarFlow, InterpolationMode } from '@openweather/maps-gl';

const sf = new ScalarFlow(map, beforeLayerId);
await sf.setLayer(imageUrlOrElement, {
  id: 'temperature',
  colors: [
    [-20, '#000080'],
    [40, '#ff0000'],
  ],
  dataRange: [-30, 50],
  interpolation: InterpolationMode.Bicubic,
});
sf.updateLayer({ contrast: 1.2 }, 'scalar');
sf.removeLayer('particles'); // or 'scalar' | 'waves' | 'all'

Layer factories

  • createScalarLayer(layerId, config) — scalar field colorization
  • createParticlesLayer(config) — GPU wind particle advection
  • createWavesLayer(layerId) — animated wave-crest glyphs from a height+direction composite image

Contours

  • computeContours, prepareContourField, assembleContoursFromSegments / assembleContoursFromSegmentsAsync / assembleContoursProgressive, assembleQuickContourLines
  • runContourCompute, configureContourWorker, createInlineContourWorkerFactory, terminateContourWorker, isContourWorkerActive — Web Worker extraction, with an inline-worker build variant for single-file bundling
  • extractContours (CPU), extractContoursWebGpu (WebGPU, where available)
  • contourLevels, stitchSegments, smoothPolyline, marchingSquares, findLocalExtrema

Field / decode utilities

  • decodeScalarValue — the same normalize → scale → range-mix path point query uses to match GPU colorization without display smoothing
  • gaussianBlurField, bilinearUpsample, decodeImageToField
  • loadImageWithMetadata — EXIF-driven physical range overrides

Capability detection

  • detectCapabilities(gl) — WebGL2 vs. WebGL1 fallback, VAO support, vertex-texture-fetch availability for the particle layer
  • isWebGL2Context
  • getDeviceTier() — 'high' | 'medium' | 'low', a one-time cached GPU micro-benchmark, scales particle budget

Types

ScalarFlowAPI, ScalarLayerConfig, ParticleLayerConfig, WavesLayerConfig, UpdateOptions, LayerConfig, LayerKind, ValueRange, VectorRange, GeoBounds, ColorConfiguration, InterpolationMode, ValueScaleMode, CustomRenderOptions, ContourLine, RendererCapabilities, DeviceTier.

Logging

logger / Logger (with LoggerLevel) — the package's internal diagnostic logger, also re-exported from @openweather/maps-maplibre.

Shader workflow

Shader sources live in packages/maps-gl/shaders/*.glsl; pnpm run bundle-shaders inlines them into a generated (gitignored) src/shaders.ts before tsup builds the package. See Development & Tooling.