@fxi/zartigl 0.14.1 → 0.15.0

package/README.md

@@ -24,7 +24,7 @@ ARCO layers of [MapX](https://app.mapx.org).
 | Runtime library | `src/lib/` | `@fxi/zartigl`: the `Zartigl` facade, Zarr/WMTS/GeoVideo layers, shaders, particle simulation, point queries |
 | Catalog | `src/catalog/`, `scripts/catalog_builder/` | `@fxi/zartigl/catalog` presets and the tools that discover, describe, and validate entries |
 | GeoVideo pipeline | `scripts/geovideo/`, `.github/workflows/geovideo.yml` | Single renders and incremental archives published to S3, rendered daily on a self-hosted runner |
-| Demos | `src/explorer/`, `src/demo-story/` | Catalog explorer and narrative story, deployed to GitHub Pages |
+| Demos | `src/explorer/`, `src/demo-story/`, `src/cube/` | Catalog explorer, narrative story and the GODAS thermocline data-cube, deployed to GitHub Pages |
 | MapX integration | `src/mapx/` | Widget and standalone snippet generation for reproducible MapX views |
 
 ## Features
@@ -214,6 +214,22 @@ npm run dev:story
 npm run build:story
 ```
 
+The Pacific Thermocline Data-Cube (`src/cube/`) explores the monthly GODAS
+ocean temperature of the equatorial Pacific (120° E–80° W, 14.5° S–15° N,
+0–300 m) since 1980 as an interactive cube, at
+[`fxi.io/zartigl/cube`](https://fxi.io/zartigl/cube/). It provides:
+- slice planes and 2D sections;
+- the 20 °C isotherm;
+- a Niño 3.4 timeline.
+
+It reads five-year blocks of the catalog entry's point-series store, about
+42 MB each. `#t=YYYY-MM` opens a month.
+
+```bash
+npm run dev:cube
+npm run build:cube
+```
+
 The demos read the built-in catalog, which points to public browser-accessible Zarr, WMTS, and GeoVideo sources. No local data download is needed; data is fetched directly from the selected source.
 
 ## Public API

package/dist/{backdrop-Dceb4d8E.js → backdrop-BMwRyFI5.js}

@@ -66,13 +66,13 @@ function p(e) {
 }
 export {
   c as B,
-  u as C,
-  l as a,
+  l as C,
+  s as a,
   p as b,
-  h as c,
-  f as d,
-  y as e,
-  s as f,
+  y as c,
+  h as d,
+  f as e,
+  u as f,
   m as g,
   O as i,
   R as r

package/dist/catalog.d.ts

@@ -29,6 +29,8 @@ export declare interface CatalogEntry {
     aliases?: string[];
     title: LocalizedText;
     description?: LocalizedText;
+    /** Methodology and sources: an immutable page published with the catalog. */
+    documentation?: string;
     category: string;
     tags?: string[];
     kind: "scalar" | "vector";
@@ -62,6 +64,21 @@ export declare interface CatalogGeoVideoSource extends CatalogSourceBase {
     indexUrl?: never;
 }
 
+/**
+ * A link of a catalog entry, found by UUID or alias: its methodology page
+ * (`documentation`), its Zarr stores (`field`, `pointSeries`) or its GeoVideo
+ * index or manifest (`geovideo`). Undefined when the entry or the link does
+ * not exist. `pointSeries` comes from the entry's query source first, the
+ * other links from its default source first; then any source of the kind.
+ *
+ * Pass the live catalog (`(await loadCatalog()).catalog`) rather than the
+ * bundled one, so links follow the catalog when objects move.
+ */
+export declare function catalogLink(layer: string, kind: CatalogLinkKind, data?: Catalog): string | undefined;
+
+/** The links a catalog entry can resolve to; see `catalogLink`. */
+export declare type CatalogLinkKind = "documentation" | "field" | "pointSeries" | "geovideo";
+
 export declare interface CatalogSearchOptions {
     locale?: string;
     category?: string;

package/dist/catalog.js

@@ -1,4 +1,4 @@
-import { C as s, L as r, P as t, h as o, R as l, i, j as y, g as L, k as S, l as E, n as c, o as g, q as T, t as d, m, a as n, p as C, e as R, d as _, u as f, v as p, r as A, w as v, c as Y, x as u, b as P, s as k } from "./index-BDIf6Jc0.js";
+import { C as s, L as r, P as t, h as o, R as l, i, j as y, k as L, g as S, l as E, n as c, o as g, q as n, t as T, u as d, m, a as C, p as R, e as _, d as f, v as p, w as A, r as v, x as Y, c as u, y as P, b as k, s as x } from "./index-jwaF2X-1.js";
 export {
   s as CATALOG_URL,
   r as LAYER_STYLE_DEFAULTS,
@@ -6,25 +6,26 @@ export {
   o as PROVIDER_LABELS,
   l as RASTER_STYLE_KEYS,
   i as catalog,
-  y as compareVersions,
-  L as diffStyle,
-  S as entryHeader,
-  E as findCatalogEntries,
-  c as formatTime,
-  g as formatVertical,
+  y as catalogLink,
+  L as compareVersions,
+  S as diffStyle,
+  E as entryHeader,
+  c as findCatalogEntries,
+  g as formatTime,
+  n as formatVertical,
   T as getCatalogEntry,
   d as loadCatalog,
   m as mergeStyles,
-  n as migrateLegacyStyle,
-  C as parseLayerStyle,
-  R as pickPreferredSource,
-  _ as pickSourceByPriority,
-  f as providerLabel,
-  p as requireCatalogEntry,
-  A as resolveEntryStyle,
-  v as resolveLayerStyle,
-  Y as resolveLocalizedText,
-  u as searchCatalog,
-  P as sourceCoversTime,
-  k as styleForKind
+  C as migrateLegacyStyle,
+  R as parseLayerStyle,
+  _ as pickPreferredSource,
+  f as pickSourceByPriority,
+  p as providerLabel,
+  A as requireCatalogEntry,
+  v as resolveEntryStyle,
+  Y as resolveLayerStyle,
+  u as resolveLocalizedText,
+  P as searchCatalog,
+  k as sourceCoversTime,
+  x as styleForKind
 };

package/dist/engine.d.ts

@@ -38,11 +38,19 @@ declare interface BackdropStyle {
  */
 export declare function backdropVec4(backdrop: BackdropStyle): [number, number, number, number];
 
+/**
+ * A ChunkStore in Cache Storage `name`; a store that keeps nothing where Cache
+ * Storage is unavailable (insecure context, some private modes), so callers need no check.
+ */
+export declare function cacheChunkStore(name?: string): ChunkStore;
+
 declare interface CatalogEntry {
     id: string;
     aliases?: string[];
     title: LocalizedText;
     description?: LocalizedText;
+    /** Methodology and sources: an immutable page published with the catalog. */
+    documentation?: string;
     category: string;
     tags?: string[];
     kind: "scalar" | "vector";
@@ -130,6 +138,49 @@ declare interface CatalogZarrSource extends CatalogSourceBase {
     variables: CatalogVariables;
 }
 
+/**
+ * A persistent store of Zarr chunks, as the compressed bytes the server sent,
+ * in the browser's Cache Storage. ZarrSource reads it before the network when
+ * given one (opt-in), so an app opens the chunks of a past session at once.
+ *
+ * Chunks of the to_zarr stores never change once written, except those of the
+ * last time chunk, which grows as months are appended. Those carry a revision
+ * (the length of the time axis): a stored chunk of another revision is stale
+ * and is read again, then replaced under the same key. A new store version has
+ * new URLs, so it never meets the chunks of the previous one.
+ */
+/** A stored chunk, without its bytes. */
+export declare interface ChunkEntry {
+    url: string;
+    /** Bytes on disk (compressed). */
+    size: number;
+    /** When the chunk was stored, ms since the epoch. */
+    storedAt: number;
+    revision: string;
+}
+
+/**
+ * The chunk revision a store expects for `indices` of a variable: the length of
+ * the time axis for chunks of the last time chunk, which grows; empty for every
+ * other chunk, which never changes.
+ */
+export declare function chunkRevision(dimensions: readonly string[], shape: readonly number[], chunks: readonly number[], indices: readonly number[]): string;
+
+export declare interface ChunkStore {
+    /** The bytes of `url`, or undefined when missing or of another revision. */
+    get(url: string, revision?: string): Promise<Uint8Array | undefined>;
+    put(url: string, bytes: Uint8Array, revision?: string): Promise<void>;
+    /** Every stored chunk whose URL starts with `prefix`. */
+    entries(prefix?: string): Promise<ChunkEntry[]>;
+    /** Removes these chunks. */
+    delete(urls: Iterable<string>): Promise<void>;
+    /** Origin storage use and quota, bytes, when the browser reports them. */
+    estimate(): Promise<{
+        usage: number;
+        quota: number;
+    } | undefined>;
+}
+
 /**
  * `vec3 gradeColor(vec3 c, vec4 g)` of `colorGradeVec4`; GLSL ES 1.0 and
  * 3.0. It contains VIBRANCE_GLSL: include one or the other, never both.
@@ -190,6 +241,13 @@ export declare function createProgram(gl: WebGL2RenderingContext, vertSource: st
 
 export declare function createShader(gl: WebGL2RenderingContext, type: number, source: string): WebGLShader;
 
+export declare interface DecodedChunk {
+    data: Float32Array;
+    shape: [number, number];
+    latRange: [number, number];
+    lonRange: [number, number];
+}
+
 /** Trail length in frames for a 0–1 `fade`. */
 export declare function fadeToFrames(fade: number): number;
 
@@ -1225,7 +1283,26 @@ export declare interface VelocityTexturePair {
 /** `vec3 applyVibrance(vec3 c, float v)`; GLSL ES 1.0 and 3.0. */
 export declare const VIBRANCE_GLSL: string;
 
-declare interface ZarrAttrs {
+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;
+}
+
+export declare interface ZarrAttrs {
     _ARRAY_DIMENSIONS?: string[];
     units?: string;
     standard_name?: string;
@@ -1235,13 +1312,20 @@ declare interface ZarrAttrs {
     [key: string]: unknown;
 }
 
-declare interface ZarrChunkFetchResult {
+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;
+    }>;
+}
+
 declare interface ZarrPointSample {
     axisValue: number;
     time?: number;
@@ -1249,7 +1333,7 @@ declare interface ZarrPointSample {
     values: Record<string, number>;
 }
 
-declare interface ZarrPointSeriesResult {
+export declare interface ZarrPointSeriesResult {
     longitude: number;
     latitude: number;
     depth?: number;
@@ -1257,7 +1341,7 @@ declare interface ZarrPointSeriesResult {
     points: ZarrPointSample[];
 }
 
-declare class ZarrSource {
+export declare class ZarrSource {
     private root;
     private meta;
     private coords;
@@ -1269,7 +1353,18 @@ declare class ZarrSource {
     private maxCacheSize;
     private abortControllers;
     private bloscCodecCache;
-    constructor(root: string, maxCacheSize?: number);
+    private chunkStore;
+    /**
+     * `options.chunkStore` keeps the compressed chunks across sessions (see
+     * chunkStore.ts); without it, chunks are only kept in memory.
+     */
+    constructor(root: string, maxCacheSize?: number, options?: {
+        chunkStore?: ChunkStore;
+    });
+    /** The URL of a chunk, as fetched and as stored. */
+    chunkUrl(variable: string, indices: number[]): string;
+    /** The revision a stored chunk must carry to be current (see chunkRevision). */
+    chunkRevision(variable: string, indices: number[]): string;
     init(): Promise<void>;
     private getArrayMeta;
     private getAttrs;
@@ -1355,7 +1450,7 @@ declare class ZarrSource {
     private loadCoordinates;
 }
 
-declare interface ZarrTimeDimension {
+export declare interface ZarrTimeDimension {
     min: number;
     max: number;
     step?: number;
@@ -1364,7 +1459,7 @@ declare interface ZarrTimeDimension {
     values: number[];
 }
 
-declare interface ZarrVerticalDimension {
+export declare interface ZarrVerticalDimension {
     name: string;
     label: "depth" | "pressure" | string;
     units?: string;

package/dist/engine.js

@@ -1,64 +1,67 @@
-import { Q as o, R as s, G as r, S as d, j as i, U as t, V as G, W as c, X as l, Y as V, n, Z as S, _ as L, $ as C, T as u, a0 as m, a1 as O, a2 as _, a3 as p, b as R, a4 as A, c as T, a5 as g, a6 as I, o as h, D as k, M as x, a7 as f, N as v, q as D, z as F, w as E, H as B, L as b, p as N, I as P, a8 as y, a9 as M, aa as W, ab as U, t as H, ac as Y, ad as j, ae as q, J as w, af as z, ag as J, P as K, v as Q, ah as X } from "./engine-C8ZNzILO.js";
-import { B as $, a as aa, f as ea, b as oa, e as sa, c as ra, g as da, i as ia, r as ta, d as Ga } from "./backdrop-Dceb4d8E.js";
+import { C as o, G as s, a as r, b as i, c as d, d as c, e as t, f as G, g as l, h as n, i as V, j as S, k as C, R as u, T as L, V as m, l as O, Z as R, m as _, n as p, o as A, p as h, q as k, r as T, s as g, t as x, u as I, v, w as F, x as D, y as E, z as f, A as B, B as N, D as b, E as y, F as P, H as M, I as W, J as U, K as H, L as K, M as Y, N as Z, O as j, P as q, Q as w, S as z, U as J, W as Q, X, Y as $, _ as aa } from "./geovideo-index-D-BHqpO6.js";
+import { B as oa, C as sa, a as ra, b as ia, c as da, d as ca, g as ta, i as Ga, r as la, e as na } from "./backdrop-BMwRyFI5.js";
 export {
-  $ as BACKDROP_OFF,
+  oa as BACKDROP_OFF,
   o as COLOR_GRADE_GLSL,
-  aa as COLOR_GRADE_OFF,
-  ea as COLOR_GRADE_VIBRANT,
+  sa as COLOR_GRADE_OFF,
+  ra as COLOR_GRADE_VIBRANT,
   s as GEOVIDEO_SCALAR_GLSL,
   r as GLOW_GAIN,
-  d as GLOW_GLSL,
-  i as GLOW_SCALE,
-  t as GeoVideoArchiveSource,
-  G as GeoVideoClock,
-  c as GeoVideoCodecScalarSource,
+  i as GLOW_GLSL,
+  d as GLOW_SCALE,
+  c as GeoVideoArchiveSource,
+  t as GeoVideoClock,
+  G as GeoVideoCodecScalarSource,
   l as GeoVideoField,
-  V as GeoVideoFrameSource,
-  n as GeoVideoPlayback,
+  n as GeoVideoFrameSource,
+  V as GeoVideoPlayback,
   S as GeoVideoScalarSource,
-  L as GeoVideoVectorSource,
-  C as RANDOM_GLSL,
-  u as TrailFade,
+  C as GeoVideoVectorSource,
+  u as RANDOM_GLSL,
+  L as TrailFade,
   m as VELOCITY_BLEND_GLSL,
   O as VIBRANCE_GLSL,
+  R as ZarrSource,
   _ as alphaFadeAt,
   p as assertGeoVideoIndexIdentity,
-  oa as backdropVec4,
-  sa as colorGradeToGrade,
-  ra as colorGradeVec4,
-  R as createColorRampTexture,
-  A as createGeoVideoFrameSource,
-  T as createProgram,
-  g as createShader,
+  ia as backdropVec4,
+  A as cacheChunkStore,
+  h as chunkRevision,
+  da as colorGradeToGrade,
+  ca as colorGradeVec4,
+  k as createColorRampTexture,
+  T as createGeoVideoFrameSource,
+  g as createProgram,
+  x as createShader,
   I as fadeToFrames,
-  h as fadeToOpacity,
-  k as formatUnit,
-  x as geoVideoChunkSources,
-  f as geoVideoGrid,
-  v as geoVideoIndexChunks,
-  D as geoVideoScalarUniforms,
-  F as geoVideoTimelineValues,
-  E as getPalettes,
-  da as gradeToColorGrade,
-  B as isGeoVideoArchiveSource,
-  ia as isHexColor,
-  b as loadGeoVideoIndex,
-  N as loadGeoVideoManifest,
-  P as nextChunk,
-  y as nextChunkSpan,
-  M as pairChunk,
-  W as pairChunkSpan,
-  U as parseTimeRange,
-  ta as resolveBackdrop,
-  Ga as resolveColorGrade,
-  H as resolveColorRamp,
-  Y as stepTime,
-  j as subtractIsoDuration,
-  q as timeBracket,
-  w as timeRangeBounds,
-  z as timeStep,
-  J as validateGeoVideoIndex,
-  K as validateGeoVideoManifest,
-  Q as validateScalarColorDomain,
-  X as velocityTexels
+  v as fadeToOpacity,
+  F as formatUnit,
+  D as geoVideoChunkSources,
+  E as geoVideoGrid,
+  f as geoVideoIndexChunks,
+  B as geoVideoScalarUniforms,
+  N as geoVideoTimelineValues,
+  b as getPalettes,
+  ta as gradeToColorGrade,
+  y as isGeoVideoArchiveSource,
+  Ga as isHexColor,
+  P as loadGeoVideoIndex,
+  M as loadGeoVideoManifest,
+  W as nextChunk,
+  U as nextChunkSpan,
+  H as pairChunk,
+  K as pairChunkSpan,
+  Y as parseTimeRange,
+  la as resolveBackdrop,
+  na as resolveColorGrade,
+  Z as resolveColorRamp,
+  j as stepTime,
+  q as subtractIsoDuration,
+  w as timeBracket,
+  z as timeRangeBounds,
+  J as timeStep,
+  Q as validateGeoVideoIndex,
+  X as validateGeoVideoManifest,
+  $ as validateScalarColorDomain,
+  aa as velocityTexels
 };