screengrid

ScreenGrid Library

npm

A GPU/Canvas hybrid Screen-Space Grid Aggregation library for MapLibre GL JS. This library provides efficient real-time aggregation of point data into screen-space grids with customizable styling, interactive features, and advanced glyph drawing capabilities. It also supports non-point geometries via a geometry placement preprocessor and per-feature glyph rendering.

This library is inspired by Aidan Slingsby’s Gridded Glyphmaps and borrows some basic concepts from deck.gl’s ScreenGridLayer, but is built from the ground up with a modular architecture.

https://danylaksono.is-a.dev/screengrid/examples/multivariate-timeseries

Documentation

Quick Start

Installation

npm install screengrid maplibre-gl

Basic Usage

import { ScreenGridLayerGL } from 'screengrid';
import maplibregl from 'maplibre-gl';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [-122.4, 37.74],
  zoom: 11
});

map.on('load', async () => {
  const data = await fetch('your-data.json').then(r => r.json());
  
  const gridLayer = new ScreenGridLayerGL({
    data: data,
    getPosition: (d) => d.coordinates,
    getWeight: (d) => d.weight,
    cellSizePixels: 60,
    colorScale: (v) => [255 * v, 200 * (1 - v), 50, 220]
  });
  
  map.addLayer(gridLayer);
});

CDN Usage

<script src="https://unpkg.com/screengrid/dist/screengrid.umd.min.js"></script>
<script src="https://unpkg.com/maplibre-gl@^4/dist/maplibre-gl.js"></script>
<script>
  const { ScreenGridLayerGL } = ScreenGrid;
  // use ScreenGridLayerGL here
</script>

See USAGE.md for more examples and CDN usage details.

Key Features

See the documentation for detailed guides on each feature.

Project Structure

screengrid/
├── src/
│   ├── index.js                    # Main entry point
│   ├── ScreenGridLayerGL.js        # Main orchestrator
│   ├── core/                       # Core business logic
│   ├── canvas/                     # Canvas rendering
│   ├── events/                     # Event system
│   ├── glyphs/                     # Glyph utilities & plugins
│   ├── aggregation/                # Aggregation modes & functions
│   ├── normalization/              # Normalization functions
│   ├── utils/                      # Utilities (Logger, DataUtilities)
│   └── legend/                     # Legend system
├── docs/                           # Documentation
├── examples/                       # Example HTML files
├── dist/                           # Built distribution
└── package.json

See ARCHITECTURE.md for detailed architecture documentation.

Examples

Run examples locally:

npx http-server -p 8000
# Open http://localhost:8000/examples/

Available examples:

See USAGE.md for complete example descriptions.

API Overview

ScreenGridLayerGL Options

Basic:

Glyphs:

Geometry Input (v2.1.0+):

Aggregation:

Events:

See API_REFERENCE.md for complete API documentation.

Exports

import {
  ScreenGridLayerGL,
  Aggregator, Projector, CellQueryEngine,
  PlacementEngine, PlacementValidator, GeometryUtils,
  CanvasManager, Renderer,
  EventBinder, EventHandlers,
  GlyphUtilities, GlyphRegistry,
  AggregationModeRegistry, ScreenGridMode, ScreenHexMode,
  AggregationFunctions, AggregationFunctionRegistry,
  NormalizationFunctions, NormalizationFunctionRegistry,
  Logger, setDebug,
  groupBy, extractAttributes, computeStats, groupByTime,
  Legend, LegendDataExtractor, LegendRenderers,
  ConfigManager
} from 'screengrid';

See QUICK_REFERENCE.md for usage examples.

Development

git clone https://github.com/danylaksono/screengrid.git
cd screengrid
npm install
npm run build

See USAGE.md for development workflow details.

Changelog

v2.2.0 (Current)

v2.1.0

v2.0.0

See ARCHITECTURE.md for version history details.

Author

dany laksono

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request
This site is open source. Improve this page.