Visualise dispersion of particles on a leaflet map.
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
L.setOptions ability to handle nested objects in initialiseshell
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
); or
- use the standalone version with dependencies bundled, in dist/leaflet-particles-standalone.js
use and options
Note that
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)`javascript
// 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|
|---|---|---|
|
||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
`javascript
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": [...]
``