Neurophysiologically Pseudoscientific Manatee

    leaflet-particles

    0.1.4 • Public • Published

    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:

    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": [...]

    Install

    npm i leaflet-particles

    DownloadsWeekly Downloads

    16

    Version

    0.1.4

    License

    none

    Unpacked Size

    108 kB

    Total Files

    9

    Last publish

    Collaborators

    • danwild