@fxi/zartigl 0.9.2 → 0.10.0

package/dist/engine.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Transparent ends of a ramp, as fractions of the ramp from each end: `low`
+ * fades the lowest values in from transparent, `high` fades the highest out.
+ */
+export declare interface AlphaFade {
+    low?: number;
+    high?: number;
+    curve?: AlphaFadeCurve;
+}
+
+/** Alpha factor at ramp position `t` in [0, 1]; the stricter end wins. */
+export declare function alphaFadeAt(t: number, fade: AlphaFade): number;
+
+/** Shape of an alpha fade inside its zone; the same curves as `logScale`. */
+export declare type AlphaFadeCurve = "linear" | "log" | "exp";
+
 /** Throws unless the index was written for this catalog entry and source. */
 export declare function assertGeoVideoIndexIdentity(source: CatalogGeoVideoArchiveSource, index: GeoVideoIndex, entry: CatalogEntry): void;
 
@@ -157,7 +173,10 @@ declare interface CoordArrays {
     longitude: Float32Array;
 }
 
-export declare function createColorRampTexture(gl: WebGL2RenderingContext, ramp?: ColorRampInput): WebGLTexture;
+export declare function createColorRampTexture(gl: WebGL2RenderingContext, ramp?: ColorRampInput, options?: {
+    reverse?: boolean;
+    alphaFade?: AlphaFade;
+}): WebGLTexture;
 
 /** The frame source decoding `manifest`: scalar or vector by its encoding. */
 export declare function createGeoVideoFrameSource(manifest: GeoVideoManifest, options?: {
@@ -527,7 +546,7 @@ export declare interface GeoVideoScalarEncoding {
     codeMax: number;
     valueMin: number;
     valueMax: number;
-    transfer: "linear";
+    transfer: "linear" | "log10-1p9";
     colorSpace: "bt709";
     colorRange: "limited" | "full";
 }
@@ -549,9 +568,11 @@ export declare class GeoVideoScalarSource extends GeoVideoFrameSource<GeoVideoSc
 }
 
 /** Uniforms of GEOVIDEO_SCALAR_GLSL for a scalar-luma encoding. */
-export declare function geoVideoScalarUniforms(encoding: Pick<GeoVideoScalarEncoding, "codeMin" | "codeMax" | "valueMin" | "valueMax">): {
+export declare function geoVideoScalarUniforms(encoding: Pick<GeoVideoScalarEncoding, "codeMin" | "codeMax" | "valueMin" | "valueMax"> & Partial<Pick<GeoVideoScalarEncoding, "transfer">>): {
     codeRange: [number, number];
     valueRange: [number, number];
+    /** `u_scalar_transfer`: 0 linear, 1 "log10-1p9". */
+    transfer: number;
 };
 
 declare interface GeoVideoSnapshotLoopTimeline {
@@ -624,7 +645,13 @@ export declare class GeoVideoVectorSource extends GeoVideoFrameSource<GeoVideoVe
     protected capture(video: HTMLVideoElement, rows: number, mask: Uint8Array): Promise<GeoVideoVectorFrame | null>;
 }
 
-export declare function getPalettes(): PaletteMeta[];
+/**
+ * Palettes to offer, without deprecated ones (still resolvable for old
+ * configs) unless `includeDeprecated`.
+ */
+export declare function getPalettes(options?: {
+    includeDeprecated?: boolean;
+}): PaletteMeta[];
 
 /** Color grade of a style `particles.grade`; an object tunes the vibrant one. */
 export declare function gradeToColorGrade(grade: ParticleGrade | undefined): ColorGrade;
@@ -649,6 +676,7 @@ export declare const isHexColor: (value: unknown) => value is string;
 /** A partial style: any key left out takes the value below it. */
 declare interface LayerStyleInput {
     palette?: string;
+    reversePalette?: boolean;
     renderMode?: StyleRenderMode;
     particles?: ParticleStyleInput;
     raster?: Partial<RasterStyle>;
@@ -705,6 +733,12 @@ export declare interface PaletteMeta {
     colors: string[];
 }
 
+/**
+ * Validate a time range from a JSON config: `{ start?, end? }` as ISO dates
+ * with start before end, or `{ trailing }` as a positive ISO 8601 duration.
+ */
+export declare function parseTimeRange(value: unknown, path: string): TimeRange;
+
 /** Particle trail color grade: a preset, or the vibrant one tuned. */
 declare type ParticleGrade = "off" | "vibrant" | GradeTuning;
 
@@ -736,6 +770,17 @@ 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;
 }
 
 /**
@@ -752,18 +797,43 @@ export declare function resolveBackdrop(input?: Partial<BackdropStyle>): Backdro
  */
 export declare function resolveColorGrade(input?: Partial<ColorGrade>): ColorGrade;
 
+/**
+ * Stops of a ramp, reversed on request, then with `alphaFade` multiplied into
+ * the alpha of its ends. The fade follows positions, not colors: on a reversed
+ * ramp it still fades the low values.
+ */
 export declare function resolveColorRamp(input: ColorRampInput, options?: {
     reverse?: boolean;
+    alphaFade?: AlphaFade;
 }): Record<number, string>;
 
 export declare type ScalarColorDomain = [number, number];
 
+declare type StyleRenderMode = "particles" | "raster" | "raster+particles";
+
+/** `anchor` minus an ISO 8601 duration, calendar months and years in UTC. */
+export declare function subtractIsoDuration(anchor: number, duration: string): number;
+
 /**
- * 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.
+ * Time windows shared by zartigl and the renderers built on its engine: a
+ * fixed `start`/`end`, either side open, or the `trailing` ISO 8601 duration
+ * before the latest available time.
  */
-declare type StyleRenderMode = "particles" | "raster" | "raster+particles";
+export declare type TimeRange = {
+    start?: Date | string | number;
+    end?: Date | string | number;
+    trailing?: never;
+} | {
+    trailing: string;
+    start?: never;
+    end?: never;
+};
+
+/**
+ * Bounds of `range` inside the available `[min, max]`, epoch ms: open sides
+ * take the available ones, `trailing` counts back from `max`.
+ */
+export declare function timeRangeBounds(range: TimeRange, [sourceMin, sourceMax]: readonly [number, number]): [number, number];
 
 /**
  * Camera-aware per-frame fade opacity: eases toward a short retention while

package/dist/engine.js

@@ -1,6 +1,6 @@
-import { F as i, H as u, I as m, G as v, T as g, J as x, b as f, K as _, c as p, L as V, M as G, l as C, y as S, D as b, N as O, O as R, n as L, t as A, z as h, A as y, C as F, m as I, B as T, P as k, Q as D, R as E, p as B, S as w, E as M, v as N } from "./geovideo-index-CzQo6UIG.js";
-import { B as z, C as H, e as K, b as U, d as J, c as Q, g as j, i as q, a as W, r as X } from "./backdrop-DctkJ45Q.js";
-var e = `vec3 applyVibrance(vec3 c, float v) {
+import { I as i, J as u, K as m, G as v, T as g, L as f, M as x, b as _, N as p, c as V, O as G, P as C, l as S, z as b, E as R, Q as O, R as A, n as L, t as h, A as F, B as I, D as T, m as y, C as D, S as k, U as B, V as E, W as w, p as M, X as N, F as P, Y as z, H as U, v as H } from "./geovideo-index-BJjE_fgO.js";
+import { B as J, C as Q, e as W, b as X, d as Y, c as j, g as q, i as Z, a as $, r as aa } from "./backdrop-DctkJ45Q.js";
+var a = `vec3 applyVibrance(vec3 c, float v) {
     float mx = max(c.r, max(c.g, c.b));
     float mn = min(c.r, min(c.g, c.b));
     float boost = v * (1.0 - (mx - mn));
@@ -21,12 +21,18 @@ vec3 gradeColor(vec3 c, vec4 g) {
     
     c = mix(c, c * c * (3.0 - 2.0 * c), g.y);
     return clamp(applyVibrance(c, g.z), 0.0, 1.0);
-}`, a = `uniform vec2 u_code_range;   
-uniform vec2 u_value_range;  
+}`, e = `uniform vec2 u_code_range;       
+uniform vec2 u_value_range;      
+uniform float u_scalar_transfer; 
+
+float geoVideoScalarCode(float r) {
+    return clamp((r - u_code_range.x) / (u_code_range.y - u_code_range.x), 0.0, 1.0);
+}
 
 float geoVideoScalarValue(float r) {
-    float code = clamp((r - u_code_range.x) / (u_code_range.y - u_code_range.x), 0.0, 1.0);
-    return mix(u_value_range.x, u_value_range.y, code);
+    float code = geoVideoScalarCode(r);
+    float t = mix(code, (pow(10.0, code) - 1.0) / 9.0, u_scalar_transfer);
+    return mix(u_value_range.x, u_value_range.y, t);
 }`, o = `uint pcg(uint v) {
     uint state = v * 747796405u + 2891336453u;
     uint word = ((state >> ((state >> 28u) + 4u)) ^ state) * 277803737u;
@@ -42,12 +48,12 @@ float random(uvec3 v) {
     float luma = dot(c, vec3(0.299, 0.587, 0.114));
     return mix(vec3(luma), c, 1.0 + boost);
 }`;
-const n = r, c = e, t = o, s = a;
+const n = r, c = a, t = o, s = e;
 export {
-  z as BACKDROP_OFF,
+  J as BACKDROP_OFF,
   c as COLOR_GRADE_GLSL,
-  H as COLOR_GRADE_OFF,
-  K as COLOR_GRADE_VIBRANT,
+  Q as COLOR_GRADE_OFF,
+  W as COLOR_GRADE_VIBRANT,
   s as GEOVIDEO_SCALAR_GLSL,
   i as GeoVideoArchiveSource,
   u as GeoVideoFrameSource,
@@ -56,36 +62,40 @@ export {
   t as RANDOM_GLSL,
   g as TrailFade,
   n as VIBRANCE_GLSL,
+  f as alphaFadeAt,
   x as assertGeoVideoIndexIdentity,
-  U as backdropVec4,
-  J as colorGradeToGrade,
-  Q as colorGradeVec4,
-  f as createColorRampTexture,
-  _ as createGeoVideoFrameSource,
-  p as createProgram,
-  V as createShader,
-  G as fadeToFrames,
-  C as fadeToOpacity,
-  S as formatUnit,
-  b as geoVideoChunkSources,
+  X as backdropVec4,
+  Y as colorGradeToGrade,
+  j as colorGradeVec4,
+  _ as createColorRampTexture,
+  p as createGeoVideoFrameSource,
+  V as createProgram,
+  G as createShader,
+  C as fadeToFrames,
+  S as fadeToOpacity,
+  b as formatUnit,
+  R as geoVideoChunkSources,
   O as geoVideoGrid,
-  R as geoVideoIndexChunks,
+  A as geoVideoIndexChunks,
   L as geoVideoScalarUniforms,
-  A as geoVideoTimelineValues,
-  h as getPalettes,
-  j as gradeToColorGrade,
-  y as isGeoVideoArchiveSource,
-  q as isHexColor,
-  F as loadGeoVideoIndex,
-  I as loadGeoVideoManifest,
-  T as nextChunk,
+  h as geoVideoTimelineValues,
+  F as getPalettes,
+  q as gradeToColorGrade,
+  I as isGeoVideoArchiveSource,
+  Z as isHexColor,
+  T as loadGeoVideoIndex,
+  y as loadGeoVideoManifest,
+  D as nextChunk,
   k as nextChunkSpan,
-  D as pairChunk,
+  B as pairChunk,
   E as pairChunkSpan,
-  W as resolveBackdrop,
-  X as resolveColorGrade,
-  B as resolveColorRamp,
-  w as validateGeoVideoIndex,
-  M as validateGeoVideoManifest,
-  N as validateScalarColorDomain
+  w as parseTimeRange,
+  $ as resolveBackdrop,
+  aa as resolveColorGrade,
+  M as resolveColorRamp,
+  N as subtractIsoDuration,
+  P as timeRangeBounds,
+  z as validateGeoVideoIndex,
+  U as validateGeoVideoManifest,
+  H as validateScalarColorDomain
 };