@fxi/zartigl 0.1.4 → 0.2.14

package/dist/index.d.ts

@@ -1,416 +0,0 @@
-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;
-    latitude: Float32Array;
-    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: "3d";
-    private map;
-    private gl;
-    private simulation;
-    private velocityField;
-    private zarrSource;
-    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: ZoomWeighted): void;
-    setFadeOpacity(v: ZoomWeighted): void;
-    setDropRate(v: number): void;
-    setDropRateBump(v: number): 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 {
-    id: string;
-    source: string;
-    variableU?: string;
-    variableV?: string;
-    /** 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;
-    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 {
-    private gl;
-    private params;
-    private updateProgram;
-    private drawProgram;
-    private fadeProgram;
-    private gridProgram;
-    private particleStateTextures;
-    private particleFramebuffers;
-    private particleIndexBuffer;
-    private particleIsCurrBuffer;
-    /** Active draw count — changes with canvas size / density, no realloc. */
-    private numParticles;
-    private screenTextures;
-    private screenFramebuffers;
-    private screenWidth;
-    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 and recompute
-     * the active particle count from density × canvas area.
-     */
-    resize(width: number, height: number): void;
-    /**
-     * Run one simulation step: update positions, fade trails, draw particles.
-     * Must be called within the MapLibre render callback.
-     */
-    render(velocityTexUnit: number, velocityMin: [number, number], velocityMax: [number, number], matrix: Iterable<number>, bounds: {
-        minX: number;
-        minY: number;
-        maxX: number;
-        maxY: number;
-    }, worldSize: number, worldCopyOffsets: number[], geoBounds?: {
-        west: number;
-        south: number;
-        east: number;
-        north: number;
-    }, isGlobe?: boolean): void;
-    private drawQuad;
-    setSpeedFactor(v: number): void;
-    setFadeOpacity(v: number): void;
-    setDropRate(v: number): void;
-    setDropRateBump(v: 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
-     * 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 {
-    /** Particles per screen pixel. Active count = clamp(w * h * density, 1, MAX). */
-    particleDensity: number;
-    speedFactor: number;
-    fadeOpacity: number;
-    dropRate: number;
-    dropRateBump: number;
-    colorRamp?: Record<number, string>;
-    opacity: number;
-    logScale: boolean;
-    vibrance: number;
-    scalarMode: boolean;
-}
-
-/**
- * Stitch multiple decoded chunks into a single global velocity grid.
- * The result covers [0,360) longitude x [-90,90] latitude.
- * Grid resolution matches the source data.
- */
-export declare function stitchVelocityChunks(uChunks: Array<{
-    data: Float32Array;
-    latStart: number;
-    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;
-}, latDescending?: boolean, scalarMode?: boolean): VelocityData;
-
-export declare interface VelocityData {
-    u: Float32Array;
-    v: Float32Array;
-    width: number;
-    height: number;
-    uMin: number;
-    uMax: number;
-    vMin: number;
-    vMax: number;
-    bounds: {
-        west: number;
-        south: number;
-        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;
-}
-
-/**
- * Manages a WebGL texture that holds stitched U/V velocity data
- * in geographic space [0,1]x[0,1], with R=u, G=v normalized to [0,1].
- */
-export declare class VelocityField {
-    private gl;
-    private texture;
-    private width;
-    private height;
-    uMin: number;
-    uMax: number;
-    vMin: number;
-    vMax: number;
-    geoBounds: {
-        west: number;
-        south: number;
-        east: number;
-        north: number;
-    };
-    scalarMode: boolean;
-    private linearFilter;
-    init(gl: WebGLRenderingContext): void;
-    /**
-     * Upload velocity data as a 2-channel (RG) texture.
-     * Input: u/v Float32Arrays with real physical values.
-     * 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;
-}
-
-export declare interface ZarrArrayMeta {
-    zarr_format: number;
-    shape: number[];
-    chunks: number[];
-    dtype: string;
-    compressor: {
-        id: string;
-        level?: number;
-        clevel?: number;
-        cname?: string;
-        shuffle?: number;
-        blocksize?: number;
-    } | null;
-    fill_value: number | string | null;
-    order: string;
-    filters: unknown[] | null;
-    dimension_separator?: string;
-}
-
-declare interface ZarrAttrs {
-    _ARRAY_DIMENSIONS?: string[];
-    units?: string;
-    standard_name?: string;
-    long_name?: string;
-    calendar?: string;
-    [key: string]: unknown;
-}
-
-export declare interface ZarrConsolidatedMeta {
-    zarr_consolidated_format: number;
-    metadata: Record<string, ZarrArrayMeta | ZarrAttrs | {
-        zarr_format: number;
-    }>;
-}
-
-export declare class ZarrSource {
-    private root;
-    private meta;
-    private coords;
-    private verticalName;
-    private timeUnits;
-    private cache;
-    private maxCacheSize;
-    private abortControllers;
-    private bloscCodecCache;
-    constructor(root: string, maxCacheSize?: number);
-    init(): Promise<void>;
-    private getArrayMeta;
-    private getAttrs;
-    getDimensionSeparator(variable: string): string;
-    getShape(variable: string): number[];
-    getChunkShape(variable: string): number[];
-    getCoords(): CoordArrays;
-    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;
-    /**
-     * Get chunk indices that intersect a geographic bounding box.
-     */
-    getChunksForBounds(variable: string, timeIdx: number, depthIdx: number, bounds: {
-        west: number;
-        south: number;
-        east: number;
-        north: number;
-    }): Array<{
-        timeIdx: number;
-        depthIdx: number;
-        latIdx: number;
-        lonIdx: number;
-        latRange: [number, number];
-        lonRange: [number, number];
-        latSize: number;
-        lonSize: number;
-    }>;
-    fetchChunk(variable: string, indices: number[]): Promise<Float32Array>;
-    cancelAll(): void;
-    private getBloscCodec;
-    private decompress;
-    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 { }