or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aggregation-layers.mdcarto-integration.mdcore-api.mdeffects-lighting.mdextensions.mdgeo-layers.mdindex.mdintegration.mdjson-configuration.mdlayers.mdmesh-layers.mdviews-controllers.md
tile.json

tessl/npm-deck-gl

WebGL2-powered data visualization framework for rendering large-scale datasets with high performance

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/deck.gl@8.9.x

To install, run

npx @tessl/cli install tessl/npm-deck-gl@8.9.0

index.mddocs/

deck.gl

deck.gl is a comprehensive WebGL2-powered data visualization framework designed for rendering large-scale datasets with high performance. It offers a modular architecture with multiple layers that can be composed together and viewed through different perspectives (map, first-person, orthographic). The library handles complex challenges including performant rendering and updating of large data sets, interactive event handling such as picking and highlighting, and provides extensible architecture for custom visualization needs.

Package Information

  • Package Name: deck.gl
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install deck.gl

Core Imports

import {Deck, ScatterplotLayer, ArcLayer, MapView} from 'deck.gl';

For React applications:

import DeckGL from '@deck.gl/react';
import {ScatterplotLayer, ArcLayer} from 'deck.gl';

CommonJS:

const {Deck, ScatterplotLayer, ArcLayer, MapView} = require('deck.gl');

Basic Usage

Standalone Usage

import {Deck, ScatterplotLayer} from 'deck.gl';

const deck = new Deck({
  canvas: 'my-canvas',
  initialViewState: {
    longitude: -122.4,
    latitude: 37.8,
    zoom: 12
  },
  controller: true,
  layers: [
    new ScatterplotLayer({
      id: 'points',
      data: [
        {position: [-122.4, 37.8], radius: 100, color: [255, 0, 0]},
        {position: [-122.5, 37.9], radius: 150, color: [0, 255, 0]}
      ],
      getPosition: d => d.position,
      getRadius: d => d.radius,
      getFillColor: d => d.color,
      pickable: true
    })
  ],
  onViewStateChange: ({viewState}) => {
    // Handle view state changes
  }
});

React Usage

import React from 'react';
import DeckGL from '@deck.gl/react';
import {ScatterplotLayer} from 'deck.gl';

function App() {
  const layers = [
    new ScatterplotLayer({
      id: 'points',
      data: myData,
      getPosition: d => d.coordinates,
      getRadius: d => d.radius,
      getFillColor: [255, 0, 0],
      pickable: true
    })
  ];

  return (
    <DeckGL
      initialViewState={{
        longitude: -122.4,
        latitude: 37.8,
        zoom: 12
      }}
      controller={true}
      layers={layers}
    />
  );
}

Architecture

deck.gl is built around several key architectural components:

  • Layer System: Composable visualization layers that handle rendering different data types
  • View System: Camera and projection management for different viewing perspectives
  • Effect System: Lighting, post-processing, and visual effects
  • Controller System: User interaction handling (pan, zoom, rotate)
  • Deck Instance: Central orchestrator managing layers, views, and rendering
  • Integration System: Platform integrations for React, Google Maps, Mapbox

Coordinate Systems

deck.gl supports multiple coordinate systems:

  • COORDINATE_SYSTEM.DEFAULT (-1): Auto-detect based on data
  • COORDINATE_SYSTEM.LNGLAT (1): Longitude/latitude coordinates
  • COORDINATE_SYSTEM.CARTESIAN (0): Cartesian coordinates
  • COORDINATE_SYSTEM.METER_OFFSETS (2): Meter offsets from anchor
  • COORDINATE_SYSTEM.LNGLAT_OFFSETS (3): Lng/lat offsets from anchor

Capabilities

Core API

The foundational rendering engine and base classes including the main Deck orchestrator, Layer base classes, and the view/controller system.

class Deck {
  constructor(props: DeckProps);
  pickObject(opts: {x: number, y: number}): PickingInfo | null;
  pickObjects(opts: {x: number, y: number, width: number, height: number}): PickingInfo[];
  redraw(): void;
  finalize(): void;
}

interface DeckProps {
  canvas?: HTMLCanvasElement | string;
  width?: string | number;
  height?: string | number;
  layers?: Layer[];
  views?: View | View[];
  viewState?: any;
  controller?: boolean | Controller;
  effects?: Effect[];
  onViewStateChange?: (params: {viewState: any}) => void;
  onLoad?: () => void;
  onError?: (error: Error) => void;
}

Core API

Visualization Layers

Core layer types for rendering different data structures including points, lines, polygons, 3D shapes, text, and images.

class ScatterplotLayer extends Layer {
  constructor(props: ScatterplotLayerProps);
}

interface ScatterplotLayerProps extends LayerProps {
  getPosition: Accessor<Position>;
  getRadius?: Accessor<number>;
  getFillColor?: Accessor<Color>;
  getLineColor?: Accessor<Color>;
  radiusScale?: number;
  radiusMinPixels?: number;
  radiusMaxPixels?: number;
  stroked?: boolean;
  filled?: boolean;
}

class ArcLayer extends Layer {
  constructor(props: ArcLayerProps);
}

class IconLayer extends Layer {
  constructor(props: IconLayerProps);
}

Visualization Layers

Views and Controllers

Camera management and user interaction systems for different viewing perspectives including map, 3D orbit, orthographic, and first-person views.

class MapView extends View {
  constructor(props?: MapViewProps);
}

interface MapViewState {
  longitude: number;
  latitude: number;
  zoom: number;
  pitch?: number;
  bearing?: number;
}

class MapController extends Controller {
  constructor(props?: MapControllerProps);
}

Views and Controllers

Effects and Lighting

Visual effects system including lighting models, post-processing effects, and material properties for realistic 3D rendering.

class LightingEffect extends Effect {
  constructor(props: {lights: Light[]});
}

class AmbientLight {
  constructor(props: {color: Color, intensity: number});
}

class DirectionalLight {
  constructor(props: {
    color: Color;
    intensity: number;
    direction: [number, number, number];
  });
}

Effects and Lighting

Aggregation Layers

Data aggregation and density visualization layers including grid-based aggregation, hexagonal binning, and heat maps.

class GridLayer extends CompositeLayer {
  constructor(props: GridLayerProps);
}

class HexagonLayer extends CompositeLayer {
  constructor(props: HexagonLayerProps);
}

class HeatmapLayer extends Layer {
  constructor(props: HeatmapLayerProps);
}

Aggregation Layers

Geographic Layers

Specialized layers for geographic data including tile systems, vector tiles, and spatial index visualizations.

class TileLayer extends CompositeLayer {
  constructor(props: TileLayerProps);
}

class MVTLayer extends Layer {
  constructor(props: MVTLayerProps);
}

class H3HexagonLayer extends Layer {
  constructor(props: H3HexagonLayerProps);
}

Geographic Layers

Mesh Layers

3D mesh rendering layers for complex geometry, models, and scenes including simple mesh rendering and scenegraph-based 3D objects.

class SimpleMeshLayer extends Layer {
  constructor(props: SimpleMeshLayerProps);
}

class ScenegraphLayer extends Layer {
  constructor(props: ScenegraphLayerProps);
}

Mesh Layers

Extensions

Layer extensions that add capabilities like data filtering, collision detection, advanced styling, and precision improvements.

class BrushingExtension extends LayerExtension {
  constructor(props?: BrushingExtensionProps);
}

class DataFilterExtension extends LayerExtension {
  constructor(props?: DataFilterExtensionProps);
}

class Fp64Extension extends LayerExtension {
  constructor();
}

Extensions

Platform Integrations

Integration modules for React applications, Google Maps, Mapbox, JSON configuration, and CARTO platform.

// React Integration
function DeckGL(props: DeckGLProps): JSX.Element;

interface DeckGLProps extends DeckProps {
  children?: React.ReactNode | ((viewport: WebMercatorViewport) => React.ReactNode);
}

// Google Maps Integration
class GoogleMapsOverlay {
  constructor(props: DeckProps);
  setMap(map: google.maps.Map | null): void;
}

// Mapbox Integration
class MapboxOverlay {
  constructor(props: DeckProps);
}

Platform Integrations

JSON Configuration

Configuration system for creating deck.gl visualizations from JSON specifications, enabling dynamic visualization creation and templates.

class JSONConverter {
  constructor(props: {configuration: JSONConfiguration});
  convert(json: any): any;
}

class JSONConfiguration {
  constructor();
  addDefaultProps(classes: any, props: any): void;
  registerClasses(classes: {[key: string]: any}): void;
}

JSON Configuration

CARTO Integration

Integration with CARTO platform for data visualization including specialized layers, basemaps, and styling functions.

class CartoLayer extends Layer {
  constructor(props: CartoLayerProps);
}

function colorBins(opts: ColorBinsOptions): any;
function colorCategories(opts: ColorCategoriesOptions): any;
function colorContinuous(opts: ColorContinuousOptions): any;

CARTO Integration

Types

type Position = [number, number] | [number, number, number];
type Color = [number, number, number] | [number, number, number, number];
type Accessor<T> = T | ((object: any, info: AccessorContext) => T);

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

interface LayerProps {
  id: string;
  data?: any;
  visible?: boolean;
  pickable?: boolean;
  opacity?: number;
  coordinateSystem?: CoordinateSystem;
  updateTriggers?: {[key: string]: any};
}

interface PickingInfo {
  layer: Layer | null;
  index: number;
  object: any;
  x: number;
  y: number;
  coordinate: Position;
  devicePixel: [number, number];
  pixelColor: [number, number, number, number];
}

interface Effect {
  id: string;
  props: any;
  preRender(gl: WebGLRenderingContext, opts: PreRenderOptions): void;
  postRender(gl: WebGLRenderingContext, opts: PostRenderOptions): void;
}

type CoordinateSystem = -1 | 0 | 1 | 2 | 3;
type Unit = 'common' | 'meters' | 'pixels';

// Mesh layer types
interface SimpleMeshLayerProps extends LayerProps {
  mesh: string | Mesh | Promise<Mesh> | null;
  texture?: string | Texture | Promise<Texture>;
  getPosition?: Accessor<any, Position>;
  getColor?: Accessor<any, Color>;
  getOrientation?: Accessor<any, [number, number, number]>;
  getScale?: Accessor<any, [number, number, number]>;
  sizeScale?: number;
  wireframe?: boolean;
  material?: Material;
}

interface ScenegraphLayerProps extends LayerProps {
  scenegraph: string | object | Promise<object>;
  _animations?: {[name: string]: any};
  sizeScale?: number;
  getPosition?: Accessor<any, Position>;
  getOrientation?: Accessor<any, [number, number, number]>;
}

type Mesh = Geometry | {attributes: MeshAttributes} | MeshAttributes;

interface MeshAttributes {
  positions?: MeshAttribute;
  POSITION?: MeshAttribute;
  normals?: MeshAttribute;
  colors?: MeshAttribute;
}

interface MeshAttribute {
  value: ArrayLike<number>;
  size?: number;
}

// JSON configuration types
interface JSONConfigurationProps {
  classes?: {[key: string]: any};
  constants?: {[key: string]: any};
  enumerations?: {[key: string]: any};
  functions?: {[key: string]: any};
}

// CARTO integration types
interface CartoLayerProps extends LayerProps {
  data: string;
  type: 'query' | 'table' | 'tileset';
  connection?: string;
  credentials?: Credentials;
  queryParameters?: {[key: string]: any};
}

interface Credentials {
  apiKey?: string;
  username?: string;
  accessToken?: string;
  region?: string;
}

// Style function types
interface ColorBinsOptions<T> {
  attr: string | ((d: T) => number);
  domain: number[];
  colors?: Color[] | string;
  nullColor?: Color;
}

interface ColorCategoriesOptions<T> {
  attr: string | ((d: T) => string | number);
  domain: (string | number)[];
  colors?: Color[] | string;
  nullColor?: Color;
}

interface ColorContinuousOptions<T> {
  attr: string | ((d: T) => number);
  domain: [number, number];
  colors?: Color[] | string;
  nullColor?: Color;
}