Merge pull request #928 from OpenGeoscience/update-pixelmap-docs

Update the pixelmap feature documentation and fix a few typos.

src/canvas/pixelmapFeature.js

@@ -3,13 +3,13 @@ var registerFeature = require('../registry').registerFeature;
 var pixelmapFeature = require('../pixelmapFeature');
 
 /**
- * Create a new instance of class pixelmapFeature
+ * Create a new instance of class pixelmapFeature.
  *
  * @class
  * @alias geo.canvas.pixelmapFeature
- * @param {Object} arg Options object
  * @extends geo.pixelmapFeature
- * @returns {canvas_pixelmapFeature}
+ * @param {geo.pixelmapFeature.spec} arg
+ * @returns {geo.canvas.pixelmapFeature}
  */
 var canvas_pixelmapFeature = function (arg) {
   'use strict';

src/heatmapFeature.js

@@ -9,28 +9,29 @@ var transform = require('./transform');
  * @typedef {geo.feature.spec} geo.heatmapFeature.spec
  * @property {geo.geoPosition|function} [position] Position of the data.
  *   Default is (data).
- * @param {function} [intensity] Scalar value of each data point.  The scalar
- *   value must be a positive real number and is used to compute the weight
- *   for each data point.
- * @param {number} [maxIntensity=null] Maximum intensity of the data.  Maximum
- *   intensity must be a positive real number and is used to normalize all
- *   intensities within a dataset.  If `null`, it is computed.
- * @param {number} [minIntensity=null] Minimum intensity of the data.  Minimum
- *   intensity must be a positive real number and is used to normalize all
- *   intensities within a dataset.  If `null`, it is computed.
- * @param {number} [updateDelay=1000] Delay in milliseconds after a zoom,
+ * @property {function} [intensity] Scalar value of each data point.  The
+ *   scalar value must be a positive real number and is used to compute the
+ *   weight for each data point.
+ * @property {number} [maxIntensity=null] Maximum intensity of the data.
+ *   Maximum intensity must be a positive real number and is used to normalize
+ *   all intensities within a dataset.  If `null`, it is computed.
+ * @property {number} [minIntensity=null] Minimum intensity of the data.
+ *   Minimum intensity must be a positive real number and is used to normalize
+ *   all intensities within a dataset.  If `null`, it is computed.
+ * @property {number} [updateDelay=1000] Delay in milliseconds after a zoom,
  *   rotate, or pan event before recomputing the heatmap.
- * @param {boolean|number|'auto'} [binned='auto'] If `true` or a number,
+ * @property {boolean|number|'auto'} [binned='auto'] If `true` or a number,
  *   spatially bin data as part of producing the heatmap.  If falsy, each
  *   datapoint stands on its own.  If `'auto'`, bin data if there are more data
  *   points than there would be bins.  Using `true` or `auto` uses bins that
  *   are `max(Math.floor((radius + blurRadius) / 8), 3)`.
- * @param {object} [style.color] An object where the keys are numbers from
+ * @property {object} [style.color] An object where the keys are numbers from
  *   [0-1] and the values are {@link geo.geoColor}.  This is used to transform
  *   normalized intensity.
- * @param {number} [style.radius=10] Radius of a point in pixels.
- * @param {number} [style.blurRadius=10] Blur radius for each point in pixels.
- * @param {boolean} [style.gaussian=true] If truthy, appoximate a gaussian
+ * @property {number} [style.radius=10] Radius of a point in pixels.
+ * @property {number} [style.blurRadius=10] Blur radius for each point in
+ *   pixels.
+ * @property {boolean} [style.gaussian=true] If truthy, appoximate a gaussian
  *   distribution for each point using a multi-segment linear radial
  *   appoximation.  The total weight of the gaussian area is approximately the
  *   `9/16 r^2`.  The sum of `radius + blurRadius` is used as the radius for
@@ -42,7 +43,7 @@ var transform = require('./transform');
  *
  * @class
  * @alias geo.heatmapFeature
- * @param {geo.heatmapFeature.spec} arg
+ * @param {geo.heatmapFeature.spec} arg Feature specification.
  * @extends geo.feature
  * @returns {geo.heatmapFeature}
  */

src/pixelmapFeature.js

@@ -5,31 +5,57 @@ var geo_event = require('./event');
 var util = require('./util');
 
 /**
- * Create a new instance of class imagemapFeature
+ * Pixelmap feature specification.
  *
- * @class
- * @alias geo.pixelmapFeature
- * @param {Object} arg Options object
- * @extends geo.feature
- * @param {Object|Function|HTMLImageElement} [url] URL of a pixel map or an
+ * @typedef {geo.feature.spec} geo.pixelmapFeature.spec
+ * @property {string|function|HTMLImageElement} [url] URL of a pixel map or an
  *   HTML Image element.  The rgb data is interpretted as an index of the form
  *   0xbbggrr.  The alpha channel is ignored.
- * @param {Object|Function} [color] The color that should be used for each data
- *   element.  Data elements correspond to the indices in the pixel map.  If an
- *   index is larger than the number of data elements, it will be transparent.
- *   If there is more data than there are indices, it is ignored.
- * @param {Object|Function} [position] Position of the image.  Default is
- *   (data).  The position is an Object which specifies the corners of the
- *   quad: ll, lr, ur, ul.  At least two opposite corners must be specified.
- *   The corners do not have to physically correspond to the order specified,
- *   but rather correspond to that part of the image map.  If a corner is
- *   unspecified, it will use the x coordinate from one adjacent corner, the y
- *   coordinate from the other adjacent corner, and the average z value of
- *   those two corners.  For instance, if ul is unspecified, it is
+ * @property {geo.geoColor|function} [color] The color that should be used
+ *   for each data element.  Data elements correspond to the indices in the
+ *   pixel map. If an index is larger than the number of data elements, it will
+ *   be transparent.  If there is more data than there are indices, it is
+ *   ignored.
+ * @property {geo.geoPosition|function} [position] Position of the image.
+ *   Default is (data).  The position is an Object which specifies the corners
+ *   of the quad: ll, lr, ur, ul.  At least two opposite corners must be
+ *   specified.  The corners do not have to physically correspond to the order
+ *   specified, but rather correspond to that part of the image map.  If a
+ *   corner is unspecified, it will use the x coordinate from one adjacent
+ *   corner, the y coordinate from the other adjacent corner, and the average z
+ *   value of those two corners.  For instance, if ul is unspecified, it is
  *   {x: ll.x, y: ur.y}.  Note that each quad is rendered as a pair of
  *   triangles: (ll, lr, ul) and (ur, ul, lr).  Nothing special is done for
  *   quads that are not convex or quads that have substantially different
  *   transformations for those two triangles.
+ */
+
+/**
+ * Pixelmap feature information record.
+ *
+ * @typedef {object} geo.pixelmapFeature.info
+ * @property {number} width The width of the source image.
+ * @property {number} height The width of the source image.
+ * @property {context} context The HTMLCanvasElement context used for handling
+ *    the pixelmap.
+ * @property {ImageData} imageData The context's image data.
+ * @property {number[]} indices An array, one per pixel, of the index value in
+ *    the image.  This decodes the pixel value to the corresponding integer.
+ * @property number} area The number of pixels in the image.  This is
+ *    `width * height`.
+ * @property {object[]} mappedColors This has one entry for each distinct index
+ *    value.  Each entry has `first` and `last` with the first and last pixel
+ *    locations where that index occurs.  Note that last is the inclusive value
+ *    of the location (so its maximum possible value is `size -1`).
+ */
+
+/**
+ * Create a new instance of class pixelmapFeature
+ *
+ * @class
+ * @alias geo.pixelmapFeature
+ * @param {geo.pixelmapFeature.spec} arg Options object.
+ * @extends geo.feature
  * @returns {geo.pixelmapFeature}
  */
 
@@ -53,9 +79,13 @@ var pixelmapFeature = function (arg) {
       s_exit = this._exit;
 
   /**
-   * Get/Set position accessor
+   * Get/Set position accessor.
    *
-   * @returns {geo.pixelmap}
+   * @param {geo.geoPosition|function} [val] If not specified, return the
+   *    current position accessor.  If specified, use this for the position
+   *    accessor and return `this`.  See {@link geo.quadFeature.position} for
+   *    for details on this position.
+   * @returns {geo.geoPosition|function|this}
    */
   this.position = function (val) {
     if (val === undefined) {
@@ -69,9 +99,12 @@ var pixelmapFeature = function (arg) {
   };
 
   /**
-   * Get/Set url accessor
+   * Get/Set url accessor.
    *
-   * @returns {geo.pixelmap}
+   * @param {string|function} [val] If not specified, return the current url
+   *    accessor.  If specified, use this for the url accessor and return
+   *    `this`.
+   * @returns {string|function|this}
    */
   this.url = function (val) {
     if (val === undefined) {
@@ -89,7 +122,7 @@ var pixelmapFeature = function (arg) {
    * Get the maximum index value from the pixelmap.  This is a value present in
    * the pixelmap.
    *
-   * @returns {geo.pixelmap}
+   * @returns {number} The maximum index value.
    */
   this.maxIndex = function () {
     if (m_info) {
@@ -108,9 +141,11 @@ var pixelmapFeature = function (arg) {
   };
 
   /**
-   * Get/Set color accessor
+   * Get/Set color accessor.
    *
-   * @returns {geo.pixelmap}
+   * @param {geo.geoColor|function} [val] The new color map accessor or
+   *    `undefined` to get the current accessor.
+   * @returns {geo.geoColor|function|this}
    */
   this.color = function (val) {
     if (val === undefined) {
@@ -126,14 +161,15 @@ var pixelmapFeature = function (arg) {
   /**
    * If the specified coordinates are in the rendered quad, use the basis
    * information from the quad to determine the pixelmap index value so that it
-   * can be included in the found results.
+   * can be included in the `found` results.
    *
-   * @param {geo.geoPosition} coordinate point to search for in map interface
-   *    gcs.
+   * @param {geo.geoPosition} geo Coordinate in interface gcs.
+   * @returns {geo.feature.searchResult} An object with a list of features and
+   *    feature indices that are located at the specified point.
    */
-  this.pointSearch = function (coordinate) {
+  this.pointSearch = function (geo) {
     if (m_quadFeature && m_info) {
-      var result = m_quadFeature.pointSearch(coordinate);
+      var result = m_quadFeature.pointSearch(geo);
       if (result.index.length === 1 && result.extra && result.extra[result.index[0]].basis) {
         var basis = result.extra[result.index[0]].basis, x, y, idx;
         x = Math.floor(basis.x * m_info.width);
@@ -153,12 +189,14 @@ var pixelmapFeature = function (arg) {
   };
 
   /**
-   * Build
+   * Build.  Fetches the image if necesary.
+   *
+   * @returns {this}
    */
   this._build = function () {
     /* Set the build time at the start of the call.  A build can result in
-     * drawing a quad, which can trigger a full layer update, which in tern
-     * checks if this feature is built.  Setting the build time avoid calling
+     * drawing a quad, which can trigger a full layer update, which in turn
+     * checks if this feature is built.  Setting the build time avoids calling
      * this a second time. */
     m_this.buildTime().modified();
     if (!m_srcImage) {
@@ -215,9 +253,11 @@ var pixelmapFeature = function (arg) {
   };
 
   /**
-   * Compute information for this pixelmap image.  It is wasterful to call this
+   * Compute information for this pixelmap image.  It is wasteful to call this
    * if the pixelmap has already been prepared (it is invalidated by a change
    * in the image).
+   *
+   * @returns {geo.pixelmapFeature.info}
    */
   this._preparePixelmap = function () {
     var i, idx, pixelData;
@@ -228,8 +268,7 @@ var pixelmapFeature = function (arg) {
     m_info = {
       width: m_srcImage.naturalWidth,
       height: m_srcImage.naturalHeight,
-      canvas: document.createElement('canvas'),
-      updateIdx: {}
+      canvas: document.createElement('canvas')
     };
 
     m_info.canvas.width = m_info.width;
@@ -348,7 +387,9 @@ var pixelmapFeature = function (arg) {
   };
 
   /**
-   * Update
+   * Update.
+   *
+   * @returns {this}
    */
   this._update = function () {
     s_update.call(m_this);
@@ -362,20 +403,25 @@ var pixelmapFeature = function (arg) {
   };
 
   /**
-   * Destroy
-   * @memberof geo.pixelmapFeature
+   * Destroy.  Deletes the associated quadFeature.
+   *
+   * @returns {this}
    */
-  this._exit = function (abc) {
+  this._exit = function () {
     if (m_quadFeature && m_this.layer()) {
       m_this.layer().deleteFeature(m_quadFeature);
       m_quadFeature = null;
       m_this.dependentFeatures([]);
     }
     s_exit();
+    return m_this;
   };
 
   /**
-   * Initialize
+   * Initialize.
+   *
+   * @param {geo.pixelmapFeature.spec} arg
+   * @returns {this}
    */
   this._init = function (arg) {
     arg = arg || {};
@@ -407,6 +453,8 @@ var pixelmapFeature = function (arg) {
     }
     m_this.style(style);
     m_this.dataTime().modified();
+
+    return m_this;
   };
 
   return this;

src/pointFeature.js

@@ -195,7 +195,7 @@ var pointFeature = function (arg) {
   /**
    * Get/Set position.
    *
-   * @param {function|geo.geoPosition} [val]  If not specified, return the
+   * @param {function|geo.geoPosition} [val] If not specified, return the
    *    position accessor, which is guaranteed to be a function.  If specified,
    *    wrap the value in an function that handles clustering if it is enabled
    *    and set the position accessor to that function.

src/quadFeature.js

@@ -209,9 +209,9 @@ var quadFeature = function (arg) {
    * Get/Set position.
    *
    * @memberof geo.quadFeature
-   * @param {object|Function} [val] Object or function that returns the
+   * @param {object|function} [val] Object or function that returns the
    *    position of each quad.  `undefined` to get the current position value.
-   * @returns {geo.quadFeature}
+   * @returns {geo.quadFeature|this}
    */
   this.position = function (val) {
     if (val === undefined) {