@fxi/zartigl 0.10.0 → 0.10.2

package/dist/engine.d.ts

@@ -193,6 +193,22 @@ export declare function fadeToFrames(fade: number): number;
 /** Per-frame trail opacity multiplier for a 0–1 `fade`. */
 export declare function fadeToOpacity(fade: number): number;
 
+declare interface FieldMeta {
+    min: number;
+    max: number;
+    unit: string;
+    time: string;
+    depth?: number;
+}
+
+/** Shader uniforms a field binds: two time steps, their mix, the bounds. */
+export declare interface FieldUniforms {
+    a: string;
+    b: string;
+    mix: string;
+    bounds: string;
+}
+
 /**
  * Short display label of a CF / UDUNITS `units` attribute, for legends and
  * query values: "mmol m-3" → "mmol/m³", "degree_Celsius_weeks" → "°C-weeks".
@@ -342,6 +358,103 @@ export declare interface GeoVideoChunkSpan {
     end: number;
 }
 
+/** The playhead shared by the layers: time, play state and speeds. */
+export declare class GeoVideoClock {
+    private readonly onPlaying;
+    private time;
+    private endFraction;
+    /** Playhead, epoch ms. Assigning it also resets a terminal step's hold. */
+    get ms(): number;
+    set ms(value: number);
+    /** Playback held, e.g. while a timeline thumb is held. */
+    held: boolean;
+    private playingValue;
+    constructor(playing: boolean, onPlaying: (playing: boolean) => void);
+    get playing(): boolean;
+    setPlaying(playing: boolean): void;
+    /** Playing and not held. */
+    get advancing(): boolean;
+    /**
+     * Advance in step units, including irregular timelines. Returns true at a
+     * non-looping end. holdLastStep gives the final sample a full step's duration.
+     */
+    advance(dt: number, times: ArrayLike<number>, stepsPerSecond: number, range?: readonly [number, number], loop?: boolean, holdLastStep?: boolean): boolean;
+}
+
+/**
+ * GeoVideo frames as textures, decoded ahead of the playhead: vector frames
+ * as float (u, v, validity, 0), scalar frames as the browser decodes them,
+ * turned into values in the shader by zartigl's GEOVIDEO_SCALAR_GLSL (with a
+ * static mask texture), the decoder of its MapLibre layer. Binds two
+ * consecutive time steps and their mix under VELOCITY_UNIFORMS for a vector
+ * field, TINT_UNIFORMS for a scalar one.
+ */
+export declare class GeoVideoField {
+    private readonly gl;
+    readonly manifest: GeoVideoManifest;
+    private readonly options;
+    readonly times: number[];
+    readonly bounds: GeoVideoBounds;
+    /** Vector field (particles); false for a scalar one (raster or tint). */
+    readonly vector: boolean;
+    private readonly source;
+    private readonly uniforms;
+    private readonly textures;
+    private readonly pending;
+    /** Static validity of a scalar field, uploaded with its first frame. */
+    private mask;
+    private pair;
+    private destroyed;
+    private linearFilter;
+    uploadedFrames: number;
+    lastUploadDurationMs: number;
+    get currentPair(): readonly [WebGLTexture, WebGLTexture, number] | null;
+    constructor(gl: WebGL2RenderingContext, manifest: GeoVideoManifest, options?: GeoVideoFieldOptions);
+    /** Fixed catalog color domain of a scalar field. */
+    get domain(): [number, number];
+    /** Top of the color ramp and of the particle speed normalization. */
+    get maxSpeed(): number;
+    /** Resolves once the step at `ms` is uploaded. */
+    prime(ms: number): Promise<void>;
+    /** True once the frames interpolated at `ms` are uploaded. */
+    ready(ms: number): boolean;
+    /**
+     * Latest wins while scrubbing: drop queued decodes outside the frames at
+     * `ms`, then request those first.
+     */
+    focus(ms: number): void;
+    /**
+     * Bracketing textures and their mix, retaining the last complete pair
+     * while a requested frame decodes.
+     */
+    sample(ms: number, interpolate?: boolean): readonly [WebGLTexture, WebGLTexture, number] | null;
+    /** Switch spatial filtering without changing the decoded-step cache. */
+    setFilter(linear: boolean): void;
+    get maskTexture(): WebGLTexture | null;
+    get cachedFrames(): number;
+    bind(program: GeoVideoProgram, ms: number, unit?: number): boolean;
+    destroy(): void;
+    private request;
+    private uploadPreservingState;
+    private upload;
+    /** The source's mask, loaded with its first frame, as an R8 texture. */
+    private uploadMask;
+    /** A bound, linearly filtered texture over the field grid. */
+    private gridTexture;
+    /** Keep a small window around the playhead. */
+    private evict;
+}
+
+export declare interface GeoVideoFieldOptions {
+    /** Repeat global grids in longitude; false for an inset MapLibre grid. */
+    repeatLongitude?: boolean;
+    /** Play the media frames of a single-date snapshot; times then follow its media cadence. */
+    animateSnapshot?: boolean;
+    onError?: (error: unknown) => void;
+    /** A decoded step was uploaded; a paused renderer can redraw it. */
+    onReady?: () => void;
+}
+
 /** A scalar frame image (decoded on the GPU) or u/v components (NaN invalid). */
 export declare type GeoVideoFrameData = GeoVideoScalarFrame | GeoVideoVectorFrame;
 
@@ -524,6 +637,101 @@ export declare interface GeoVideoManifest {
     };
 }
 
+/** Render-driven GeoVideo playback and chunk handoff, shared by both MapLibre adapters. */
+export declare class GeoVideoPlayback {
+    private readonly repaint;
+    private readonly emit;
+    field: GeoVideoField | null;
+    manifest: GeoVideoManifest | null;
+    private gl;
+    private pendingField;
+    private standby;
+    private awaitingNext;
+    private playOnReady;
+    private loop;
+    private playbackRate;
+    private stepsPerSecond?;
+    private requestedTime;
+    private requestedTimeRange?;
+    private timeRange;
+    private lastTick;
+    private lastStepTime;
+    private seekId;
+    private seeking;
+    private failed;
+    private exactTime;
+    private endEmitted;
+    private destroyed;
+    private resumePlayback;
+    private readonly clock;
+    constructor(options: GeoVideoPlaybackOptions, repaint: () => void, emit: <K extends keyof GeoVideoPlaybackEvents>(event: K, ...args: Parameters<GeoVideoPlaybackEvents[K]>) => void);
+    load(gl: WebGL2RenderingContext, manifest: GeoVideoManifest): Promise<void>;
+    sample(now: number): readonly [WebGLTexture, WebGLTexture, number] | null;
+    get time(): number;
+    get preloadedMediaUrl(): string | undefined;
+    setStepsPerSecond(value: number): void;
+    suspend(): void;
+    resume(): void;
+    destroy(): void;
+    private tick;
+    setTime(time: string | number): void;
+    /** Load the requested step first; stale seeks and swaps cannot replace it. */
+    private prepare;
+    /** Keep the outgoing pair until the incoming chunk's requested step is ready. */
+    replaceManifest(manifest: GeoVideoManifest, options?: GeoVideoPlaybackReplaceOptions): boolean;
+    /** Decode the next chunk ahead of its swap, including its static mask. */
+    preloadManifest(manifest: GeoVideoManifest, options?: GeoVideoPlaybackReplaceOptions): boolean;
+    private discardStandby;
+    /** Clamped time range of a compatible replacement, else null. */
+    private replacementTimeRange;
+    play(): Promise<void>;
+    pause(): void;
+    isPlaying(): boolean;
+    private reachEnd;
+    setLoop(loop: boolean): void;
+    setPlaybackRate(rate: number): void;
+    setTimeRange(range: [number, number]): void;
+    private playbackRange;
+    private createField;
+    private reportError;
+}
+
+export 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;
+};
+
+export declare interface GeoVideoPlaybackOptions {
+    time?: string | number;
+    timeRange?: [number, number];
+    autoplay?: boolean;
+    loop?: boolean;
+    playbackRate?: number;
+    stepsPerSecond?: number;
+}
+
+export declare interface GeoVideoPlaybackReplaceOptions {
+    time?: number;
+    stepsPerSecond?: number;
+    timeRange?: [number, number];
+    loop?: boolean;
+    playbackRate?: number;
+}
+
+/** Texture and uniform binding supplied by the renderer. */
+export declare interface GeoVideoProgram {
+    texture(name: string, unit: number, texture: WebGLTexture): void;
+    float(name: string, value: number): void;
+    vec2(name: string, x: number, y: number): void;
+    vec4(name: string, value: readonly number[]): void;
+}
+
 declare interface GeoVideoRangeTimeline {
     kind: "range";
     dateStart: string;
@@ -809,11 +1017,20 @@ export declare function resolveColorRamp(input: ColorRampInput, options?: {
 
 export declare type ScalarColorDomain = [number, number];
 
+/** Time at a fractional step, clamped to the available samples. */
+export declare function stepTime(times: ArrayLike<number>, step: number): number;
+
 declare type StyleRenderMode = "particles" | "raster" | "raster+particles";
 
 /** `anchor` minus an ISO 8601 duration, calendar months and years in UTC. */
 export declare function subtractIsoDuration(anchor: number, duration: string): number;
 
+/** Index of the step at or before `ms` and the fraction toward the next. */
+export declare function timeBracket(times: ArrayLike<number>, ms: number): {
+    index: number;
+    fraction: number;
+};
+
 /**
  * Time windows shared by zartigl and the renderers built on its engine: a
  * fixed `start`/`end`, either side open, or the `trailing` ISO 8601 duration
@@ -835,6 +1052,9 @@ export declare type TimeRange = {
  */
 export declare function timeRangeBounds(range: TimeRange, [sourceMin, sourceMax]: readonly [number, number]): [number, number];
 
+/** Fractional step corresponding to a time. */
+export declare function timeStep(times: ArrayLike<number>, ms: number): number;
+
 /**
  * Camera-aware per-frame fade opacity: eases toward a short retention while
  * the camera moves, then back to the configured one. Smoothstep avoids
@@ -872,6 +1092,28 @@ declare type VectorFieldSource = Pick<ZarrSource, "init" | "cancelAll" | "getCoo
     getValueDomain?(): number;
 };
 
+/** Physical velocity/validity decoding and temporal blending; GLSL ES 1.0 and 3.0. */
+export declare const VELOCITY_BLEND_GLSL: string;
+
+/** Interleaves masked u/v planes into (u, v, validity, 0) texels. */
+export declare function velocityTexels(frame: GeoVideoVectorFrame): Float32Array;
+
+/** One bound velocity texture and the physical range used to decode it. */
+export 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;
+}
+
+export declare interface VelocityTexturePair {
+    a: VelocityTextureField;
+    b: VelocityTextureField;
+    mix: number;
+}
+
 /** `vec3 applyVibrance(vec3 c, float v)`; GLSL ES 1.0 and 3.0. */
 export declare const VIBRANCE_GLSL: string;
 
@@ -1021,4 +1263,28 @@ declare interface ZarrVerticalDimension {
     values: number[];
 }
 
+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 { }

package/dist/engine.js

@@ -1,6 +1,14 @@
-import { I as i, J as u, K as m, G as v, T as g, L as f, M as x, b as _, N as p, c as V, O as G, P as C, l as S, z as b, E as R, Q as O, R as A, n as L, t as h, A as F, B as I, D as T, m as y, C as D, S as k, U as B, V as E, W as w, p as M, X as N, F as P, Y as z, H as U, v as H } from "./geovideo-index-BJjE_fgO.js";
-import { B as J, C as Q, e as W, b as X, d as Y, c as j, g as q, i as Z, a as $, r as aa } from "./backdrop-DctkJ45Q.js";
-var a = `vec3 applyVibrance(vec3 c, float v) {
+import { I as u, J as v, K as f, L as x, G as g, M as _, N as V, T as p, O as G, P as C, b as S, Q as b, c as y, R as L, S as R, l as O, z as h, D as A, U as T, V as k, n as I, u as D, q as F, A as B, C as E, m as w, B as N, W as P, X as z, Y as M, Z as U, o as H, _ as K, $ as Y, a0 as q, E as J, a1 as Q, a2 as W, H as X, v as Z, a3 as $ } from "./geovideo-index-BqOLqzgA.js";
+import { B as ee, C as ae, e as oe, b as ne, d as re, c as ce, g as te, i as se, a as ie, r as le } from "./backdrop-DctkJ45Q.js";
+var e = `vec3 velocityValue(vec4 texel, vec2 minimum, vec2 maximum, float physical) {
+    if (physical > 0.5) return texel.xyz;
+    return vec3(mix(minimum, maximum, texel.rg), texel.a);
+}
+
+vec3 blendVelocity(vec3 a, vec3 b, float fraction) {
+    if (fraction <= 0.0) return a;
+    return mix(a, b, fraction);
+}`, a = `vec3 applyVibrance(vec3 c, float v) {
     float mx = max(c.r, max(c.g, c.b));
     float mn = min(c.r, min(c.g, c.b));
     float boost = v * (1.0 - (mx - mn));
@@ -21,7 +29,7 @@ vec3 gradeColor(vec3 c, vec4 g) {
     
     c = mix(c, c * c * (3.0 - 2.0 * c), g.y);
     return clamp(applyVibrance(c, g.z), 0.0, 1.0);
-}`, e = `uniform vec2 u_code_range;       
+}`, o = `uniform vec2 u_code_range;       
 uniform vec2 u_value_range;      
 uniform float u_scalar_transfer; 
 
@@ -33,7 +41,7 @@ float geoVideoScalarValue(float r) {
     float code = geoVideoScalarCode(r);
     float t = mix(code, (pow(10.0, code) - 1.0) / 9.0, u_scalar_transfer);
     return mix(u_value_range.x, u_value_range.y, t);
-}`, o = `uint pcg(uint v) {
+}`, n = `uint pcg(uint v) {
     uint state = v * 747796405u + 2891336453u;
     uint word = ((state >> ((state >> 28u) + 4u)) ^ state) * 277803737u;
     return (word >> 22u) ^ word;
@@ -48,54 +56,62 @@ float random(uvec3 v) {
     float luma = dot(c, vec3(0.299, 0.587, 0.114));
     return mix(vec3(luma), c, 1.0 + boost);
 }`;
-const n = r, c = a, t = o, s = e;
+const c = r, t = a, s = n, i = o, l = e;
 export {
-  J as BACKDROP_OFF,
-  c as COLOR_GRADE_GLSL,
-  Q as COLOR_GRADE_OFF,
-  W as COLOR_GRADE_VIBRANT,
-  s as GEOVIDEO_SCALAR_GLSL,
-  i as GeoVideoArchiveSource,
-  u as GeoVideoFrameSource,
-  m as GeoVideoScalarSource,
-  v as GeoVideoVectorSource,
-  t as RANDOM_GLSL,
-  g as TrailFade,
-  n as VIBRANCE_GLSL,
-  f as alphaFadeAt,
-  x as assertGeoVideoIndexIdentity,
-  X as backdropVec4,
-  Y as colorGradeToGrade,
-  j as colorGradeVec4,
-  _ as createColorRampTexture,
-  p as createGeoVideoFrameSource,
-  V as createProgram,
-  G as createShader,
-  C as fadeToFrames,
-  S as fadeToOpacity,
-  b as formatUnit,
-  R as geoVideoChunkSources,
-  O as geoVideoGrid,
-  A as geoVideoIndexChunks,
-  L as geoVideoScalarUniforms,
-  h as geoVideoTimelineValues,
+  ee as BACKDROP_OFF,
+  t as COLOR_GRADE_GLSL,
+  ae as COLOR_GRADE_OFF,
+  oe as COLOR_GRADE_VIBRANT,
+  i as GEOVIDEO_SCALAR_GLSL,
+  u as GeoVideoArchiveSource,
+  v as GeoVideoClock,
+  f as GeoVideoField,
+  x as GeoVideoFrameSource,
+  g as GeoVideoPlayback,
+  _ as GeoVideoScalarSource,
+  V as GeoVideoVectorSource,
+  s as RANDOM_GLSL,
+  p as TrailFade,
+  l as VELOCITY_BLEND_GLSL,
+  c as VIBRANCE_GLSL,
+  G as alphaFadeAt,
+  C as assertGeoVideoIndexIdentity,
+  ne as backdropVec4,
+  re as colorGradeToGrade,
+  ce as colorGradeVec4,
+  S as createColorRampTexture,
+  b as createGeoVideoFrameSource,
+  y as createProgram,
+  L as createShader,
+  R as fadeToFrames,
+  O as fadeToOpacity,
+  h as formatUnit,
+  A as geoVideoChunkSources,
+  T as geoVideoGrid,
+  k as geoVideoIndexChunks,
+  I as geoVideoScalarUniforms,
+  D as geoVideoTimelineValues,
   F as getPalettes,
-  q as gradeToColorGrade,
-  I as isGeoVideoArchiveSource,
-  Z as isHexColor,
-  T as loadGeoVideoIndex,
-  y as loadGeoVideoManifest,
-  D as nextChunk,
-  k as nextChunkSpan,
-  B as pairChunk,
-  E as pairChunkSpan,
-  w as parseTimeRange,
-  $ as resolveBackdrop,
-  aa as resolveColorGrade,
-  M as resolveColorRamp,
-  N as subtractIsoDuration,
-  P as timeRangeBounds,
-  z as validateGeoVideoIndex,
-  U as validateGeoVideoManifest,
-  H as validateScalarColorDomain
+  te as gradeToColorGrade,
+  B as isGeoVideoArchiveSource,
+  se as isHexColor,
+  E as loadGeoVideoIndex,
+  w as loadGeoVideoManifest,
+  N as nextChunk,
+  P as nextChunkSpan,
+  z as pairChunk,
+  M as pairChunkSpan,
+  U as parseTimeRange,
+  ie as resolveBackdrop,
+  le as resolveColorGrade,
+  H as resolveColorRamp,
+  K as stepTime,
+  Y as subtractIsoDuration,
+  q as timeBracket,
+  J as timeRangeBounds,
+  Q as timeStep,
+  W as validateGeoVideoIndex,
+  X as validateGeoVideoManifest,
+  Z as validateScalarColorDomain,
+  $ as velocityTexels
 };