@fxi/zartigl 0.5.0 → 0.6.0

package/dist/engine.d.ts

@@ -0,0 +1,616 @@
+declare interface CatalogEntry {
+    id: string;
+    aliases?: string[];
+    title: LocalizedText;
+    description?: LocalizedText;
+    category: string;
+    tags?: string[];
+    kind: "scalar" | "vector";
+    sources: CatalogSource[];
+    defaults: {
+        sourceId: string;
+        querySourceId?: string;
+        palette?: string;
+        renderMode?: "particles" | "raster" | "raster+particles";
+        particles?: {
+            density?: number;
+            speed?: number;
+            fade?: number;
+        };
+        raster?: {
+            opacity?: number;
+            logScale?: boolean;
+            vibrance?: number;
+            colorDomain?: [number, number];
+        };
+    };
+}
+
+/**
+ * An incremental archive of calendar-aligned artifacts listed by a mutable
+ * index; zartigl resolves it to the chunk covering the requested time.
+ */
+declare interface CatalogGeoVideoArchiveSource extends CatalogSourceBase {
+    type: "geovideo";
+    indexUrl: string;
+    manifestUrl?: never;
+}
+
+/** One published artifact. */
+declare interface CatalogGeoVideoSource extends CatalogSourceBase {
+    type: "geovideo";
+    manifestUrl: string;
+    indexUrl?: never;
+}
+
+declare type CatalogSource = CatalogZarrSource | CatalogWmtsSource | CatalogGeoVideoSource | CatalogGeoVideoArchiveSource;
+
+declare interface CatalogSourceBase {
+    id: string;
+    title: LocalizedText;
+    provenance?: CatalogSourceProvenance;
+    temporal?: CatalogTemporalSummary;
+}
+
+declare interface CatalogSourceProvenance {
+    provider: string;
+    identifiers?: Record<string, string>;
+}
+
+declare interface CatalogTemporalSummary {
+    cadence?: string;
+    mode: "historical" | "near-real-time" | "analysis-forecast" | "fixed";
+    start?: string;
+    end?: string;
+}
+
+declare type CatalogVariables = {
+    kind: "scalar";
+    value: string;
+} | {
+    kind: "vector";
+    u?: string;
+    v?: string;
+    derivation?: CatalogVectorDerivation;
+};
+
+declare interface CatalogVectorDerivation {
+    kind: "direction_magnitude";
+    direction_variable: string;
+    magnitude_variable: string;
+    direction_convention: "from" | "toward";
+    output_direction: "from" | "toward";
+}
+
+declare interface CatalogWmtsSource extends CatalogSourceBase {
+    type: "wmts";
+    capabilitiesUrl: string;
+    baseUrl?: string;
+    layer: 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 const COLOR_GRADE_OFF: Readonly<ColorGrade>;
+
+export declare const COLOR_GRADE_VIBRANT: Readonly<ColorGrade>;
+
+/**
+ * Optional color grade applied when particle trails are composited
+ * (`shaders/color-grade.glsl`): more intense highlights, deeper shadows and
+ * richer colors, without hard clipping. Off by default; when off, the
+ * composite returns the trail colors unchanged.
+ */
+export declare interface ColorGrade {
+    enabled: boolean;
+    /** Mid-tone lift [0, 4]; 0 keeps the tones. */
+    exposure: number;
+    /** S-curve strength [0, 1]. */
+    contrast: number;
+    /** Vibrance-weighted saturation [-1, 1]. */
+    saturation: number;
+    /** Push of the bright half toward white [0, 1]. */
+    highlights: number;
+}
+
+/** `u_grade` uniform: (exposure, contrast, saturation, highlights). */
+export declare function colorGradeVec4(grade: ColorGrade): [number, number, number, number];
+
+export declare type ColorRampInput = string | string[] | Record<number, string>;
+
+declare interface CoordArrays {
+    time: Float64Array | Float32Array;
+    vertical: Float32Array;
+    latitude: Float32Array;
+    longitude: Float32Array;
+}
+
+export declare function createColorRampTexture(gl: WebGL2RenderingContext, ramp?: ColorRampInput): WebGLTexture;
+
+export declare function createProgram(gl: WebGL2RenderingContext, vertSource: string, fragSource: string): WebGLProgram;
+
+/** Trail length in frames for a 0–1 `fade`. */
+export declare function fadeToFrames(fade: number): number;
+
+/** Per-frame trail opacity multiplier for a 0–1 `fade`. */
+export declare function fadeToOpacity(fade: number): number;
+
+export declare type GeoVideoBounds = [
+west: number,
+south: number,
+east: number,
+north: number
+];
+
+/**
+ * Fixed-period GeoVideo sources, one per chunk. They keep the archive source
+ * id, which the chunk manifests carry as their identity.
+ */
+export declare function geoVideoChunkSources(source: CatalogGeoVideoArchiveSource, index: GeoVideoIndex, entry: CatalogEntry): CatalogGeoVideoSource[];
+
+/**
+ * GeoVideo frames read one time step at a time (seek, no playback): video
+ * and static mask loading, luma readback, a serial decode queue that
+ * cancelAll() aborts, and a small LRU cache of decoded frames. Subclasses
+ * turn the luma codes of a frame into values.
+ */
+export declare abstract class GeoVideoFrameSource<TFrame> {
+    /** Grid size; the video stacks `planes` grids vertically. */
+    readonly width: number;
+    readonly height: number;
+    protected readonly manifest: GeoVideoManifest;
+    protected readonly times: Float64Array;
+    private readonly planes;
+    private readonly cacheSize;
+    private readonly reader;
+    private video;
+    private mask;
+    private initPromise;
+    private presented;
+    private primed;
+    private queue;
+    private epoch;
+    private readonly frames;
+    constructor(manifest: GeoVideoManifest, planes: number, options?: {
+        cacheSize?: number;
+    });
+    /** Codes of the stacked planes and the per-cell mask to frame values. */
+    protected abstract decodeCodes(codes: Uint8Array, mask: Uint8Array, threshold: number): TFrame;
+    init(): Promise<void>;
+    /** Abort queued frame decodes; frames already decoded stay cached. */
+    cancelAll(): void;
+    /** Release the video element and GL context; a later init() reloads them. */
+    release(): void;
+    /** One decode per time step, cached. */
+    frame(index: number): Promise<TFrame>;
+    private load;
+    private loadMask;
+    private loadVideo;
+    /** Seek to a frame and wait until it is presented. */
+    private presentFrame;
+    /**
+     * Some mobile browsers expose no decoded pixels to WebGL until playback
+     * started once. A muted play/pause primes the decoder, only when needed:
+     * playback would otherwise buffer far beyond the requested frame.
+     */
+    private primeDecoder;
+    protected decode(index: number, epoch: number): Promise<TFrame>;
+}
+
+/** Mutable listing of an archive's published chunks, written by the renderer. */
+export declare interface GeoVideoIndex {
+    schemaVersion: 1;
+    type: "geovideo-index";
+    catalogEntryId: string;
+    sourceId: string;
+    updatedAt: string | null;
+    chunks: GeoVideoIndexChunk[];
+}
+
+/** One immutable, calendar-aligned artifact of a GeoVideo archive. */
+export declare interface GeoVideoIndexChunk {
+    period: {
+        start: string;
+        end: string;
+    };
+    /** First and last encoded sample. */
+    start: string;
+    end: string;
+    samples: number;
+    key: string;
+    /** Relative to the index URL. */
+    manifestUrl: string;
+    provisional?: boolean;
+}
+
+export declare interface GeoVideoManifest {
+    schemaVersion: 3;
+    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: GeoVideoScalarEncoding | GeoVideoVectorEncoding;
+    mask: {
+        kind: "static-validity";
+        url: string;
+        mimeType: "image/png" | string;
+        width: number;
+        height: number;
+        threshold: number;
+    };
+    timeline: GeoVideoRangeTimeline | GeoVideoSnapshotLoopTimeline | GeoVideoSampleSequenceTimeline;
+    provenance: {
+        catalogEntryId: string;
+        inputSourceId: string;
+        provider?: string;
+        identifiers?: Record<string, string>;
+        variables: string[];
+        generatedAt: string;
+    };
+    style: {
+        palette: string;
+        colorDomain: [number, number];
+        unit?: string;
+        logScale?: boolean;
+        vibrance?: number;
+    };
+}
+
+declare interface GeoVideoRangeTimeline {
+    kind: "range";
+    dateStart: string;
+    dateEnd: string;
+    interpolation: "linear" | "nearest";
+}
+
+declare interface GeoVideoSampleSequenceTimeline {
+    kind: "sample-sequence";
+    values: string[];
+}
+
+export declare interface GeoVideoScalarEncoding {
+    kind: "scalar-luma";
+    bits: 8;
+    codeMin: number;
+    codeMax: number;
+    valueMin: number;
+    valueMax: number;
+    transfer: "linear";
+    colorSpace: "bt709";
+    colorRange: "limited" | "full";
+}
+
+/**
+ * Scalar-luma GeoVideo read frame by frame (seek, no playback), for values
+ * sampled on the GPU rather than the styled playback of GeoVideoLayer.
+ */
+export declare class GeoVideoScalarSource extends GeoVideoFrameSource<Float32Array> {
+    private readonly encoding;
+    constructor(manifest: GeoVideoManifest, options?: {
+        cacheSize?: number;
+    });
+    protected decodeCodes(codes: Uint8Array, mask: Uint8Array, threshold: number): Float32Array;
+}
+
+declare interface GeoVideoSnapshotLoopTimeline {
+    kind: "snapshot-loop";
+    date: string;
+}
+
+export declare function geoVideoTimelineValues(manifest: GeoVideoManifest): number[];
+
+/**
+ * u and v stacked vertically in luma (u rows on top). Each component maps
+ * [-valueDomain, valueDomain] to [codeMin, codeMax]; "sqrt" stores
+ * sign(x)·sqrt(|x|/valueDomain) to keep precision on slow flows. The static
+ * mask covers one component (media height / 2).
+ */
+export declare interface GeoVideoVectorEncoding {
+    kind: "vector-luma";
+    bits: 8;
+    codeMin: number;
+    codeMax: number;
+    valueDomain: number;
+    transfer: "linear" | "sqrt";
+    layout: "stacked-uv";
+    colorSpace: "bt709";
+    colorRange: "limited" | "full";
+}
+
+/** Decoded u/v planes of one frame, NaN where the static mask is invalid. */
+export declare interface GeoVideoVectorFrame {
+    u: Float32Array;
+    v: Float32Array;
+}
+
+/**
+ * VectorLayer field source backed by a vector-luma GeoVideo: each time step is
+ * one video frame, decoded on demand (frame by frame, no playback) into a
+ * single chunk covering the whole grid.
+ */
+export declare class GeoVideoVectorSource extends GeoVideoFrameSource<GeoVideoVectorFrame> implements VectorFieldSource {
+    private readonly encoding;
+    private readonly coords;
+    constructor(manifest: GeoVideoManifest, options?: {
+        cacheSize?: number;
+    });
+    getValueDomain(): number;
+    getCoords(): {
+        time: Float64Array;
+        vertical: Float32Array;
+        latitude: Float32Array;
+        longitude: Float32Array;
+    };
+    getDimensions(): string[];
+    getChunkShape(): number[];
+    findDepthIndex(): number;
+    findTimeIndex(time: string | number): number;
+    getChunksForBounds(_variable: string, timeIdx: number, depthIdx: number): Array<{
+        timeIdx: number;
+        depthIdx: number;
+        latIdx: number;
+        lonIdx: number;
+        latRange: [number, number];
+        lonRange: [number, number];
+        latSize: number;
+        lonSize: number;
+    }>;
+    fetchSpatialChunkResult(variable: string, selection: {
+        timeIndex: number;
+    }): Promise<ZarrChunkFetchResult>;
+    protected decodeCodes(codes: Uint8Array, mask: Uint8Array, threshold: number): GeoVideoVectorFrame;
+}
+
+export declare function getPalettes(): PaletteMeta[];
+
+export declare function isGeoVideoArchiveSource(source: CatalogSource): source is CatalogGeoVideoArchiveSource;
+
+export declare function loadGeoVideoIndex(url: string, signal?: AbortSignal): Promise<GeoVideoIndex>;
+
+export declare function loadGeoVideoManifest(source: string | GeoVideoManifest, signal?: AbortSignal): Promise<GeoVideoManifest>;
+
+declare type LocalizedText = Record<string, string>;
+
+/**
+ * The chunk of `current`'s archive that follows it inside `range`, or with
+ * `loop`, the first one inside it, with the time playback resumes at.
+ */
+export declare function nextChunk<T extends CatalogSource>(chunks: readonly T[], current: CatalogSource, options?: {
+    range?: readonly [number, number] | null;
+    loop?: boolean;
+}): {
+    source: T;
+    time: number;
+} | null;
+
+/**
+ * The candidate whose sample range overlaps `chunk` the most: archives
+ * sampled at different hours (six-hourly from 00:00, daily at 12:00) still
+ * pair by calendar period. Null when none overlaps.
+ */
+export declare function pairChunk<T extends CatalogSource>(chunk: CatalogSource, candidates: readonly T[]): T | null;
+
+export declare interface PaletteMeta {
+    id: string;
+    label: string;
+    tags: string[];
+    colors: string[];
+}
+
+/**
+ * Complete grade from partial input. Missing or non-finite values take the
+ * vibrant preset, others are clamped to their range; `enabled` defaults to
+ * true when any input is given, so `{}` means "vibrant".
+ */
+export declare function resolveColorGrade(input?: Partial<ColorGrade>): ColorGrade;
+
+export declare function resolveColorRamp(input: ColorRampInput, options?: {
+    reverse?: boolean;
+}): Record<number, string>;
+
+export declare type ScalarColorDomain = [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
+ * visible slope changes at both ends.
+ */
+export declare class TrailFade {
+    private base;
+    private moving;
+    private from;
+    private to;
+    private start;
+    private duration;
+    constructor(base: number);
+    /** Configured opacity, applied at once unless the camera moves. */
+    setBase(base: number): void;
+    setMoving(moving: boolean, now: number): void;
+    value(now: number): number;
+}
+
+export declare function validateGeoVideoIndex(value: unknown): GeoVideoIndex;
+
+export declare function validateGeoVideoManifest(value: unknown): GeoVideoManifest;
+
+export declare function validateScalarColorDomain(domain: ScalarColorDomain | null): ScalarColorDomain | null;
+
+/**
+ * Field source contract used by VectorLayer. ZarrSource satisfies it; frame
+ * sources such as GeoVideoVectorSource implement it to feed decoded frames.
+ */
+declare type VectorFieldSource = Pick<ZarrSource, "init" | "cancelAll" | "getCoords" | "getDimensions" | "getChunkShape" | "findTimeIndex" | "findDepthIndex" | "getChunksForBounds" | "fetchSpatialChunkResult"> & {
+    /**
+     * Fixed symmetric component domain [-d, d]. When provided, it replaces the
+     * per-frame min/max so speed and color normalization stay stable in time.
+     */
+    getValueDomain?(): number;
+};
+
+declare interface ZarrAttrs {
+    _ARRAY_DIMENSIONS?: string[];
+    units?: string;
+    standard_name?: string;
+    long_name?: string;
+    calendar?: string;
+    positive?: "up" | "down" | string;
+    [key: string]: unknown;
+}
+
+declare interface ZarrChunkFetchResult {
+    data: Float32Array;
+    missing: boolean;
+    status?: number;
+    url: string;
+}
+
+declare interface ZarrPointSample {
+    axisValue: number;
+    time?: number;
+    depth?: number;
+    values: Record<string, number>;
+}
+
+declare interface ZarrPointSeriesResult {
+    longitude: number;
+    latitude: number;
+    depth?: number;
+    time?: number;
+    points: ZarrPointSample[];
+}
+
+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(variable?: string): 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>;
+    /**
+     * 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;
+    private getBloscCodec;
+    private decompress;
+    private loadCoordinates;
+}
+
+declare interface ZarrTimeDimension {
+    min: number;
+    max: number;
+    step?: number;
+    size: number;
+    units: string;
+    values: number[];
+}
+
+declare interface ZarrVerticalDimension {
+    name: string;
+    label: "depth" | "pressure" | string;
+    units?: string;
+    values: number[];
+}
+
+export { }

package/dist/engine.js

@@ -0,0 +1,29 @@
+import { C as o, a as r, G as s, b as i, T as d, c as l, d as t, e as c, f as G, g as V, h as m, i as n, j as u, k as C, l as f, m as p, n as v, p as x, r as R, o as S, v as T, q as O } from "./geovideo-index-CD5wflJT.js";
+import { G as h } from "./GeoVideoScalarSource-DoQAnyTy.js";
+import { v as k } from "./scalar-color-domain-PEK8Hxg1.js";
+export {
+  o as COLOR_GRADE_OFF,
+  r as COLOR_GRADE_VIBRANT,
+  s as GeoVideoFrameSource,
+  h as GeoVideoScalarSource,
+  i as GeoVideoVectorSource,
+  d as TrailFade,
+  l as colorGradeVec4,
+  t as createColorRampTexture,
+  c as createProgram,
+  G as fadeToFrames,
+  V as fadeToOpacity,
+  m as geoVideoChunkSources,
+  n as geoVideoTimelineValues,
+  u as getPalettes,
+  C as isGeoVideoArchiveSource,
+  f as loadGeoVideoIndex,
+  p as loadGeoVideoManifest,
+  v as nextChunk,
+  x as pairChunk,
+  R as resolveColorGrade,
+  S as resolveColorRamp,
+  T as validateGeoVideoIndex,
+  O as validateGeoVideoManifest,
+  k as validateScalarColorDomain
+};