@fxi/zartigl 0.6.0 → 0.7.0

package/dist/zartigl.d.ts

@@ -2,6 +2,21 @@ import { CustomLayerInterface } from 'maplibre-gl';
 import { CustomRenderMethodInput } from 'maplibre-gl';
 import { Map as Map_2 } from 'maplibre-gl';
 
+/** Particle backdrop off: see BackdropStyle. */
+export declare const BACKDROP_OFF: Readonly<BackdropStyle>;
+
+/**
+ * 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.
+ */
+declare interface BackdropStyle {
+    enabled: boolean;
+    /** Hex color, `#rgb` or `#rrggbb`. */
+    color: string;
+    opacity: number;
+}
+
 export declare function buildMapxWidgetSnippet(options: MapxWidgetSnippetOptions): string;
 
 export declare function buildStandaloneDemoHtml(options: StandaloneDemoSnippetOptions): string;
@@ -41,22 +56,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];
-        };
     };
 }
 
@@ -178,6 +181,9 @@ export declare interface ColorGrade {
     highlights: number;
 }
 
+/** Style `particles.grade` of a color grade: a preset when it is one. */
+export declare function colorGradeToGrade(input: Partial<ColorGrade>): ParticleGrade;
+
 export declare type ColorRampInput = string | string[] | Record<number, string>;
 
 declare interface CoordArrays {
@@ -557,6 +563,24 @@ export declare function getPalettes(): PaletteMeta[];
 
 export declare function getVectorDerivationVariables(derivation: VectorDerivation): [string, string];
 
+/** Color grade of a style `particles.grade`; an object tunes the vibrant one. */
+export declare function gradeToColorGrade(grade: ParticleGrade | undefined): ColorGrade;
+
+/** Vibrant grade values; each one left out takes the vibrant preset's. */
+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;
+}
+
+/** A `#rgb` or `#rrggbb` color. */
+export declare const isHexColor: (value: unknown) => value is string;
+
 declare type LayerEventMap = {
     loading: () => void;
     loaded: (meta: FieldMeta) => void;
@@ -577,6 +601,25 @@ declare type LayerEventMap_2 = {
     cacheInvalidated: () => void;
 };
 
+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. */
+declare interface LayerStyleInput {
+    palette?: string;
+    renderMode?: StyleRenderMode;
+    particles?: ParticleStyleInput;
+    raster?: Partial<RasterStyle>;
+}
+
+/** Where each deprecated flat style setting moved in the style. */
+export declare const LEGACY_STYLE_SETTINGS: Readonly<Partial<Record<keyof ZartiglSettings, string>>>;
+
 export declare type Legend = {
     type: "gradient";
     palette: string;
@@ -598,12 +641,20 @@ declare type LocalizedText = Record<string, string>;
 export declare interface MapxWidgetSnippetOptions {
     layerId: string;
     layerKind: CatalogEntry["kind"];
+    /**
+     * The layer's own style, the catalog `defaults`: only override keys that
+     * differ from it are written. Unknown, the whole override is written.
+     */
+    layerDefaults?: LayerStyleInput;
     source?: string;
     sourceType?: SnippetSourceType;
     time?: string | number | Date;
     timeRange?: TimeRange;
     geoVideo?: GeoVideoOptions;
     depth?: number;
+    /** Style override; only keys that differ from the layer's own are written. */
+    style?: LayerStyleInput;
+    /** Engine tuning; flat style keys are ignored. */
     settings?: Partial<ZartiglSettings>;
 }
 
@@ -614,6 +665,9 @@ export declare interface PaletteMeta {
     colors: string[];
 }
 
+/** Particle trail color grade: a preset, or the vibrant one tuned. */
+declare type ParticleGrade = "off" | "vibrant" | GradeTuning;
+
 export declare class ParticleSimulation {
     private gl;
     private params;
@@ -686,13 +740,13 @@ export declare class ParticleSimulation {
         south: number;
         east: number;
         north: number;
-    }, opacityScale?: number): void;
+    }, opacityScale?: number, solid?: Vec4): 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): void;
+    }, clippingPlane: [number, number, number, number], opacityScale?: number, solid?: Vec4): void;
     private setGridFieldUniforms;
     private bindRasterGrid;
     private unbindRasterGrid;
@@ -713,6 +767,8 @@ export declare class ParticleSimulation {
     setVibrance(v: number): void;
     /** Partial values take the vibrant preset; see resolveColorGrade. */
     setColorGrade(grade: Partial<ColorGrade>): void;
+    /** Missing values take the defaults; see resolveBackdrop. */
+    setBackdrop(backdrop: Partial<BackdropStyle>): void;
     setScalarMode(v: boolean): void;
     setRgba8MaxParticleZoom(v: number): void;
     /**
@@ -749,6 +805,7 @@ export declare interface ParticleSimulationDebugInfo {
     logScale: boolean;
     vibrance: number;
     colorGrade: ColorGrade;
+    backdrop: BackdropStyle;
     scalarMode: boolean;
     devicePixelRatio?: number;
     webgl: WebGLRendererInfo | null;
@@ -758,6 +815,24 @@ export declare type ParticleStateKind = StateTextureFormat["kind"];
 
 export declare type ParticleStateMode = "auto" | "rgba8";
 
+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. */
+declare type ParticleStyleInput = Partial<Omit<ParticleStyle, "backdrop">> & {
+    backdrop?: Partial<BackdropStyle>;
+};
+
 export declare interface PlaybackState {
     /** Whether the active source plays automatically: GeoVideo only. */
     available: boolean;
@@ -783,8 +858,24 @@ export declare interface QueryPointOptions {
     maxPoints?: number;
 }
 
+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 type RenderMode = "raster" | "particles" | "raster+particles";
 
+/**
+ * Complete backdrop from partial input. Missing or invalid values take the
+ * defaults, opacity is clamped; `enabled` defaults to true when any input is
+ * given, so `{ opacity: 0.2 }` means "on".
+ */
+export declare function resolveBackdrop(input?: Partial<BackdropStyle>): BackdropStyle;
+
 /**
  * Complete grade from partial input. Missing or non-finite values take the
  * vibrant preset, others are clamped to their range; `enabled` defaults to
@@ -914,6 +1005,8 @@ declare interface SimulationParams {
     vibrance: number;
     /** Grade of the trail composite; off by default. */
     colorGrade: ColorGrade;
+    /** Solid color under the trails, on valid cells; off by default. */
+    backdrop: BackdropStyle;
     scalarMode: boolean;
     particleState: ParticleStateMode;
     rgba8MaxParticleZoom: number;
@@ -921,6 +1014,17 @@ declare interface SimulationParams {
 
 declare type SnippetSourceType = "zarr" | "geovideo" | "wmts";
 
+/**
+ * Split flat settings into the style their style keys make and the engine
+ * tuning left. A custom palette ramp, not a palette id, stays in
+ * `settings`. `legacyKeys` lists the style keys found.
+ */
+export declare function splitLegacySettings(settings?: Partial<ZartiglSettings>): {
+    style: LayerStyleInput;
+    settings: Partial<ZartiglSettings>;
+    legacyKeys: (keyof ZartiglSettings)[];
+};
+
 export declare interface StandaloneDemoSnippetOptions extends MapxWidgetSnippetOptions {
     moduleBaseUrl?: string;
     center?: [number, number];
@@ -928,7 +1032,8 @@ export declare interface StandaloneDemoSnippetOptions extends MapxWidgetSnippetO
     bearing?: number;
     pitch?: number;
     projection?: "mercator" | "globe";
-    style?: string;
+    /** MapLibre map style URL; a cloudless imagery style when omitted. */
+    mapStyle?: string;
 }
 
 /**
@@ -968,6 +1073,13 @@ export declare function stitchVelocityChunks(uChunks: Array<{
     north: number;
 }, latDescending?: boolean, scalarMode?: boolean): VelocityData;
 
+/**
+ * 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.
+ */
+declare type StyleRenderMode = "particles" | "raster" | "raster+particles";
+
 export declare type TimeGranularity = "year" | "month" | "day" | "hour" | "minute" | "second";
 
 export declare interface TimeMeta {
@@ -999,6 +1111,8 @@ export declare interface VariableMeta {
     units?: string;
 }
 
+declare type Vec4 = [number, number, number, number];
+
 /**
  * Vector GeoVideo speeds: each step re-seeds the particles, so trails need
  * time to settle (the projection demo plays 0.2 to 2 steps per second).
@@ -1092,6 +1206,7 @@ export declare class VectorLayer implements CustomLayerInterface {
     setLogScale(v: boolean): void;
     setVibrance(v: number): void;
     setColorGrade(grade: Partial<ColorGrade>): void;
+    setBackdrop(backdrop: Partial<BackdropStyle>): void;
     getDebugInfo(): VectorLayerDebugInfo;
     on<K extends keyof LayerEventMap_2>(event: K, handler: LayerEventMap_2[K]): this;
     off<K extends keyof LayerEventMap_2>(event: K, handler: LayerEventMap_2[K]): this;
@@ -1145,6 +1260,8 @@ export declare interface VectorLayerOptions {
      * vibrant preset (see resolveColorGrade).
      */
     colorGrade?: Partial<ColorGrade>;
+    /** Solid color under the trails, on valid cells. Omitted: off. */
+    backdrop?: Partial<BackdropStyle>;
     unit?: string;
 }
 
@@ -1424,6 +1541,8 @@ export declare class Zartigl {
     /** GeoVideo manifests that failed to load; "auto" falls back to Zarr. */
     private failedGeoVideo;
     private settings;
+    /** Style override over the layer's own, kept across layers. */
+    private style;
     private colorDomainOverridden;
     private paletteOverridden;
     private lastMeta;
@@ -1453,7 +1572,7 @@ export declare class Zartigl {
     private readonly onMapIdle;
     constructor(options: ZartiglOptions);
     init(): Promise<void>;
-    update(change: ZartiglUpdate): Promise<void>;
+    update(input: ZartiglUpdate): Promise<void>;
     /**
      * Queue a change after earlier ones. Internal seeks, such as an archive
      * chunk handoff, come here directly and keep playback going.
@@ -1534,7 +1653,19 @@ export declare class Zartigl {
     private hasPlayback;
     /** Whether palette/domain styling is applied to values in the active renderer. */
     supportsDynamicStyle(): boolean;
+    /**
+     * The style drawn: the layer's own, then the override, with what the
+     * source chose, such as a GeoVideo archive's palette.
+     */
+    getStyle(): LayerStyle;
+    /** The style override over the layer's own. */
+    getStyleOverride(): LayerStyleInput;
     getDebugInfo(): ZartiglDebugInfo;
+    /**
+     * Every style key of the shown layer with the override, the palette and
+     * color domain of a GeoVideo archive included, as a load sets them.
+     */
+    private styledSettings;
     private applySettings;
     queryTimeSeries(options: QueryPointOptions): Promise<ZarrPointSeriesResult>;
     queryDepthProfile(options: QueryDepthProfileOptions): Promise<ZarrPointSeriesResult>;
@@ -1679,6 +1810,12 @@ export declare interface ZartiglOptions {
     depth?: number;
     geoVideo?: GeoVideoOptions;
     visible?: boolean;
+    /** Style override over the layer's own. */
+    style?: LayerStyleInput;
+    /**
+     * Engine tuning (`particleState`, `rgba8MaxParticleZoom`). Flat style
+     * keys are deprecated: they move to `style`, with a warning.
+     */
     settings?: Partial<ZartiglSettings>;
     metadata?: Record<string, unknown>;
     before?: string;
@@ -1698,6 +1835,8 @@ export declare interface ZartiglSettings {
      * vibrant preset (see resolveColorGrade).
      */
     colorGrade: Partial<ColorGrade>;
+    /** Solid color under particle trails, on valid cells; off by default. */
+    backdrop: Partial<BackdropStyle>;
     /** Fixed physical-value domain for scalar colors. Null uses frame extrema. */
     colorDomain: [number, number] | null;
     particleState: ParticleStateMode;
@@ -1734,6 +1873,17 @@ export declare interface ZartiglUpdate {
     timeRange?: TimeRange | null;
     time?: Date | string | number;
     depth?: number;
+    /**
+     * Replaces the style override: every style key returns to the layer's own,
+     * then this one applies (`{}` clears it). Omitted, the override stays,
+     * across layers too, without the keys a new layer kind cannot draw. Kept
+     * once a layer switch loads.
+     */
+    style?: LayerStyleInput;
+    /**
+     * Engine tuning. Flat style keys are deprecated: they patch the style
+     * override, with a warning.
+     */
     settings?: Partial<ZartiglSettings>;
     geoVideo?: GeoVideoOptions;
     visible?: boolean;