@fxi/zartigl 0.6.0 → 0.7.1

package/README.md

@@ -70,7 +70,7 @@ const z = new Zartigl({
   timeRange: { trailing: "P1M" },
   time: new Date("2025-01-01T00:00:00Z"),
   depth: 0,
-  settings: { palette: "rdylbu", opacity: 0.9 },
+  style: { palette: "rdylbu", raster: { opacity: 0.9 } },
   geoVideo: { autoplay: false, loop: true, stepsPerSecond: 4 },
 });
 
@@ -81,10 +81,76 @@ await z.init();
 Use `await z.update({ ... })` to change any subset of the active configuration.
 Pass `layer` and `source` together when both should switch atomically.
 
+`source` takes a source id or a preference:
+
+- `"geovideo"`: fast; surface level and GeoVideo dates only.
+- `"zarr"`: all dates and depths; heavier on the client.
+- `"auto"`: GeoVideo, falling back to Zarr for other dates and depths; the
+  layer style always applies. WMTS only when the entry has neither.
+- `"wmts"`: rendered by the server, palette and legend included; no
+  particles, and the layer style has no effect.
+
 `init()` and layer/source updates resolve after consolidated metadata and coordinate axes have loaded. Metadata getters are therefore authoritative afterward, including exact values for irregular time axes.
 
 The root import does not bundle the catalog presets. Import catalog data from `@fxi/zartigl/catalog` only when you want the built-in catalog.
 
+## Layer style
+
+A layer style has the same shape everywhere: catalog `defaults`, the
+`Zartigl` `style` option and `update({ style })`, story views, projversor,
+the MapX `ArcoMapLegend` and the snippets the demo exports.
+
+```jsonc
+{
+  "palette": "thermal",
+  "renderMode": "particles", // or "raster", "raster+particles"
+  "particles": {
+    "density": 0.03,
+    "speed": 1,
+    "fade": 0.7,
+    "grade": "vibrant",
+    "backdrop": { "enabled": true, "color": "#000000", "opacity": 0.3 }
+  },
+  "raster": { "opacity": 0.9, "logScale": false, "vibrance": 0.2, "colorDomain": null }
+}
+```
+
+`particles.grade` is `"off"`, `"vibrant"`, or a tuned vibrant grade
+`{ exposure, contrast, saturation, highlights }`; it is replaced as a whole.
+
+`particles.backdrop` paints a flat color under the particle trails, on the
+valid cells of the field only (the ocean, not the land), so particles stay
+readable over a light basemap. It is off by default; an object is on unless
+`enabled` is false, and its keys left out take the defaults (`color:
+"#000000"`, `#rgb` or `#rrggbb`; `opacity: 0.5`). Like the grade, it is
+replaced as a whole.
+
+Keys merge one by one: engine defaults (`LAYER_STYLE_DEFAULTS`), then the
+catalog entry `defaults`, then the engine's own layer style, then the view.
+From `@fxi/zartigl/catalog`: `resolveEntryStyle(entry, ...styles)` gives the
+style a layer is drawn with, `mergeStyles` patches an override,
+`diffStyle` keeps what differs from a resolved style, and `parseLayerStyle`
+validates, with the path of the offending key. `z.getStyle()` returns the
+style drawn, `z.getStyleOverride()` the override.
+
+The view style is an override that replaces the previous one:
+`update({ style })` and projversor `apply({ style })` return every style key
+to the layer's own, then apply it (`{}` clears it). Without `style`, the
+override stays, across layers too. Scalar layers take no `particles` and only
+the `"raster"` render mode.
+
+`particles.speed` is always the particle speed; playback speed lives
+elsewhere (`geoVideo.stepsPerSecond`, or a projversor view `playback.speed`).
+In projversor, playback also scales the particles by `particleSpeedFactor`:
+0.325 at 1×, 1 at 5×.
+
+`settings` carries engine tuning only (`particleState`,
+`rgba8MaxParticleZoom`). Flat style keys in it (`particleDensity`,
+`opacity`, `colorGrade`…) are deprecated until 1.0: they patch the style
+override, `style` winning, with one warning per key
+(`splitLegacySettings`, `LEGACY_STYLE_SETTINGS`). A custom palette ramp
+stays a setting.
+
 ## Demo
 
 The production demo is the default Vite app and is published at
@@ -161,49 +227,23 @@ finishes publishing it; a renderable sparse frame is cached normally.
 
 `VectorLayer`, `ScalarLayer`, `GeoVideoLayer`, and `ZarrSource` remain exported for advanced use cases that need direct control over renderer internals. Ordinary MapLibre integrations should prefer `Zartigl`.
 
-### Projversor and story entries
+### Entries without MapLibre
 
-Two entries need no MapLibre (`maplibre-gl` is an optional peer):
+Three entries need no MapLibre (`maplibre-gl` is an optional peer):
 
-- `@fxi/zartigl/projversor`: GeoVideo archives on a WebGL2 sphere that morphs
-  between world projections.
+- `@fxi/zartigl/engine`: GeoVideo manifests, indexes, decoders and archive
+  timelines, palettes and color ramps, color grade, backdrop and trail fade,
+  WebGL helpers and the shared GLSL chunks as strings (`VIBRANCE_GLSL`,
+  `COLOR_GRADE_GLSL`, `RANDOM_GLSL`).
+- `@fxi/zartigl/catalog`: the built-in catalog, named palettes and styles.
 - `@fxi/zartigl/story`: the story runtime, with JSON documents, localized
   copy and scroll activation.
 
-```ts
-import { Projversor, ProjversorStoryView } from "@fxi/zartigl/projversor";
-import {
-  StoryScroller,
-  parseStoryDocuments,
-  sceneViewId,
-} from "@fxi/zartigl/story";
-
-// Three stacked canvases in a positioned stage. Attach them before
-// constructing: the overlay reads its colors (--ocean, --land, --coast,
-// --graticule…) from the front canvas computed style. Throws without WebGL2.
-const projversor = new Projversor({ stage, back, gl, front });
-projversor.setPlaying(true);
-
-// One view per scene: layer, preset, rotate, zoom, palette, tint, time…
-const { story, views } = parseStoryDocuments(storyJson, viewsJson);
-const adapter = new ProjversorStoryView(projversor);
-
-// The section crossing 60% of the viewport height activates its view.
-const scroller = new StoryScroller(sections, (index) => {
-  const id = sceneViewId(story.scenes[index]);
-  const view = views.views.find((v) => v.id === id);
-  if (view) {
-    void adapter.activate(view);
-  }
-}, { line: 0.6 });
-
-// Later: scroller.destroy(); adapter.destroy();
-```
-
-`parseProjversorView` validates a view against the projversor layers and
-presets. `goTo`, `jumpTo` and `setInset` move the camera, keeping a screen area
-free for text. The finer coastline loads in a separate chunk after the first
-paint. `src/demo-site/` is a complete scroll story page built on both entries.
+[projversor](https://github.com/fxi/projversor) (`@fxi/projversor`), the
+renderer of GeoVideo archives on a sphere that morphs between world
+projections, is built on these entries in its own repository, with its demos.
+zartigl never imports it. It replaces the former `@fxi/zartigl/projversor`
+entry: the same names are exported by `@fxi/projversor/zartigl`.
 
 ## Alternatives And Project Fit
 

package/dist/backdrop-DctkJ45Q.js

@@ -0,0 +1,79 @@
+const i = {
+  exposure: 0.8,
+  contrast: 0.6,
+  saturation: 0.4,
+  highlights: 0.6
+}, l = Object.freeze({
+  enabled: !1,
+  ...i
+}), s = Object.freeze({
+  enabled: !0,
+  ...i
+}), u = {
+  exposure: [0, 4],
+  contrast: [0, 1],
+  saturation: [-1, 1],
+  highlights: [0, 1]
+}, a = u;
+function f(e) {
+  if (!e)
+    return { ...l };
+  const o = {
+    ...s,
+    enabled: e.enabled ?? !0
+  };
+  for (const n of Object.keys(a)) {
+    const t = e[n];
+    if (typeof t == "number" && Number.isFinite(t)) {
+      const [r, b] = a[n];
+      o[n] = Math.min(b, Math.max(r, t));
+    }
+  }
+  return o;
+}
+function h(e) {
+  return [e.exposure, e.contrast, e.saturation, e.highlights];
+}
+function m(e) {
+  return e === void 0 || e === "off" ? { ...l } : e === "vibrant" ? { ...s } : f({ ...e, enabled: !0 });
+}
+function y(e) {
+  const o = f(e);
+  if (!o.enabled)
+    return "off";
+  const n = Object.keys(a);
+  return n.every((t) => o[t] === s[t]) ? "vibrant" : Object.fromEntries(n.map((t) => [t, o[t]]));
+}
+const c = Object.freeze({
+  enabled: !1,
+  color: "#000000",
+  opacity: 0.5
+}), d = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i, O = (e) => typeof e == "string" && d.test(e);
+function R(e) {
+  if (!e)
+    return { ...c };
+  const o = { ...c, enabled: !0 };
+  return typeof e.enabled == "boolean" && (o.enabled = e.enabled), O(e.color) && (o.color = e.color), typeof e.opacity == "number" && Number.isFinite(e.opacity) && (o.opacity = Math.min(1, Math.max(0, e.opacity))), o;
+}
+function p(e) {
+  const o = e.color.slice(1), n = o.length === 3 ? o.split("").map((r) => r + r).join("") : o, t = (r) => parseInt(n.slice(r, r + 2), 16) / 255;
+  return [
+    t(0),
+    t(2),
+    t(4),
+    e.enabled ? e.opacity : 0
+  ];
+}
+export {
+  c as B,
+  l as C,
+  R as a,
+  p as b,
+  h as c,
+  y as d,
+  s as e,
+  u as f,
+  m as g,
+  O as i,
+  f as r
+};

package/dist/catalog.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Solid color under the particle trails, drawn on valid data cells only: it
+ * keeps particles readable over a light basemap. Off by default; an object
+ * without `enabled` is on.
+ */
+export declare interface BackdropStyle {
+    enabled: boolean;
+    /** Hex color, `#rgb` or `#rrggbb`. */
+    color: string;
+    opacity: number;
+}
+
 export declare interface Catalog {
     schemaVersion: 2;
     defaultLocale: string;
@@ -15,22 +27,10 @@ export declare interface CatalogEntry {
     tags?: string[];
     kind: "scalar" | "vector";
     sources: CatalogSource[];
-    defaults: {
+    /** Default source, plus the layer's base style. */
+    defaults: LayerStyleInput & {
         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];
-        };
     };
 }
 
@@ -126,6 +126,9 @@ export declare interface CatalogZarrSource extends CatalogSourceBase {
     variables: CatalogVariables;
 }
 
+/** The keys of `style` whose value differs from `base`'s. */
+export declare function diffStyle(style: LayerStyleInput, base: LayerStyle): LayerStyleInput;
+
 export declare function findCatalogEntries(selector: CatalogEntrySelector, data?: Catalog): CatalogEntry[];
 
 export declare function formatTime(ms: number): string;
@@ -134,10 +137,89 @@ export declare function formatVertical(v: number, label: string, units?: string)
 
 export declare function getCatalogEntry(id: string, data?: Catalog): CatalogEntry | undefined;
 
+/** Vibrant grade values; each one left out takes the vibrant preset's. */
+export declare interface GradeTuning {
+    /** Mid-tone lift [0, 4]. */
+    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;
+}
+
+/** Engine fallbacks, under the catalog `defaults`. */
+export declare const LAYER_STYLE_DEFAULTS: Readonly<LayerStyle>;
+
+export declare interface LayerStyle {
+    /** Palette id; undefined lets the engine pick its own. */
+    palette?: string;
+    renderMode: StyleRenderMode;
+    particles: ParticleStyle;
+    raster: RasterStyle;
+}
+
+/** A partial style: any key left out takes the value below it. */
+export declare interface LayerStyleInput {
+    palette?: string;
+    renderMode?: StyleRenderMode;
+    particles?: ParticleStyleInput;
+    raster?: Partial<RasterStyle>;
+}
+
 export declare type LocalizedText = Record<string, string>;
 
 /**
- * Preferred render source: GeoVideo, then WMTS (scalar), then Zarr, skipping
+ * One partial style from several, later inputs winning key by key: patch an
+ * override without resolving defaults.
+ */
+export declare function mergeStyles(...inputs: (LayerStyleInput | undefined)[]): LayerStyleInput;
+
+/**
+ * Validate a style, throwing an error that names the offending path, e.g.
+ * `views.swell.config.style.particles.density must be a number in (0, 0.2]`.
+ */
+export declare function parseLayerStyle(value: unknown, path: string, options?: ParseLayerStyleOptions): LayerStyleInput;
+
+/** Which keys a caller supports, and for which layer kind. */
+export declare interface ParseLayerStyleOptions {
+    kind?: "scalar" | "vector";
+    /** Keys left out are rejected as unsupported; all when omitted. */
+    supports?: {
+        palette?: boolean;
+        renderMode?: boolean;
+        particles?: readonly (keyof ParticleStyle)[];
+        raster?: readonly (keyof RasterStyle)[];
+    };
+}
+
+/** Style keys, for checks against other definitions of the same shape. */
+export declare const PARTICLE_STYLE_KEYS: (keyof ParticleStyle)[];
+
+/** Particle trail color grade: a preset, or the vibrant one tuned. */
+export declare type ParticleGrade = "off" | "vibrant" | GradeTuning;
+
+export declare interface ParticleStyle {
+    /** Particles per device pixel, (0, 0.2]. */
+    density: number;
+    /** Css px per frame for the fastest value of the field, (0, 10]. */
+    speed: number;
+    /** Trail length, [0, 1] (longer when higher). */
+    fade: number;
+    /** Trail color grade; replaced as a whole, not merged. */
+    grade: ParticleGrade;
+    /** Solid color under the trails; replaced as a whole, not merged. */
+    backdrop: BackdropStyle;
+}
+
+/** Partial particle style; a partial backdrop takes the defaults' keys. */
+export declare type ParticleStyleInput = Partial<Omit<ParticleStyle, "backdrop">> & {
+    backdrop?: Partial<BackdropStyle>;
+};
+
+/**
+ * Preferred render source: GeoVideo, then Zarr, then WMTS (scalar), skipping
  * fixed-period sources that cannot show the requested time. Several GeoVideo
  * periods may coexist; the latest covering one wins. GeoVideo is a
  * lightweight display transport; Zarr stays the fallback and query source.
@@ -150,8 +232,31 @@ export declare function pickPreferredSource(entry: CatalogEntry, request?: Sourc
  */
 export declare function pickSourceByPriority(entry: CatalogEntry, priority: readonly CatalogSource["type"][], request?: SourceTimeRequest): CatalogSource | undefined;
 
+export declare const RASTER_STYLE_KEYS: (keyof RasterStyle)[];
+
+export declare interface RasterStyle {
+    opacity: number;
+    logScale: boolean;
+    /** Vibrance adjustment, [-1, 1]. */
+    vibrance: number;
+    /** Fixed physical-value domain; null follows the data. */
+    colorDomain: [number, number] | null;
+}
+
 export declare function requireCatalogEntry(id: string, data?: Catalog): CatalogEntry;
 
+/**
+ * The style a catalog layer is drawn with: its own style, then `inputs`.
+ * Scalar layers draw a raster.
+ */
+export declare function resolveEntryStyle(entry: StyledEntry | undefined, ...inputs: (LayerStyleInput | undefined)[]): LayerStyle;
+
+/**
+ * Merge styles over {@link LAYER_STYLE_DEFAULTS}, later inputs winning key by
+ * key. Usual order: catalog `defaults`, engine style, view.
+ */
+export declare function resolveLayerStyle(...inputs: (LayerStyleInput | undefined)[]): LayerStyle;
+
 export declare function resolveLocalizedText(value: LocalizedText | undefined, locale: string, defaultLocale?: string): string;
 
 export declare function searchCatalog(query: string, options?: CatalogSearchOptions, data?: Catalog): CatalogEntry[];
@@ -170,4 +275,20 @@ export declare interface SourceTimeRequest {
     end?: number;
 }
 
+/** A catalog entry, or anything with its kind and default style. */
+export declare interface StyledEntry {
+    kind: "scalar" | "vector";
+    defaults?: LayerStyleInput;
+}
+
+/** `style` without the keys a layer of `kind` cannot draw. */
+export declare function styleForKind(style: LayerStyleInput, kind: StyledEntry["kind"] | undefined): LayerStyleInput;
+
+/**
+ * Layer style: how a layer looks, with the same keys in the catalog
+ * `defaults`, the engines and story views. Playback (how time moves) is not
+ * part of it, so `particles.speed` is always the particle speed.
+ */
+export declare type StyleRenderMode = "particles" | "raster" | "raster+particles";
+
 export { }