@fxi/zartigl 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { CustomLayerInterface } from 'maplibre-gl';
 import { CustomRenderMethodInput } from 'maplibre-gl';
 import { Map as Map_2 } from 'maplibre-gl';
 
+export declare type ColorRampInput = string | string[] | Record<number, string>;
+
 declare interface CoordArrays {
     time: Float64Array | Float32Array;
     vertical: Float32Array;
@@ -9,35 +11,107 @@ declare interface CoordArrays {
     longitude: Float32Array;
 }
 
+export declare interface FieldMeta {
+    min: number;
+    max: number;
+    unit: string;
+    time: string;
+    depth?: number;
+}
+
+export declare function getPalettes(): PaletteMeta[];
+
+declare type LayerEventMap = {
+    loading: () => void;
+    loaded: (meta: FieldMeta) => void;
+    error: (err: Error) => void;
+    /** Fired when a time step has been pre-fetched and is ready for instant swap. */
+    frameBuffered: (ms: number) => void;
+    /** Fired when the frame cache is wiped (viewport changed). */
+    cacheInvalidated: () => void;
+};
+
+export declare interface PaletteMeta {
+    id: string;
+    label: string;
+    tags: string[];
+    colors: string[];
+}
+
 export declare class ParticleLayer implements CustomLayerInterface {
     readonly id: string;
     readonly type: "custom";
-    readonly renderingMode: "2d";
+    readonly renderingMode: "3d";
     private map;
     private gl;
     private simulation;
     private velocityField;
     private zarrSource;
-    private opts;
+    private speedFactorParam;
+    private fadeOpacityParam;
+    private zoomRange;
+    private variableU;
+    private variableV;
+    private time;
+    private depth;
+    private scalarMode;
+    private scalarUnit;
     private initialized;
     private loading;
     private velocityTexUnit;
+    private moveStartHandler;
     private moveEndHandler;
+    /** Pre-fetched frames keyed by time-ms. Cleared when the viewport changes. */
+    private frameCache;
+    /** Time-ms values currently being fetched in the background. */
+    private inflight;
+    private listeners;
     constructor(options: ParticleLayerOptions);
     onAdd(map: Map_2, gl: WebGLRenderingContext): Promise<void>;
     private initAsync;
+    private timeToMs;
+    private computeFieldMeta;
+    /**
+     * Fetch and stitch velocity data for the given time without touching GL state.
+     * The map's current viewport is used to determine the lat bounds of the request.
+     */
+    private fetchVelocityData;
     private loadViewportVelocity;
     render(gl: WebGLRenderingContext, options: CustomRenderMethodInput | number[]): void;
     onRemove(): void;
+    /**
+     * Interpolate speed and fade per render frame (cheap uniform uploads).
+     * t=0 at low zoom (global), t=1 at high zoom (local).
+     * For each range [min, max]: min applies at high zoom, max at low zoom.
+     */
+    private applyZoomWeighting;
     setTime(time: string | number): void;
+    /**
+     * Pre-fetch velocity data for a future time step without swapping the active
+     * field. Fires `frameBuffered(ms)` when ready so playback can advance
+     * immediately without a loading gap.
+     */
+    prefetchTime(ms: number): Promise<void>;
+    /** True when the frame for the given time (ms) is already in the cache. */
+    isFrameCached(ms: number): boolean;
+    /** Abort all pending Zarr prefetch fetches and clear the inflight set. */
+    cancelPrefetches(): void;
     setDepth(depth: number): void;
-    setSpeedFactor(v: number): void;
-    setFadeOpacity(v: number): void;
+    setSpeedFactor(v: ZoomWeighted): void;
+    setFadeOpacity(v: ZoomWeighted): void;
     setDropRate(v: number): void;
     setDropRateBump(v: number): void;
-    setPointSize(v: number): void;
-    setParticleCount(count: number): void;
-    setColorRamp(ramp: Record<number, string>): void;
+    setParticleDensity(density: number): void;
+    setZoomRange(range: [number, number]): void;
+    setColorRamp(ramp: ColorRampInput): void;
+    setRenderMode(mode: RenderMode): void;
+    setOpacity(v: number): void;
+    setLogScale(v: boolean): void;
+    setVibrance(v: number): void;
+    setScalarVariable(varName: string): void;
+    on<K extends keyof LayerEventMap>(event: K, handler: LayerEventMap[K]): this;
+    off<K extends keyof LayerEventMap>(event: K, handler: LayerEventMap[K]): this;
+    private emit;
 }
 
 export declare interface ParticleLayerOptions {
@@ -45,15 +119,27 @@ export declare interface ParticleLayerOptions {
     source: string;
     variableU?: string;
     variableV?: string;
-    particleCount?: number;
-    speedFactor?: number;
-    fadeOpacity?: number;
+    /** Particles per screen pixel. Count = clamp(w × h × density, 1, 262144). Default 0.05. */
+    particleDensity?: number;
+    /** Fixed speed or [atHighZoom, atLowZoom]. */
+    speedFactor?: ZoomWeighted;
+    /** Fixed fade or [atHighZoom, atLowZoom]. */
+    fadeOpacity?: ZoomWeighted;
     dropRate?: number;
     dropRateBump?: number;
-    pointSize?: number;
     colorRamp?: Record<number, string>;
     time?: string | number;
     depth?: number;
+    /** [lowZoom, highZoom] breakpoints for zoom-weighted params. Default [2, 12]. */
+    zoomRange?: [number, number];
+    /** Global layer opacity [0, 1]. Default 1.0. */
+    opacity?: number;
+    /** Logarithmic speed normalization. Default false. */
+    logScale?: boolean;
+    /** Vibrance adjustment [-1, 1]. Default 0.0. */
+    vibrance?: number;
+    scalarMode?: boolean;
+    scalarUnit?: string;
 }
 
 export declare class ParticleSimulation {
@@ -62,10 +148,12 @@ export declare class ParticleSimulation {
     private updateProgram;
     private drawProgram;
     private fadeProgram;
+    private gridProgram;
     private particleStateTextures;
     private particleFramebuffers;
-    private particleStateRes;
     private particleIndexBuffer;
+    private particleIsCurrBuffer;
+    /** Active draw count — changes with canvas size / density, no realloc. */
     private numParticles;
     private screenTextures;
     private screenFramebuffers;
@@ -73,15 +161,18 @@ export declare class ParticleSimulation {
     private screenHeight;
     private quadBuffer;
     private colorRampTexture;
+    renderMode: RenderMode;
     private updateLocs;
     private drawLocs;
     private fadeLocs;
+    private gridLocs;
     constructor(params?: Partial<SimulationParams>);
     init(gl: WebGLRenderingContext): void;
     private getUniforms;
     private initParticleState;
     /**
-     * Ensure screen textures match the current canvas size.
+     * Ensure screen textures match the current canvas size and recompute
+     * the active particle count from density × canvas area.
      */
     resize(width: number, height: number): void;
     /**
@@ -93,35 +184,51 @@ export declare class ParticleSimulation {
         minY: number;
         maxX: number;
         maxY: number;
-    }, worldSize: number, geoBounds?: {
+    }, worldSize: number, worldCopyOffsets: number[], geoBounds?: {
         west: number;
         south: number;
         east: number;
         north: number;
-    }): void;
+    }, isGlobe?: boolean): void;
     private drawQuad;
     setSpeedFactor(v: number): void;
     setFadeOpacity(v: number): void;
     setDropRate(v: number): void;
     setDropRateBump(v: number): void;
-    setPointSize(v: number): void;
-    setParticleCount(count: number): void;
+    setParticleDensity(density: number): void;
     setColorRamp(ramp: Record<number, string>): void;
+    setRenderMode(mode: RenderMode): void;
+    setOpacity(v: number): void;
+    setLogScale(v: boolean): void;
+    setVibrance(v: number): void;
+    setScalarMode(v: boolean): void;
     /**
-     * Reset all particles to random positions. Call after time/depth change.
+     * Reset all particles to random positions. Call after time/depth change
+     * or map move. Randomises the full state texture and clears trail FBOs.
      */
     resetParticles(): void;
+    /**
+     * Clear screen framebuffers to transparent black.
+     * Eliminates ghost trails when the viewport shifts.
+     */
+    clearState(): void;
     destroy(): void;
 }
 
+declare type RenderMode = 'raster' | 'particles' | 'raster+particles';
+
 declare interface SimulationParams {
-    particleCount: number;
+    /** Particles per screen pixel. Active count = clamp(w * h * density, 1, MAX). */
+    particleDensity: number;
     speedFactor: number;
     fadeOpacity: number;
     dropRate: number;
     dropRateBump: number;
-    pointSize: number;
     colorRamp?: Record<number, string>;
+    opacity: number;
+    logScale: boolean;
+    vibrance: number;
+    scalarMode: boolean;
 }
 
 /**
@@ -135,18 +242,20 @@ export declare function stitchVelocityChunks(uChunks: Array<{
     lonStart: number;
     latSize: number;
     lonSize: number;
+    lonChunkSize: number;
 }>, vChunks: Array<{
     data: Float32Array;
     latStart: number;
     lonStart: number;
     latSize: number;
     lonSize: number;
+    lonChunkSize: number;
 }>, totalLat: number, totalLon: number, geoBounds?: {
     west: number;
     south: number;
     east: number;
     north: number;
-}): VelocityData;
+}, latDescending?: boolean, scalarMode?: boolean): VelocityData;
 
 export declare interface VelocityData {
     u: Float32Array;
@@ -163,6 +272,10 @@ export declare interface VelocityData {
         east: number;
         north: number;
     };
+    /** True when latitude rows are stored north-to-south (needs GL Y-flip). */
+    latDescending?: boolean;
+    /** When true: R=scalar_norm, G=128(neutral), V loop skipped. */
+    scalarMode?: boolean;
 }
 
 /**
@@ -184,6 +297,8 @@ export declare class VelocityField {
         east: number;
         north: number;
     };
+    scalarMode: boolean;
+    private linearFilter;
     init(gl: WebGLRenderingContext): void;
     /**
      * Upload velocity data as a 2-channel (RG) texture.
@@ -191,6 +306,8 @@ export declare class VelocityField {
      * Stored normalized to [0,1] using uMin/uMax/vMin/vMax.
      */
     update(data: VelocityData): void;
+    /** Switch between bilinear (particles) and nearest-neighbour (raster) sampling. */
+    setFilter(linear: boolean): void;
     bind(unit: number): void;
     hasData(): boolean;
     destroy(): void;
@@ -236,6 +353,7 @@ export declare class ZarrSource {
     private meta;
     private coords;
     private verticalName;
+    private timeUnits;
     private cache;
     private maxCacheSize;
     private abortControllers;
@@ -251,6 +369,12 @@ export declare class ZarrSource {
     getDimensions(variable: string): string[];
     findNearestIndex(array: Float32Array | Float64Array, value: number): number;
     findTimeIndex(time: string | number): number;
+    /**
+     * Convert a Unix-ms timestamp to the native time units used by this zarr
+     * (read from the time variable's .zattrs "units" field).
+     * Falls back to a magnitude heuristic when units are absent or unparseable.
+     */
+    private msToZarrTime;
     findDepthIndex(depth: number): number;
     /** Return the actual name of the vertical dimension ("depth" or "elevation"). */
     getVerticalDimName(): string;
@@ -279,4 +403,14 @@ export declare class ZarrSource {
     private loadCoordinates;
 }
 
+/**
+ * A param that is either a fixed scalar or a zoom-weighted range.
+ * When a range [min, max] is given:
+ *   - min is the value at high zoom (local / detail view)
+ *   - max is the value at low zoom  (global / overview)
+ * The layer interpolates between them based on the current map zoom
+ * and the configured zoomRange.
+ */
+export declare type ZoomWeighted = number | [min: number, max: number];
+
 export { }