@fxi/zartigl 0.9.2 → 0.10.0

package/README.md

@@ -103,6 +103,7 @@ the MapX `ArcoMapLegend` and the snippets the demo exports.
 ```jsonc
 {
   "palette": "thermal",
+  "reversePalette": false,
   "renderMode": "particles", // or "raster", "raster+particles"
   "particles": {
     "density": 0.03,
@@ -111,10 +112,36 @@ the MapX `ArcoMapLegend` and the snippets the demo exports.
     "grade": "vibrant",
     "backdrop": { "enabled": true, "color": "#000000", "opacity": 0.3 }
   },
-  "raster": { "opacity": 0.9, "logScale": false, "vibrance": 0.2, "colorDomain": null }
+  "raster": {
+    "opacity": 0.9, "logScale": false, "vibrance": 0.2, "colorDomain": null,
+    "alphaFadeLow": 0, "alphaFadeHigh": 0, "alphaFadeCurve": "linear"
+  }
 }
 ```
 
+`reversePalette` runs the palette from its last color to its first, for the
+raster and the particles.
+
+`raster.alphaFadeLow` and `alphaFadeHigh` make the ends of the color range
+transparent, with any palette. Each is a fraction of the range as displayed
+(the color domain, after log scale): `alphaFadeLow: 0.25` fades the lowest
+quarter in from transparent, `alphaFadeHigh: 0.5` fades the upper half out,
+and values beyond the domain take its transparent ends. A field that is
+mostly zero, such as fire radiative power or coral heat stress, then shows
+only where something happens. `alphaFadeCurve` shapes both fades, with the
+curves of `logScale`: `"linear"`, `"log"` (`log10(1 + 9x)`, rises fast) or
+`"exp"` (its inverse, stays faint longer, which also hides codec noise at the
+ends of a GeoVideo). The fade is part of the color ramp
+(`resolveColorRamp(palette, { reverse, alphaFade })`), so Zarr, GeoVideo,
+projversor and legends show the same transparency. Neither key changes how
+GeoVideo archives are encoded, so restyling never re-renders them.
+
+`heat-alert`, which faded low values in through transparent palette stops, is
+deprecated: `migrateLegacyStyle` reads it as `heat` with `alphaFadeLow: 0.25`
+(the closest fit of its alpha), wherever a style enters, so old catalogs,
+share links and story views keep working. `getPalettes()` leaves deprecated
+palettes out of pickers.
+
 `particles.grade` is `"off"`, `"vibrant"`, or a tuned vibrant grade
 `{ exposure, contrast, saturation, highlights }`; it is replaced as a whole.
 

package/dist/catalog.d.ts

@@ -1,3 +1,6 @@
+/** Shape of an alpha fade inside its zone; the same curves as `logScale`. */
+export declare type AlphaFadeCurve = "linear" | "log" | "exp";
+
 /**
  * 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
@@ -155,6 +158,8 @@ export declare const LAYER_STYLE_DEFAULTS: Readonly<LayerStyle>;
 export declare interface LayerStyle {
     /** Palette id; undefined lets the engine pick its own. */
     palette?: string;
+    /** Run the palette from its last color to its first, for raster and particles. */
+    reversePalette: boolean;
     renderMode: StyleRenderMode;
     particles: ParticleStyle;
     raster: RasterStyle;
@@ -163,6 +168,7 @@ export declare interface LayerStyle {
 /** A partial style: any key left out takes the value below it. */
 export declare interface LayerStyleInput {
     palette?: string;
+    reversePalette?: boolean;
     renderMode?: StyleRenderMode;
     particles?: ParticleStyleInput;
     raster?: Partial<RasterStyle>;
@@ -176,6 +182,14 @@ export declare type LocalizedText = Record<string, string>;
  */
 export declare function mergeStyles(...inputs: (LayerStyleInput | undefined)[]): LayerStyleInput;
 
+/**
+ * `input` with legacy palettes rewritten, so old catalogs, share links and
+ * story views keep their look. Keys the input sets itself win.
+ */
+export declare function migrateLegacyStyle(input: LayerStyleInput): LayerStyleInput;
+
+export declare function migrateLegacyStyle(input: LayerStyleInput | undefined): LayerStyleInput | undefined;
+
 /**
  * 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]`.
@@ -241,6 +255,17 @@ export declare interface RasterStyle {
     vibrance: number;
     /** Fixed physical-value domain; null follows the data. */
     colorDomain: [number, number] | null;
+    /**
+     * Fraction of the color range, from its low end, over which colors fade in
+     * from transparent, [0, 1]: a field that is mostly zero (fires, heat
+     * stress) shows only where something happens. Values below the domain are
+     * transparent too.
+     */
+    alphaFadeLow: number;
+    /** Fraction of the color range, from its high end, fading out, [0, 1]. */
+    alphaFadeHigh: number;
+    /** Shape of both fades: "log" rises fast, "exp" stays faint longer. */
+    alphaFadeCurve: AlphaFadeCurve;
 }
 
 export declare function requireCatalogEntry(id: string, data?: Catalog): CatalogEntry;
@@ -284,11 +309,6 @@ export declare interface StyledEntry {
 /** `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 { }