From a62a34efa089d7820db237cdce4b5500b6a87ccf Mon Sep 17 00:00:00 2001 From: David Manthey Date: Thu, 13 Sep 2018 16:23:25 -0400 Subject: [PATCH] Update the pixelmap feature documentation and fix a few typos. --- src/canvas/pixelmapFeature.js | 6 +- src/heatmapFeature.js | 33 ++++----- src/pixelmapFeature.js | 130 +++++++++++++++++++++++----------- src/pointFeature.js | 2 +- src/quadFeature.js | 4 +- 5 files changed, 112 insertions(+), 63 deletions(-) diff --git a/src/canvas/pixelmapFeature.js b/src/canvas/pixelmapFeature.js index 1f10ac9282..7ac299c70c 100644 --- a/src/canvas/pixelmapFeature.js +++ b/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'; diff --git a/src/heatmapFeature.js b/src/heatmapFeature.js index 7e579552f6..55bec6becf 100644 --- a/src/heatmapFeature.js +++ b/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} */ diff --git a/src/pixelmapFeature.js b/src/pixelmapFeature.js index 12ed2089c8..fc53405c9f 100644 --- a/src/pixelmapFeature.js +++ b/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; diff --git a/src/pointFeature.js b/src/pointFeature.js index 4844bbee46..1dbddd8674 100644 --- a/src/pointFeature.js +++ b/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. diff --git a/src/quadFeature.js b/src/quadFeature.js index 5dff8ac89d..ea976f1d04 100644 --- a/src/quadFeature.js +++ b/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) {