@fxi/zartigl 0.10.1 → 0.10.3

package/dist/zartigl.d.ts

@@ -252,29 +252,14 @@ 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;
-    /** Playback reached the end of the timeline without looping. */
-    playbackEnd: () => void;
-};
+declare type GeoVideoEventMap = GeoVideoPlaybackEvents;
 
 export declare class GeoVideoLayer implements CustomLayerInterface {
     readonly id: string;
     readonly type: "custom";
     readonly renderingMode: "3d";
     private readonly source;
-    /** Start playback once ready: autoplay, or a swap that was playing. */
-    private playOnReady;
-    private loop;
-    private playbackRate;
-    private requestedTime;
-    private requestedTimeRange?;
-    private timeRange;
+    private readonly playback;
     private opacity;
     private colorRamp;
     private colorDomain;
@@ -283,78 +268,25 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     private map;
     private gl;
     private manifest;
-    private video;
-    /** Manifest of `video`, which still differs from `manifest` mid-swap. */
-    private videoManifest;
-    /** Incoming media of a swap, shown once its first frame is decodable. */
-    private pendingVideo;
-    private standby;
-    /** Ended on a preloaded artifact: playing until it is swapped in or paused. */
-    private awaitingNext;
-    private maskUrl;
-    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 stepTimer;
-    private endEmitted;
     private listeners;
     constructor(options: GeoVideoLayerOptions);
     onAdd(map: Map_2, context: WebGLRenderingContext | WebGL2RenderingContext): Promise<void>;
     render(context: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
     onRemove(): void;
     setTime(time: string | number): void;
-    /**
-     * Switch to another artifact of the same frame size, such as the next
-     * archive chunk, keeping the map layer and GL state. The current frame stays
-     * on screen until the new media can show its first one, at once when it was
-     * preloaded. Returns false when the artifact needs a new layer.
-     */
     replaceManifest(manifest: GeoVideoManifest, options?: GeoVideoReplaceOptions): boolean;
-    /**
-     * Load the artifact expected next, such as the following archive chunk, so
-     * `replaceManifest` can show it without waiting for the network. Until then,
-     * reaching the end of the current artifact keeps the playing state and
-     * emits `playbackEnd` for the caller to swap it in, or to pause. Returns
-     * false when the artifact cannot replace the current one in place.
-     */
     preloadManifest(manifest: GeoVideoManifest, options?: GeoVideoReplaceOptions): boolean;
-    /** Clamped time range of a compatible replacement, else null. */
-    private replacementTimeRange;
-    /** The preloaded artifact when it holds this media; any other is dropped. */
-    private takeStandby;
     setTimeAndDepth(time: string | number, _depth: number): void;
     setDepth(_depth: number): void;
-    prefetchTime(_ms: number): Promise<void>;
-    isFrameCached(_ms: number): boolean;
+    prefetchTime(ms: number): Promise<void>;
+    isFrameCached(ms: number): boolean;
     cancelPrefetches(): void;
     suspend(): void;
     resume(): void;
@@ -366,24 +298,6 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     setOpacity(value: number): void;
     play(): Promise<void>;
     pause(): void;
-    /**
-     * Playback is a request, applied once ready, while the manifest loads,
-     * mid-swap, or at an end waiting for the preloaded artifact.
-     */
-    private deferredPlayback;
-    private isPlaying;
-    /**
-     * Below the slowest media rate browsers accept, keep the video paused and
-     * seek one sample (or frame) at a time.
-     */
-    private startStepping;
-    private stopStepping;
-    private step;
-    /**
-     * The timeline ended without looping. With a preloaded artifact, keep the
-     * playing state for the caller to swap it in; otherwise stop.
-     */
-    private reachEnd;
     setLoop(loop: boolean): void;
     setPlaybackRate(rate: number): void;
     setTimeRange(range: [number, number]): void;
@@ -392,35 +306,6 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     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;
-    /**
-     * Media element for a manifest. Its events drive the layer only while it is
-     * the current video and no swap is pending.
-     */
-    private createVideo;
-    /** Track presented frames of the current video. */
-    private startFrameCallbacks;
-    /**
-     * Time a loading video opens at: its preload target, or the requested time
-     * within the active range.
-     */
-    private startTime;
-    private checkVideoSize;
-    private cancelFrameCallback;
-    /** Stop the current video and free its media resources. */
-    private releaseVideo;
-    private discardStandby;
-    private discardPendingVideo;
-    private bufferFrame;
-    private createMaskImage;
-    /** Show the mask of a manifest once its image, possibly preloaded, loads. */
-    private applyMask;
-    private emitReady;
-    private createVideoTexture;
-    private uploadTextureSource;
-    private startRepaintLoop;
-    private stopRepaintLoop;
-    private presentedFps;
     private bindGrid;
     private unbindGrid;
     private emit;
@@ -515,6 +400,34 @@ export declare interface GeoVideoOptions {
     stepsPerSecond?: number;
 }
 
+declare type GeoVideoPlaybackEvents = {
+    loading: () => void;
+    loaded: (meta: FieldMeta) => void;
+    error: (error: Error) => void;
+    status: (status: ZartiglStatus) => void;
+    timeChange: (time: number) => void;
+    playbackChange: (playing: boolean) => void;
+    /** Playback reached the end of the timeline without looping. */
+    playbackEnd: () => void;
+};
+
+declare interface GeoVideoPlaybackOptions {
+    time?: string | number;
+    timeRange?: [number, number];
+    autoplay?: boolean;
+    loop?: boolean;
+    playbackRate?: number;
+    stepsPerSecond?: number;
+}
+
+declare interface GeoVideoPlaybackReplaceOptions {
+    time?: number;
+    stepsPerSecond?: number;
+    timeRange?: [number, number];
+    loop?: boolean;
+    playbackRate?: number;
+}
+
 export declare interface GeoVideoRangeTimeline {
     kind: "range";
     dateStart: string;
@@ -526,12 +439,7 @@ export declare interface GeoVideoRangeTimeline {
  * Playback state for an artifact swapped in with `replaceManifest`, or
  * loaded ahead with `preloadManifest`.
  */
-declare interface GeoVideoReplaceOptions {
-    time?: number;
-    timeRange?: [number, number];
-    loop?: boolean;
-    playbackRate?: number;
-}
+declare type GeoVideoReplaceOptions = GeoVideoPlaybackReplaceOptions;
 
 export declare interface GeoVideoSampleSequenceTimeline {
     kind: "sample-sequence";
@@ -616,7 +524,7 @@ declare type LayerEventMap = {
     cacheInvalidated: () => void;
 };
 
-declare type LayerEventMap_2 = {
+declare type LayerEventMap_2 = GeoVideoPlaybackEvents & {
     loading: () => void;
     loaded: (meta: FieldMeta) => void;
     error: (err: Error) => void;
@@ -674,6 +582,11 @@ declare type LocalizedText = Record<string, string>;
 export declare interface MapxWidgetSnippetOptions {
     layerId: string;
     layerKind: CatalogEntry["kind"];
+    /** Legend header (MapX widget only); MapX derives it from the layer when unset. */
+    title?: LocalizedText | string;
+    subtitle?: LocalizedText | string;
+    /** Shown as the legend title's tooltip. */
+    description?: LocalizedText | string;
     /**
      * The layer's own style, the catalog `defaults`: only override keys that
      * differ from it are written. Unknown, the whole override is written.
@@ -773,19 +686,19 @@ export declare class ParticleSimulation {
         south: number;
         east: number;
         north: number;
-    }, isGlobe?: boolean, globeCenter?: [number, number, number], clippingPlane?: [number, number, number, number]): void;
+    }, isGlobe?: boolean, globeCenter?: [number, number, number], clippingPlane?: [number, number, number, number], velocityPair?: VelocityTexturePair): 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, solid?: Vec4): void;
+    }, opacityScale?: number, solid?: Vec4, velocityPair?: VelocityTexturePair): 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, solid?: Vec4): void;
+    }, clippingPlane: [number, number, number, number], opacityScale?: number, solid?: Vec4, velocityPair?: VelocityTexturePair): void;
     private setGridFieldUniforms;
     private bindRasterGrid;
     private unbindRasterGrid;
@@ -1199,9 +1112,12 @@ export declare class VectorLayer implements CustomLayerInterface {
     readonly renderingMode: "3d";
     private map;
     private gl;
+    private readonly playback;
+    private readonly geoVideoManifest?;
     private simulation;
     private velocityField;
-    private zarrSource;
+    private readonly zarrSourceValue;
+    private get zarrSource();
     private variableU;
     private variableV;
     private vectorDerivation;
@@ -1256,6 +1172,13 @@ export declare class VectorLayer implements CustomLayerInterface {
     suspend(): void;
     resume(): void;
     setDepth(depth: number): void;
+    play(): Promise<void>;
+    pause(): void;
+    setLoop(loop: boolean): void;
+    setStepsPerSecond(value: number): void;
+    setTimeRange(range: [number, number]): void;
+    replaceManifest(manifest: GeoVideoManifest, options?: GeoVideoPlaybackReplaceOptions): boolean;
+    preloadManifest(manifest: GeoVideoManifest, options?: GeoVideoPlaybackReplaceOptions): boolean;
     setSpeed(v: number): void;
     setFade(v: number): void;
     setParticleDensity(density: number): void;
@@ -1287,6 +1210,10 @@ export declare interface VectorLayerDebugInfo {
 }
 
 export declare interface VectorLayerOptions {
+    /** Decoded GeoVideo playback; omitted for the unchanged Zarr field path. */
+    geoVideo?: GeoVideoPlaybackOptions & {
+        manifest: GeoVideoManifest;
+    };
     id: string;
     source: string;
     /** Optional initialized/shared source. When omitted, the layer creates one from `source`. */
@@ -1382,6 +1309,22 @@ export declare class VelocityField {
     destroy(): void;
 }
 
+/** One bound velocity texture and the physical range used to decode it. */
+declare interface VelocityTextureField {
+    unit: number;
+    min: [number, number];
+    max: [number, number];
+    /** Physical (u, v, validity, 0); otherwise normalized (u, v, 0, validity). */
+    physical?: boolean;
+    northToSouth?: boolean;
+}
+
+declare interface VelocityTexturePair {
+    a: VelocityTextureField;
+    b: VelocityTextureField;
+    mix: number;
+}
+
 declare interface WebGLRendererInfo {
     vendor: string;
     renderer: string;
@@ -1736,7 +1679,7 @@ export declare class Zartigl {
     /** GeoVideo playback options shared by a new layer and an in-place swap. */
     private geoVideoPlayback;
     /**
-     * Show another artifact of the same scalar GeoVideo entry, such as the next
+     * Show another artifact of the same GeoVideo entry, such as the next
      * archive chunk, in the attached layer. The last frame stays on screen until
      * the new media is ready, instead of a blank map while a new layer loads.
      */