Clarify behavior of some existing turf modules (#2683)

* update turf-rectangle-grid and turf-square-grid docs * improve area docs * cleanup * update earthRadius, first crack at units link, other nits * improve docs * nit * add readme units file * update area readme manually * one more readme * update all readmes
Turfjs · Aug 9, 2024 · 5f0d405 · 5f0d405
1 parent ad8012c
commit 5f0d405
Show file tree

Hide file tree

Showing 13 changed files with 282 additions and 228 deletions.
diff --git a/packages/turf-area/README.md b/packages/turf-area/README.md
@@ -4,11 +4,11 @@
 
 ## area
 
-Takes one or more features and returns their area in square meters.
+Calculates the geodesic area in square meters of one or more polygons.
 
 ### Parameters
 
-*   `geojson` **[GeoJSON][1]** input GeoJSON feature(s)
+*   `geojson` **[GeoJSON][1]** input polygon(s) as [Geometry][2], [Feature][3], or [FeatureCollection][4]
 
 ### Examples
 
@@ -22,11 +22,17 @@ var addToMap = [polygon]
 polygon.properties.area = area
 ```
 
-Returns **[number][2]** area in square meters
+Returns **[number][5]** area in square meters
 
 [1]: https://tools.ietf.org/html/rfc7946#section-3
 
-[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[2]: https://tools.ietf.org/html/rfc7946#section-3.1
+
+[3]: https://tools.ietf.org/html/rfc7946#section-3.2
+
+[4]: https://tools.ietf.org/html/rfc7946#section-3.3
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
 <!-- This file is automatically generated. Please don't edit it directly. If you find an error, edit the source file of the module in question (likely index.js or index.ts), and re-run "yarn docs" from the root of the turf project. -->
 

diff --git a/packages/turf-area/index.ts b/packages/turf-area/index.ts
@@ -3,10 +3,10 @@ import { earthRadius } from "@turf/helpers";
 import { geomReduce } from "@turf/meta";
 
 /**
- * Takes one or more features and returns their area in square meters.
+ * Calculates the geodesic area in square meters of one or more polygons.
  *
  * @name area
- * @param {GeoJSON} geojson input GeoJSON feature(s)
+ * @param {GeoJSON} geojson input polygon(s) as {@link Geometry}, {@link Feature}, or {@link FeatureCollection}
  * @returns {number} area in square meters
  * @example
  * var polygon = turf.polygon([[[125, -15], [113, -22], [154, -27], [144, -15], [125, -15]]]);

diff --git a/packages/turf-helpers/README.md b/packages/turf-helpers/README.md
diff --git a/packages/turf-helpers/README_UNITS.md b/packages/turf-helpers/README_UNITS.md
@@ -0,0 +1,37 @@
+# @turf/helpers
+
+## Units
+
+* meters
+* metres
+* millimeters
+* millimetres
+* centimeters
+* centimetres
+* kilometers
+* kilometres
+* miles
+* nauticalmiles
+* inches
+* yards
+* feet
+* radians
+* degrees
+
+## AreaUnits
+
+* meters
+* metres
+* millimeters
+* millimetres
+* centimeters
+* centimetres
+* kilometers
+* kilometres
+* miles
+* nauticalmiles
+* inches
+* yards
+* feet
+* acres
+* hectares
diff --git a/packages/turf-helpers/index.ts b/packages/turf-helpers/index.ts
@@ -57,15 +57,14 @@ export type AllGeoJSON =
  */
 
 /**
- * Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.
- *
+ * The Earth radius in kilometers. Used by Turf modules that model the Earth as a sphere. The {@link https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius mean radius} was selected because it is {@link https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended recommended } by the Haversine formula (used by turf/distance) to reduce error.
  * @memberof helpers
  * @type {number}
  */
 export const earthRadius = 6371008.8;
 
 /**
- * Unit of measurement factors using a spherical (non-ellipsoid) earth radius.
+ * Unit of measurement factors based on earthRadius.
  *
  * Keys are the name of the unit, values are the number of that unit in a single radian
  *

diff --git a/packages/turf-point-grid/README.md b/packages/turf-point-grid/README.md
@@ -4,17 +4,17 @@
 
 ## pointGrid
 
-Creates a [Point][1] grid from a bounding box, [FeatureCollection][2] or [Feature][3].
+Creates a grid of points
 
 ### Parameters
 
-*   `bbox` **[Array][4]<[number][5]>** extent in \[minX, minY, maxX, maxY] order
-*   `cellSide` **[number][5]** the distance between points, in units
-*   `options` **[Object][6]** Optional parameters (optional, default `{}`)
+*   `bbox` **[BBox][1]** extent of grid in \[minX, minY, maxX, maxY] order
+*   `cellSide` **[number][2]** the distance between points
+*   `options` **[Object][3]** Optional parameters (optional, default `{}`)
 
-    *   `options.units` **[string][7]** used in calculating cellSide, can be degrees, radians, miles, or kilometers (optional, default `'kilometers'`)
-    *   `options.mask` **[Feature][3]<([Polygon][8] | [MultiPolygon][9])>?** if passed a Polygon or MultiPolygon, the grid Points will be created only inside it
-    *   `options.properties` **[Object][6]** passed to each point of the grid (optional, default `{}`)
+    *   `options.units` **Units** the units of the cellSide value.  Supports all valid Turf [Units][4] (optional, default `'kilometers'`)
+    *   `options.mask` **[Feature][5]<([Polygon][6] | [MultiPolygon][7])>?** if passed a Polygon or MultiPolygon, the grid Points will be created only inside it
+    *   `options.properties` **[Object][3]** passed to each point of the grid (optional, default `{}`)
 
 ### Examples
 
@@ -29,25 +29,25 @@ var grid = turf.pointGrid(extent, cellSide, options);
 var addToMap = [grid];
 ```
 
-Returns **[FeatureCollection][2]<[Point][1]>** grid of points
+Returns **[FeatureCollection][8]<[Point][9]>** grid of points
 
-[1]: https://tools.ietf.org/html/rfc7946#section-3.1.2
+[1]: https://tools.ietf.org/html/rfc7946#section-5
 
-[2]: https://tools.ietf.org/html/rfc7946#section-3.3
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[3]: https://tools.ietf.org/html/rfc7946#section-3.2
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[4]: https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[5]: https://tools.ietf.org/html/rfc7946#section-3.2
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[6]: https://tools.ietf.org/html/rfc7946#section-3.1.6
 
-[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[7]: https://tools.ietf.org/html/rfc7946#section-3.1.7
 
-[8]: https://tools.ietf.org/html/rfc7946#section-3.1.6
+[8]: https://tools.ietf.org/html/rfc7946#section-3.3
 
-[9]: https://tools.ietf.org/html/rfc7946#section-3.1.7
+[9]: https://tools.ietf.org/html/rfc7946#section-3.1.2
 
 <!-- This file is automatically generated. Please don't edit it directly. If you find an error, edit the source file of the module in question (likely index.js or index.ts), and re-run "yarn docs" from the root of the turf project. -->
 

diff --git a/packages/turf-point-grid/index.ts b/packages/turf-point-grid/index.ts
@@ -12,13 +12,13 @@ import { distance } from "@turf/distance";
 import { point, featureCollection, Units } from "@turf/helpers";
 
 /**
- * Creates a {@link Point} grid from a bounding box, {@link FeatureCollection} or {@link Feature}.
+ * Creates a grid of points
  *
  * @name pointGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellSide the distance between points, in units
+ * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order
+ * @param {number} cellSide the distance between points
  * @param {Object} [options={}] Optional parameters
- * @param {string} [options.units='kilometers'] used in calculating cellSide, can be degrees, radians, miles, or kilometers
+ * @param {Units} [options.units='kilometers'] the units of the cellSide value.  Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units}
  * @param {Feature<Polygon|MultiPolygon>} [options.mask] if passed a Polygon or MultiPolygon, the grid Points will be created only inside it
  * @param {Object} [options.properties={}] passed to each point of the grid
  * @returns {FeatureCollection<Point>} grid of points

diff --git a/packages/turf-rectangle-grid/README.md b/packages/turf-rectangle-grid/README.md
@@ -4,20 +4,22 @@
 
 ## rectangleGrid
 
-Creates a grid of rectangles from a bounding box, [Feature][1] or [FeatureCollection][2].
+Creates a grid of rectangular polygons with width and height consistent in degrees
 
 ### Parameters
 
-*   `bbox` **[Array][3]<[number][4]>** extent in \[minX, minY, maxX, maxY] order
-*   `cellWidth` **[number][4]** of each cell, in units
-*   `cellHeight` **[number][4]** of each cell, in units
-*   `options` **[Object][5]** Optional parameters (optional, default `{}`)
+*   `bbox` **[BBox][1]** extent of grid in \[minX, minY, maxX, maxY] order.  If the grid does not fill the bbox perfectly, it is centered.
+*   `cellWidth` **[number][2]** width of each cell, in units
+*   `cellHeight` **[number][2]** height of each cell, in units
+*   `options` **[Object][3]** Optional parameters (optional, default `{}`)
 
-    *   `options.units` **[string][6]** units ("degrees", "radians", "miles", "kilometers") that the given cellWidth
-        and cellHeight are expressed in. Converted at the southern border. (optional, default `'kilometers'`)
-    *   `options.mask` **[Feature][1]<([Polygon][7] | [MultiPolygon][8])>?** if passed a Polygon or MultiPolygon,
+    *   `options.units` **Units** the units of the cell width and height value.
+        Supports all valid Turf [Units][4].
+        If you are looking for rectangles with equal width and height in linear units (e.g. kilometers) this is not the module for you.
+        The cellWidth and cellHeight is converted from units provided to degrees internally, so the width and height of resulting polygons will be consistent only in degrees. (optional, default `'kilometers'`)
+    *   `options.mask` **[Feature][5]<([Polygon][6] | [MultiPolygon][7])>?** if passed a Polygon or MultiPolygon,
         the grid Points will be created only inside it
-    *   `options.properties` **[Object][5]** passed to each point of the grid (optional, default `{}`)
+    *   `options.properties` **[Object][3]** passed to each point of the grid (optional, default `{}`)
 
 ### Examples
 
@@ -33,23 +35,23 @@ var rectangleGrid = turf.rectangleGrid(bbox, cellWidth, cellHeight, options);
 var addToMap = [rectangleGrid]
 ```
 
-Returns **[FeatureCollection][2]<[Polygon][7]>** a grid of polygons
+Returns **[FeatureCollection][8]<[Polygon][6]>** a grid of polygons
 
-[1]: https://tools.ietf.org/html/rfc7946#section-3.2
+[1]: https://tools.ietf.org/html/rfc7946#section-5
 
-[2]: https://tools.ietf.org/html/rfc7946#section-3.3
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[4]: https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[5]: https://tools.ietf.org/html/rfc7946#section-3.2
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[6]: https://tools.ietf.org/html/rfc7946#section-3.1.6
 
-[7]: https://tools.ietf.org/html/rfc7946#section-3.1.6
+[7]: https://tools.ietf.org/html/rfc7946#section-3.1.7
 
-[8]: https://tools.ietf.org/html/rfc7946#section-3.1.7
+[8]: https://tools.ietf.org/html/rfc7946#section-3.3
 
 <!-- This file is automatically generated. Please don't edit it directly. If you find an error, edit the source file of the module in question (likely index.js or index.ts), and re-run "yarn docs" from the root of the turf project. -->
 

diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts
@@ -14,15 +14,17 @@ import {
   Units,
 } from "@turf/helpers";
 /**
- * Creates a grid of rectangles from a bounding box, {@link Feature} or {@link FeatureCollection}.
+ * Creates a grid of rectangular polygons with width and height consistent in degrees
  *
  * @name rectangleGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellWidth of each cell, in units
- * @param {number} cellHeight of each cell, in units
+ * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order.  If the grid does not fill the bbox perfectly, it is centered.
+ * @param {number} cellWidth width of each cell, in units
+ * @param {number} cellHeight height of each cell, in units
  * @param {Object} [options={}] Optional parameters
- * @param {string} [options.units='kilometers'] units ("degrees", "radians", "miles", "kilometers") that the given cellWidth
- * and cellHeight are expressed in. Converted at the southern border.
+ * @param {Units} [options.units='kilometers'] the units of the cell width and height value.
+ * Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units}.
+ * If you are looking for rectangles with equal width and height in linear units (e.g. kilometers) this is not the module for you.
+ * The cellWidth and cellHeight is converted from units provided to degrees internally, so the width and height of resulting polygons will be consistent only in degrees.
  * @param {Feature<Polygon|MultiPolygon>} [options.mask] if passed a Polygon or MultiPolygon,
  * the grid Points will be created only inside it
  * @param {Object} [options.properties={}] passed to each point of the grid

diff --git a/packages/turf-square-grid/README.md b/packages/turf-square-grid/README.md
@@ -4,16 +4,18 @@
 
 ## squareGrid
 
-Creates a square grid from a bounding box.
+Creates a grid of square polygons with cell length consistent in degrees
 
 ### Parameters
 
-*   `bbox` **[Array][1]<[number][2]>** extent in \[minX, minY, maxX, maxY] order
-*   `cellSide` **[number][2]** of each cell, in units
+*   `bbox` **[BBox][1]** extent of grid in \[minX, minY, maxX, maxY] order.  If the grid does not fill the bbox perfectly, it is centered.
+*   `cellSide` **[number][2]** length of each cell side.
 *   `options` **[Object][3]** Optional parameters (optional, default `{}`)
 
-    *   `options.units` **[string][4]** used in calculating cellSide, can be degrees,
-        radians, miles, or kilometers (optional, default `'kilometers'`)
+    *   `options.units` **Units** the units of the cellSide value.
+        Supports all valid Turf [Units][4].
+        If you are looking for squares with sides of equal lengths in linear units (e.g. kilometers) this is not the module for you.
+        The cellSide is converted from units provided to degrees internally, so the width and height of resulting polygons will be consistent only in degrees. (optional, default `'kilometers'`)
     *   `options.mask` **[Feature][5]<([Polygon][6] | [MultiPolygon][7])>?** if passed a Polygon or MultiPolygon,
         the grid Points will be created only inside it
     *   `options.properties` **[Object][3]** passed to each point of the grid (optional, default `{}`)
@@ -31,15 +33,15 @@ var squareGrid = turf.squareGrid(bbox, cellSide, options);
 var addToMap = [squareGrid]
 ```
 
-Returns **[FeatureCollection][8]<[Polygon][6]>** grid a grid of polygons
+Returns **[FeatureCollection][8]<[Polygon][6]>** a grid of polygons with equal width and height in degrees.
 
-[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[1]: https://tools.ietf.org/html/rfc7946#section-5
 
 [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
 [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[4]: https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md
 
 [5]: https://tools.ietf.org/html/rfc7946#section-3.2
 

diff --git a/packages/turf-square-grid/index.ts b/packages/turf-square-grid/index.ts
@@ -10,18 +10,20 @@ import { Units } from "@turf/helpers";
 import { rectangleGrid } from "@turf/rectangle-grid";
 
 /**
- * Creates a square grid from a bounding box.
+ * Creates a grid of square polygons with cell length consistent in degrees
  *
  * @name squareGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellSide of each cell, in units
+ * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order.  If the grid does not fill the bbox perfectly, it is centered.
+ * @param {number} cellSide length of each cell side.
  * @param {Object} [options={}] Optional parameters
- * @param {string} [options.units='kilometers'] used in calculating cellSide, can be degrees,
- * radians, miles, or kilometers
+ * @param {Units} [options.units='kilometers'] the units of the cellSide value.
+ * Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units}.
+ * If you are looking for squares with sides of equal lengths in linear units (e.g. kilometers) this is not the module for you.
+ * The cellSide is converted from units provided to degrees internally, so the width and height of resulting polygons will be consistent only in degrees.
  * @param {Feature<Polygon|MultiPolygon>} [options.mask] if passed a Polygon or MultiPolygon,
  * the grid Points will be created only inside it
  * @param {Object} [options.properties={}] passed to each point of the grid
- * @returns {FeatureCollection<Polygon>} grid a grid of polygons
+ * @returns {FeatureCollection<Polygon>} a grid of polygons with equal width and height in degrees.
  * @example
  * var bbox = [-95, 30 ,-85, 40];
  * var cellSide = 50;

diff --git a/packages/turf-triangle-grid/README.md b/packages/turf-triangle-grid/README.md
@@ -4,17 +4,17 @@
 
 ## triangleGrid
 
-Takes a bounding box and a cell depth and returns a set of triangular [polygons][1] in a grid.
+Creates a grid of triangular polygons.
 
 ### Parameters
 
-*   `bbox` **[Array][2]<[number][3]>** extent in \[minX, minY, maxX, maxY] order
-*   `cellSide` **[number][3]** dimension of each cell
-*   `options` **[Object][4]** Optional parameters (optional, default `{}`)
+*   `bbox` **[BBox][1]** extent of grid in \[minX, minY, maxX, maxY] order
+*   `cellSide` **[number][2]** dimension of each grid cell.  Two triangles are created in each cell.
+*   `options` **[Object][3]** Optional parameters (optional, default `{}`)
 
-    *   `options.units` **[string][5]** used in calculating cellSide, can be degrees, radians, miles, or kilometers (optional, default `'kilometers'`)
-    *   `options.mask` **[Feature][6]<[Polygon][1]>?** if passed a Polygon or MultiPolygon, the grid Points will be created only inside it
-    *   `options.properties` **[Object][4]** passed to each point of the grid (optional, default `{}`)
+    *   `options.units` **Units** used in calculating cellSide.  Supports all valid Turf [Units][4] (optional, default `'kilometers'`)
+    *   `options.mask` **[Feature][5]<[Polygon][6]>?** if passed a Polygon or MultiPolygon, the grid Points will be created only inside it
+    *   `options.properties` **[Object][3]** passed to each point of the grid (optional, default `{}`)
 
 ### Examples
 
@@ -29,19 +29,19 @@ var triangleGrid = turf.triangleGrid(bbox, cellSide, options);
 var addToMap = [triangleGrid];
 ```
 
-Returns **[FeatureCollection][7]<[Polygon][1]>** grid of polygons
+Returns **[FeatureCollection][7]<[Polygon][6]>** grid of polygons
 
-[1]: https://tools.ietf.org/html/rfc7946#section-3.1.6
+[1]: https://tools.ietf.org/html/rfc7946#section-5
 
-[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[4]: https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[5]: https://tools.ietf.org/html/rfc7946#section-3.2
 
-[6]: https://tools.ietf.org/html/rfc7946#section-3.2
+[6]: https://tools.ietf.org/html/rfc7946#section-3.1.6
 
 [7]: https://tools.ietf.org/html/rfc7946#section-3.3