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

package/src/utils/utf8-string-view.ts

@@ -0,0 +1,273 @@
+import type * as arrow from 'apache-arrow';
+
+/** Byte-range view for one UTF-8 encoded string. */
+export type Utf8StringView = {
+  /** Backing UTF-8 bytes. */
+  data: Uint8Array;
+  /** Inclusive byte offset where the string starts. */
+  start: number;
+  /** Exclusive byte offset where the string ends. */
+  end: number;
+};
+
+/** Normalized direct-buffer source for one Arrow Utf8 vector. */
+export type Utf8ColumnSource = {
+  /** Number of logical rows in the column. */
+  readonly rowCount: number;
+  /** Direct-buffer chunks that make up the column. */
+  readonly chunks: readonly Utf8ColumnSourceChunk[];
+  /** Returns whether one logical row is valid. */
+  readonly isValid: (rowIndex: number) => boolean;
+};
+
+/** One direct-buffer chunk in a normalized Arrow Utf8 column source. */
+export type Utf8ColumnSourceChunk = {
+  /** Logical row index where this chunk starts. */
+  readonly rowOffset: number;
+  /** Number of logical rows in this chunk. */
+  readonly rowCount: number;
+  /** Row offset inside the chunk's value-offset buffer. */
+  readonly valueOffsetIndex: number;
+  /** UTF-8 value-offset buffer. */
+  readonly valueOffsets: Int32Array | Uint32Array;
+  /** Contiguous UTF-8 value bytes. */
+  readonly values: Uint8Array;
+};
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * Encodes one JavaScript string into a reusable UTF-8 byte view.
+ */
+export function makeUtf8StringView(value: string): Utf8StringView {
+  const data = textEncoder.encode(value);
+  return {data, start: 0, end: data.length};
+}
+
+/**
+ * Builds a direct-buffer source from an Arrow Utf8 vector without copying UTF-8 bytes.
+ */
+export function getArrowUtf8ColumnSource(
+  utf8Column: arrow.Vector<arrow.Utf8>
+): Utf8ColumnSource | null {
+  const chunks = getArrowUtf8DataChunks(utf8Column);
+  if (!chunks || chunks.length === 0) {
+    return null;
+  }
+
+  const sourceChunks: Utf8ColumnSourceChunk[] = [];
+  let rowOffset = 0;
+  for (const chunk of chunks) {
+    const valueOffsets = chunk.valueOffsets;
+    const values = chunk.values;
+    if (!valueOffsets || !values) {
+      return null;
+    }
+    sourceChunks.push({
+      rowOffset,
+      rowCount: chunk.length,
+      valueOffsetIndex: 0,
+      valueOffsets,
+      values
+    });
+    rowOffset += chunk.length;
+  }
+
+  return {
+    rowCount: utf8Column.length,
+    chunks: sourceChunks,
+    isValid: rowIndex => utf8Column.isValid(rowIndex)
+  };
+}
+
+/**
+ * Fills a reusable UTF-8 view for one Arrow Utf8 row without decoding the row to a string.
+ */
+export function getArrowUtf8RowView(
+  utf8Column: arrow.Vector<arrow.Utf8>,
+  rowIndex: number,
+  out: Utf8StringView
+): boolean {
+  if (!Number.isInteger(rowIndex) || rowIndex < 0 || rowIndex >= utf8Column.length) {
+    return false;
+  }
+  if (!utf8Column.isValid(rowIndex)) {
+    return false;
+  }
+
+  const chunks = getArrowUtf8DataChunks(utf8Column);
+  if (!chunks || chunks.length === 0) {
+    return false;
+  }
+
+  let rowOffset = 0;
+  for (const chunk of chunks) {
+    const chunkEnd = rowOffset + chunk.length;
+    if (rowIndex >= rowOffset && rowIndex < chunkEnd) {
+      const valueOffsets = chunk.valueOffsets;
+      const values = chunk.values;
+      if (!valueOffsets || !values) {
+        return false;
+      }
+      return fillUtf8StringView(valueOffsets, values, rowIndex - rowOffset, out);
+    }
+    rowOffset = chunkEnd;
+  }
+
+  return false;
+}
+
+/**
+ * Fills a reusable UTF-8 view for one normalized Utf8 column row.
+ */
+export function getUtf8ColumnSourceRowView(
+  source: Utf8ColumnSource,
+  rowIndex: number,
+  out: Utf8StringView
+): boolean {
+  if (!Number.isInteger(rowIndex) || rowIndex < 0 || rowIndex >= source.rowCount) {
+    return false;
+  }
+  if (!source.isValid(rowIndex)) {
+    return false;
+  }
+
+  for (const chunk of source.chunks) {
+    const chunkEnd = chunk.rowOffset + chunk.rowCount;
+    if (rowIndex < chunk.rowOffset || rowIndex >= chunkEnd) {
+      continue;
+    }
+
+    return fillUtf8StringView(
+      chunk.valueOffsets,
+      chunk.values,
+      chunk.valueOffsetIndex + rowIndex - chunk.rowOffset,
+      out
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Finds the first row in an Arrow Utf8 column whose bytes equal the requested string view.
+ */
+export function arrowFindUtf8(
+  utf8Column: arrow.Vector<arrow.Utf8>,
+  value: Utf8StringView,
+  startRow = 0
+): number {
+  const normalizedStartRow = Math.max(0, startRow);
+  const fastResult = arrowFindUtf8InDataChunks(utf8Column, value, normalizedStartRow);
+  if (fastResult !== null) {
+    return fastResult;
+  }
+
+  const expected = decodeUtf8StringView(value);
+  for (let rowIndex = normalizedStartRow; rowIndex < utf8Column.length; rowIndex += 1) {
+    if (utf8Column.get(rowIndex) === expected) {
+      return rowIndex;
+    }
+  }
+  return -1;
+}
+
+type ArrowUtf8DataChunk = {
+  /** Number of rows in this Arrow data chunk. */
+  readonly length: number;
+  /** Row offset inside the chunk's value-offset buffer. */
+  readonly offset?: number;
+  /** UTF-8 value-offset buffer. */
+  readonly valueOffsets?: Int32Array | Uint32Array;
+  /** Contiguous UTF-8 value bytes. */
+  readonly values?: Uint8Array;
+};
+
+/**
+ * Scans Arrow's contiguous Utf8 buffers directly when the vector exposes them.
+ */
+function arrowFindUtf8InDataChunks(
+  utf8Column: arrow.Vector<arrow.Utf8>,
+  value: Utf8StringView,
+  startRow: number
+): number | null {
+  const chunks = getArrowUtf8DataChunks(utf8Column);
+  if (!chunks || chunks.length === 0) {
+    return null;
+  }
+
+  let globalRowOffset = 0;
+  for (const chunk of chunks) {
+    const valueOffsets = chunk.valueOffsets;
+    const values = chunk.values;
+    if (!valueOffsets || !values) {
+      return null;
+    }
+
+    const chunkStartRow = Math.max(0, startRow - globalRowOffset);
+    for (let chunkRow = chunkStartRow; chunkRow < chunk.length; chunkRow += 1) {
+      const globalRow = globalRowOffset + chunkRow;
+      if (!utf8Column.isValid(globalRow)) {
+        continue;
+      }
+
+      const start = valueOffsets[chunkRow];
+      const end = valueOffsets[chunkRow + 1];
+      if (start !== undefined && end !== undefined && utf8BytesEqual(values, start, end, value)) {
+        return globalRow;
+      }
+    }
+    globalRowOffset += chunk.length;
+  }
+  return -1;
+}
+
+function getArrowUtf8DataChunks(
+  utf8Column: arrow.Vector<arrow.Utf8>
+): readonly ArrowUtf8DataChunk[] | undefined {
+  return (utf8Column as unknown as {data?: readonly ArrowUtf8DataChunk[]}).data;
+}
+
+function fillUtf8StringView(
+  valueOffsets: Int32Array | Uint32Array,
+  values: Uint8Array,
+  offsetIndex: number,
+  out: Utf8StringView
+): boolean {
+  const start = valueOffsets[offsetIndex];
+  const end = valueOffsets[offsetIndex + 1];
+  if (start === undefined || end === undefined) {
+    return false;
+  }
+
+  out.data = values;
+  out.start = start;
+  out.end = end;
+  return true;
+}
+
+/**
+ * Returns whether a UTF-8 byte range equals one target UTF-8 view.
+ */
+function utf8BytesEqual(
+  data: Uint8Array,
+  start: number,
+  end: number,
+  value: Utf8StringView
+): boolean {
+  const valueLength = value.end - value.start;
+  if (end - start !== valueLength) {
+    return false;
+  }
+  for (let index = 0; index < valueLength; index += 1) {
+    if (data[start + index] !== value.data[value.start + index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function decodeUtf8StringView(value: Utf8StringView): string {
+  return textDecoder.decode(value.data.subarray(value.start, value.end));
+}

package/src/views/bounds-utils.ts

@@ -0,0 +1,88 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Two-dimensional world-space bounds represented by minimum and maximum corners. */
+export type Bounds = [[number, number], [number, number]];
+/** Interleaved X/Y block geometry values accepted by {@link getPaddedBlockBounds}. */
+export type Geometry = ArrayLike<number> | null | undefined;
+
+/** Padding configuration for {@link getPaddedBlockBounds}. */
+export type PaddedBlockBoundsOptions = {
+  /** Padding added as a fraction of geometry width and height. @defaultValue 0.1 */
+  paddingFraction?: number;
+  /** Minimum world-space padding added on each axis. @defaultValue 1 */
+  minimumPadding?: number;
+};
+
+/**
+ * Computes padded bounds for a block geometry represented as an interleaved array of X/Y
+ * coordinates.
+ *
+ * @param geometry - The geometry describing the block perimeter, or `null`/`undefined` when the
+ * block has not been rendered.
+ * @param options - Optional padding configuration. When omitted, a small percentage padding is
+ * applied so that the block does not touch the viewport edges.
+ * @returns The padded bounds for the geometry or `null` if the input does not contain any points.
+ */
+export function getPaddedBlockBounds(
+  geometry: Geometry,
+  options?: PaddedBlockBoundsOptions
+): Bounds | null {
+  const bounds = getGeometryBounds(geometry);
+  if (!bounds) {
+    return null;
+  }
+
+  const paddingFraction = options?.paddingFraction ?? 0.1;
+  const minimumPadding = options?.minimumPadding ?? 1;
+  return padBounds(bounds, paddingFraction, minimumPadding);
+}
+
+function getGeometryBounds(geometry: Geometry): Bounds | null {
+  if (!geometry || geometry.length < 2) {
+    return null;
+  }
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (let index = 0; index < geometry.length; index += 2) {
+    const x = geometry[index]!;
+    const y = geometry[index + 1]!;
+
+    if (x < minX) minX = x;
+    if (y < minY) minY = y;
+    if (x > maxX) maxX = x;
+    if (y > maxY) maxY = y;
+  }
+
+  if (
+    !Number.isFinite(minX) ||
+    !Number.isFinite(minY) ||
+    !Number.isFinite(maxX) ||
+    !Number.isFinite(maxY)
+  ) {
+    return null;
+  }
+
+  return [
+    [minX, minY],
+    [maxX, maxY]
+  ];
+}
+
+function padBounds(bounds: Bounds, paddingFraction: number, minimumPadding: number): Bounds {
+  const [[minX, minY], [maxX, maxY]] = bounds;
+  const width = maxX - minX;
+  const height = maxY - minY;
+  const paddingX = Math.max(width * paddingFraction, minimumPadding);
+  const paddingY = Math.max(height * paddingFraction, minimumPadding);
+
+  return [
+    [minX - paddingX, minY - paddingY],
+    [maxX + paddingX, maxY + paddingY]
+  ];
+}

package/src/views/layer-bounds-filter.ts

@@ -0,0 +1,160 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {FilterContext, Layer, Viewport} from '@deck.gl/core';
+
+/** Deck.gl layer filter callback or `null` when no filter should be applied. */
+export type LayerFilter = ((context: FilterContext) => boolean) | null;
+
+/** Flat two-dimensional bounds represented as `[minX, minY, maxX, maxY]`. */
+export type Bounds = [number, number, number, number];
+
+/** Reason emitted when the viewport bounds filter makes or skips a filter decision. */
+export type LayerBoundsFilterDecision =
+  | {
+      /** Indicates that the layer was filtered because it missed the viewport. */
+      decision: 'filter';
+      /** Deck.gl filter context evaluated by the filter. */
+      context: FilterContext;
+      /** Layer bounds evaluated by the filter. */
+      layerBounds: Bounds;
+      /** Viewport bounds evaluated by the filter. */
+      viewportBounds: Bounds;
+    }
+  | {
+      /** Indicates that the layer did not expose usable bounds. */
+      decision: 'missing-layer-bounds';
+      /** Deck.gl filter context evaluated by the filter. */
+      context: FilterContext;
+    }
+  | {
+      /** Indicates that the viewport did not expose usable bounds. */
+      decision: 'missing-viewport-bounds';
+      /** Deck.gl filter context evaluated by the filter. */
+      context: FilterContext;
+      /** Layer bounds evaluated before viewport bounds were found missing. */
+      layerBounds: Bounds;
+    };
+
+/** Configuration for {@link createViewportBoundsFilter}. */
+export type LayerBoundsFilterOptions = {
+  /** Callback invoked when the filter skips or applies a bounds decision. */
+  onDecision?: (decision: LayerBoundsFilterDecision) => void;
+};
+
+type BoundsCache<Id extends WeakKey> = WeakMap<Id, Bounds | null>;
+
+/**
+ * Combine multiple layer filters.
+ * Returns null when none of the supplied filters are defined.
+ * @param filters - Layer filters to evaluate in order.
+ * @returns One filter that requires every defined filter to pass, or `null`.
+ */
+export function combineLayerFilters(filters: (LayerFilter | undefined | null)[]): LayerFilter {
+  const definedFilters = filters.filter(Boolean) as ((context: FilterContext) => boolean)[];
+  if (!definedFilters.length) {
+    return null;
+  }
+  if (definedFilters.length === 1) {
+    return definedFilters[0]!;
+  }
+  return context => definedFilters.every(filter => filter(context));
+}
+
+/**
+ * Creates a layer filter that compares layer and viewport bounds.
+ * Layers that do not intersect the viewport bounds are filtered out.
+ * @param options - Optional decision callback configuration.
+ * @returns Layer filter that keeps only layers intersecting the current viewport.
+ */
+export function createViewportBoundsFilter(options?: LayerBoundsFilterOptions): LayerFilter {
+  const layerBoundsCache: BoundsCache<Layer> = new WeakMap();
+  const viewportBoundsCache: BoundsCache<Viewport> = new WeakMap();
+
+  return (context: FilterContext) => {
+    const {layer, viewport} = context;
+
+    let layerBounds = layerBoundsCache.get(layer);
+    if (layerBounds === undefined) {
+      layerBounds = getLayerBounds(layer);
+      layerBoundsCache.set(layer, layerBounds);
+    }
+    if (!layerBounds) {
+      options?.onDecision?.({decision: 'missing-layer-bounds', context});
+      return true;
+    }
+
+    let viewportBounds = viewportBoundsCache.get(viewport);
+    if (viewportBounds === undefined) {
+      viewportBounds = getViewportBounds(viewport);
+      viewportBoundsCache.set(viewport, viewportBounds);
+    }
+    if (!viewportBounds) {
+      options?.onDecision?.({decision: 'missing-viewport-bounds', context, layerBounds});
+      return true;
+    }
+
+    const shouldRender = boundsOverlap(layerBounds, viewportBounds);
+    if (!shouldRender) {
+      options?.onDecision?.({decision: 'filter', context, layerBounds, viewportBounds});
+    }
+    return shouldRender;
+  };
+}
+
+function getLayerBounds(layer: Layer): Bounds | null {
+  const bounds = layer.getBounds();
+  if (!bounds || bounds.length < 2) {
+    return null;
+  }
+  return normalizeBounds(bounds[0], bounds[1]);
+}
+
+function getViewportBounds(viewport: Viewport): Bounds | null {
+  const bounds = viewport.getBounds();
+  if (!bounds || bounds.length < 4) {
+    return null;
+  }
+
+  const [minX, minY, maxX, maxY] = bounds;
+  if (
+    !isFiniteNumber(minX) ||
+    !isFiniteNumber(minY) ||
+    !isFiniteNumber(maxX) ||
+    !isFiniteNumber(maxY)
+  ) {
+    return null;
+  }
+  return normalizeBounds([minX, minY], [maxX, maxY]);
+}
+
+function normalizeBounds(min: number[] | undefined, max: number[] | undefined): Bounds | null {
+  if (!min || !max || min.length < 2 || max.length < 2) {
+    return null;
+  }
+
+  const minX = Math.min(min[0]!, max[0]!);
+  const minY = Math.min(min[1]!, max[1]!);
+  const maxX = Math.max(min[0]!, max[0]!);
+  const maxY = Math.max(min[1]!, max[1]!);
+
+  if (
+    !isFiniteNumber(minX) ||
+    !isFiniteNumber(minY) ||
+    !isFiniteNumber(maxX) ||
+    !isFiniteNumber(maxY)
+  ) {
+    return null;
+  }
+
+  return [minX, minY, maxX, maxY];
+}
+
+function boundsOverlap(a: Bounds, b: Bounds): boolean {
+  return !(a[2] < b[0] || b[2] < a[0] || a[3] < b[1] || b[3] < a[1]);
+}
+
+function isFiniteNumber(value: number): boolean {
+  return Number.isFinite(value);
+}

package/src/views/orthographic-utils.ts

@@ -2,38 +2,57 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-type Bounds = [[number, number], [number, number]];
+import type {Bounds} from './bounds-utils';
 
+/**
+ * Fits two-dimensional bounds into an orthographic viewport using one shared zoom value.
+ * @param width - Viewport width in pixels.
+ * @param height - Viewport height in pixels.
+ * @param bounds - World-space bounds to fit.
+ * @param zoomMode - Shared-zoom mode selector.
+ * @returns View target and shared/per-axis zoom values.
+ */
 export function fitBoundsOrthographic(
   width: number,
   height: number,
   bounds: Readonly<Bounds>,
   zoomMode: 'single'
-): {target: [number, number]; zoom: number};
+): {target: [number, number]; zoom: number; zoomX: number; zoomY: number};
 
+/**
+ * Fits two-dimensional bounds into an orthographic viewport using one zoom per axis.
+ * @param width - Viewport width in pixels.
+ * @param height - Viewport height in pixels.
+ * @param bounds - World-space bounds to fit.
+ * @param zoomMode - Per-axis zoom mode selector.
+ * @returns View target and per-axis zoom values.
+ */
 export function fitBoundsOrthographic(
   width: number,
   height: number,
   bounds: Readonly<Bounds>,
   zoomMode: 'per-axis'
-): {target: [number, number]; zoom: [number, number]};
+): {target: [number, number]; zoom: [number, number]; zoomX: number; zoomY: number};
 
 /**
- * Compute center & zoom for an OrthographicViewport so that `bounds` fills the viewport.
- * @param width  viewport width in px
- * @param height viewport height in px
- * @param bounds [[minX,minY],[maxX,maxY]] in the same world units you’re rendering
- * @returns { target: [number, number], zoom: number }
- *   target: center of the viewport in world units
- *   zoom: deck.gl orthographic zoom level (log2(scale))
- *   (deck.gl orthographic zoom is the log2 of the scale factor)
+ * Fits two-dimensional bounds into an orthographic viewport.
+ * @param width - Viewport width in pixels.
+ * @param height - Viewport height in pixels.
+ * @param bounds - World-space bounds to fit.
+ * @param zoomMode - Whether to use one shared zoom or one zoom per axis.
+ * @returns View target plus deck.gl orthographic zoom values.
  */
 export function fitBoundsOrthographic(
   width: number,
   height: number,
   bounds: Readonly<Bounds>,
   zoomMode: 'single' | 'per-axis' = 'per-axis'
-): {target: [number, number]; zoom: number | [number, number]} {
+): {
+  target: [number, number];
+  zoom: number | [number, number];
+  zoomX: number;
+  zoomY: number;
+} {
   const [[minX, minY], [maxX, maxY]] = bounds;
 
   // center of the box
@@ -41,12 +60,12 @@ export function fitBoundsOrthographic(
   const centerY = (minY + maxY) / 2;
 
   // size of the box
-  const boxW = maxX - minX;
-  const boxH = maxY - minY;
+  const boxW = Math.max(0, maxX - minX);
+  const boxH = Math.max(0, maxY - minY);
 
   // scale (world units → screen pixels)
-  const scaleX = width / boxW;
-  const scaleY = height / boxH;
+  const scaleX = boxW ? Math.max(1, width) / boxW : 1;
+  const scaleY = boxH ? Math.max(1, height) / boxH : 1;
 
   // pick the smaller scale so the whole box fits
   const scale = Math.min(scaleX, scaleY);
@@ -58,13 +77,41 @@ export function fitBoundsOrthographic(
   const zoomX = Math.log2(scaleX);
   const zoomY = Math.log2(scaleY);
 
-  if (Number.isNaN(zoom) || Number.isNaN(zoomX) || Number.isNaN(zoom)) {
+  if (Number.isNaN(zoom) || Number.isNaN(zoomX) || Number.isNaN(zoomY)) {
     // eslint-disable-next-line no-console
     console.warn('Invalid zoom values:', {zoom, zoomX, zoomY});
   }
 
   return {
     target: [centerX, centerY],
-    zoom: zoomMode === 'single' ? zoom : [zoomX, zoomY]
+    zoom: zoomMode === 'single' ? zoom : [zoomX, zoomY],
+    zoomX: zoomMode === 'single' ? zoom : zoomX,
+    zoomY: zoomMode === 'single' ? zoom : zoomY
   };
 }
+
+/**
+ * Computes world-space bounds covered by an orthographic viewport.
+ * @param width - Viewport width in pixels.
+ * @param height - Viewport height in pixels.
+ * @param zoom - Deck.gl orthographic zoom level, as one value or `[zoomX, zoomY]`.
+ * @param target - Deck.gl orthographic target `[centerX, centerY]`.
+ * @returns World-space bounds covered by the viewport.
+ */
+export function getBoundsOrthographic(
+  width: number,
+  height: number,
+  zoom: number | [number, number],
+  target: [number, number]
+): Bounds {
+  const [centerX, centerY] = target;
+  const scaleX = Array.isArray(zoom) ? 2 ** zoom[0] : 2 ** zoom;
+  const scaleY = Array.isArray(zoom) ? 2 ** zoom[1] : 2 ** zoom;
+  const worldW = width / scaleX;
+  const worldH = height / scaleY;
+
+  return [
+    [centerX - worldW / 2, centerY - worldH / 2],
+    [centerX + worldW / 2, centerY + worldH / 2]
+  ];
+}