@deck.gl-community/infovis-layers 9.3.2 → 9.3.7

package/src/layers/animation-layer/animation.ts

@@ -0,0 +1,328 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** A simple animation engine for deck.gl layers. */
+import {type Layer} from '@deck.gl/core';
+
+/** One timed set of layer prop changes in an animation. */
+export type AnimationFrame<LayerT extends Layer> = {
+  /** Child layer prop values to transition to. */
+  props: Partial<LayerT['props']>;
+  /** Duration in milliseconds used to execute the transition. */
+  duration: number;
+  /** Pause in milliseconds before this frame starts. @defaultValue 0 */
+  delay?: number;
+  /** Easing function that defines the transition curve. @defaultValue linear */
+  easing?: (t: number) => number;
+};
+
+/** A schedulable group of animation frames. */
+export type AnimationFramesGroup<LayerT extends Layer> = {
+  /**
+   * How to schedule the child frames.
+   * `sequence`: each frame starts after the previous frame ends.
+   * `concurrence`: all frames start together.
+   * `stagger`: frames start one-by-one at a fixed interval.
+   */
+  type: 'sequence' | 'concurrence' | 'stagger';
+  /**
+   * Optional delay in milliseconds.
+   * In `sequence` mode, delay refers to the wait after a step ends and before starting the next step.
+   * In `concurrence` mode, delay refers to the wait before starting all steps together.
+   * In `stagger` mode, delay refers to the interval between starting steps
+   */
+  delay?: number;
+
+  /** Frames or nested frame groups scheduled by this group. */
+  frames: (AnimationFramesGroup<LayerT> | AnimationFrame<LayerT>)[];
+};
+
+/** Repeat and schedule options used to resolve an animation timeline. */
+export type AnimationExtensionOptions<LayerT extends Layer> = {
+  /** Frames scheduled by the animation. */
+  frames: AnimationFramesGroup<LayerT>;
+  /** Number of additional animation iterations after the first pass. @defaultValue 0 */
+  repeat?: number;
+  /** Whether repeated frames restart or alternate in reverse. @defaultValue 'loop' */
+  repeatType?: 'loop' | 'reverse';
+  /** Delay in milliseconds before each repeated iteration. @defaultValue 0 */
+  repeatDelay?: number;
+};
+
+type ResolvedAnimationFrame<LayerT extends Layer> = {
+  /** Assigned at start time */
+  from: Partial<LayerT['props']> | undefined;
+  /** Provided by user */
+  to: Partial<LayerT['props']>;
+  /** Calculated start time of this frame if the whole animation starts at 0 */
+  start: number;
+  /** Calculated end time of this frame if the whole animation starts at 0 */
+  end: number;
+  /** Easing function */
+  easing: (t: number) => number;
+};
+
+/** Runtime state for one resolved layer animation. */
+export type AnimationState<LayerT extends Layer> = {
+  /** Timeline timestamp at which the current iteration started. */
+  start: number;
+  /** Timeline timestamp at which the current iteration ends. */
+  end: number;
+  /** Whether the end state has not yet been fully committed. */
+  inProgress: boolean;
+  /** Number of completed animation iterations. */
+  iterations: number;
+  /** Resolved frames executed during the current iteration. */
+  frames: ResolvedAnimationFrame<LayerT>[];
+};
+
+const LINEAR_EASING = (t: number) => t;
+
+type ResolvedFramesResult<LayerT extends Layer> = {
+  frames: ResolvedAnimationFrame<LayerT>[];
+  duration: number;
+};
+
+function resolveFramesGroup<LayerT extends Layer = Layer>(
+  group: AnimationFramesGroup<LayerT> | AnimationFrame<LayerT>,
+  baseStart: number
+): ResolvedFramesResult<LayerT> {
+  if ('props' in group) {
+    const delay = group.delay ?? 0;
+    const start = baseStart + delay;
+    const end = start + group.duration;
+    return {
+      frames: [
+        {
+          from: undefined,
+          to: group.props,
+          start,
+          end,
+          easing: group.easing ?? LINEAR_EASING
+        }
+      ],
+      duration: delay + group.duration
+    };
+  }
+
+  const delay = group.delay ?? 0;
+  const frames: ResolvedAnimationFrame<LayerT>[] = [];
+
+  if (group.type === 'sequence') {
+    let current = baseStart;
+    for (let i = 0; i < group.frames.length; i += 1) {
+      const child = group.frames[i]!;
+      const childResult = resolveFramesGroup(child, current);
+      frames.push(...childResult.frames);
+      current += childResult.duration;
+      if (i < group.frames.length - 1) current += delay;
+    }
+    return {frames, duration: Math.max(0, current - baseStart)};
+  }
+
+  if (group.type === 'concurrence') {
+    const start = baseStart + delay;
+    let maxDuration = 0;
+    for (const child of group.frames) {
+      const childResult = resolveFramesGroup(child, start);
+      frames.push(...childResult.frames);
+      if (childResult.duration > maxDuration) maxDuration = childResult.duration;
+    }
+    return {frames, duration: delay + maxDuration};
+  }
+
+  let maxEnd = baseStart;
+  for (let i = 0; i < group.frames.length; i += 1) {
+    const child = group.frames[i]!;
+    const childResult = resolveFramesGroup(child, baseStart + i * delay);
+    frames.push(...childResult.frames);
+    const childEnd = baseStart + i * delay + childResult.duration;
+    if (childEnd > maxEnd) maxEnd = childEnd;
+  }
+
+  frames.sort((f1, f2) => f1.end - f2.end);
+
+  return {frames, duration: Math.max(0, maxEnd - baseStart)};
+}
+
+function getFramesDuration<LayerT extends Layer = Layer>(
+  frames: ResolvedAnimationFrame<LayerT>[]
+): number {
+  let maxEnd = 0;
+  for (const frame of frames) {
+    if (frame.end > maxEnd) maxEnd = frame.end;
+  }
+  return maxEnd;
+}
+
+function reverseResolvedFrames<LayerT extends Layer = Layer>(
+  frames: ResolvedAnimationFrame<LayerT>[]
+): ResolvedAnimationFrame<LayerT>[] {
+  const duration = getFramesDuration(frames);
+  const reversed: ResolvedAnimationFrame<LayerT>[] = [];
+  for (let i = frames.length - 1; i >= 0; i -= 1) {
+    const frame = frames[i]!;
+    reversed.push({
+      from: undefined,
+      to: frame.from ?? frame.to,
+      start: duration - frame.end,
+      end: duration - frame.start,
+      easing: frame.easing
+    });
+  }
+  return reversed;
+}
+
+/**
+ * Resolves the animation iteration that should be active at a timeline timestamp.
+ * @param time - Current timeline timestamp in milliseconds.
+ * @param opts - Animation frame and repeat configuration.
+ * @param prevState - Previous animation state, when one has already been resolved.
+ * @returns The current or next resolved animation state.
+ */
+export function resolveAnimationFrames<LayerT extends Layer = Layer>(
+  time: number,
+  opts: AnimationExtensionOptions<LayerT>,
+  prevState?: AnimationState<LayerT>
+): AnimationState<LayerT> {
+  const {frames, repeat = 0, repeatType = 'loop', repeatDelay = 0} = opts;
+  if (!prevState) {
+    const resolved = resolveFramesGroup(frames, 0);
+    return {
+      start: time,
+      end: time + resolved.duration,
+      inProgress: true,
+      iterations: 0,
+      frames: resolved.frames
+    };
+  }
+
+  const state = prevState;
+  if (time < state.end) {
+    return state;
+  }
+
+  const iterationEnd = state.end;
+  const iterations = state.iterations + 1;
+  if (iterations > repeat) {
+    return state;
+  }
+  const start = iterationEnd + repeatDelay;
+  if (repeatType === 'reverse' && iterations % 2 === 1) {
+    const duration = state.end - state.start;
+    return {
+      start,
+      end: start + duration,
+      iterations,
+      frames: reverseResolvedFrames(state.frames),
+      inProgress: true
+    };
+  } else {
+    const resolved = resolveFramesGroup(frames, 0);
+    return {
+      start,
+      end: start + resolved.duration,
+      inProgress: true,
+      iterations,
+      frames: resolved.frames
+    };
+  }
+}
+
+function interpolateProp<PropT extends number | number[] | string | Function | object>(
+  from: PropT | undefined,
+  to: PropT | undefined,
+  ratio: number
+): PropT | undefined {
+  if (from === undefined || to === undefined) return to;
+  if (typeof to === 'string' || typeof to === 'function') return to;
+  if (typeof to === 'number' && typeof from === 'number') {
+    return (from + (to - from) * ratio) as PropT;
+  }
+  if (Array.isArray(to) && Array.isArray(from)) {
+    const len = to.length;
+    const out = new Array(len);
+    for (let i = 0; i < len; i += 1) {
+      const toValue = to[i];
+      const fromValue = from[i];
+      out[i] =
+        typeof toValue === 'number' && typeof fromValue === 'number'
+          ? fromValue + (toValue - fromValue) * ratio
+          : toValue;
+    }
+    return out as PropT;
+  }
+  return to;
+}
+
+/**
+ * Resolves animated child layer props for a point inside one animation iteration.
+ * @param layer - Base child layer whose props provide the interpolation starting values.
+ * @param frames - Resolved frames for the active animation iteration.
+ * @param timeSinceStart - Milliseconds elapsed since the iteration started.
+ * @returns Child layer props that should be applied at the requested time.
+ */
+export function resolveProps<LayerT extends Layer = Layer>(
+  layer: LayerT,
+  frames: ResolvedAnimationFrame<LayerT>[],
+  timeSinceStart: number
+): Partial<LayerT['props']> {
+  if (timeSinceStart < 0 || frames.length === 0) return {} as LayerT['props'];
+
+  const baseProps = layer.props as LayerT['props'];
+  const nextProps: Partial<LayerT['props']> = {};
+  let transitions = baseProps.transitions ? {...baseProps.transitions} : undefined;
+  const updateTriggers = {...baseProps.updateTriggers};
+
+  const getPropValue = (key: keyof LayerT['props']) =>
+    Object.prototype.hasOwnProperty.call(nextProps, key) ? nextProps[key] : baseProps[key];
+
+  for (const frame of frames) {
+    if (timeSinceStart < frame.start) continue;
+
+    const duration = frame.end - frame.start;
+    if (duration <= 0) {
+      Object.assign(nextProps, frame.to);
+      continue;
+    }
+
+    if (frame.from === undefined) {
+      const from: Partial<LayerT['props']> = {};
+      for (const key of Object.keys(frame.to) as (keyof LayerT['props'])[]) {
+        from[key] = getPropValue(key);
+      }
+      frame.from = from;
+    }
+
+    if (timeSinceStart >= frame.end) {
+      Object.assign(nextProps, frame.to);
+      continue;
+    }
+
+    const t = frame.easing((timeSinceStart - frame.start) / duration);
+    for (const key of Object.keys(frame.to) as (keyof LayerT['props'])[]) {
+      const toValue = frame.to[key];
+      const fromValue = frame.from[key];
+      if (
+        String(key).startsWith('get') &&
+        (typeof fromValue === 'function' || typeof toValue === 'function')
+      ) {
+        nextProps[key] = toValue as any;
+        updateTriggers[key as string] = {...updateTriggers[key as string], animation: toValue};
+        transitions ??= {};
+        transitions[key as string] = {
+          duration: frame.end - frame.start,
+          easing: frame.easing
+        };
+      } else {
+        const value = interpolateProp(fromValue as any, toValue, t);
+        if (value !== undefined) {
+          nextProps[key] = value;
+        }
+      }
+    }
+  }
+
+  return nextProps;
+}

package/src/layers/block-layer/block-layer-fragment.glsl.ts

@@ -0,0 +1,41 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export default `\
+#version 300 es
+#define SHADER_NAME block-layer-fragment-shader
+
+precision highp float;
+
+in vec2 unitPosition;
+flat in vec4 vFillColor;
+flat in vec4 vLineColor;
+flat in float lineWidth;
+flat in vec2 size;
+
+out vec4 fragColor;
+
+void main(void) {
+  if (lineWidth > 0.0) {
+    vec2 relPosition = unitPosition * size;
+    float distToBorder =
+      min(
+        min(
+          min(relPosition.x, relPosition.y),
+          size.x - relPosition.x
+        ),
+        size.y - relPosition.y
+      );
+    if (distToBorder <= lineWidth) {
+      fragColor = vLineColor;
+    } else {
+      fragColor = vFillColor;
+    }
+  } else {
+    fragColor = vFillColor;
+  }
+
+  DECKGL_FILTER_COLOR(fragColor, geometry);
+}
+`;

package/src/layers/block-layer/block-layer-uniforms.ts

@@ -0,0 +1,43 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+const glslUniformBlock = `\
+uniform blockUniforms {
+  highp int sizeUnits;
+  highp float widthMinPixels;
+  highp float heightMinPixels;
+  highp float sizeMaxPixels;
+  highp int lineWidthUnits;
+} block;
+`;
+
+/** Shader uniform values used by {@link BlockLayer}. */
+export type BlockProps = {
+  /** Numeric deck.gl unit for block width and height. */
+  sizeUnits: number;
+  /** Minimum rendered block width in pixels. */
+  widthMinPixels: number;
+  /** Minimum rendered block height in pixels. */
+  heightMinPixels: number;
+  /** Maximum rendered block width or height in pixels. */
+  sizeMaxPixels: number;
+  /** Numeric deck.gl unit for block outline width. */
+  lineWidthUnits: number;
+};
+
+/** Shader module that defines uniforms consumed by {@link BlockLayer}. */
+export const blockUniforms = {
+  name: 'block',
+  vs: glslUniformBlock,
+  fs: glslUniformBlock,
+  uniformTypes: {
+    sizeUnits: 'i32',
+    widthMinPixels: 'f32',
+    heightMinPixels: 'f32',
+    sizeMaxPixels: 'f32',
+    lineWidthUnits: 'i32'
+  }
+} as const satisfies ShaderModule<BlockProps>;

package/src/layers/block-layer/block-layer-vertex.glsl.ts

@@ -0,0 +1,67 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export default `\
+#version 300 es
+#define SHADER_NAME block-layer-vertex-shader
+
+in vec3 positions;
+in vec3 instancePositions;
+in vec3 instancePositions64Low;
+in vec2 instanceSizes;
+in float instanceLineWidths;
+in vec4 instanceFillColors;
+in vec4 instanceLineColors;
+in vec3 instancePickingColors;
+
+out vec2 unitPosition;
+flat out vec4 vFillColor;
+flat out vec4 vLineColor;
+flat out float lineWidth;
+flat out vec2 size;
+
+// This needs to be added back to the project module
+vec2 project_size_to_pixel(vec2 size, int unit) {
+  if (unit == UNIT_PIXELS) return size;
+  if (unit == UNIT_COMMON && project.projectionMode != PROJECTION_MODE_IDENTITY) {
+    return size * project.scale;
+  }
+  return project_size(size) * project.scale;
+}
+
+float clamp_signed_size(float size, float minPixels, float maxPixels) {
+  float clampedMagnitude = clamp(abs(size), minPixels, maxPixels);
+  if (size < 0.0) {
+    return -clampedMagnitude;
+  }
+  return clampedMagnitude;
+}
+
+void main(void) {
+  geometry.worldPosition = instancePositions;
+  geometry.pickingColor = instancePickingColors;
+  geometry.uv = positions.xy;
+
+  vec2 pixelSize = project_size_to_pixel(instanceSizes, block.sizeUnits);
+  pixelSize.x = clamp_signed_size(pixelSize.x, block.widthMinPixels, block.sizeMaxPixels);
+  pixelSize.y = clamp_signed_size(pixelSize.y, block.heightMinPixels, block.sizeMaxPixels);
+  unitPosition = positions.xy;
+  size = pixelSize;
+  lineWidth = project_size_to_pixel(vec2(instanceLineWidths, 0.0), block.lineWidthUnits).x;
+
+  // Find the center of the point and add the current vertex
+  vec3 offset = vec3(unitPosition * project_pixel_size(pixelSize), 0.0);
+  DECKGL_FILTER_SIZE(offset, geometry);
+
+  gl_Position = project_position_to_clipspace(instancePositions, instancePositions64Low, offset, geometry.position);
+  DECKGL_FILTER_GL_POSITION(gl_Position, geometry);
+
+  // Apply opacity to instance color, or return instance picking color
+  vFillColor = vec4(instanceFillColors.rgb, instanceFillColors.a * layer.opacity);
+  DECKGL_FILTER_COLOR(vFillColor, geometry);
+
+  vLineColor = vec4(instanceLineColors.rgb, instanceLineColors.a * layer.opacity);
+  DECKGL_FILTER_COLOR(vLineColor, geometry);
+}
+`;

package/src/layers/block-layer/block-layer.ts

@@ -0,0 +1,199 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  Accessor,
+  AccessorFunction,
+  color,
+  Color,
+  DefaultProps,
+  Layer,
+  LayerDataSource,
+  LayerProps,
+  picking,
+  Position,
+  project32,
+  UNIT,
+  Unit,
+  UpdateParameters
+} from '@deck.gl/core';
+import {Geometry, Model} from '@luma.gl/engine';
+
+import fs from './block-layer-fragment.glsl';
+import {BlockProps, blockUniforms} from './block-layer-uniforms';
+import vs from './block-layer-vertex.glsl';
+
+const DEFAULT_COLOR: [number, number, number, number] = [0, 0, 0, 255];
+
+const defaultProps: DefaultProps<BlockLayerProps> = {
+  sizeUnits: 'meters',
+  widthMinPixels: {type: 'number', min: 0, value: 0},
+  heightMinPixels: {type: 'number', min: 0, value: 0},
+  sizeMaxPixels: {type: 'number', min: 0, value: Number.MAX_SAFE_INTEGER},
+
+  lineWidthUnits: 'pixels',
+
+  getPosition: {type: 'accessor', value: (x: any) => x.position},
+  getSize: {type: 'accessor', value: [10, 10]},
+  getLineWidth: {type: 'accessor', value: 1},
+  getFillColor: {type: 'accessor', value: DEFAULT_COLOR},
+  getLineColor: {type: 'accessor', value: DEFAULT_COLOR}
+};
+
+/** Properties supported by {@link BlockLayer}. */
+export type BlockLayerProps<DataT = unknown> = _BlockLayerProps<DataT> & LayerProps;
+
+/** Properties added by BlockLayer. */
+type _BlockLayerProps<DataT> = {
+  /** Data objects rendered as rectangular blocks. */
+  data: LayerDataSource<DataT>;
+  /**
+   * The units of the block size, one of `'meters'`, `'common'`, and `'pixels'`.
+   * @defaultValue 'meters'
+   */
+  sizeUnits?: Unit;
+
+  /**
+   * The minimum width in pixels. This prop can be used to prevent the block from getting too small when zoomed out.
+   * @defaultValue 0
+   */
+  widthMinPixels?: number;
+  /**
+   * The minimum height in pixels. This prop can be used to prevent the block from getting too small when zoomed out.
+   * @defaultValue 0
+   */
+  heightMinPixels?: number;
+  /**
+   * The maximum width or height in pixels. This prop can be used to prevent the block from getting too big when zoomed in.
+   * @defaultValue Number.MAX_SAFE_INTEGER
+   */
+  sizeMaxPixels?: number;
+
+  /**
+   * The units of the stroke width, one of `'meters'`, `'common'`, and `'pixels'`.
+   * @defaultValue 'pixels'
+   */
+  lineWidthUnits?: Unit;
+
+  /**
+   * The outline width of each object.
+   * @defaultValue 1
+   */
+  getLineWidth?: Accessor<DataT, number>;
+
+  /**
+   * Method called to retrieve the position of each object.
+   * @defaultValue object => object.position
+   */
+  getPosition?: AccessorFunction<DataT, Position>;
+  /** Width and height of each block. @defaultValue [10, 10] */
+  getSize?: Accessor<DataT, [number, number]>;
+  /**
+   * The rgba color is in the format of `[r, g, b, [a]]`
+   * @defaultValue [0, 0, 0, 255]
+   */
+  getLineColor?: Accessor<DataT, Color>;
+  /**
+   * The rgba color is in the format of `[r, g, b, [a]]`
+   * @defaultValue [0, 0, 0, 255]
+   */
+  getFillColor?: Accessor<DataT, Color>;
+};
+
+/** Renders axis-aligned rectangular blocks with fill and outline colors. */
+export class BlockLayer<DataT = any, ExtraPropsT extends {} = {}> extends Layer<
+  ExtraPropsT & Required<_BlockLayerProps<DataT>>
+> {
+  static override layerName = 'BlockLayer';
+  static override defaultProps = defaultProps;
+
+  override state: {
+    model?: Model;
+  } = {};
+
+  override getShaders() {
+    return super.getShaders({
+      vs,
+      fs,
+      modules: [project32, color, picking, blockUniforms]
+    });
+  }
+
+  initializeState() {
+    this.getAttributeManager()!.addInstanced({
+      instancePositions: {
+        size: 3,
+        type: 'float64',
+        fp64: this.use64bitPositions(),
+        transition: true,
+        accessor: 'getPosition'
+      },
+      instanceSizes: {
+        size: 2,
+        transition: true,
+        accessor: 'getSize'
+      },
+      instanceLineWidths: {
+        size: 1,
+        transition: true,
+        accessor: 'getLineWidth'
+      },
+      instanceLineColors: {
+        size: this.props.colorFormat.length,
+        type: 'unorm8',
+        transition: true,
+        accessor: 'getLineColor',
+        defaultValue: DEFAULT_COLOR
+      },
+      instanceFillColors: {
+        size: this.props.colorFormat.length,
+        type: 'unorm8',
+        transition: true,
+        accessor: 'getFillColor',
+        defaultValue: DEFAULT_COLOR
+      }
+    });
+  }
+
+  override updateState(params: UpdateParameters<this>): void {
+    const {changeFlags} = params;
+    super.updateState(params);
+    if (changeFlags.extensionsChanged) {
+      this.state.model?.destroy();
+      this.state.model = this._getModel();
+      this.getAttributeManager()!.invalidateAll();
+    }
+  }
+
+  override draw() {
+    const {sizeUnits, widthMinPixels, heightMinPixels, sizeMaxPixels, lineWidthUnits} = this.props;
+    const model = this.state.model!;
+    const blockProps: BlockProps = {
+      sizeUnits: UNIT[sizeUnits],
+      widthMinPixels,
+      heightMinPixels,
+      sizeMaxPixels,
+      lineWidthUnits: UNIT[lineWidthUnits]
+    };
+    model.shaderInputs.setProps({block: blockProps});
+    model.draw(this.context.renderPass);
+  }
+
+  protected _getModel(): Model {
+    // a square
+    const positions = [0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0];
+    return new Model(this.context.device, {
+      ...this.getShaders(),
+      id: this.props.id,
+      bufferLayout: this.getAttributeManager()!.getBufferLayouts(),
+      geometry: new Geometry({
+        topology: 'triangle-strip',
+        attributes: {
+          positions: new Float32Array(positions)
+        }
+      }),
+      isInstanced: true
+    });
+  }
+}