@longline/aqua-ui 1.0.299 → 1.0.302

package/formatters/NumberFormatter/NumberFormatter.d.ts

@@ -16,15 +16,28 @@ interface INumberFormatterProps {
     locale?: string;
 }
 /**
- * `NumberFormatter` formats a number with thousands separators and optional
- * fractional digits. If provided with a string, `NumberFormatter` will
- * convert it to a float first. By default, two decimals are printed.
+ * Formats numbers with locale-aware thousands separators and configurable
+ * decimal precision.
  *
- * If the input is not a valid number, it returns `null`.
+ * Use `NumberFormatter` when displaying numeric values that benefit from
+ * grouping (e.g., financial figures, statistics, counts). For large numbers
+ * that should be abbreviated (e.g., "1.2M"), use `HumanFormatter` instead.
+ *
+ * ## Output Examples
+ *
+ * | Input | Props | Output |
+ * |-------|-------|--------|
+ * | `35100.2` | (default) | `35,100.20` |
+ * | `35100.2` | `decimals={0}` | `35,100` |
+ * | `1234.567` | `locale="de-DE"` | `1.234,57` |
+ * | `"1000"` | (default) | `1,000.00` |
+ * | `NaN` | (default) | *(null)* |
+ *
+ * ## Usage
  *
  * ```tsx
- * <NumberFormatter value={35100.20}/>
- * <NumberFormatter value={35100.20} decimals={0}/>
+ * <NumberFormatter value={35100.20} />
+ * <NumberFormatter value={35100.20} decimals={0} />
  * <NumberFormatter value={1234.567} locale="de-DE" />
  * ```
  */

package/formatters/NumberFormatter/NumberFormatter.js

@@ -1,14 +1,27 @@
 import * as React from 'react';
 /**
- * `NumberFormatter` formats a number with thousands separators and optional
- * fractional digits. If provided with a string, `NumberFormatter` will
- * convert it to a float first. By default, two decimals are printed.
+ * Formats numbers with locale-aware thousands separators and configurable
+ * decimal precision.
  *
- * If the input is not a valid number, it returns `null`.
+ * Use `NumberFormatter` when displaying numeric values that benefit from
+ * grouping (e.g., financial figures, statistics, counts). For large numbers
+ * that should be abbreviated (e.g., "1.2M"), use `HumanFormatter` instead.
+ *
+ * ## Output Examples
+ *
+ * | Input | Props | Output |
+ * |-------|-------|--------|
+ * | `35100.2` | (default) | `35,100.20` |
+ * | `35100.2` | `decimals={0}` | `35,100` |
+ * | `1234.567` | `locale="de-DE"` | `1.234,57` |
+ * | `"1000"` | (default) | `1,000.00` |
+ * | `NaN` | (default) | *(null)* |
+ *
+ * ## Usage
  *
  * ```tsx
- * <NumberFormatter value={35100.20}/>
- * <NumberFormatter value={35100.20} decimals={0}/>
+ * <NumberFormatter value={35100.20} />
+ * <NumberFormatter value={35100.20} decimals={0} />
  * <NumberFormatter value={1234.567} locale="de-DE" />
  * ```
  */

package/formatters/StringFormatter/StringFormatter.d.ts

@@ -1,3 +1,4 @@
+import * as React from 'react';
 interface IStringFormatterProps {
     /** String to format */
     value: string;
@@ -5,16 +6,33 @@ interface IStringFormatterProps {
     type: 'capitalize' | 'capitalizeWords' | 'upper' | 'lower' | 'reverse' | 'snake' | 'kebab';
 }
 /**
- * `StringFormatter` formats a string in different ways.
+ * Transforms strings using common text formatting operations.
+ *
+ * All operations are Unicode-safe, using `toLocaleUpperCase()` and
+ * `toLocaleLowerCase()` for proper internationalization.
+ *
+ * ## Format Types
+ *
+ * | Type | Input | Output |
+ * |------|-------|--------|
+ * | `capitalize` | `"hello world"` | `"Hello world"` |
+ * | `capitalizeWords` | `"hello world"` | `"Hello World"` |
+ * | `upper` | `"Hello World"` | `"HELLO WORLD"` |
+ * | `lower` | `"Hello World"` | `"hello world"` |
+ * | `reverse` | `"Hello"` | `"olleH"` |
+ * | `snake` | `"Hello World"` | `"hello_world"` |
+ * | `kebab` | `"Hello World"` | `"hello-world"` |
+ *
+ * ## Usage
  *
  * ```tsx
  * <StringFormatter value="hello world" type="capitalize" />
  * <StringFormatter value="hello world" type="capitalizeWords" />
- * <StringFormatter value="hello world" type="snake" />
+ * <StringFormatter value="my variable name" type="snake" />
  * ```
  */
 declare const StringFormatter: {
-    ({ value, type }: IStringFormatterProps): string;
+    ({ value, type }: IStringFormatterProps): React.JSX.Element;
     displayName: string;
 };
-export { StringFormatter };
+export { StringFormatter, IStringFormatterProps };

package/formatters/StringFormatter/StringFormatter.js

@@ -1,3 +1,4 @@
+import * as React from 'react';
 /** Unicode-safe capitalize first letter */
 var capitalize = function (str) {
     if (!str)
@@ -26,12 +27,29 @@ var formatters = {
     kebab: function (s) { return s.trim().toLocaleLowerCase().replace(/\s+/g, '-'); },
 };
 /**
- * `StringFormatter` formats a string in different ways.
+ * Transforms strings using common text formatting operations.
+ *
+ * All operations are Unicode-safe, using `toLocaleUpperCase()` and
+ * `toLocaleLowerCase()` for proper internationalization.
+ *
+ * ## Format Types
+ *
+ * | Type | Input | Output |
+ * |------|-------|--------|
+ * | `capitalize` | `"hello world"` | `"Hello world"` |
+ * | `capitalizeWords` | `"hello world"` | `"Hello World"` |
+ * | `upper` | `"Hello World"` | `"HELLO WORLD"` |
+ * | `lower` | `"Hello World"` | `"hello world"` |
+ * | `reverse` | `"Hello"` | `"olleH"` |
+ * | `snake` | `"Hello World"` | `"hello_world"` |
+ * | `kebab` | `"Hello World"` | `"hello-world"` |
+ *
+ * ## Usage
  *
  * ```tsx
  * <StringFormatter value="hello world" type="capitalize" />
  * <StringFormatter value="hello world" type="capitalizeWords" />
- * <StringFormatter value="hello world" type="snake" />
+ * <StringFormatter value="my variable name" type="snake" />
  * ```
  */
 var StringFormatter = function (_a) {
@@ -42,7 +60,7 @@ var StringFormatter = function (_a) {
     if (typeof value !== 'string')
         return null;
     var formatter = (_b = formatters[type]) !== null && _b !== void 0 ? _b : (function (s) { return s; });
-    return formatter(value);
+    return React.createElement(React.Fragment, null, formatter(value));
 };
 StringFormatter.displayName = 'StringFormatter';
 export { StringFormatter };

package/map/layers/ParticlesLayer/ParticlesLayer.d.ts

@@ -46,9 +46,105 @@ interface IParticlesLayerProps {
      * @default 99
      */
     maxZoom?: number;
+    /**
+     * Minimum visible velocity magnitude for particle trails.
+     * Velocities are linearly remapped to [minSpeed, maxSpeed] range.
+     * @default 0.02
+     */
+    minSpeed?: number;
+    /**
+     * Maximum visible velocity magnitude for particle trails.
+     * Velocities are linearly remapped to [minSpeed, maxSpeed] range.
+     * @default 0.15
+     */
+    maxSpeed?: number;
 }
+/**
+ * A WebGL-based Mapbox GL custom layer that visualizes vector flow fields (such as
+ * ocean currents or wind patterns) using animated particle trails.
+ *
+ * ## Overview
+ *
+ * The component takes an array of data points, each with a geographic position and
+ * a velocity vector (U and V components). It renders animated particles that flow
+ * along these velocity vectors, creating a visual representation of the flow field.
+ *
+ * Particle trails are colored using a configurable gradient, where the head of the
+ * trail is typically bright and the tail fades out. The animation continuously cycles
+ * particles through their trails, creating a flowing effect.
+ *
+ * ## Data Format
+ *
+ * Input data should be an array of points with the following structure:
+ *
+ * ```typescript
+ * interface IPoint {
+ *   latitude: number;   // Geographic latitude
+ *   longitude: number;  // Geographic longitude
+ *   u: number;          // Velocity component in X direction
+ *   v: number;          // Velocity component in Y direction
+ * }
+ * ```
+ *
+ * The component uses Delaunay triangulation (via Turf.js) to interpolate velocity
+ * values between data points, so the data does not need to be on a regular grid.
+ *
+ * ## Velocity Remapping
+ *
+ * To ensure all particles have visible trails regardless of the actual velocity
+ * magnitudes in the data, velocities are linearly remapped to a visible range:
+ *
+ * - The `minSpeed` prop sets the minimum trail speed (for the slowest currents)
+ * - The `maxSpeed` prop sets the maximum trail speed (for the fastest currents)
+ * - All velocities are scaled proportionally within this range
+ * - The relative differences between fast and slow currents are preserved
+ * - Particles with exactly zero velocity are not rendered
+ *
+ * ## Performance
+ *
+ * The component is optimized for performance using several GPU-based techniques:
+ *
+ * 1. **UV Texture Caching**: The velocity field is rendered to a texture only when
+ *    the map view changes (pan/zoom), not on every animation frame.
+ *
+ * 2. **Combined UV Texture**: U and V components are stored in a single texture
+ *    (U in red channel, V in green channel) to reduce texture fetches.
+ *
+ * 3. **Position Pre-computation**: Particle positions are pre-computed in a GPU
+ *    shader pass when the view changes, eliminating expensive per-vertex loops
+ *    during animation.
+ *
+ * With default settings (`density=40`, `particles=80`), the component renders
+ * 128,000 particles efficiently.
+ *
+ * ## Example
+ *
+ * ```tsx
+ * <Map>
+ *   <ParticlesLayer
+ *     data={oceanCurrentData}
+ *     density={50}
+ *     particles={100}
+ *     gradientStops={[
+ *       { pos: 0.0, color: '#00ffffff' },
+ *       { pos: 0.5, color: '#0088ffff' },
+ *       { pos: 1.0, color: '#0088ff00' },
+ *     ]}
+ *     minSpeed={0.01}
+ *     maxSpeed={0.2}
+ *   />
+ * </Map>
+ * ```
+ *
+ * ## Notes
+ *
+ * - The component requires a Mapbox GL map context (via `react-map-gl`)
+ * - WebGL 1.0 is used for maximum browser compatibility (no extensions required)
+ * - The layer renders before the "overlay" layer in the Mapbox style
+ * - Changing props triggers a full re-initialization of the WebGL resources
+ */
 declare const ParticlesLayer: {
-    ({ particles, density, delay, gradientStops, minZoom, maxZoom, ...props }: IParticlesLayerProps): React.JSX.Element;
+    ({ particles, density, delay, gradientStops, minZoom, maxZoom, minSpeed, maxSpeed, ...props }: IParticlesLayerProps): React.JSX.Element;
     displayName: string;
 };
 export { ParticlesLayer, IParticlesLayerProps };

package/map/layers/ParticlesLayer/ParticlesLayer.js

@@ -38,6 +38,8 @@ import { UVVertexShader } from './UVVertexShader';
 import { UVFragmentShader } from './UVFragmentShader';
 import { ParticlesFragmentShader } from './ParticlesFragmentShader';
 import { ParticlesVertexShader } from './ParticlesVertexShader';
+import { PositionComputeVertexShader } from './PositionComputeVertexShader';
+import { PositionComputeFragmentShader } from './PositionComputeFragmentShader';
 import { RgbColor } from '../../../helper/RgbColor';
 var TEXTURE_WIDTH = 1024;
 var TEXTURE_HEIGHT = 1024;
@@ -54,14 +56,23 @@ var ParticlesLayerBase = function (props) {
     var maxU = React.useRef(0);
     var minV = React.useRef(0);
     var maxV = React.useRef(0);
-    var textureU = React.useRef(null);
-    var textureV = React.useRef(null);
-    var fboU = React.useRef(null);
-    var fboV = React.useRef(null);
+    // Combined UV texture: U in R channel, V in G channel, alpha indicates valid data
+    var textureUV = React.useRef(null);
+    var fboUV = React.useRef(null);
+    // Position texture: stores pre-computed particle positions (X in RG, Y in BA)
+    var positionProgram = React.useRef(null);
+    var texturePosition = React.useRef(null);
+    var fboPosition = React.useRef(null);
+    var bufferQuad = React.useRef(null);
+    // Dynamic position texture dimensions (computed based on density * density * particles)
+    var posTexWidth = React.useRef(0);
+    var posTexHeight = React.useRef(0);
     var frame = React.useRef(0);
     var skip = React.useRef(0);
     // requestAnimationFrame ID:
     var animation = React.useRef(null);
+    // Last matrix used to render UV textures (for caching):
+    var lastMatrix = React.useRef(null);
     // Current time is used to force component rerender when props change:
     var _a = React.useState(0), time = _a[0], setTime = _a[1];
     // Force component rerender when props change:
@@ -70,11 +81,12 @@ var ParticlesLayerBase = function (props) {
         setTime(Date.now());
         frame.current = 0;
         skip.current = 0;
+        lastMatrix.current = null; // Reset matrix cache so UV textures are re-rendered
         animation.current = window.requestAnimationFrame(draw);
-    }, [props.data, props.gradientStops, props.particles, props.density, props.delay, props.pointSize]);
+    }, [props.data, props.gradientStops, props.particles, props.density, props.delay, props.pointSize, props.minSpeed, props.maxSpeed]);
     var draw = function () {
         skip.current++;
-        if (skip.current >= props.delay) {
+        if (skip.current > props.delay) {
             skip.current = 0;
             frame.current = (frame.current + 1) % props.particles;
             map.current.triggerRepaint();
@@ -169,6 +181,53 @@ var ParticlesLayerBase = function (props) {
         gl.attachShader(particlesProgram.current, fragmentShader);
         gl.linkProgram(particlesProgram.current);
     };
+    var createPositionComputeProgram = function (gl) {
+        var vertexShader = gl.createShader(gl.VERTEX_SHADER);
+        gl.shaderSource(vertexShader, PositionComputeVertexShader);
+        gl.compileShader(vertexShader);
+        var fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
+        gl.shaderSource(fragmentShader, PositionComputeFragmentShader);
+        gl.compileShader(fragmentShader);
+        positionProgram.current = gl.createProgram();
+        gl.attachShader(positionProgram.current, vertexShader);
+        gl.attachShader(positionProgram.current, fragmentShader);
+        gl.linkProgram(positionProgram.current);
+    };
+    var createPositionTexture = function (gl) {
+        // Compute texture dimensions to fit all particles
+        // Total particles = density * density * particles
+        var totalParticles = props.density * props.density * props.particles;
+        // Find suitable texture dimensions (width should be power of 2 for compatibility)
+        // Use a width that balances the texture shape
+        var width = 256;
+        while (width * width < totalParticles) {
+            width *= 2;
+        }
+        var height = Math.ceil(totalParticles / width);
+        posTexWidth.current = width;
+        posTexHeight.current = height;
+        var texture = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        return texture;
+    };
+    var createQuadBuffer = function (gl) {
+        // Full-screen quad (two triangles covering clip space)
+        bufferQuad.current = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, bufferQuad.current);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
+            -1, -1,
+            1, -1,
+            -1, 1,
+            -1, 1,
+            1, -1,
+            1, 1
+        ]), gl.STATIC_DRAW);
+    };
     var createBufferU = function (gl) {
         var min = getGeometryU[0], max = getGeometryU[1], geometry = getGeometryU[2];
         minU.current = min;
@@ -240,16 +299,20 @@ var ParticlesLayerBase = function (props) {
         createBufferU(gl);
         createBufferV(gl);
         createBufferScreen(gl);
+        createQuadBuffer(gl);
         createUVProgram(gl);
         createParticlesProgram(gl);
-        textureU.current = createTexture(gl);
-        textureV.current = createTexture(gl);
-        fboU.current = createFrameBuffer(gl, textureU.current);
-        fboV.current = createFrameBuffer(gl, textureV.current);
+        createPositionComputeProgram(gl);
+        // Single combined texture for both U and V (U in R, V in G)
+        textureUV.current = createTexture(gl);
+        fboUV.current = createFrameBuffer(gl, textureUV.current);
+        // Position texture for pre-computed particle positions
+        texturePosition.current = createPositionTexture(gl);
+        fboPosition.current = createFrameBuffer(gl, texturePosition.current);
     };
     var renderSpeedBuffer = function (gl, matrix, buffer, numTriangles) {
         gl.useProgram(uvProgram.current);
-        // Pass a matrix uniform in: 
+        // Pass a matrix uniform in:
         gl.uniformMatrix4fv(gl.getUniformLocation(uvProgram.current, 'u_matrix'), false, matrix);
         // Vertices:
         var aPos = gl.getAttribLocation(uvProgram.current, 'a_pos');
@@ -263,6 +326,43 @@ var ParticlesLayerBase = function (props) {
         gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.drawArrays(gl.TRIANGLES, 0, numTriangles * 3);
     };
+    //
+    // Render particle positions to the position texture.
+    // This moves the expensive trace loop from the particle vertex shader
+    // to a one-time-per-view-change fragment shader pass.
+    //
+    var renderPositionTexture = function (gl) {
+        gl.useProgram(positionProgram.current);
+        // Bind position framebuffer
+        gl.bindFramebuffer(gl.FRAMEBUFFER, fboPosition.current);
+        gl.viewport(0, 0, posTexWidth.current, posTexHeight.current);
+        gl.clearColor(0, 0, 0, 0);
+        gl.clear(gl.COLOR_BUFFER_BIT);
+        // Disable blending for position computation
+        gl.disable(gl.BLEND);
+        // UV texture (already rendered)
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, textureUV.current);
+        gl.uniform1i(gl.getUniformLocation(positionProgram.current, 'uvTexture'), 0);
+        // UV range uniforms
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'minU'), minU.current);
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'maxU'), maxU.current);
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'minV'), minV.current);
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'maxV'), maxV.current);
+        // Grid parameters
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'u_density'), props.density);
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'u_particles'), props.particles);
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'u_texWidth'), posTexWidth.current);
+        // Velocity magnitude remapping parameters
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'u_minVisMag'), props.minSpeed);
+        gl.uniform1f(gl.getUniformLocation(positionProgram.current, 'u_maxVisMag'), props.maxSpeed);
+        // Render full-screen quad
+        var aPos = gl.getAttribLocation(positionProgram.current, 'a_pos');
+        gl.bindBuffer(gl.ARRAY_BUFFER, bufferQuad.current);
+        gl.enableVertexAttribArray(aPos);
+        gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0);
+        gl.drawArrays(gl.TRIANGLES, 0, 6);
+    };
     var renderParticles = function (gl, matrix) {
         gl.useProgram(particlesProgram.current);
         // Matrix: 
@@ -281,19 +381,14 @@ var ParticlesLayerBase = function (props) {
         gl.uniform1i(gl.getUniformLocation(particlesProgram.current, "u_num_instances"), props.particles);
         // Size of points to be drawn (in pixels).
         gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "u_point_size"), props.pointSize);
-        // U/V mins and maxes:
-        gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "minU"), minU.current);
-        gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "maxU"), maxU.current);
-        gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "minV"), minV.current);
-        gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "maxV"), maxV.current);
-        // u-texture:
+        // Position texture (pre-computed particle positions):
         gl.activeTexture(gl.TEXTURE0);
-        gl.bindTexture(gl.TEXTURE_2D, textureU.current);
-        gl.uniform1i(gl.getUniformLocation(particlesProgram.current, "uTexture"), 0);
-        // v-texture:
-        gl.activeTexture(gl.TEXTURE1);
-        gl.bindTexture(gl.TEXTURE_2D, textureV.current);
-        gl.uniform1i(gl.getUniformLocation(particlesProgram.current, "vTexture"), 1);
+        gl.bindTexture(gl.TEXTURE_2D, texturePosition.current);
+        gl.uniform1i(gl.getUniformLocation(particlesProgram.current, "positionTexture"), 0);
+        // Position texture dimensions and grid parameters for coordinate lookup:
+        gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "u_posTexWidth"), posTexWidth.current);
+        gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "u_posTexHeight"), posTexHeight.current);
+        gl.uniform1f(gl.getUniformLocation(particlesProgram.current, "u_density"), props.density);
         // Vertices:
         var aPos = gl.getAttribLocation(particlesProgram.current, 'a_pos'); // on-screen position [-1..1]
         var aIdx = gl.getAttribLocation(particlesProgram.current, 'a_idx'); // particle index
@@ -309,24 +404,46 @@ var ParticlesLayerBase = function (props) {
         gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.drawArrays(gl.POINTS, 0, props.density * props.density * props.particles);
     };
+    //
+    // Check if two matrices are equal.
+    //
+    var matricesEqual = function (a, b) {
+        if (!a || !b)
+            return false;
+        for (var i = 0; i < 16; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    };
     var onRender = function (gl, matrix, zoom, width, height) {
         if (zoom < props.minZoom)
             return;
         if (zoom > props.maxZoom)
             return;
-        gl.useProgram(uvProgram.current);
-        // Render U-texture:
-        gl.bindFramebuffer(gl.FRAMEBUFFER, fboU.current);
-        gl.viewport(0, 0, TEXTURE_WIDTH, TEXTURE_HEIGHT);
-        gl.clearColor(0, 0, 0, 0); // clear to transparent
-        gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
-        renderSpeedBuffer(gl, matrix, bufferU.current, numTrianglesU.current);
-        // Render V-texture:
-        gl.bindFramebuffer(gl.FRAMEBUFFER, fboV.current);
-        gl.viewport(0, 0, TEXTURE_WIDTH, TEXTURE_HEIGHT);
-        gl.clearColor(0, 0, 0, 0); // clear to transparent
-        gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
-        renderSpeedBuffer(gl, matrix, bufferV.current, numTrianglesV.current);
+        // Only re-render UV textures when the matrix changes (i.e., when the map
+        // view changes due to panning or zooming). This is a significant performance
+        // optimization since UV texture rendering involves expensive draw calls.
+        var matrixChanged = !matricesEqual(matrix, lastMatrix.current);
+        if (matrixChanged) {
+            lastMatrix.current = __spreadArray([], matrix, true);
+            gl.useProgram(uvProgram.current);
+            // Render to combined UV texture (U in R channel, V in G channel)
+            gl.bindFramebuffer(gl.FRAMEBUFFER, fboUV.current);
+            gl.viewport(0, 0, TEXTURE_WIDTH, TEXTURE_HEIGHT);
+            gl.clearColor(0, 0, 0, 0); // clear to transparent
+            gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+            // Render U to R channel and A channel (alpha indicates valid data)
+            gl.colorMask(true, false, false, true);
+            renderSpeedBuffer(gl, matrix, bufferU.current, numTrianglesU.current);
+            // Render V to G channel only (preserve R and A from U pass)
+            gl.colorMask(false, true, false, false);
+            renderSpeedBuffer(gl, matrix, bufferV.current, numTrianglesV.current);
+            // Reset color mask to default
+            gl.colorMask(true, true, true, true);
+            // Compute particle positions (moves expensive loop from vertex shader)
+            renderPositionTexture(gl);
+        }
         // Unbind framebuffer so we're rendering to the screen:
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         // Reset the viewport size to equal the map size:
@@ -336,14 +453,98 @@ var ParticlesLayerBase = function (props) {
     };
     return (React.createElement(Layer, { id: null, type: "custom", beforeId: "overlay", key: time, onAdd: onAddLayer, render: function (gl, matrix) { return onRender(gl, matrix, map.current.getZoom(), map.current.getContainer().clientWidth, map.current.getContainer().clientHeight); } }));
 };
+/**
+ * A WebGL-based Mapbox GL custom layer that visualizes vector flow fields (such as
+ * ocean currents or wind patterns) using animated particle trails.
+ *
+ * ## Overview
+ *
+ * The component takes an array of data points, each with a geographic position and
+ * a velocity vector (U and V components). It renders animated particles that flow
+ * along these velocity vectors, creating a visual representation of the flow field.
+ *
+ * Particle trails are colored using a configurable gradient, where the head of the
+ * trail is typically bright and the tail fades out. The animation continuously cycles
+ * particles through their trails, creating a flowing effect.
+ *
+ * ## Data Format
+ *
+ * Input data should be an array of points with the following structure:
+ *
+ * ```typescript
+ * interface IPoint {
+ *   latitude: number;   // Geographic latitude
+ *   longitude: number;  // Geographic longitude
+ *   u: number;          // Velocity component in X direction
+ *   v: number;          // Velocity component in Y direction
+ * }
+ * ```
+ *
+ * The component uses Delaunay triangulation (via Turf.js) to interpolate velocity
+ * values between data points, so the data does not need to be on a regular grid.
+ *
+ * ## Velocity Remapping
+ *
+ * To ensure all particles have visible trails regardless of the actual velocity
+ * magnitudes in the data, velocities are linearly remapped to a visible range:
+ *
+ * - The `minSpeed` prop sets the minimum trail speed (for the slowest currents)
+ * - The `maxSpeed` prop sets the maximum trail speed (for the fastest currents)
+ * - All velocities are scaled proportionally within this range
+ * - The relative differences between fast and slow currents are preserved
+ * - Particles with exactly zero velocity are not rendered
+ *
+ * ## Performance
+ *
+ * The component is optimized for performance using several GPU-based techniques:
+ *
+ * 1. **UV Texture Caching**: The velocity field is rendered to a texture only when
+ *    the map view changes (pan/zoom), not on every animation frame.
+ *
+ * 2. **Combined UV Texture**: U and V components are stored in a single texture
+ *    (U in red channel, V in green channel) to reduce texture fetches.
+ *
+ * 3. **Position Pre-computation**: Particle positions are pre-computed in a GPU
+ *    shader pass when the view changes, eliminating expensive per-vertex loops
+ *    during animation.
+ *
+ * With default settings (`density=40`, `particles=80`), the component renders
+ * 128,000 particles efficiently.
+ *
+ * ## Example
+ *
+ * ```tsx
+ * <Map>
+ *   <ParticlesLayer
+ *     data={oceanCurrentData}
+ *     density={50}
+ *     particles={100}
+ *     gradientStops={[
+ *       { pos: 0.0, color: '#00ffffff' },
+ *       { pos: 0.5, color: '#0088ffff' },
+ *       { pos: 1.0, color: '#0088ff00' },
+ *     ]}
+ *     minSpeed={0.01}
+ *     maxSpeed={0.2}
+ *   />
+ * </Map>
+ * ```
+ *
+ * ## Notes
+ *
+ * - The component requires a Mapbox GL map context (via `react-map-gl`)
+ * - WebGL 1.0 is used for maximum browser compatibility (no extensions required)
+ * - The layer renders before the "overlay" layer in the Mapbox style
+ * - Changing props triggers a full re-initialization of the WebGL resources
+ */
 var ParticlesLayer = function (_a) {
     var _b = _a.particles, particles = _b === void 0 ? 80 : _b, _c = _a.density, density = _c === void 0 ? 40 : _c, _d = _a.delay, delay = _d === void 0 ? 0 : _d, _e = _a.gradientStops, gradientStops = _e === void 0 ? [
         { pos: 0.0, color: '#ffffffff' },
         { pos: 0.25, color: '#5c5cffff' },
         { pos: 0.5, color: '#5c5cff00' },
         { pos: 1.0, color: '#5c5cff00' }, // transparent blue
-    ] : _e, _f = _a.minZoom, minZoom = _f === void 0 ? 0 : _f, _g = _a.maxZoom, maxZoom = _g === void 0 ? 99 : _g, props = __rest(_a, ["particles", "density", "delay", "gradientStops", "minZoom", "maxZoom"]);
-    return React.createElement(ParticlesLayerBase, __assign({ particles: particles, density: density, gradientStops: gradientStops, delay: delay, minZoom: minZoom, maxZoom: maxZoom }, props));
+    ] : _e, _f = _a.minZoom, minZoom = _f === void 0 ? 0 : _f, _g = _a.maxZoom, maxZoom = _g === void 0 ? 99 : _g, _h = _a.minSpeed, minSpeed = _h === void 0 ? 0.02 : _h, _j = _a.maxSpeed, maxSpeed = _j === void 0 ? 0.15 : _j, props = __rest(_a, ["particles", "density", "delay", "gradientStops", "minZoom", "maxZoom", "minSpeed", "maxSpeed"]);
+    return React.createElement(ParticlesLayerBase, __assign({ particles: particles, density: density, gradientStops: gradientStops, delay: delay, minZoom: minZoom, maxZoom: maxZoom, minSpeed: minSpeed, maxSpeed: maxSpeed }, props));
 };
 ParticlesLayer.displayName = 'ParticlesLayer';
 export { ParticlesLayer };

package/map/layers/ParticlesLayer/ParticlesVertexShader.d.ts

@@ -1,2 +1,2 @@
-declare const ParticlesVertexShader = "\n  uniform   mat4 u_matrix;\n  attribute vec2 a_pos;\n  attribute float a_idx;\n  attribute float a_offset;\n\n  uniform float u_point_size;\n  uniform int u_num_instances;\n  uniform int u_frame;\n  uniform sampler2D uTexture;\n  uniform sampler2D vTexture;  \n  uniform float minU;\n  uniform float maxU;\n  uniform float minV;\n  uniform float maxV;\n  uniform float u_gradientStops[12];\n  uniform vec4 u_gradientColors[12];  \n\n  // Output color, calculated by this vertex shader:\n  varying vec4 v_color;\n\n  //\n  // Returns texture color at pixelCoord.\n  //\n  vec4 texelFetch(sampler2D tex, vec2 normalizedCoord) {\n    return texture2D(tex, normalizedCoord);\n  }\n\n  //\n  // Given a value, find its corresponding color in the gradient stops.\n  //\n  vec4 getGradientColor(float position) {\n    // Find left and right stop:\n    float left = -1.0;\n    float right = 99.0;\n    vec4 leftColor;\n    vec4 rightColor;\n\n    for(int i = 0; i < 12; i++) {\n      if (u_gradientStops[i] <= position) {\n        left = u_gradientStops[i]; \n        leftColor = u_gradientColors[i];\n      } else break;\n    }\n\n    for(int i = 12 - 1; i >= 0; i--) {\n      if (u_gradientStops[i] >= position) {\n        right = u_gradientStops[i]; \n        rightColor = u_gradientColors[i];\n      } else break;\n    }\n\n    // Distance between stops:\n    float width = right - left;\n    // Distance from left stop:\n    float dist = position - left;\n    // Right stop weight:\n    float weight;\n    if(dist == 0.0) {\n      weight = dist;\n    } else {\n      weight = dist / width;\n    }\n\n    float r = leftColor.x + (rightColor.x - leftColor.x) * weight;\n    float g = leftColor.y + (rightColor.y - leftColor.y) * weight;\n    float b = leftColor.z + (rightColor.z - leftColor.z) * weight;\n    float a = leftColor.w + (rightColor.w - leftColor.w) * weight;\n    return vec4(r, g, b, a);    \n  }   \n\n  // Vertex shader merely sets vertex position. Fragment shader \n  // does all the work.\n  void main() {\n    int idx = int(a_idx);   \n    int offset = int(a_offset);\n    int frame = u_frame + offset;\n    if(frame >= u_num_instances) frame -= u_num_instances;\n\n    // Determine color from frame.\n    int start = idx - frame;\n    if(start < 0) start += u_num_instances;\n    v_color = getGradientColor(float(u_num_instances - start) / float(u_num_instances));\n\n    // a_pos.x is -1..1, left to right.\n    // a_pox.y is -1..1, bottom to top (negative is bottom).\n    vec2 pos = a_pos; // Start off at initial position.\n\n    // Find initial U. If there isn't one (outside of bounds of texture), \n    // then we don't draw anything.\n    float w = texelFetch(uTexture, (pos + 1.0) / 2.0).w;\n    if(w == 0.0) return;\n\n\n    // Use velocity vector [idx] times.\n    float uRange = maxU - minU;\n    float vRange = maxV - minV;\n\n    for(int i = 1; i < 100; i++) {\n      if(i > idx) break;\n      // Find velocity vector at current position.\n      // u and v are 0..1 values.\n      vec4 uColor = texelFetch(uTexture, (pos + 1.0) / 2.0);\n      vec4 vColor = texelFetch(vTexture, (pos + 1.0) / 2.0);\n      if(uColor.w == 0.0) return;\n      float u = uRange * uColor.x + minU;\n      float v = vRange * vColor.x + minV;\n      \n      pos.x += u / 10.0;\n      pos.y += v / 10.0;\n      if(pos.x <= -1.0 || pos.x >= 1.0 || pos.y <= -1.0 || pos.x >= 1.0) {\n        return;\n      }\n    }\n\n    gl_Position = vec4(pos.x, pos.y, 0.0, 1.0);\n    gl_PointSize = u_point_size;\n  }\n";
+declare const ParticlesVertexShader = "\n  attribute vec2 a_pos;\n  attribute float a_idx;\n  attribute float a_offset;\n\n  uniform float u_point_size;\n  uniform int u_num_instances;\n  uniform int u_frame;\n  uniform sampler2D positionTexture;  // Pre-computed positions (X in RG, Y in BA)\n  uniform float u_posTexWidth;\n  uniform float u_posTexHeight;\n  uniform float u_density;\n  uniform float u_gradientStops[12];\n  uniform vec4 u_gradientColors[12];\n\n  // Output color, calculated by this vertex shader:\n  varying vec4 v_color;\n\n  //\n  // Given a value, find its corresponding color in the gradient stops.\n  //\n  vec4 getGradientColor(float position) {\n    // Find left and right stop:\n    float left = -1.0;\n    float right = 99.0;\n    vec4 leftColor;\n    vec4 rightColor;\n\n    for(int i = 0; i < 12; i++) {\n      if (u_gradientStops[i] <= position) {\n        left = u_gradientStops[i];\n        leftColor = u_gradientColors[i];\n      } else break;\n    }\n\n    for(int i = 12 - 1; i >= 0; i--) {\n      if (u_gradientStops[i] >= position) {\n        right = u_gradientStops[i];\n        rightColor = u_gradientColors[i];\n      } else break;\n    }\n\n    // Distance between stops:\n    float width = right - left;\n    // Distance from left stop:\n    float dist = position - left;\n    // Right stop weight:\n    float weight;\n    if(dist == 0.0) {\n      weight = dist;\n    } else {\n      weight = dist / width;\n    }\n\n    float r = leftColor.x + (rightColor.x - leftColor.x) * weight;\n    float g = leftColor.y + (rightColor.y - leftColor.y) * weight;\n    float b = leftColor.z + (rightColor.z - leftColor.z) * weight;\n    float a = leftColor.w + (rightColor.w - leftColor.w) * weight;\n    return vec4(r, g, b, a);\n  }\n\n  // Decode a 16-bit encoded position from two bytes (high, low as 0-1 floats)\n  float decodePosition(float hi, float lo) {\n    float encoded = hi * 255.0 * 256.0 + lo * 255.0;\n    return encoded / 65535.0 * 2.0 - 1.0;\n  }\n\n  void main() {\n    int idx = int(a_idx);\n    int offset = int(a_offset);\n    int frame = u_frame + offset;\n    if(frame >= u_num_instances) frame -= u_num_instances;\n\n    // Determine color from frame.\n    int start = idx - frame;\n    if(start < 0) start += u_num_instances;\n    v_color = getGradientColor(float(u_num_instances - start) / float(u_num_instances));\n\n    // Compute texture coordinates for this particle's pre-computed position.\n    // WebGL 1 doesn't have gl_VertexID, so we compute the particle index from\n    // vertex attributes. The vertex buffer layout is:\n    // for y in [0, density): for x in [0, density): for i in [0, particles): (pos, idx, offset)\n\n    // Convert grid position back to grid index\n    float gridX = (a_pos.x + 0.99) * (u_density - 1.0) / 1.98;\n    float gridY = (a_pos.y + 0.99) * (u_density - 1.0) / 1.98;\n    float gridIndex = floor(gridY + 0.5) * u_density + floor(gridX + 0.5);\n    float particleIdx = gridIndex * float(u_num_instances) + a_idx;\n\n    // Convert particle index to texture coordinates\n    float texX = mod(particleIdx, u_posTexWidth);\n    float texY = floor(particleIdx / u_posTexWidth);\n\n    // Sample position texture (add 0.5 to sample pixel center)\n    vec2 texCoord = vec2((texX + 0.5) / u_posTexWidth, (texY + 0.5) / u_posTexHeight);\n    vec4 encodedPos = texture2D(positionTexture, texCoord);\n\n    // Decode position (X in RG, Y in BA)\n    float posX = decodePosition(encodedPos.r, encodedPos.g);\n    float posY = decodePosition(encodedPos.b, encodedPos.a);\n\n    // Check for off-screen marker (position > 1.5 means invalid)\n    if(posX > 1.5) return;\n\n    gl_Position = vec4(posX, posY, 0.0, 1.0);\n    gl_PointSize = u_point_size;\n  }\n";
 export { ParticlesVertexShader };