@fxi/zartigl 0.3.1 → 0.4.1

package/dist/zartigl.d.ts

@@ -2,108 +2,6 @@ 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;
@@ -127,53 +25,23 @@ export declare function buildWmtsTileUrl(options: {
 }): string;
 
 export declare interface Catalog {
-    schemaVersion: 1;
-    layers: CatalogLayer[];
-}
-
-export declare interface CatalogGeoVideo {
-    id: string;
-    label?: string;
-    manifestUrl: string;
+    schemaVersion: 2;
+    defaultLocale: string;
+    layers: CatalogEntry[];
 }
 
-export declare type CatalogLayer = (CatalogLayerBase & {
-    kind: "scalar";
-    variables: Extract<CatalogVariables, {
-        kind: "scalar";
-    }>;
-}) | (CatalogLayerBase & {
-    kind: "vector";
-    variables: Extract<CatalogVariables, {
-        kind: "vector";
-    }>;
-});
-
-declare interface CatalogLayerBase {
+export declare interface CatalogEntry {
     id: string;
-    label: string;
-    description?: string;
-    category?: string;
+    aliases?: string[];
+    title: LocalizedText;
+    description?: LocalizedText;
+    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";
+    kind: "scalar" | "vector";
+    sources: CatalogSource[];
+    defaults: {
+        sourceId: string;
+        querySourceId?: string;
         palette?: string;
         renderMode?: "particles" | "raster" | "raster+particles";
         particles?: {
@@ -185,12 +53,57 @@ declare interface CatalogLayerBase {
             opacity?: number;
             logScale?: boolean;
             vibrance?: number;
-            /** Fixed physical-value domain for scalar color normalization. */
             colorDomain?: [number, number];
         };
     };
 }
 
+declare interface CatalogGeoVideoSource extends CatalogSourceBase {
+    type: "geovideo";
+    manifestUrl: string;
+}
+
+declare type CatalogRenderLayerBackend = "vector-zarr" | "scalar-zarr" | "scalar-geovideo" | "scalar-wmts";
+
+declare type CatalogRenderLayerDebugInfo = {
+    id: string;
+    backend: CatalogRenderLayerBackend;
+    catalogLayer: {
+        id: string;
+        title: string;
+        kind: CatalogEntry["kind"];
+    };
+    time: string | number;
+    depth: number;
+    opacity: number;
+    delegate: VectorLayerDebugInfo | ScalarLayerDebugInfo | GeoVideoLayerDebugInfo | null;
+};
+
+export declare type CatalogSource = CatalogZarrSource | CatalogWmtsSource | CatalogGeoVideoSource;
+
+declare interface CatalogSourceBase {
+    id: string;
+    title: LocalizedText;
+    provenance?: CatalogSourceProvenance;
+    temporal?: CatalogTemporalSummary;
+}
+
+export declare type CatalogSourcePreference = "auto" | CatalogSourceType | string;
+
+declare interface CatalogSourceProvenance {
+    provider: string;
+    identifiers?: Record<string, string>;
+}
+
+export declare type CatalogSourceType = CatalogSource["type"];
+
+declare interface CatalogTemporalSummary {
+    cadence?: string;
+    mode: "historical" | "near-real-time" | "analysis-forecast" | "fixed";
+    start?: string;
+    end?: string;
+}
+
 export declare type CatalogVariables = {
     kind: "scalar";
     value: string;
@@ -209,13 +122,24 @@ export declare interface CatalogVectorDerivation {
     output_direction: "from" | "toward";
 }
 
-export declare interface CatalogWmts {
-    capabilities_url: string;
-    base_url: string;
+declare interface CatalogWmtsSource extends CatalogSourceBase {
+    type: "wmts";
+    capabilitiesUrl: string;
+    baseUrl?: string;
     layer: string;
-    tileMatrixSet: string;
-    format: string;
+    tileMatrixSet?: string;
+    format?: string;
     style?: string;
+    tileUrlTemplate?: string;
+}
+
+declare interface CatalogZarrSource extends CatalogSourceBase {
+    type: "zarr";
+    endpoints: {
+        field: string;
+        pointSeries?: string;
+    };
+    variables: CatalogVariables;
 }
 
 export declare type ColorRampInput = string | string[] | Record<number, string>;
@@ -399,7 +323,7 @@ export declare interface GeoVideoLayerOptions {
 }
 
 export declare interface GeoVideoManifest {
-    schemaVersion: 2;
+    schemaVersion: 3;
     id: string;
     type: "geovideo";
     projection: "equirectangular";
@@ -432,11 +356,13 @@ export declare interface GeoVideoManifest {
         height: number;
         threshold: number;
     };
-    timeline: GeoVideoRangeTimeline | GeoVideoSnapshotLoopTimeline;
+    timeline: GeoVideoRangeTimeline | GeoVideoSnapshotLoopTimeline | GeoVideoSampleSequenceTimeline;
     provenance: {
-        layerId: string;
-        datasetId: string;
-        variable: string;
+        catalogEntryId: string;
+        inputSourceId: string;
+        provider?: string;
+        identifiers?: Record<string, string>;
+        variables: string[];
         generatedAt: string;
     };
     style: {
@@ -461,6 +387,11 @@ export declare interface GeoVideoRangeTimeline {
     interpolation: "linear" | "nearest";
 }
 
+export declare interface GeoVideoSampleSequenceTimeline {
+    kind: "sample-sequence";
+    values: string[];
+}
+
 export declare function geoVideoSecondsForTime(manifest: GeoVideoManifest, timeMs: number): number;
 
 export declare interface GeoVideoSnapshotLoopTimeline {
@@ -496,17 +427,6 @@ declare type LayerEventMap_2 = {
     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;
@@ -523,9 +443,13 @@ export declare type Legend = {
 
 export declare function loadGeoVideoManifest(source: string | GeoVideoManifest, signal?: AbortSignal): Promise<GeoVideoManifest>;
 
+declare type LocalizedText = Record<string, string>;
+
 export declare interface MapxWidgetSnippetOptions {
     layerId: string;
-    backend?: "auto" | "zarr" | "geovideo" | "wmts";
+    layerKind: CatalogEntry["kind"];
+    source?: string;
+    sourceType?: SnippetSourceType;
     time?: string | number | Date;
     timeRange?: TimeRange;
     geoVideo?: GeoVideoOptions;
@@ -806,8 +730,6 @@ export declare interface ScalarLayerOptions {
     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;
@@ -825,6 +747,8 @@ declare interface SimulationParams {
     rgba8MaxParticleZoom: number;
 }
 
+declare type SnippetSourceType = "zarr" | "geovideo" | "wmts";
+
 export declare interface StandaloneDemoSnippetOptions extends MapxWidgetSnippetOptions {
     moduleBaseUrl?: string;
     center?: [number, number];
@@ -1171,7 +1095,7 @@ export declare class ZarrSource {
     getChunkShape(variable: string): number[];
     getCoords(): CoordArrays;
     getTimeDimension(): ZarrTimeDimension;
-    getVerticalDimension(): ZarrVerticalDimension | undefined;
+    getVerticalDimension(variable?: string): ZarrVerticalDimension | undefined;
     hasVariable(variable: string): boolean;
     getVariableAttrs(variable: string): ZarrAttrs;
     getDimensions(variable: string): string[];
@@ -1229,6 +1153,17 @@ export declare class ZarrSource {
         lonSize: number;
     }>;
     fetchChunk(variable: string, indices: number[]): Promise<Float32Array>;
+    /**
+     * Fetch one latitude/longitude chunk and extract the requested time/vertical
+     * plane from it. Logical coordinate indices are converted to physical Zarr
+     * chunk indices before fetching.
+     */
+    fetchSpatialChunkResult(variable: string, selection: {
+        timeIndex: number;
+        verticalIndex: number;
+        latitudeChunkIndex: number;
+        longitudeChunkIndex: number;
+    }): Promise<ZarrChunkFetchResult>;
     fetchChunkResult(variable: string, indices: number[]): Promise<ZarrChunkFetchResult>;
     cancelAll(): void;
     private cacheChunk;
@@ -1257,7 +1192,7 @@ export declare class Zartigl {
     private readonly id;
     private readonly map;
     private readonly catalog;
-    private readonly backendPreference;
+    private sourcePreference;
     private timeRange?;
     private fullTimeMeta;
     private readonly autoplay;
@@ -1267,12 +1202,14 @@ export declare class Zartigl {
     private readonly before?;
     private visible;
     private catalogLayer;
+    private catalogSource;
     private layer;
     private time;
     private pendingTime;
     private depth;
     private settings;
     private colorDomainOverridden;
+    private paletteOverridden;
     private lastMeta;
     private timeMeta;
     private resolvedTimeRange;
@@ -1280,6 +1217,7 @@ export declare class Zartigl {
     private variableUnit;
     private variableStandardName;
     private geoVideoManifest;
+    private wmtsMetadata;
     private fieldSources;
     private activeFieldSource;
     private switchGeneration;
@@ -1292,7 +1230,8 @@ export declare class Zartigl {
     private readonly onStyleData;
     private readonly onMapIdle;
     constructor(options: ZartiglOptions);
-    setLayer(id: string): Promise<void>;
+    setLayer(id: string, preference?: CatalogSourcePreference): Promise<void>;
+    setSource(preference: CatalogSourcePreference): Promise<void>;
     show(): void;
     hide(): void;
     /** Pause rendering and abort field requests without discarding layer state. */
@@ -1318,20 +1257,30 @@ export declare class Zartigl {
     getVariableMeta(): VariableMeta;
     getLegend(): Legend;
     getPalettes(): PaletteMeta[];
-    getBackend(): "zarr" | "geovideo" | "wmts" | undefined;
+    getSource(): {
+        id: string;
+        type: CatalogSource["type"];
+    } | undefined;
+    getCapabilities(): {
+        render: true;
+        time: boolean;
+        depth: boolean;
+        pointQuery: boolean;
+        sourceTypes: CatalogSource["type"][];
+    };
     /** 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 resolveSource;
+    private querySource;
     private isMapReady;
     private getBeforeLayerId;
     private requireLayer;
@@ -1346,8 +1295,11 @@ export declare interface ZartiglDebugInfo {
     destroyed: boolean;
     visible: boolean;
     suspended: boolean;
-    backendPreference: "auto" | "zarr" | "geovideo" | "wmts";
-    activeBackend?: "zarr" | "geovideo" | "wmts";
+    sourcePreference: CatalogSourcePreference;
+    activeSource?: {
+        id: string;
+        type: CatalogSource["type"];
+    };
     projection?: string;
     canvasSize?: {
         width: number;
@@ -1358,17 +1310,17 @@ export declare interface ZartiglDebugInfo {
         height: number;
     };
     devicePixelRatio?: number;
-    catalogLayer: {
+    catalogEntry: {
         id: string;
-        label: string;
-        kind: CatalogLayer["kind"];
+        title: string;
+        kind: CatalogEntry["kind"];
     } | null;
     time: number;
     depth: number;
     settings: Partial<ZartiglSettings>;
     timeRange?: TimeRange;
     geoVideo: Required<GeoVideoOptions>;
-    layer: ArcoLayerDebugInfo | null;
+    layer: CatalogRenderLayerDebugInfo | null;
 }
 
 declare type ZartiglEventMap = {
@@ -1393,7 +1345,7 @@ export declare interface ZartiglOptions {
     id?: string;
     map: Map_2;
     catalog: Catalog;
-    backend?: "auto" | "zarr" | "geovideo" | "wmts";
+    source?: CatalogSourcePreference;
     timeRange?: TimeRange;
     geoVideo?: GeoVideoOptions;
     visible?: boolean;