heatmapFeature.js

  1. var inherit = require('./inherit');
  2. var feature = require('./feature');
  3. var transform = require('./transform');
  4. var util = require('./util');
  6. /**
  7.  * Heatmap feature specification.
  8.  *
  9.  * @typedef {geo.feature.spec} geo.heatmapFeature.spec
  10.  * @extends geo.feature.spec
  11.  * @property {geo.geoPosition|function} [position] Position of the data.
  12.  *   Default is (data).
  13.  * @property {function} [intensity] Scalar value of each data point.  The
  14.  *   scalar value must be a positive real number and is used to compute the
  15.  *   weight for each data point.
  16.  * @property {number} [maxIntensity=null] Maximum intensity of the data.
  17.  *   Maximum intensity must be a positive real number and is used to normalize
  18.  *   all intensities within a dataset.  If `null`, it is computed.
  19.  * @property {number} [minIntensity=null] Minimum intensity of the data.
  20.  *   Minimum intensity must be a positive real number and is used to normalize
  21.  *   all intensities within a dataset.  If `null`, it is computed.
  22.  * @property {number} [updateDelay=-1] Delay in milliseconds after a zoom,
  23.  *   rotate, or pan event before recomputing the heatmap.  If 0, this is double
  24.  *   the last render time.  If negative, it is roughly the last render time
  25.  *   plus the absolute value of the specified number of refresh intervals.
  26.  *   compute a delay based on the last heatmap render time.
  27.  * @property {boolean|number|'auto'} [binned='auto'] If `true` or a number,
  28.  *   spatially bin data as part of producing the heatmap.  If falsy, each
  29.  *   datapoint stands on its own.  If `'auto'`, bin data if there are more data
  30.  *   points than there would be bins.  Using `true` or `auto` uses bins that
  31.  *   are `max(Math.floor((radius + blurRadius) / 8), 3)`.
  32.  * @property {object} [style] A style for the heatmap.
  33.  * @property {object} [style.color] An object where the keys are numbers from
  34.  *   [0-1] and the values are {@link geo.geoColor}.  This is used to transform
  35.  *   normalized intensity.
  36.  * @property {number} [style.radius=10] Radius of a point in pixels.
  37.  * @property {number} [style.blurRadius=10] Blur radius for each point in
  38.  *   pixels.
  39.  * @property {boolean} [style.gaussian=true] If truthy, approximate a gaussian
  40.  *   distribution for each point using a multi-segment linear radial
  41.  *   approximation.  The total weight of the gaussian area is approximately the
  42.  *   `9/16 r^2`.  The sum of `radius + blurRadius` is used as the radius for
  43.  *   the gaussian distribution.
  44.  * @property {boolean} [scaleWithZoom=false] If truthy, the value for radius
  45.  *   and blurRadius scale with zoom.  In this case, the values for radius and
  46.  *   blurRadius are the values at zoom-level zero.  If the scaled radius is
  47.  *   less than 0.5 or more than 8192 screen pixels, the heatmap will not
  48.  *   render.
  49.  */
  51. /**
  52.  * Create a new instance of class heatmapFeature.
  53.  *
  54.  * @class
  55.  * @alias geo.heatmapFeature
  56.  * @param {geo.heatmapFeature.spec} arg Feature specification.
  57.  * @extends geo.feature
  58.  * @returns {geo.heatmapFeature}
  59.  */
  60. var heatmapFeature = function (arg) {
  61.   'use strict';
  62.   if (!(this instanceof heatmapFeature)) {
  63.     return new heatmapFeature(arg);
  64.   }
  65.   arg = arg || {};
  66.   feature.call(this, arg);
  68.   /**
  69.    * @private
  70.    */
  71.   var m_this = this,
  72.       m_position,
  73.       m_intensity,
  74.       m_maxIntensity,
  75.       m_minIntensity,
  76.       m_updateDelay,
  77.       m_binned,
  78.       m_gcsPosition,
  79.       s_init = this._init;
  81.   this.featureType = 'heatmap';
  83.   m_position = arg.position || util.identityFunction;
  84.   m_intensity = arg.intensity || function (d) { return 1; };
  85.   m_maxIntensity = arg.maxIntensity !== undefined ? arg.maxIntensity : null;
  86.   m_minIntensity = arg.minIntensity !== undefined ? arg.minIntensity : null;
  87.   m_binned = arg.binned !== undefined ? arg.binned : 'auto';
  88.   m_updateDelay = (arg.updateDelay || arg.updateDelay === 0) ? parseInt(arg.updateDelay, 10) : -1;
  90.   /**
  91.    * Get/Set maxIntensity.
  92.    *
  93.    * @param {number|null} [val] If not specified, return the current value.
  94.    *    If a number, use this as the maximum intensity.  If `null`, compute
  95.    *    the maximum intensity.
  96.    * @returns {number|null|this}
  97.    */
  98.   this.maxIntensity = function (val) {
  99.     if (val === undefined) {
  100.       return m_maxIntensity;
  101.     } else {
  102.       m_maxIntensity = val;
  103.       m_this.dataTime().modified();
  104.       m_this.modified();
  105.     }
  106.     return m_this;
  107.   };
  109.   /**
  110.    * Get/Set minIntensity.
  111.    *
  112.    * @param {number|null} [val] If not specified, return the current value.
  113.    *    If a number, use this as the minimum intensity.  If `null`, compute
  114.    *    the minimum intensity.
  115.    * @returns {number|null|this}
  116.    */
  117.   this.minIntensity = function (val) {
  118.     if (val === undefined) {
  119.       return m_minIntensity;
  120.     } else {
  121.       m_minIntensity = val;
  122.       m_this.dataTime().modified();
  123.       m_this.modified();
  124.     }
  125.     return m_this;
  126.   };
  128.   /**
  129.    * Get/Set updateDelay.
  130.    *
  131.    * @param {number} [val] If not specified, return the current update delay.
  132.    *    If specified, this is the delay in milliseconds after a zoom, rotate,
  133.    *    or pan event before recomputing the heatmap.  If 0, this is double the
  134.    *    last render time.  If negative, it is roughly the last render time plus
  135.    *    the absolute value of the specified number of refresh intervals.
  136.    * @returns {number|this}
  137.    */
  138.   this.updateDelay = function (val) {
  139.     if (val === undefined) {
  140.       return m_updateDelay;
  141.     } else {
  142.       m_updateDelay = parseInt(val, 10);
  143.     }
  144.     return m_this;
  145.   };
  147.   /**
  148.    * Get/Set binned value.
  149.    *
  150.    * @param {boolean|number|'auto'} [val] If not specified, return the current
  151.    *    binned value.  If `true` or a number, spatially bin data as part of
  152.    *    producing the heatmap.  If falsy, each datapoint stands on its own.
  153.    *    If `'auto'`, bin data if there are more data points than there would be
  154.    *    bins.  Using `true` or `auto` uses bins that are
  155.    *    `max(Math.floor((radius + blurRadius) / 8), 3)`.
  156.    * @returns {boolean|number|'auto'|this}
  157.    */
  158.   this.binned = function (val) {
  159.     if (val === undefined) {
  160.       return m_binned;
  161.     } else {
  162.       if (val === 'true') {
  163.         val = true;
  164.       } else if (val === 'false') {
  165.         val = false;
  166.       } else if (val !== 'auto' && val !== true && val !== false) {
  167.         val = parseInt(val, 10);
  168.         if (val <= 0 || isNaN(val)) {
  169.           val = false;
  170.         }
  171.       }
  172.       m_binned = val;
  173.       m_this.dataTime().modified();
  174.       m_this.modified();
  175.     }
  176.     return m_this;
  177.   };
  179.   /**
  180.    * Get/Set position accessor.
  181.    *
  182.    * @param {geo.geoPosition|function} [val] If not specified, return the
  183.    *    current position accessor.  If specified, use this for the position
  184.    *    accessor and return `this`.  If a function is given, this is called
  185.    *    with `(dataElement, dataIndex)`.
  186.    * @returns {geo.geoPosition|function|this} The current position or this
  187.    *    feature.
  188.    */
  189.   this.position = function (val) {
  190.     if (val === undefined) {
  191.       return m_position;
  192.     } else {
  193.       m_position = val;
  194.       m_this.dataTime().modified();
  195.       m_this.modified();
  196.     }
  197.     return m_this;
  198.   };
  200.   /**
  201.    * Get pre-computed gcs position accessor.
  202.    *
  203.    * @returns {geo.heatmap}
  204.    */
  205.   this.gcsPosition = function () {
  206.     m_this._update();
  207.     return m_gcsPosition;
  208.   };
  210.   /**
  211.    * Get/Set intensity.
  212.    *
  213.    * @param {function} [val] If not specified, the current intensity accessor.
  214.    *    Otherwise, a function that returns the intensity of each data point.
  215.    * @returns {function|this}
  216.    */
  217.   this.intensity = function (val) {
  218.     if (val === undefined) {
  219.       return m_intensity;
  220.     } else {
  221.       m_intensity = val;
  222.       m_this.dataTime().modified();
  223.       m_this.modified();
  224.     }
  225.     return m_this;
  226.   };
  228.   /**
  229.    * Initialize.
  230.    *
  231.    * @param {geo.heatmapFeature.spec} arg
  232.    */
  233.   this._init = function (arg) {
  234.     s_init.call(m_this, arg);
  236.     var defaultStyle = Object.assign(
  237.       {},
  238.       {
  239.         radius: 10,
  240.         blurRadius: 10,
  241.         gaussian: true,
  242.         color: {
  243.           0:    {r: 0, g: 0, b: 0.0, a: 0.0},
  244.           0.25: {r: 0, g: 0, b: 1, a: 0.5},
  245.           0.5:  {r: 0, g: 1, b: 1, a: 0.6},
  246.           0.75: {r: 1, g: 1, b: 0, a: 0.7},
  247.           1:    {r: 1, g: 0, b: 0, a: 0.8}},
  248.         scaleWithZoom: false
  249.       },
  250.       arg.style === undefined ? {} : arg.style
  251.     );
  253.     m_this.style(defaultStyle);
  255.     if (m_position) {
  256.       m_this.dataTime().modified();
  257.     }
  258.   };
  260.   /**
  261.    * Build the feature.
  262.    *
  263.    * @returns {this}
  264.    */
  265.   this._build = function () {
  266.     var data = m_this.data(),
  267.         intensity = null,
  268.         position = [],
  269.         setMax = (m_maxIntensity === null || m_maxIntensity === undefined),
  270.         setMin = (m_minIntensity === null || m_minIntensity === undefined);
  272.     data.forEach(function (d, i) {
  273.       position.push(m_this.position()(d, i));
  274.       if (setMax || setMin) {
  275.         intensity = m_this.intensity()(d, i);
  276.         if (m_maxIntensity === null || m_maxIntensity === undefined) {
  277.           m_maxIntensity = intensity;
  278.         }
  279.         if (m_minIntensity === null || m_minIntensity === undefined) {
  280.           m_minIntensity = intensity;
  281.         }
  282.         if (setMax && intensity > m_maxIntensity) {
  283.           m_maxIntensity = intensity;
  284.         }
  285.         if (setMin && intensity < m_minIntensity) {
  286.           m_minIntensity = intensity;
  287.         }
  289.       }
  290.     });
  291.     if (setMin && setMax && m_minIntensity === m_maxIntensity) {
  292.       m_minIntensity -= 1;
  293.     }
  294.     m_gcsPosition = transform.transformCoordinates(
  295.       m_this.gcs(), m_this.layer().map().gcs(), position);
  297.     m_this.buildTime().modified();
  298.     return m_this;
  299.   };
  301.   this._init(arg);
  302.   return this;
  303. };
  305. inherit(heatmapFeature, feature);
  306. module.exports = heatmapFeature;