@fxi/zartigl 0.1.4 → 0.2.13

package/dist/zartigl.d.ts

@@ -0,0 +1,1444 @@
+import { CustomLayerInterface } from 'maplibre-gl';
+import { CustomRenderMethodInput } from 'maplibre-gl';
+import { Map as Map_2 } from 'maplibre-gl';
+
+export declare class ArcoLayer implements CustomLayerInterface {
+    readonly id: string;
+    readonly type: "custom";
+    readonly renderingMode: "3d";
+    readonly metadata?: Record<string, unknown>;
+    private readonly options;
+    private readonly backend;
+    private delegate;
+    private map;
+    private rasterSourceId;
+    private rasterLayerId;
+    private time;
+    private depth;
+    private opacity;
+    private suspended;
+    private listeners;
+    constructor(options: ArcoLayerOptions);
+    getBackend(): ArcoLayerBackend;
+    getDebugInfo(): ArcoLayerDebugInfo;
+    onAdd(map: Map_2, gl: WebGLRenderingContext): void | Promise<void>;
+    render(gl: WebGLRenderingContext, options: CustomRenderMethodInput): void;
+    onRemove(): void;
+    setTime(time: string | number): void;
+    setTimeAndDepth(time: string | number, depth: number): void;
+    setDepth(depth: number): void;
+    prefetchTime(ms: number): Promise<void>;
+    isFrameCached(ms: number): boolean;
+    cancelPrefetches(): void;
+    suspend(): void;
+    resume(): void;
+    setSpeed(v: number): void;
+    setFade(v: number): void;
+    setParticleDensity(density: number): void;
+    setRenderMode(mode: RenderMode): void;
+    setRgba8MaxParticleZoom(v: number): void;
+    setColorRamp(ramp: ColorRampInput): void;
+    setOpacity(v: number): void;
+    setLogScale(v: boolean): void;
+    setVibrance(v: number): void;
+    setColorDomain(domain: [number, number] | null): void;
+    play(): Promise<void>;
+    pause(): void;
+    setLoop(loop: boolean): void;
+    setPlaybackRate(rate: number): void;
+    setTimeRange(range: [number, number]): void;
+    samplePoint(options: {
+        longitude: number;
+        latitude: number;
+        time?: string | number;
+        depth?: number;
+    }): Promise<{
+        longitude: number;
+        latitude: number;
+        value: number;
+        unit: string;
+        time: number;
+        depth?: number;
+    } | undefined>;
+    on<K extends keyof LayerEventMap_3>(event: K, handler: LayerEventMap_3[K]): this;
+    off<K extends keyof LayerEventMap_3>(event: K, handler: LayerEventMap_3[K]): this;
+    private addOrUpdateWmts;
+    private removeWmts;
+    private emitLoaded;
+    private emit;
+    private getBeforeLayerId;
+}
+
+export declare type ArcoLayerBackend = "vector" | "scalar-zarr" | "scalar-geovideo" | "scalar-wmts";
+
+export declare type ArcoLayerBackendPreference = "auto" | "wmts" | "geovideo" | "zarr";
+
+export declare type ArcoLayerCatalogLayer = CatalogLayer;
+
+export declare type ArcoLayerDebugInfo = {
+    id: string;
+    backend: ArcoLayerBackend;
+    catalogLayer: {
+        id: string;
+        label: string;
+        kind: CatalogLayer["kind"];
+    };
+    time: string | number;
+    depth: number;
+    opacity: number;
+    delegate: VectorLayerDebugInfo | ScalarLayerDebugInfo | GeoVideoLayerDebugInfo | null;
+};
+
+export declare interface ArcoLayerOptions extends Omit<VectorLayerOptions, "source" | "variableU" | "variableV"> {
+    layer: ArcoLayerCatalogLayer;
+    backend?: ArcoLayerBackendPreference;
+    /** Fixed physical-value domain for scalar colors. Null/omitted uses frame extrema. */
+    colorDomain?: [number, number] | null;
+    geoVideoManifest?: GeoVideoManifest;
+    geoVideoAutoplay?: boolean;
+    geoVideoLoop?: boolean;
+    geoVideoPlaybackRate?: number;
+    geoVideoTimeRange?: [number, number];
+    verticalLabel?: string;
+    metadata?: Record<string, unknown>;
+    before?: string;
+}
+
+export declare function buildMapxWidgetSnippet(options: MapxWidgetSnippetOptions): string;
+
+export declare function buildStandaloneDemoSnippet(options: StandaloneDemoSnippetOptions): string;
+
+export declare function buildWmtsLegendUrl(options: {
+    baseUrl: string;
+    layer: string;
+    format?: string;
+    style?: string;
+}): string;
+
+export declare function buildWmtsTileUrl(options: {
+    baseUrl: string;
+    layer: string;
+    tileMatrixSet: string;
+    format: string;
+    style?: string;
+    time?: string | number;
+    depth?: number;
+    verticalLabel?: string;
+}): string;
+
+export declare interface Catalog {
+    schemaVersion: 1;
+    layers: CatalogLayer[];
+}
+
+export declare interface CatalogGeoVideo {
+    id: string;
+    label?: string;
+    manifestUrl: string;
+}
+
+export declare type CatalogLayer = (CatalogLayerBase & {
+    kind: "scalar";
+    variables: Extract<CatalogVariables, {
+        kind: "scalar";
+    }>;
+}) | (CatalogLayerBase & {
+    kind: "vector";
+    variables: Extract<CatalogVariables, {
+        kind: "vector";
+    }>;
+});
+
+declare interface CatalogLayerBase {
+    id: string;
+    label: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    dataset: {
+        id: string;
+        provider?: "copernicus" | string;
+        productId?: string;
+    };
+    stores: {
+        field: {
+            url: string;
+        };
+        pointSeries?: {
+            url: string;
+        };
+        wmts?: CatalogWmts;
+    };
+    derived?: {
+        geoVideos?: CatalogGeoVideo[];
+    };
+    defaults?: {
+        backend?: "zarr" | "geovideo" | "wmts";
+        palette?: string;
+        renderMode?: "particles" | "raster" | "raster+particles";
+        particles?: {
+            density?: number;
+            speed?: number;
+            fade?: number;
+        };
+        raster?: {
+            opacity?: number;
+            logScale?: boolean;
+            vibrance?: number;
+            /** Fixed physical-value domain for scalar color normalization. */
+            colorDomain?: [number, number];
+        };
+    };
+}
+
+export declare type CatalogVariables = {
+    kind: "scalar";
+    value: string;
+} | {
+    kind: "vector";
+    u?: string;
+    v?: string;
+    derivation?: CatalogVectorDerivation;
+};
+
+export declare interface CatalogVectorDerivation {
+    kind: "direction_magnitude";
+    direction_variable: string;
+    magnitude_variable: string;
+    direction_convention: "from" | "toward";
+    output_direction: "from" | "toward";
+}
+
+export declare interface CatalogWmts {
+    capabilities_url: string;
+    base_url: string;
+    layer: string;
+    tileMatrixSet: string;
+    format: string;
+    style?: string;
+}
+
+export declare type ColorRampInput = string | string[] | Record<number, string>;
+
+declare interface CoordArrays {
+    time: Float64Array | Float32Array;
+    vertical: Float32Array;
+    latitude: Float32Array;
+    longitude: Float32Array;
+}
+
+export declare interface DepthMeta {
+    values: number[];
+    name?: string;
+    label: "depth" | "pressure" | string;
+    units?: string;
+    current?: number;
+}
+
+export declare function deriveDirectionMagnitudeComponents(directionDegrees: number, magnitude: number, derivation: VectorDerivation): {
+    u: number;
+    v: number;
+};
+
+export declare interface DirectionMagnitudeVectorDerivation {
+    kind: "direction_magnitude";
+    direction_variable: string;
+    magnitude_variable: string;
+    direction_convention: "from" | "toward";
+    output_direction: "from" | "toward";
+}
+
+export declare interface FieldMeta {
+    min: number;
+    max: number;
+    unit: string;
+    time: string;
+    depth?: number;
+}
+
+export declare type GeoVideoBounds = [west: number, south: number, east: number, north: number];
+
+declare type GeoVideoEventMap = {
+    loading: () => void;
+    loaded: (meta: FieldMeta) => void;
+    error: (error: Error) => void;
+    status: (status: ZartiglStatus) => void;
+    timeChange: (time: number) => void;
+    playbackChange: (playing: boolean) => void;
+};
+
+export declare class GeoVideoLayer implements CustomLayerInterface {
+    readonly id: string;
+    readonly type: "custom";
+    readonly renderingMode: "3d";
+    private readonly source;
+    private readonly autoplay;
+    private loop;
+    private playbackRate;
+    private requestedTime;
+    private requestedTimeRange?;
+    private timeRange;
+    private opacity;
+    private colorRamp;
+    private colorDomain;
+    private logScale;
+    private vibrance;
+    private map;
+    private gl;
+    private manifest;
+    private video;
+    private colorTexture;
+    private maskTexture;
+    private colorRampTexture;
+    private maskCanvas;
+    private maskContext;
+    private mercatorProgram;
+    private globeProgram;
+    private vertexBuffer;
+    private indexBuffer;
+    private indexCount;
+    private frameCallback;
+    private repaintFrame;
+    private frameDirty;
+    private maskDirty;
+    private colorTextureInitialized;
+    private maskTextureInitialized;
+    private maskCaptured;
+    private mediaReady;
+    private readyEmitted;
+    private hasVideoFrameCallback;
+    private lastBufferedMediaTime;
+    private lastUploadedMediaTime;
+    private decodedFrames;
+    private frameCallbackCount;
+    private frameCallbackTimes;
+    private lastFrameCallbackAt;
+    private bufferedFrames;
+    private skippedFrames;
+    private uploadedFrames;
+    private lastUploadDurationMs;
+    private abortController;
+    private resumePlayback;
+    private listeners;
+    constructor(options: GeoVideoLayerOptions);
+    onAdd(map: Map_2, gl: WebGLRenderingContext): Promise<void>;
+    render(gl: WebGLRenderingContext, options: CustomRenderMethodInput): void;
+    onRemove(): void;
+    setTime(time: string | number): void;
+    setTimeAndDepth(time: string | number, _depth: number): void;
+    setDepth(_depth: number): void;
+    prefetchTime(_ms: number): Promise<void>;
+    isFrameCached(_ms: number): boolean;
+    cancelPrefetches(): void;
+    suspend(): void;
+    resume(): void;
+    setRgba8MaxParticleZoom(_value: number): void;
+    setColorRamp(ramp: ColorRampInput): void;
+    setLogScale(value: boolean): void;
+    setVibrance(value: number): void;
+    setColorDomain(domain: [number, number] | null): void;
+    setOpacity(value: number): void;
+    play(): Promise<void>;
+    pause(): void;
+    setLoop(loop: boolean): void;
+    setPlaybackRate(rate: number): void;
+    setTimeRange(range: [number, number]): void;
+    getManifest(): GeoVideoManifest | null;
+    getDebugInfo(): GeoVideoLayerDebugInfo;
+    on<K extends keyof GeoVideoEventMap>(event: K, handler: GeoVideoEventMap[K]): this;
+    off<K extends keyof GeoVideoEventMap>(event: K, handler: GeoVideoEventMap[K]): this;
+    private initGl;
+    private initVideo;
+    private bufferFrame;
+    private loadStaticMask;
+    private emitReady;
+    private createVideoTexture;
+    private uploadTextureSource;
+    private startRepaintLoop;
+    private stopRepaintLoop;
+    private presentedFps;
+    private bindGrid;
+    private unbindGrid;
+    private emit;
+}
+
+export declare interface GeoVideoLayerDebugInfo {
+    kind: "scalar-geovideo";
+    id: string;
+    initialized: boolean;
+    playing: boolean;
+    currentTime: number;
+    manifestId?: string;
+    mediaUrl?: string;
+    decodedFrames: number;
+    bufferedFrames: number;
+    skippedFrames: number;
+    uploadedFrames: number;
+    droppedFrames: number;
+    lastUploadDurationMs: number;
+    frameCallbackCount: number;
+    presentedFps: number;
+    lastFrameAgeMs: number | null;
+    readyState: number;
+    networkState: number;
+}
+
+export declare interface GeoVideoLayerOptions {
+    id: string;
+    manifest: string | GeoVideoManifest;
+    opacity?: number;
+    autoplay?: boolean;
+    loop?: boolean;
+    playbackRate?: number;
+    time?: string | number;
+    timeRange?: [number, number];
+    colorRamp?: ColorRampInput;
+    colorDomain?: [number, number] | null;
+    logScale?: boolean;
+    vibrance?: number;
+}
+
+export declare interface GeoVideoManifest {
+    schemaVersion: 2;
+    id: string;
+    type: "geovideo";
+    projection: "equirectangular";
+    bounds: GeoVideoBounds;
+    media: {
+        url: string;
+        mimeType: "video/mp4" | string;
+        width: number;
+        height: number;
+        fps: number;
+        durationSeconds: number;
+        codec: "h264" | string;
+    };
+    encoding: {
+        kind: "scalar-luma";
+        bits: 8;
+        codeMin: number;
+        codeMax: number;
+        valueMin: number;
+        valueMax: number;
+        transfer: "linear";
+        colorSpace: "bt709";
+        colorRange: "limited" | "full";
+    };
+    mask: {
+        kind: "static-validity";
+        url: string;
+        mimeType: "image/png" | string;
+        width: number;
+        height: number;
+        threshold: number;
+    };
+    timeline: GeoVideoRangeTimeline | GeoVideoSnapshotLoopTimeline;
+    provenance: {
+        layerId: string;
+        datasetId: string;
+        variable: string;
+        generatedAt: string;
+    };
+    style: {
+        palette: string;
+        colorDomain: [number, number];
+        unit?: string;
+        logScale?: boolean;
+        vibrance?: number;
+    };
+}
+
+export declare interface GeoVideoOptions {
+    autoplay?: boolean;
+    loop?: boolean;
+    playbackRate?: number;
+}
+
+export declare interface GeoVideoRangeTimeline {
+    kind: "range";
+    dateStart: string;
+    dateEnd: string;
+    interpolation: "linear" | "nearest";
+}
+
+export declare function geoVideoSecondsForTime(manifest: GeoVideoManifest, timeMs: number): number;
+
+export declare interface GeoVideoSnapshotLoopTimeline {
+    kind: "snapshot-loop";
+    date: string;
+}
+
+export declare function geoVideoTimeForSeconds(manifest: GeoVideoManifest, seconds: number): number;
+
+export declare function geoVideoTimelineValues(manifest: GeoVideoManifest): number[];
+
+export declare function getPalettes(): PaletteMeta[];
+
+export declare function getVectorDerivationVariables(derivation: VectorDerivation): [string, string];
+
+declare type LayerEventMap = {
+    loading: () => void;
+    loaded: (meta: FieldMeta) => void;
+    error: (err: Error) => void;
+    status: (status: ZartiglStatus) => void;
+    frameBuffered: (ms: number) => void;
+    cacheInvalidated: () => void;
+};
+
+declare type LayerEventMap_2 = {
+    loading: () => void;
+    loaded: (meta: FieldMeta) => void;
+    error: (err: Error) => void;
+    status: (status: ZartiglStatus) => 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;
+};
+
+declare type LayerEventMap_3 = {
+    loading: () => void;
+    loaded: (meta: FieldMeta) => void;
+    error: (err: Error) => void;
+    status: (status: ZartiglStatus) => void;
+    frameBuffered: (ms: number) => void;
+    cacheInvalidated: () => void;
+    timeChange: (time: number) => void;
+    playbackChange: (playing: boolean) => void;
+};
+
+export declare type Legend = {
+    type: "gradient";
+    palette: string;
+    min?: number;
+    max?: number;
+    unit?: string;
+} | {
+    type: "image";
+    url: string;
+    format?: string;
+} | {
+    type: "empty";
+};
+
+export declare function loadGeoVideoManifest(source: string | GeoVideoManifest, signal?: AbortSignal): Promise<GeoVideoManifest>;
+
+export declare interface MapxWidgetSnippetOptions {
+    layerId: string;
+    backend?: "auto" | "zarr" | "geovideo" | "wmts";
+    time?: string | number | Date;
+    timeRange?: TimeRange;
+    geoVideo?: GeoVideoOptions;
+    depth?: number;
+    settings?: Partial<ZartiglSettings>;
+}
+
+export declare interface PaletteMeta {
+    id: string;
+    label: string;
+    tags: string[];
+    colors: string[];
+}
+
+export declare class ParticleSimulation {
+    private gl;
+    private params;
+    private updateProgram;
+    private drawProgram;
+    private fadeProgram;
+    private gridProgram;
+    private gridGlobeProgram;
+    private particleStateTextures;
+    private particleFramebuffers;
+    private particleIndexBuffer;
+    private particleIsCurrBuffer;
+    /** Active draw count — changes with canvas size / density, no realloc. */
+    private numParticles;
+    private prevBounds;
+    private redistributionBoost;
+    private cameraMoving;
+    private currentFadeOpacity;
+    private fadeTransitionStartOpacity;
+    private fadeTransitionTargetOpacity;
+    private fadeTransitionStartMs;
+    private fadeTransitionDurationMs;
+    private webglInfo;
+    private stateFormat;
+    private lastRgba8ParticlesSuppressed;
+    private screenTextures;
+    private screenFramebuffers;
+    private screenWidth;
+    private screenHeight;
+    private quadBuffer;
+    private rasterGridBuffer;
+    private rasterGridIndexBuffer;
+    private rasterGridIndexCount;
+    private colorRampTexture;
+    renderMode: RenderMode;
+    private updateLocs;
+    private drawLocs;
+    private fadeLocs;
+    private gridLocs;
+    private gridGlobeLocs;
+    constructor(params?: Partial<SimulationParams>);
+    init(gl: WebGLRenderingContext): void;
+    private getUniforms;
+    /** Random initial particle positions, matching the active state format. */
+    private makeStateData;
+    private createStateTexture;
+    private initParticleState;
+    private initRasterGrid;
+    /**
+     * 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, globeCenter?: [number, number, number], clippingPlane?: [number, number, number, number]): void;
+    renderGrid(velocityTexUnit: number, velocityMin: [number, number], velocityMax: [number, number], matrix: Iterable<number>, worldSize: number, worldCopyOffsets: number[], geoBounds: {
+        west: number;
+        south: number;
+        east: number;
+        north: number;
+    }, opacityScale?: number): void;
+    renderGridGlobe(velocityTexUnit: number, velocityMin: [number, number], velocityMax: [number, number], matrix: Iterable<number>, geoBounds: {
+        west: number;
+        south: number;
+        east: number;
+        north: number;
+    }, clippingPlane: [number, number, number, number], opacityScale?: number): void;
+    private setGridFieldUniforms;
+    private bindRasterGrid;
+    private unbindRasterGrid;
+    private drawQuad;
+    setSpeed(v: number): void;
+    setFadeOpacity(v: number): void;
+    /** Smoothly switch between normal and camera-motion trail retention. */
+    setCameraMoving(moving: boolean): void;
+    private updateTrailFadeOpacity;
+    private shouldSuppressRgba8Particles;
+    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;
+    setRgba8MaxParticleZoom(v: number): 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;
+    getDebugInfo(): ParticleSimulationDebugInfo;
+    destroy(): void;
+}
+
+export declare interface ParticleSimulationDebugInfo {
+    particleState: ParticleStateKind;
+    particleStateMode: ParticleStateMode;
+    particleStateResolution: number;
+    maxParticles: number;
+    activeParticles: number;
+    rgba8MaxParticleZoom: number;
+    rgba8ParticlesSuppressed: boolean;
+    screenSize: {
+        width: number;
+        height: number;
+    };
+    renderMode: RenderMode;
+    speed: number;
+    fadeOpacity: number;
+    particleDensity: number;
+    opacity: number;
+    logScale: boolean;
+    vibrance: number;
+    scalarMode: boolean;
+    devicePixelRatio?: number;
+    webgl: WebGLRendererInfo | null;
+}
+
+export declare type ParticleStateKind = StateTextureFormat["kind"];
+
+export declare type ParticleStateMode = "auto" | "rgba8";
+
+export declare interface QueryDepthProfileOptions {
+    longitude: number;
+    latitude: number;
+    time?: string | number;
+    maxDepths?: number;
+}
+
+export declare interface QueryPointOptions {
+    longitude: number;
+    latitude: number;
+    depth?: number;
+    maxPoints?: number;
+}
+
+export declare type RenderMode = 'raster' | 'particles' | 'raster+particles';
+
+/** Resolve a native date/time control value against actual available times. */
+export declare function resolveTimeInputSelection(values: readonly number[], value: string, granularity: TimeGranularity): number | undefined;
+
+declare type ScalarColorDomain = [number, number];
+
+export declare class ScalarLayer implements CustomLayerInterface {
+    readonly id: string;
+    readonly type: "custom";
+    readonly renderingMode: "3d";
+    private map;
+    private gl;
+    private zarrSource;
+    private simulation;
+    private activeField;
+    private activeData;
+    private initialized;
+    private suspended;
+    private loading;
+    private reloadQueued;
+    private generation;
+    private requestId;
+    private pendingReadyTime;
+    private frameCache;
+    private inflight;
+    private listeners;
+    private variable;
+    private time;
+    private depth;
+    private unit;
+    private colorDomain;
+    private textureUnit;
+    constructor(options: ScalarLayerOptions);
+    onAdd(map: Map_2, gl: WebGLRenderingContext): Promise<void>;
+    private moveEndHandler;
+    private initAsync;
+    render(gl: WebGLRenderingContext, options: CustomRenderMethodInput): void;
+    onRemove(): void;
+    setTime(time: string | number): void;
+    setTimeAndDepth(time: string | number, depth: number): void;
+    setDepth(depth: number): void;
+    prefetchTime(ms: number): Promise<void>;
+    isFrameCached(ms: number): boolean;
+    cancelPrefetches(): void;
+    suspend(): void;
+    resume(): void;
+    setColorRamp(ramp: ColorRampInput): void;
+    setOpacity(v: number): void;
+    setLogScale(v: boolean): void;
+    setVibrance(v: number): void;
+    setColorDomain(domain: [number, number] | null): void;
+    setRgba8MaxParticleZoom(v: number): void;
+    getDebugInfo(): ScalarLayerDebugInfo;
+    samplePoint(options: {
+        longitude: number;
+        latitude: number;
+        time?: string | number;
+        depth?: number;
+    }): Promise<{
+        longitude: number;
+        latitude: number;
+        value: number;
+        unit: string;
+        time: number;
+        depth?: number;
+    }>;
+    on<K extends keyof LayerEventMap>(event: K, handler: LayerEventMap[K]): this;
+    off<K extends keyof LayerEventMap>(event: K, handler: LayerEventMap[K]): this;
+    private loadCurrent;
+    private fetchScalarData;
+    private setActive;
+    private sampleActiveData;
+    private computeFieldMeta;
+    private timeToMs;
+    private emit;
+}
+
+export declare interface ScalarLayerDebugInfo {
+    kind: "scalar-zarr";
+    id: string;
+    initialized: boolean;
+    loading: boolean;
+    variable: string;
+    time: string | number;
+    depth: number;
+    unit: string;
+    colorDomain: [number, number] | null;
+    simulation: ParticleSimulationDebugInfo;
+}
+
+export declare interface ScalarLayerOptions {
+    id: string;
+    source: string;
+    /** Optional initialized/shared source. When omitted, the layer creates one from `source`. */
+    zarrSource?: ZarrSource;
+    variable: string;
+    colorRamp?: Record<number, string>;
+    time?: string | number;
+    depth?: number;
+    opacity?: number;
+    logScale?: boolean;
+    vibrance?: number;
+    /** Fixed physical-value domain for scalar colors. Null/omitted uses frame extrema. */
+    colorDomain?: [number, number] | null;
+    unit?: string;
+    particleState?: ParticleStateMode;
+    rgba8MaxParticleZoom?: number;
+}
+
+export declare function selectArcoLayerBackend(options: ArcoLayerOptions): ArcoLayerBackend;
+
+declare interface SimulationParams {
+    /** Particles per screen pixel. Active count = clamp(w * h * density, 1, MAX). */
+    particleDensity: number;
+    /** Max pixels/frame for the fastest current. Constant visual speed at any zoom. */
+    speed: number;
+    fadeOpacity: number;
+    dropRate: number;
+    dropRateBump: number;
+    colorRamp?: Record<number, string>;
+    opacity: number;
+    logScale: boolean;
+    vibrance: number;
+    scalarMode: boolean;
+    particleState: ParticleStateMode;
+    rgba8MaxParticleZoom: number;
+}
+
+export declare interface StandaloneDemoSnippetOptions extends MapxWidgetSnippetOptions {
+    moduleBaseUrl?: string;
+    center?: [number, number];
+    zoom?: number;
+    bearing?: number;
+    pitch?: number;
+    projection?: "mercator" | "globe";
+    style?: string;
+}
+
+/**
+ * Capability + GL constants for the particle-state texture format.
+ * Float state stores particle positions directly and avoids the RGBA8 packed
+ * coordinate lattice. RGBA8 remains the compatibility fallback.
+ */
+declare interface StateTextureFormat {
+    kind: "float32" | "float16" | "rgba8-packed";
+    internalFormat: number;
+    type: number;
+}
+
+/**
+ * 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 type TimeGranularity = "year" | "month" | "day" | "hour" | "minute" | "second";
+
+export declare interface TimeMeta {
+    min: number;
+    max: number;
+    step?: number;
+    size: number;
+    values: number[];
+    units?: string;
+    current?: number;
+    granularity: TimeGranularity;
+    timelineKind?: GeoVideoManifest["timeline"]["kind"];
+}
+
+export declare type TimeRange = {
+    start?: Date | string | number;
+    end?: Date | string | number;
+    trailing?: never;
+} | {
+    trailing: string;
+    start?: never;
+    end?: never;
+};
+
+export declare function validateGeoVideoManifest(value: unknown): GeoVideoManifest;
+
+export declare interface VariableMeta {
+    standardName?: string;
+    units?: string;
+}
+
+export declare type VectorDerivation = DirectionMagnitudeVectorDerivation;
+
+export declare class VectorLayer implements CustomLayerInterface {
+    readonly id: string;
+    readonly type: "custom";
+    readonly renderingMode: "3d";
+    private map;
+    private gl;
+    private simulation;
+    private velocityField;
+    private zarrSource;
+    private variableU;
+    private variableV;
+    private vectorDerivation;
+    private unit;
+    private time;
+    private depth;
+    private initialized;
+    private suspended;
+    private loading;
+    private reloadQueued;
+    private reloadQueuedResetParticles;
+    private generation;
+    private requestId;
+    private pendingReadyTime;
+    private velocityTexUnit;
+    private moveStartHandler;
+    private moveHandler;
+    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: VectorLayerOptions);
+    onAdd(map: Map_2, gl: WebGLRenderingContext): Promise<void>;
+    private initAsync;
+    private timeToMs;
+    private computeFieldMeta;
+    private isViewportCovered;
+    private reloadIfViewportUncovered;
+    /**
+     * 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): void;
+    onRemove(): void;
+    setTime(time: string | number): void;
+    setTimeAndDepth(time: string | number, depth: 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;
+    suspend(): void;
+    resume(): void;
+    setDepth(depth: number): void;
+    setSpeed(v: number): void;
+    setFade(v: number): void;
+    setParticleDensity(density: number): void;
+    setColorRamp(ramp: ColorRampInput): void;
+    setRenderMode(mode: RenderMode): void;
+    setRgba8MaxParticleZoom(v: number): void;
+    setOpacity(v: number): void;
+    setLogScale(v: boolean): void;
+    setVibrance(v: number): void;
+    getDebugInfo(): VectorLayerDebugInfo;
+    on<K extends keyof LayerEventMap_2>(event: K, handler: LayerEventMap_2[K]): this;
+    off<K extends keyof LayerEventMap_2>(event: K, handler: LayerEventMap_2[K]): this;
+    private emit;
+}
+
+export declare interface VectorLayerDebugInfo {
+    kind: "vector";
+    id: string;
+    initialized: boolean;
+    loading: boolean;
+    variableU: string;
+    variableV: string;
+    time: string | number;
+    depth: number;
+    unit: string;
+    simulation: ParticleSimulationDebugInfo;
+}
+
+export declare interface VectorLayerOptions {
+    id: string;
+    source: string;
+    /** Optional initialized/shared source. When omitted, the layer creates one from `source`. */
+    zarrSource?: ZarrSource;
+    variableU?: string;
+    variableV?: string;
+    vectorDerivation?: VectorDerivation;
+    /** Particles per screen pixel. Count = clamp(w × h × density, 1, 262144). Default 0.05. */
+    particleDensity?: number;
+    /** Max pixels/frame for the fastest current. Constant visual speed at any zoom. Default 1.0. */
+    speed?: number;
+    /** Trail length [0, 1] (higher = longer trails). Default 0.7. */
+    fade?: number;
+    /** Vector display mode. Default particles. */
+    renderMode?: RenderMode;
+    /** Particle state format selection. Default auto. */
+    particleState?: ParticleStateMode;
+    /** In RGBA8 mode, particles are suppressed above this zoom and raster remains visible. Default 4. */
+    rgba8MaxParticleZoom?: number;
+    colorRamp?: Record<number, string>;
+    time?: string | number;
+    depth?: 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;
+    unit?: string;
+}
+
+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, except scalar
+     * fields may use a fixed color domain so fragments never decode physical values.
+     */
+    update(data: VelocityData, colorDomain?: ScalarColorDomain | null): void;
+    /** Switch between bilinear (particles) and nearest-neighbour (raster) sampling. */
+    setFilter(linear: boolean): void;
+    bind(unit: number): void;
+    hasData(): boolean;
+    destroy(): void;
+}
+
+declare interface WebGLRendererInfo {
+    vendor: string;
+    renderer: string;
+    unmaskedVendor?: string;
+    unmaskedRenderer?: string;
+    version?: string;
+}
+
+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;
+    positive?: "up" | "down" | string;
+    [key: string]: unknown;
+}
+
+export declare interface ZarrChunkFetchResult {
+    data: Float32Array;
+    missing: boolean;
+    status?: number;
+    url: string;
+}
+
+export declare interface ZarrConsolidatedMeta {
+    zarr_consolidated_format: number;
+    metadata: Record<string, ZarrArrayMeta | ZarrAttrs | {
+        zarr_format: number;
+    }>;
+}
+
+export declare interface ZarrPointSample {
+    axisValue: number;
+    time?: number;
+    depth?: number;
+    values: Record<string, number>;
+}
+
+export declare interface ZarrPointSeriesResult {
+    longitude: number;
+    latitude: number;
+    depth?: number;
+    time?: number;
+    points: ZarrPointSample[];
+}
+
+export declare class ZarrSource {
+    private root;
+    private meta;
+    private coords;
+    private initPromise;
+    private verticalName;
+    private timeUnits;
+    private timeCalendar;
+    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;
+    getTimeDimension(): ZarrTimeDimension;
+    getVerticalDimension(): ZarrVerticalDimension | undefined;
+    hasVariable(variable: string): boolean;
+    getVariableAttrs(variable: string): ZarrAttrs;
+    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).
+     * Unsupported units are rejected during initialization rather than guessed.
+     */
+    private msToZarrTime;
+    private zarrTimeToMs;
+    private parseTimeEncoding;
+    private findNearestLongitudeIndex;
+    private sampleVariableAt;
+    private getFlatOffset;
+    findDepthIndex(depth: number): number;
+    sampleTimeSeries(options: {
+        variables: string[];
+        longitude: number;
+        latitude: number;
+        depth?: number;
+        timeStartIndex?: number;
+        timeEndIndex?: number;
+        stride?: number;
+        stopAfterMissingSamples?: number;
+    }): Promise<ZarrPointSeriesResult>;
+    sampleVerticalProfile(options: {
+        variables: string[];
+        longitude: number;
+        latitude: number;
+        time: string | number;
+        maxDepths?: number;
+        stride?: number;
+        stopAfterMissingSamples?: number;
+    }): Promise<ZarrPointSeriesResult>;
+    /** 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>;
+    fetchChunkResult(variable: string, indices: number[]): Promise<ZarrChunkFetchResult>;
+    cancelAll(): void;
+    private cacheChunk;
+    private getBloscCodec;
+    private decompress;
+    private loadCoordinates;
+}
+
+export declare interface ZarrTimeDimension {
+    min: number;
+    max: number;
+    step?: number;
+    size: number;
+    units: string;
+    values: number[];
+}
+
+export declare interface ZarrVerticalDimension {
+    name: string;
+    label: "depth" | "pressure" | string;
+    units?: string;
+    values: number[];
+}
+
+export declare class Zartigl {
+    private readonly id;
+    private readonly map;
+    private readonly catalog;
+    private readonly backendPreference;
+    private timeRange?;
+    private fullTimeMeta;
+    private readonly autoplay;
+    private loop;
+    private playbackRate;
+    private readonly metadata?;
+    private readonly before?;
+    private visible;
+    private catalogLayer;
+    private layer;
+    private time;
+    private pendingTime;
+    private depth;
+    private settings;
+    private colorDomainOverridden;
+    private lastMeta;
+    private timeMeta;
+    private resolvedTimeRange;
+    private verticalMeta;
+    private variableUnit;
+    private variableStandardName;
+    private geoVideoManifest;
+    private fieldSources;
+    private activeFieldSource;
+    private switchGeneration;
+    private destroyed;
+    private suspended;
+    private attachQueued;
+    private querySources;
+    private listeners;
+    private readonly onMapLoad;
+    private readonly onStyleData;
+    private readonly onMapIdle;
+    constructor(options: ZartiglOptions);
+    setLayer(id: string): Promise<void>;
+    show(): void;
+    hide(): void;
+    /** Pause rendering and abort field requests without discarding layer state. */
+    suspend(): void;
+    /** Resume rendering and load only the latest requested time/depth state. */
+    resume(): void;
+    destroy(): void;
+    setTime(time: Date | string | number): void;
+    play(): Promise<void>;
+    pause(): void;
+    setLoop(loop: boolean): void;
+    setPlaybackRate(rate: number): void;
+    /** Apply or clear a time window without rebuilding source metadata or the map layer. */
+    setTimeRange(range?: TimeRange | null): TimeMeta;
+    setDepth(depth: number): void;
+    setTimeAndDepth(time: Date | string | number, depth: number): void;
+    on<K extends keyof ZartiglEventMap>(event: K, handler: ZartiglEventMap[K]): this;
+    off<K extends keyof ZartiglEventMap>(event: K, handler: ZartiglEventMap[K]): this;
+    getTimeMeta(options?: {
+        full?: boolean;
+    }): TimeMeta;
+    getDepthMeta(): DepthMeta;
+    getVariableMeta(): VariableMeta;
+    getLegend(): Legend;
+    getPalettes(): PaletteMeta[];
+    getBackend(): "zarr" | "geovideo" | "wmts" | undefined;
+    /** Whether palette/domain styling is applied to values in the active renderer. */
+    supportsDynamicStyle(): boolean;
+    getDebugInfo(): ZartiglDebugInfo;
+    updateSettings(settings: Partial<ZartiglSettings>): void;
+    queryTimeSeries(options: QueryPointOptions): Promise<ZarrPointSeriesResult>;
+    queryDepthProfile(options: QueryDepthProfileOptions): Promise<ZarrPointSeriesResult>;
+    private activeBackendPreference;
+    private backendForLayer;
+    private attachWhenReady;
+    private detach;
+    private applyMutableSettings;
+    private getQuerySource;
+    private getFieldSource;
+    private isMapReady;
+    private getBeforeLayerId;
+    private requireLayer;
+    private assertAlive;
+    private emit;
+}
+
+export declare interface ZartiglDebugInfo {
+    timestamp: string;
+    userAgent?: string;
+    id: string;
+    destroyed: boolean;
+    visible: boolean;
+    suspended: boolean;
+    backendPreference: "auto" | "zarr" | "geovideo" | "wmts";
+    activeBackend?: "zarr" | "geovideo" | "wmts";
+    projection?: string;
+    canvasSize?: {
+        width: number;
+        height: number;
+    };
+    canvasCssSize?: {
+        width: number;
+        height: number;
+    };
+    devicePixelRatio?: number;
+    catalogLayer: {
+        id: string;
+        label: string;
+        kind: CatalogLayer["kind"];
+    } | null;
+    time: number;
+    depth: number;
+    settings: Partial<ZartiglSettings>;
+    timeRange?: TimeRange;
+    geoVideo: Required<GeoVideoOptions>;
+    layer: ArcoLayerDebugInfo | null;
+}
+
+declare type ZartiglEventMap = {
+    loading: () => void;
+    loaded: (meta: FieldMeta) => void;
+    error: (err: Error) => void;
+    status: (status: ZartiglStatus) => void;
+    frameBuffered: (ms: number) => void;
+    cacheInvalidated: () => void;
+    timeChange: (time: number) => void;
+    playbackChange: (playing: boolean) => void;
+};
+
+export declare class ZartiglFrameUnavailableError extends Error {
+    readonly time: number;
+    readonly statuses: number[];
+    readonly urls: string[];
+    constructor(time: number, statuses: number[], urls: string[]);
+}
+
+export declare interface ZartiglOptions {
+    id?: string;
+    map: Map_2;
+    catalog: Catalog;
+    backend?: "auto" | "zarr" | "geovideo" | "wmts";
+    timeRange?: TimeRange;
+    geoVideo?: GeoVideoOptions;
+    visible?: boolean;
+    settings?: Partial<ZartiglSettings>;
+    metadata?: Record<string, unknown>;
+    before?: string;
+}
+
+export declare interface ZartiglSettings {
+    palette: ColorRampInput;
+    particleDensity: number;
+    speed: number;
+    fade: number;
+    renderMode: RenderMode;
+    opacity: number;
+    logScale: boolean;
+    vibrance: number;
+    /** Fixed physical-value domain for scalar colors. Null uses frame extrema. */
+    colorDomain: [number, number] | null;
+    particleState: ParticleStateMode;
+    rgba8MaxParticleZoom: number;
+}
+
+export declare type ZartiglStatus = {
+    phase: "metadata";
+} | {
+    phase: "fetching";
+    time: number;
+    completed: number;
+    total: number;
+} | {
+    phase: "rendering";
+    time: number;
+} | {
+    phase: "ready";
+    time: number;
+} | {
+    phase: "blocked";
+    time: number;
+    statuses: number[];
+    message: string;
+} | {
+    phase: "error";
+    time?: number;
+    error: Error;
+};
+
+export { }