leaflet-particles

Plugin to visualise dispersion of particles on a leaflet map.

Creates a custom leaflet layer with display modes:

• Final particle distribution:
  • final downstream (source) or upstream (sink) percentages
• Cumulative exposure:
  • percentage passing through cell from an upstream source or to a downstream sink
  • displays a heat-map of total exposure
• Animation:
  • use key frames to facilitate animation of particle positions over time
  • displays circles at particle locations, colored by their age

todo

• investigate L.setOptions ability to handle nested objects in initialise
• unify color scale options for diff displayModes
• better parameterisation of styling, options

install

Assuming you have node and npm installed:

npm install leaflet-particles --save

dependencies

This plugin has external dependencies:

• chroma-js
• leaflet-heatbin

To use this plugin, you either need to:

• load these dependencies yourself (prior to loading leaflet-particles); or
• use the standalone version with dependencies bundled, in dist/leaflet-particles-standalone.js

use and options

Note that L.setOptions does not seem to be deep extending as expected, to avoid issues in the immediate term - supply a full set of options (explicitly define defaults)

// create a particle layer
const mode = 'FINAL';
const particleLayer = L.particlesLayer({

  // an array of keyframes, default: null
  data: data,

  pane: 'myCustomPane', // name of an existing leaflet pane to add the layer to, default: 'overlayPane'

  // define the indices of your data point arrays, default:
  dataFormat: {
    idIndex:    0,
    lonIndex:   1,
    latIndex:   2,
    depthIndex: 3,
    ageIndex:   4
  },

  // one of: 'FINAL', 'EXPOSURE', 'KEYFRAME', default: null
  displayMode: mode,

  // which keyframe should display on init, default: 0
  startFrameIndex: 0,

  // the colors to use in chroma-js scale, default: (shown below)
  ageColorScale: ['green', 'yellow', 'red'],

  // the domain to fit the ageColorScale, default: keyframe length
  ageDomain: [0, 100],

  // heatmap.js options for heatmap layers, see:
  // https://www.patrick-wied.at/static/heatmapjs/example-heatmap-leaflet.html
  // note that additionally; we have an enhanced version of the leaflet-heatmap.js plugin (see /src)
  // that provides advanced cell/radius options, see: https://github.com/danwild/leaflet-heatbin
  heatOptions: {

    // example fixed radius of 1000m
    fixedRadius: true,
    radiusMeters: 1000,

    // e.g. bin values into 250m grid cells
    heatBin: {
      enabled: true,
      cellSizeKm: 0.25
    }
  },

  // the intensity value to use for each point on the heatmap, default: 1
  // only used if not heatBin.enabled
  exposureIntensity: 1,
  finalIntensity: 1,

  // callbacks when layer is added/removed from map
  onAdd: function(){}
  onRemove: function(){}

});

// add the layer to overlay control
const layerControl = L.control.layers({}, { particles: particleLayer });
layerControl.addTo(map);

// data and display mode can be updated like:
particleLayer.setData(newData);
particleLayer.setDisplayMode('KEYFRAME');

// when in keyframe mode, set active frame like:
particleLayer.setFrameIndex(index);

public methods

|method|params|description| |---|---|---| |isActive||check if the particle layer is currently active on the map| |setData|data: {Object}|update the layer with new data| |update||update the layer/redraw| |setOptions|options: {Object}|update the layer with new options| |setDisplayMode|mode: {String}|one of: FINAL, EXPOSURE, KEYFRAME| |getDisplayMode||Returns the current displayMode| |setFrameIndex|index: {Number}|display the particles at the given frame index| |getFrameIndex||Get the current frame index (-1 if not set)| |getGridInfo||A wrapper function for L.heatBin.getGridInfo to get information about the grid used for binning| |getParticleLayer||get the current underlying map layer used for drawing READONLY| |getParticleIds||get an array of unique particle ID's| |getUniquePercentRange|ignoreStatic: {boolean} disregard staticMax if set|get an array of unique particle ID's| |onAdd||optional callback when layer has been added to map| |onRemove||optional callback when layer has been removed from map|

data format

const data = {
  // ISO timestamp for each keyframe
  // contains an array of particles (each particle snapshot is represented by an array)
  "2017-03-02T01:00:00.000Z": [
    [
	  6,       // particle id
	  145.077, // lon
	  10.0710, // lat
	  0.5,     // depth (m)
	  1.0      // age
	],
	..
  ],
  "2017-03-02T02:00:00.000Z": [...]