@deck.gl-community/timeline-layers 9.2.0-beta.8

package/src/layers/horizon-graph-layer/horizon-graph-layer.ts

@@ -0,0 +1,202 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DefaultProps, LayerProps, Color, LayerContext, UpdateParameters} from '@deck.gl/core';
+import {Layer, project32} from '@deck.gl/core';
+import {Model, Geometry} from '@luma.gl/engine';
+import vs from './horizon-graph-layer.vs';
+import fs from './horizon-graph-layer.fs';
+import {Texture} from '@luma.gl/core';
+import {horizonLayerUniforms} from './horizon-graph-layer-uniforms';
+
+export type _HorizonGraphLayerProps = {
+  data: number[] | Float32Array;
+
+  yAxisScale?: number;
+
+  bands?: number;
+
+  positiveColor?: Color;
+  negativeColor?: Color;
+
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+};
+
+export type HorizonGraphLayerProps = _HorizonGraphLayerProps & LayerProps;
+
+const defaultProps: DefaultProps<HorizonGraphLayerProps> = {
+  yAxisScale: {type: 'number', value: 1000},
+
+  bands: {type: 'number', value: 2},
+
+  positiveColor: {type: 'color', value: [0, 128, 0]},
+  negativeColor: {type: 'color', value: [0, 0, 255]},
+
+  x: {type: 'number', value: 0},
+  y: {type: 'number', value: 0},
+  width: {type: 'number', value: 800},
+  height: {type: 'number', value: 300}
+};
+
+export class HorizonGraphLayer<ExtraProps extends {} = {}> extends Layer<
+  ExtraProps & Required<_HorizonGraphLayerProps>
+> {
+  static layerName = 'HorizonGraphLayer';
+  static defaultProps = defaultProps;
+
+  state: {
+    model?: Model;
+    dataTexture?: Texture;
+    dataTextureSize?: number;
+    dataTextureCount?: number;
+  } = {};
+
+  initializeState() {
+    this.state = {};
+  }
+
+  getShaders() {
+    return super.getShaders({
+      vs,
+      fs,
+      modules: [project32, horizonLayerUniforms]
+    });
+  }
+
+  _createDataTexture(seriesData: Float32Array | number[]): {
+    dataTexture: Texture;
+    dataTextureSize: number;
+    dataTextureCount: number;
+  } {
+    const _data = seriesData instanceof Float32Array ? seriesData : new Float32Array(seriesData);
+
+    const {device} = this.context;
+    const count = _data.length;
+
+    let dataTextureSize = 32;
+    while (count > dataTextureSize * dataTextureSize) {
+      dataTextureSize *= 2;
+    }
+
+    // TODO: use the right way to only submit the minimum amount of data
+    const data = new Float32Array(dataTextureSize * dataTextureSize);
+    data.set(_data, 0);
+
+    return {
+      dataTexture: device.createTexture({
+        data,
+        format: 'r32float',
+        dimension: '2d',
+        width: dataTextureSize,
+        height: dataTextureSize,
+        sampler: {
+          minFilter: 'nearest',
+          magFilter: 'nearest',
+          addressModeU: 'clamp-to-edge',
+          addressModeV: 'clamp-to-edge'
+        }
+      }),
+      dataTextureSize,
+      dataTextureCount: count
+    };
+  }
+
+  _createModel() {
+    const {x, y, width, height} = this.props;
+
+    // Create a rectangle using triangle strip (4 vertices)
+    // Order: bottom-left, bottom-right, top-left, top-right
+    const positions = [
+      x,
+      y,
+      0.0,
+
+      x + width,
+      y,
+      0.0,
+
+      x,
+      y + height,
+      0.0,
+
+      x + width,
+      y + height,
+      0.0
+    ];
+
+    const uv = [0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0];
+
+    const geometry = new Geometry({
+      topology: 'triangle-strip',
+      attributes: {
+        positions: {value: new Float32Array(positions), size: 3},
+        uv: {value: new Float32Array(uv), size: 2}
+      }
+    });
+
+    return new Model(this.context.device, {
+      ...this.getShaders(),
+      geometry,
+      bufferLayout: this.getAttributeManager().getBufferLayouts()
+    });
+  }
+
+  updateState(params: UpdateParameters<Layer<ExtraProps & Required<_HorizonGraphLayerProps>>>) {
+    super.updateState(params);
+
+    const {changeFlags} = params;
+
+    if (changeFlags.dataChanged) {
+      this.state.dataTexture?.destroy();
+      this.setState(this._createDataTexture(this.props.data));
+    }
+
+    if (changeFlags.extensionsChanged || changeFlags.propsChanged) {
+      this.state.model?.destroy();
+      this.setState({model: this._createModel()});
+    }
+  }
+
+  draw() {
+    const {model, dataTexture} = this.state;
+
+    if (!model) {
+      this.setState({model: this._createModel()});
+      return;
+    }
+
+    if (!dataTexture) {
+      this.setState(this._createDataTexture(this.props.data));
+      return;
+    }
+
+    const {bands, yAxisScale, positiveColor, negativeColor} = this.props;
+
+    model.shaderInputs.setProps({
+      horizonLayer: {
+        dataTexture: this.state.dataTexture,
+        dataTextureSize: this.state.dataTextureSize,
+        dataTextureSizeInv: 1.0 / this.state.dataTextureSize,
+        dataTextureCount: this.state.dataTextureCount,
+
+        bands,
+        bandsInv: 1.0 / bands,
+        yAxisScaleInv: 1.0 / yAxisScale,
+
+        positiveColor: positiveColor.map((c) => c / 255),
+        negativeColor: negativeColor.map((c) => c / 255)
+      }
+    });
+    model.draw(this.context.renderPass);
+  }
+
+  finalizeState(context: LayerContext): void {
+    this.state.model?.destroy();
+    this.state.dataTexture?.destroy();
+    super.finalizeState(context);
+  }
+}

package/src/layers/horizon-graph-layer/horizon-graph-layer.vs.ts

@@ -0,0 +1,24 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export default `#version 300 es
+#define SHADER_NAME horizon-graph-layer-vertex-shader
+
+in vec3 positions;
+in vec2 uv;
+
+out vec2 v_uv;
+
+void main(void) {
+  geometry.worldPosition = positions;
+  
+  vec4 position_commonspace = project_position(vec4(positions.xy, 0.0, 1.0));
+  gl_Position = project_common_position_to_clipspace(position_commonspace);
+  geometry.position = position_commonspace;
+  
+  DECKGL_FILTER_GL_POSITION(gl_Position, geometry);
+  
+  v_uv = uv;
+}
+`;

package/src/layers/horizon-graph-layer/multi-horizon-graph-layer.ts

@@ -0,0 +1,164 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DefaultProps, LayerProps, Color, LayerDataSource, Accessor} from '@deck.gl/core';
+import {CompositeLayer} from '@deck.gl/core';
+import {SolidPolygonLayer} from '@deck.gl/layers';
+import {HorizonGraphLayer} from './horizon-graph-layer';
+
+export type _MultiHorizonGraphLayerProps<DataT> = {
+  data: LayerDataSource<DataT>;
+  getSeries: Accessor<DataT, number[] | Float32Array>;
+  getScale: Accessor<DataT, number>;
+
+  bands?: number;
+
+  positiveColor?: Color;
+  negativeColor?: Color;
+
+  dividerColor?: Color;
+  dividerWidth?: number;
+
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+};
+
+export type MultiHorizonGraphLayerProps<DataT = unknown> = _MultiHorizonGraphLayerProps<DataT> &
+  LayerProps;
+
+const defaultProps: DefaultProps<MultiHorizonGraphLayerProps> = {
+  getSeries: {type: 'accessor', value: (series: any) => series.values},
+  getScale: {type: 'accessor', value: (series: any) => series.scale},
+
+  bands: {type: 'number', value: 2},
+
+  positiveColor: {type: 'color', value: [0, 128, 0]},
+  negativeColor: {type: 'color', value: [0, 0, 255]},
+
+  dividerColor: {type: 'color', value: [0, 0, 0]},
+  dividerWidth: {type: 'number', value: 2},
+
+  x: {type: 'number', value: 0},
+  y: {type: 'number', value: 0},
+  width: {type: 'number', value: 800},
+  height: {type: 'number', value: 300}
+};
+
+export class MultiHorizonGraphLayer<DataT = any, ExtraProps extends {} = {}> extends CompositeLayer<
+  ExtraProps & Required<_MultiHorizonGraphLayerProps<DataT>>
+> {
+  static layerName = 'MultiHorizonGraphLayer';
+  static defaultProps = defaultProps;
+
+  renderLayers() {
+    const {
+      data,
+      getSeries,
+      getScale,
+      bands,
+      positiveColor,
+      negativeColor,
+      dividerColor,
+      dividerWidth,
+      x,
+      y,
+      width,
+      height
+    } = this.props;
+
+    const seriesCount = (data as any).length;
+
+    if (!seriesCount) {
+      return [];
+    }
+
+    // Calculate layout dimensions
+    const totalDividerSpace = dividerWidth * (seriesCount + 1);
+    const availableHeight = height - totalDividerSpace;
+    const seriesHeight = availableHeight / seriesCount;
+
+    const layers = [];
+
+    // Create divider rectangles
+    if (dividerWidth > 0) {
+      const dividerData = [];
+
+      // Top divider
+      dividerData.push({
+        polygon: [
+          [x, y],
+          [x + width, y],
+          [x + width, y + dividerWidth],
+          [x, y + dividerWidth]
+        ]
+      });
+
+      // Dividers between series
+      for (let i = 0; i < seriesCount - 1; i++) {
+        const dividerY = y + dividerWidth + (i + 1) * seriesHeight + i * dividerWidth;
+        dividerData.push({
+          polygon: [
+            [x, dividerY],
+            [x + width, dividerY],
+            [x + width, dividerY + dividerWidth],
+            [x, dividerY + dividerWidth]
+          ]
+        });
+      }
+
+      // Bottom divider
+      const bottomDividerY = y + height - dividerWidth;
+      dividerData.push({
+        polygon: [
+          [x, bottomDividerY],
+          [x + width, bottomDividerY],
+          [x + width, y + height],
+          [x, y + height]
+        ]
+      });
+
+      layers.push(
+        new SolidPolygonLayer({
+          id: `${this.props.id}-dividers`,
+          data: dividerData,
+          getPolygon: (d: any) => d.polygon,
+          getFillColor: dividerColor,
+          pickable: false
+        })
+      );
+    }
+
+    // Create horizon graph layers for each series
+    (data as any).forEach((series, index) => {
+      const seriesData = (getSeries as any)(series);
+
+      if (!seriesData || seriesData.length === 0) {
+        return;
+      }
+
+      const seriesY = y + dividerWidth + index * (seriesHeight + dividerWidth);
+
+      const yAxisScale = (getScale as any)(series);
+
+      layers.push(
+        new HorizonGraphLayer({
+          id: `${this.props.id}-series-${index}`,
+          data: seriesData,
+          yAxisScale,
+          bands,
+          positiveColor,
+          negativeColor,
+          x,
+          y: seriesY,
+          width,
+          height: seriesHeight
+        })
+      );
+    });
+
+    return layers;
+  }
+}

package/src/layers/time-axis-layer.ts

@@ -0,0 +1,102 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {CompositeLayer, type CompositeLayerProps, type UpdateParameters} from '@deck.gl/core';
+import {LineLayer, TextLayer} from '@deck.gl/layers';
+
+import {formatTimeMs} from '../utils/format-utils';
+import {getPrettyTicks, getZoomedRange} from '../utils/tick-utils';
+
+export type TimeAxisLayerProps = CompositeLayerProps & {
+  unit: 'timestamp' | 'milliseconds';
+  /** Start time in milliseconds since epoch */
+  startTimeMs: number;
+  /** End time in milliseconds since epoch */
+  endTimeMs: number;
+  /** Optional: Number of tick marks (default: 5) */
+  tickCount?: number;
+  /** Optional: Y-coordinate for the axis line (default: 0) */
+  y?: number;
+  /** Optional: RGBA color for axis and ticks (default: [0, 0, 0, 255]) */
+  color?: [number, number, number, number];
+  /** Optional: Bounds for the axis line (default: viewport bounds) */
+  bounds?: [number, number, number, number];
+};
+
+export class TimeAxisLayer extends CompositeLayer<TimeAxisLayerProps> {
+  static override layerName = 'TimeAxisLayer';
+  static override defaultProps: Required<Omit<TimeAxisLayerProps, keyof CompositeLayerProps>> = {
+    startTimeMs: 0,
+    endTimeMs: 100,
+    tickCount: 5,
+    y: 0,
+    color: [0, 0, 0, 255],
+    unit: 'timestamp',
+    bounds: undefined!
+  };
+
+  // Called whenever props/data/viewports change
+  override shouldUpdateState(params: UpdateParameters<TimeAxisLayer>): boolean {
+    return params.changeFlags.viewportChanged || super.shouldUpdateState(params);
+  }
+
+  override renderLayers() {
+    const {startTimeMs, endTimeMs, tickCount = 10, y = 0, color = [0, 0, 0, 255]} = this.props;
+
+    let bounds: [number, number, number, number];
+    try {
+      bounds = this.context.viewport.getBounds();
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.log('Error getting bounds from viewport:', error);
+      throw error;
+    }
+    const [startTimeZoomed, endTimeZoomed] = getZoomedRange(startTimeMs, endTimeMs, bounds);
+    // Generate tick positions and labels
+    const ticks = getPrettyTicks(startTimeZoomed, endTimeZoomed, tickCount);
+
+    const tickLines = ticks.map((x) => ({
+      sourcePosition: [x, y - 5],
+      targetPosition: [x, y + 5]
+    }));
+
+    const tickLabels = ticks.map((x) => ({
+      position: [x, y - 10],
+      text:
+        this.props.unit === 'timestamp' ? new Date(x).toLocaleTimeString() : formatTimeMs(x, false)
+    }));
+
+    return [
+      // Axis line
+      new LineLayer({
+        id: 'axis-line',
+        data: [{sourcePosition: [startTimeZoomed, y], targetPosition: [endTimeZoomed, y]}],
+        getSourcePosition: (d) => d.sourcePosition,
+        getTargetPosition: (d) => d.targetPosition,
+        getColor: color,
+        getWidth: 2
+      }),
+      // Tick marks
+      new LineLayer({
+        id: 'tick-marks',
+        data: tickLines,
+        getSourcePosition: (d) => d.sourcePosition,
+        getTargetPosition: (d) => d.targetPosition,
+        getColor: color,
+        getWidth: 1
+      }),
+      // Tick labels
+      new TextLayer({
+        id: 'tick-labels',
+        data: tickLabels,
+        getPosition: (d) => d.position,
+        getText: (d) => d.text,
+        getSize: 12,
+        getColor: color,
+        getTextAnchor: 'middle',
+        getAlignmentBaseline: 'top'
+      })
+    ];
+  }
+}

package/src/layers/vertical-grid-layer.ts

@@ -0,0 +1,69 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {CompositeLayer, type CompositeLayerProps, type UpdateParameters} from '@deck.gl/core';
+import {LineLayer} from '@deck.gl/layers';
+
+import {getPrettyTicks, getZoomedRange} from '../utils/tick-utils';
+
+export type VerticalGridLayerProps = CompositeLayerProps & {
+  /** Start time in milliseconds since epoch */
+  xMin: number;
+  /** End time in milliseconds since epoch */
+  xMax: number;
+  /** Optional: Number of tick marks (default: 5) */
+  tickCount?: number;
+  /** Minimum Y-coordinate for grid lines */
+  yMin?: number;
+  /** Maximum Y-coordinate for grid lines */
+  yMax?: number;
+  /** Optional: Width of the grid lines (default: 1) */
+  width?: number;
+  /** Optional: RGBA color for grid lines (default: [200, 200, 200, 255]) */
+  color?: [number, number, number, number];
+};
+
+export class VerticalGridLayer extends CompositeLayer<VerticalGridLayerProps> {
+  static override layerName = 'VerticalGridLayer';
+  static override defaultProps = {
+    yMin: -1e6,
+    yMax: 1e6,
+    tickCount: 5,
+    width: 1,
+    color: [200, 200, 200, 255]
+  };
+
+  override shouldUpdateState(params: UpdateParameters<VerticalGridLayer>): boolean {
+    return params.changeFlags.viewportChanged || super.shouldUpdateState(params);
+  }
+
+  override renderLayers() {
+    const {xMin, xMax, tickCount = 5, yMin, yMax, color} = this.props;
+
+    // Access the current viewport
+    const viewport = this.context.viewport;
+    const bounds = viewport.getBounds(); // Returns [minX, minY, maxX, maxY]
+
+    // Calculate the visible time range based on the viewport bounds
+    const [startTimeZoomed, endTimeZoomed] = getZoomedRange(xMin, xMax, bounds);
+
+    // Generate tick positions
+    const tickPositions = getPrettyTicks(startTimeZoomed, endTimeZoomed, tickCount);
+
+    // Create vertical grid lines at each tick position
+    const gridLines = tickPositions.map((x) => ({
+      sourcePosition: [x, yMin],
+      targetPosition: [x, yMax]
+    }));
+
+    return new LineLayer({
+      id: `${this.props.id}-lines`,
+      data: gridLines,
+      getSourcePosition: (d) => d.sourcePosition,
+      getTargetPosition: (d) => d.targetPosition,
+      getColor: color,
+      getWidth: 1
+    });
+  }
+}

package/src/utils/format-utils.ts

@@ -0,0 +1,80 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Convert a time in microseconds to a human-readable string
+ * @param us Time in microseconds
+ */
+export function formatTimeMs(timeMs: number, space: boolean = true): string {
+  const sep = space ? ' ' : '';
+  const us = timeMs * 1000;
+  if (us === 0) {
+    return '0s';
+  }
+  if (Math.abs(us) < 1000) {
+    return `${floatToStr(us)}${sep}µs`;
+  }
+  const ms = us / 1000;
+  if (Math.abs(ms) < 1000) {
+    return `${floatToStr(ms)}${sep} ms`;
+  }
+  const s = ms / 1000;
+  if (Math.abs(s) < 60) {
+    return `${floatToStr(s)}${sep} s`;
+  }
+  const m = s / 60;
+  if (Math.abs(m) < 60) {
+    return `${floatToStr(m)}${sep} min`;
+  }
+  const h = m / 60;
+  if (Math.abs(h) < 24) {
+    return `${floatToStr(h)}${sep} hrs`;
+  }
+  const d = h / 24;
+  return `${floatToStr(d)}${sep} days`;
+}
+
+export function formatTimeRangeMs(startMs: number, endMs: number): string {
+  return `${formatTimeMs(startMs)} - ${formatTimeMs(endMs)}`;
+}
+
+/**
+ * Convert a float to a string
+ */
+function floatToStr(f: number, roundDigits: number = 5): string {
+  if (Number.isInteger(f)) {
+    return f.toString();
+  }
+
+  for (let i = 1; i < roundDigits - 1; i++) {
+    const rounded = parseFloat(f.toPrecision(i));
+    if (rounded === f) {
+      return rounded.toPrecision(i);
+    }
+  }
+
+  return f.toPrecision(roundDigits);
+}
+
+// export function formatTimesUs(ticks: number[]): string {
+//   // Try from 0 up to a reasonable max (e.g. 20)
+//   for (let d = 0; d <= 20; d++) {
+//     const seen = new Set<string>();
+//     let allDistinct = true;
+//     for (const t of ticks) {
+//       // Format each tick with d decimals
+//       const str = t.toFixed(d);
+//       if (seen.has(str)) {
+//         allDistinct = false;
+//         break;
+//       }
+//       seen.add(str);
+//     }
+//     if (allDistinct) {
+//       return d;
+//     }
+//   }
+//   // Fallback if somehow not distinct even at 20 decimals
+//   return 20;
+// }

package/src/utils/tick-utils.ts

@@ -0,0 +1,41 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export function getZoomedRange(
+  startTime: number,
+  endTime: number,
+  bounds: [number, number, number, number]
+) {
+  const [startTimeZoomed, , endTimeZoomed] = bounds;
+  // console.log(`startTimeZoomed: ${startTimeZoomed}, endTimeZoomed: ${endTimeZoomed}, tickInterval: ${tickInterval} tickCountZoomed: ${tickCountZoomed}`);
+  return [Math.max(startTime, startTimeZoomed), Math.min(endTime, endTimeZoomed)];
+}
+
+/**
+ * Get nicely rounded tick close to the natural spacing
+ * @param startTime
+ * @param endTime
+ * @param tickCount
+ * @returns
+ */
+export function getPrettyTicks(startTime: number, endTime: number, tickCount: number = 5) {
+  const range = endTime - startTime;
+  const roughStep = range / (tickCount - 1);
+  const exponent = Math.floor(Math.log10(roughStep));
+  const base = Math.pow(10, exponent);
+  const multiples = [1, 2, 5, 10];
+
+  // Find the smallest multiple that is greater than or equal to roughStep
+  const niceStep = multiples.find((m) => base * m >= roughStep) * base;
+
+  const niceStart = Math.ceil(startTime / niceStep) * niceStep;
+  const niceEnd = Math.floor(endTime / niceStep) * niceStep;
+
+  const ticks = [];
+  for (let t = niceStart; t <= niceEnd; t += niceStep) {
+    ticks.push(t);
+  }
+
+  return ticks;
+}