or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

aggregation-systems.md contour-layer.md grid-layer.md heatmap-layer.md hexagon-layer.md index.md screen-grid-layer.md

tile.json

Screen Grid Layer

ScreenGridLayer aggregates data into histogram bins based on screen pixel coordinates and renders them as a regular grid. This layer is ideal for showing data density across screen space, automatically adjusting bin size based on zoom level.

Capabilities

ScreenGridLayer Class

Creates a layer that aggregates data points into screen-space grid cells with customizable styling and aggregation methods.

/**
 * Aggregates data into histogram bins and renders them as a screen-space grid
 * @param props - Configuration properties for the screen grid layer
 */
class ScreenGridLayer<DataT = any> extends AggregationLayer<DataT, ScreenGridLayerProps<DataT>> {
  constructor(props: ScreenGridLayerProps<DataT>);
}

interface ScreenGridLayerProps<DataT> extends LayerProps {
  /** Array of data objects to aggregate */
  data: DataT[];
  /** Function to extract position from data object */
  getPosition: Accessor<DataT, Position>;
  /** Function to extract weight value for aggregation */
  getWeight?: Accessor<DataT, number>;
  /** Size of each grid cell in pixels */
  cellSizePixels?: number;
  /** Margin between grid cells in pixels */
  cellMarginPixels?: number;
  /** Array of colors for the color scale */
  colorRange?: Color[];
  /** Type of color scale to apply */
  colorScaleType?: 'linear' | 'quantize';
  /** Whether to use GPU aggregation for better performance */
  gpuAggregation?: boolean;
  /** Aggregation operation to apply to values in each bin */
  aggregation?: AggregationOperation;
  /** Domain for color scale [min, max] */
  colorDomain?: [number, number] | null;
  /** Minimum color value for linear scale */
  lowerPercentile?: number;
  /** Maximum color value for linear scale */
  upperPercentile?: number;
  /** Scale factor for color domain */
  colorScaleType?: 'linear' | 'quantize';
}

interface ScreenGridLayerPickingInfo<DataT = any> extends PickingInfo<DataT> {
  /** The aggregated bin data */
  object: AggregatedBin | null;
  /** Column index of the picked bin */
  col: number;
  /** Row index of the picked bin */
  row: number;
  /** Total count of points in the bin */
  count: number;
  /** Aggregated value for the bin */
  colorValue?: number;
  /** Array indices of points in this bin (CPU aggregation only) */
  pointIndices?: number[];
}

Usage Examples:

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

// Basic screen grid layer
const basicLayer = new ScreenGridLayer({
  id: "screen-grid",
  data: [
    { coordinates: [-122.4, 37.8], value: 100 },
    { coordinates: [-122.3, 37.9], value: 200 },
    { coordinates: [-122.45, 37.75], value: 150 }
  ],
  getPosition: (d) => d.coordinates,
  getWeight: (d) => d.value,
  cellSizePixels: 50,
  pickable: true
});

// Advanced configuration with custom colors
const advancedLayer = new ScreenGridLayer({
  id: "density-grid",
  data: locationData,
  getPosition: (d) => [d.lng, d.lat],
  getWeight: (d) => d.density,
  cellSizePixels: 100,
  cellMarginPixels: 2,
  colorRange: [
    [255, 255, 178],
    [254, 204, 92],
    [253, 141, 60],
    [240, 59, 32],
    [189, 0, 38]
  ],
  colorScaleType: 'quantize',
  aggregation: 'MEAN',
  gpuAggregation: true,
  colorDomain: [0, 500],
  pickable: true,
  onHover: (info) => {
    if (info.object) {
      console.log(`Cell [${info.col}, ${info.row}]: ${info.count} points, value: ${info.colorValue}`);
    }
  }
});

Cell Size Configuration

Controls the size and spacing of grid cells in screen pixels.

/** Size of each grid cell in pixels (default: 100) */
cellSizePixels?: number;

/** Margin between grid cells in pixels (default: 2) */
cellMarginPixels?: number;

Color Configuration

Configures the visual appearance and color mapping for grid cells.

/** Array of colors for the color scale */
colorRange?: Color[];

/** Type of color scale to apply */
colorScaleType?: 'linear' | 'quantize';

/** Domain for color scale [min, max] */
colorDomain?: [number, number] | null;

/** Minimum color value for linear scale (0-100) */
lowerPercentile?: number;

/** Maximum color value for linear scale (0-100) */
upperPercentile?: number;

Aggregation Configuration

Controls how data points are aggregated within each grid cell.

/** Aggregation operation to apply to values in each bin */
aggregation?: AggregationOperation;

/** Whether to use GPU aggregation for better performance (default: true) */
gpuAggregation?: boolean;

/** Function to extract weight value for aggregation */
getWeight?: Accessor<DataT, number>;

Performance Considerations

GPU Aggregation: Recommended for datasets with more than 100,000 points
Cell Size: Larger cells require less computation but provide lower resolution
Color Scale: 'quantize' scale type is more performant than 'linear' for large datasets
Memory Usage: GPU aggregation uses WebGL textures which have size limitations

Common Patterns

// Event tracking heatmap
const eventLayer = new ScreenGridLayer({
  id: "events",
  data: events,
  getPosition: (d) => [d.x, d.y],
  cellSizePixels: 25,
  aggregation: 'COUNT', // Count events per cell
  colorRange: [[0, 0, 255, 100], [255, 0, 0, 200]],
  colorScaleType: 'linear'
});

// Weighted density visualization
const densityLayer = new ScreenGridLayer({
  id: "density",
  data: measurements,
  getPosition: (d) => d.location,
  getWeight: (d) => d.importance,
  aggregation: 'SUM',
  cellSizePixels: 75,
  cellMarginPixels: 1,
  colorDomain: [0, 1000],
  gpuAggregation: true
});