or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aggregation-systems.mdcontour-layer.mdgrid-layer.mdheatmap-layer.mdhexagon-layer.mdindex.mdscreen-grid-layer.md
tile.json

index.mddocs/

@deck.gl/aggregation-layers

@deck.gl/aggregation-layers provides GPU-accelerated data aggregation and visualization layers for the deck.gl WebGL framework. It enables high-performance rendering of large datasets through specialized layer types including ContourLayer, GridLayer, HeatmapLayer, HexagonLayer, and ScreenGridLayer with both CPU and GPU aggregation strategies.

Package Information

  • Package Name: @deck.gl/aggregation-layers
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @deck.gl/aggregation-layers

Core Imports

import {
  ScreenGridLayer,
  HexagonLayer,
  ContourLayer,
  GridLayer,
  HeatmapLayer,
  WebGLAggregator,
  CPUAggregator,
  _AggregationLayer
} from "@deck.gl/aggregation-layers";

For CommonJS:

const {
  ScreenGridLayer,
  HexagonLayer,
  ContourLayer,
  GridLayer,
  HeatmapLayer
} = require("@deck.gl/aggregation-layers");

Basic Usage

import { HexagonLayer } from "@deck.gl/aggregation-layers";

// Create a hexagon layer for data visualization
const layer = new HexagonLayer({
  id: "hexagon-layer",
  data: [
    { position: [-122.4, 37.8], value: 100 },
    { position: [-122.3, 37.9], value: 200 }
  ],
  getPosition: (d) => d.position,
  getElevationWeight: (d) => d.value,
  getColorWeight: (d) => d.value,
  radius: 1000,
  elevationScale: 4,
  extruded: true,
  coverage: 0.88
});

Architecture

@deck.gl/aggregation-layers is built around several key components:

  • Layer Classes: Five specialized layer types (ScreenGridLayer, HexagonLayer, ContourLayer, GridLayer, HeatmapLayer) for different visualization patterns
  • Aggregation Engine: Both CPU and GPU-based aggregation implementations for optimal performance across different data sizes
  • Base Architecture: Common AggregationLayer base class providing shared functionality and WebGL integration
  • Type System: Complete TypeScript definitions with generic types for data handling and layer props
  • Performance Optimization: GPU-accelerated processing for datasets over 100K points with automatic fallback to CPU

Capabilities

Screen Grid Aggregation

Aggregates data into histogram bins and renders them as a screen-space grid, ideal for showing data density across screen pixels.

class ScreenGridLayer<DataT = any> extends AggregationLayer<DataT, ScreenGridLayerProps<DataT>> {
  constructor(props: ScreenGridLayerProps<DataT>);
}

interface ScreenGridLayerProps<DataT> {
  data: DataT[];
  getPosition?: Accessor<DataT, Position>;
  getWeight?: Accessor<DataT, number>;
  cellSizePixels?: number;
  cellMarginPixels?: number;
  colorDomain?: [number, number] | null;
  colorRange?: Color[];
  colorScaleType?: 'linear' | 'quantize';
  gpuAggregation?: boolean;
  aggregation?: AggregationOperation;
}

Screen Grid Layer

Hexagonal Binning

Aggregates data into a hexagonal grid-based heatmap with optional 3D extrusion for geographic data visualization.

class HexagonLayer<DataT = any> extends AggregationLayer<DataT, HexagonLayerProps<DataT>> {
  constructor(props: HexagonLayerProps<DataT>);
}

interface HexagonLayerProps<DataT> {
  data: DataT[];
  getPosition?: Accessor<DataT, Position>;
  getColorWeight?: Accessor<DataT, number>;
  getElevationWeight?: Accessor<DataT, number>;
  radius?: number;
  coverage?: number;
  extruded?: boolean;
  elevationScale?: number;
  colorDomain?: [number, number] | null;
  elevationDomain?: [number, number] | null;
  colorRange?: Color[];
  elevationRange?: [number, number];
  upperPercentile?: number;
  lowerPercentile?: number;
  elevationUpperPercentile?: number;
  elevationLowerPercentile?: number;
  colorScaleType?: 'quantize' | 'linear' | 'quantile' | 'ordinal';
  elevationScaleType?: 'linear';
  material?: Material;
  colorAggregation?: AggregationOperation;
  elevationAggregation?: AggregationOperation;
  gpuAggregation?: boolean;
}

Hexagon Layer

Grid Aggregation

Aggregates data into a regular grid-based heatmap with customizable cell size and optional 3D visualization.

class GridLayer<DataT = any> extends AggregationLayer<DataT, GridLayerProps<DataT>> {
  constructor(props: GridLayerProps<DataT>);
}

interface GridLayerProps<DataT> {
  data: DataT[];
  getPosition?: Accessor<DataT, Position>;
  getColorWeight?: Accessor<DataT, number>;
  getElevationWeight?: Accessor<DataT, number>;
  cellSize?: number;
  coverage?: number;
  extruded?: boolean;
  elevationScale?: number;
  colorDomain?: [number, number] | null;
  elevationDomain?: [number, number] | null;
  colorRange?: Color[];
  elevationRange?: [number, number];
  upperPercentile?: number;
  lowerPercentile?: number;
  elevationUpperPercentile?: number;
  elevationLowerPercentile?: number;
  colorScaleType?: 'quantize' | 'linear' | 'quantile' | 'ordinal';
  elevationScaleType?: 'linear' | 'quantile';
  material?: Material;
  colorAggregation?: AggregationOperation;
  elevationAggregation?: AggregationOperation;
  gpuAggregation?: boolean;
}

Grid Layer

Contour Visualization

Renders contour lines and bands from aggregated data using marching squares algorithm for isoline generation.

class ContourLayer<DataT = any> extends AggregationLayer<DataT, ContourLayerProps<DataT>> {
  constructor(props: ContourLayerProps<DataT>);
}

interface ContourLayerProps<DataT> {
  data: DataT[];
  getPosition?: Accessor<DataT, Position>;
  getWeight?: Accessor<DataT, number>;
  cellSize?: number;
  gridOrigin?: [number, number];
  contours?: Contour[];
  zOffset?: number;
  gpuAggregation?: boolean;
  aggregation?: AggregationOperation;
}

interface Contour {
  threshold: number;
  color?: Color;
  strokeWidth?: number;
}

Contour Layer

Heatmap Visualization

Visualizes spatial distribution of data as a continuous heatmap with customizable intensity and color gradients.

class HeatmapLayer<DataT = any> extends AggregationLayer<DataT, HeatmapLayerProps<DataT>> {
  constructor(props: HeatmapLayerProps<DataT>);
}

interface HeatmapLayerProps<DataT> {
  data: DataT[];
  getPosition?: Accessor<DataT, Position>;
  getWeight?: Accessor<DataT, number>;
  radiusPixels?: number;
  colorRange?: Color[];
  intensity?: number;
  threshold?: number;
  colorDomain?: [number, number] | null;
  aggregation?: 'SUM' | 'MEAN';
  weightsTextureSize?: number;
  debounceTimeout?: number;
}

Heatmap Layer

Aggregation Systems

High-performance data aggregation implementations supporting both CPU and GPU processing strategies.

class WebGLAggregator implements Aggregator {
  constructor(device: Device, props: WebGLAggregatorProps);
  static isSupported(device: Device): boolean;
  setProps(props: Partial<AggregationProps>): void;
  setNeedsUpdate(channel?: number): void;
  update(): void;
  preDraw(): void;
  destroy(): void;
  get binCount(): number;
  getBins(): BinaryAttribute | null;
  getResult(channel: number): BinaryAttribute | null;
  getResultDomain(channel: number): [min: number, max: number];
  getBin(index: number): AggregatedBin | null;
}

class CPUAggregator implements Aggregator {
  constructor(props: CPUAggregatorProps);
  setProps(props: Partial<AggregationProps>): void;
  setNeedsUpdate(channel?: number): void;
  update(): void;
  preDraw(): void;
  destroy(): void;
  get binCount(): number;
  getBins(): BinaryAttribute | null;
  getResult(channel: number): BinaryAttribute | null;
  getResultDomain(channel: number): [min: number, max: number];
  getBin(index: number): AggregatedBin | null;
}

Aggregation Systems

Core Types

type AggregationOperation = 'SUM' | 'MEAN' | 'MIN' | 'MAX' | 'COUNT';

type ScaleType = 'linear' | 'quantize' | 'quantile' | 'ordinal';

type Position = [number, number] | [number, number, number];

type Color = [number, number, number] | [number, number, number, number];

type Accessor<DataT, ValueT> = ((d: DataT, info: AccessorContext<DataT>) => ValueT) | ValueT;

interface AccessorContext<DataT> {
  index: number;
  data: DataT[];
  target: any[];
}

interface AggregatedBin {
  id: number[];
  value: number[];
  count: number;
  pointIndices?: number[];
}

interface Aggregator {
  setProps(props: Partial<AggregationProps>): void;
  setNeedsUpdate(channel?: number): void;
  update(): void;
  preDraw(): void;
  destroy(): void;
  get binCount(): number;
  getBins(): BinaryAttribute | null;
  getResult(channel: number): BinaryAttribute | null;
  getResultDomain(channel: number): [min: number, max: number];
  getBin(index: number): AggregatedBin | null;
}

interface PickingInfo<DataT = any> {
  index: number;
  object: AggregatedBin | null;
  x: number;
  y: number;
  coordinate: [number, number];
  layer: Layer<DataT>;
}

interface LayerProps {
  id: string;
  data?: any[];
  visible?: boolean;
  pickable?: boolean;
  opacity?: number;
  onHover?: (info: PickingInfo) => void;
  onClick?: (info: PickingInfo) => void;
  updateTriggers?: Record<string, any>;
}

abstract class Layer<PropsT = {}> {
  constructor(props: PropsT & LayerProps);
  abstract render(): void;
}

abstract class AggregationLayer<DataT, PropsT> extends Layer<PropsT> {
  constructor(props: PropsT & LayerProps);
}

interface Device {
  features: Set<string>;
  gl: WebGL2RenderingContext | WebGLRenderingContext;
}

interface BinaryAttribute {
  value: ArrayBufferView;
  size: number;
  type?: number;
  normalized?: boolean;
}

interface Attribute {
  size: number;
  value: ArrayBufferView;
  type?: number;
  normalized?: boolean;
}

interface Material {
  ambient?: number;
  diffuse?: number;
  shininess?: number;
  specularColor?: [number, number, number];
}

interface BufferLayout {
  name: string;
  format: string;
  stepMode?: 'vertex' | 'instance';
}

interface ShaderModule {
  name: string;
  vs?: string;
  fs?: string;
  dependencies?: ShaderModule[];
}

type VertexAccessor<T, D> = (d: D, i: number) => T;

type AggregateAccessor<DataT> = (bin: AggregatedBin, data: DataT[]) => number;

type AccessorFunction<DataT, ValueT> = (d: DataT, info: { index: number; data: DataT[]; target: any[] }) => ValueT;

interface AggregationProps {
  pointCount: number;
  attributes: {[id: string]: Attribute};
  operations: AggregationOperation[];
  binOptions: Record<string, number | number[]>;
  onUpdate?: (event: {channel: number}) => void;
}

interface WebGLAggregatorProps {
  dimensions: 1 | 2;
  channelCount: 1 | 2 | 3;
  bufferLayout?: BufferLayout[];
  vs: string;
  modules?: ShaderModule[];
  defines?: Record<string, string | number | boolean>;
}

interface CPUAggregatorProps {
  dimensions: number;
  getBin: VertexAccessor<number[] | null, any>;
  getValue: VertexAccessor<number>[];
}