Skip to content

README.md

Latest commit

 

History

History
251 lines (190 loc) · 8.43 KB

README.md

File metadata and controls

251 lines (190 loc) · 8.43 KB

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

  • Real-time Aggregation - Efficient screen-space grid aggregation
  • Multiple Modes - Rectangular (screen-grid) and hexagonal (screen-hex) grids
  • Glyph Visualizations - Custom glyph drawing with Canvas 2D
  • Plugin System - Reusable glyph plugins (circle, bar, pie, heatmap)
  • Geometry Input - Support for Polygon, LineString, and other non-point geometries
  • Interactive Events - Hover and click handlers with reactive state
  • Time Series - Built-in time series glyph utility
  • Legend System - Auto-generated data-driven legends
  • Aggregation Functions - Built-in (sum, mean, count, max, min) and custom functions
  • Normalization - Multiple strategies (max-local, max-global, z-score, percentile)
  • Data Utilities - Helper functions for common data processing patterns
  • Debug Logging - Configurable logging for troubleshooting

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:

  • index.html - Full demo with all features
  • hex-mode.html - Hexagonal aggregation
  • plugin-glyph.html - Custom plugin example
  • timeseries.html - Time series visualization
  • us-states.html - Geometry input (polygons)
  • data-utilities.html - Data processing utilities
  • creative-coding.html - Artistic visualizations

See USAGE.md for complete example descriptions.

API Overview

ScreenGridLayerGL Options

Basic:

  • data - Array of data points
  • getPosition - Extract coordinates: (d) => [lng, lat]
  • getWeight - Extract weight: (d) => number
  • cellSizePixels - Cell size in pixels (default: 50)
  • colorScale - Color function: (v) => [r, g, b, a]

Glyphs:

  • enableGlyphs - Enable glyph rendering (default: false)
  • onDrawCell - Custom glyph drawing callback
  • glyph - Registered plugin name (circle, bar, pie, heatmap)
  • glyphConfig - Plugin configuration object

Geometry Input (v2.1.0+):

  • source - GeoJSON FeatureCollection (mutually exclusive with data)
  • placement - Placement configuration
  • renderMode - screen-grid or feature-anchors

Aggregation:

  • aggregationMode - screen-grid or screen-hex
  • aggregationFunction - sum, mean, count, max, min
  • normalizationFunction - max-local, max-global, z-score, percentile

Events:

  • onHover - Hover callback
  • onClick - Click callback
  • onAggregate - Aggregation callback

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)

  • NEW: Hexagonal aggregation mode (screen-hex)
  • NEW: Aggregation mode registry system
  • IMPROVED: Mode-specific configuration

v2.1.0

  • NEW: Geometry input & placement (non-point geometries)
  • NEW: Aggregation function registry (sum, mean, count, max, min)
  • NEW: Normalization function registry
  • NEW: Data utilities (groupBy, extractAttributes, computeStats, groupByTime)
  • NEW: Logger utility with debug logging

v2.0.0

  • NEW: Modular architecture refactoring
  • NEW: Glyph plugin system
  • NEW: Legend system
  • NEW: Time series glyph utility

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

Related Documentation