From 8b7a57e7fadb0959d807d22d86692b866ca9a36a Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Tue, 6 Aug 2024 22:50:42 -0700 Subject: [PATCH 01/10] update turf-rectangle-grid and turf-square-grid docs --- packages/turf-rectangle-grid/index.ts | 7 +++---- packages/turf-square-grid/index.ts | 10 +++++----- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts index 68492330a5..548faaceb7 100644 --- a/packages/turf-rectangle-grid/index.ts +++ b/packages/turf-rectangle-grid/index.ts @@ -14,15 +14,14 @@ import { Units, } from "@turf/helpers"; /** - * Creates a grid of rectangles from a bounding box, {@link Feature} or {@link FeatureCollection}. + * Creates a rectangular grid, with polygon cells of equal width and height in degrees. * * @name rectangleGrid - * @param {Array} bbox extent in [minX, minY, maxX, maxY] order + * @param {Array} 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 of each cell, in units * @param {number} cellHeight 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 {string} [options.units='kilometers'] the units the cellWidth and cellLenth values are expressed in, defaults to kilometers. Internally cellWidth and cellLength values are converted to degrees, regardless of input units. * @param {Feature} [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/index.ts b/packages/turf-square-grid/index.ts index e70a5e9537..6cd0b1d611 100644 --- a/packages/turf-square-grid/index.ts +++ b/packages/turf-square-grid/index.ts @@ -10,18 +10,18 @@ import { Units } from "@turf/helpers"; import { rectangleGrid } from "@turf/rectangle-grid"; /** - * Creates a square grid from a bounding box. + * Creates a square grid, with polygon cells with equal length sides in degrees. * * @name squareGrid - * @param {Array} bbox extent in [minX, minY, maxX, maxY] order - * @param {number} cellSide of each cell, in units + * @param {Array} 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, + * @param {string} [options.units='kilometers'] the units the cellSide value is expressed in, defaults to kilometers. Internally cellSide value is converted to degrees, regardless of input units. * radians, miles, or kilometers * @param {Feature} [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} grid a grid of polygons + * @returns {FeatureCollection} a grid of polygons with equal width and height in degrees. * @example * var bbox = [-95, 30 ,-85, 40]; * var cellSide = 50; From e0ac5ff11f0ac10cd6c7eb85fd2cfc3245d85319 Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Tue, 6 Aug 2024 23:16:33 -0700 Subject: [PATCH 02/10] improve area docs --- packages/turf-area/index.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/turf-area/index.ts b/packages/turf-area/index.ts index 51887938fb..3b0c7a1d57 100644 --- 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]]]); From cd887508a700852bd7e92f705351513111bc2486 Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Tue, 6 Aug 2024 23:35:09 -0700 Subject: [PATCH 03/10] cleanup --- packages/turf-rectangle-grid/index.ts | 6 +++--- packages/turf-square-grid/index.ts | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts index 548faaceb7..d52f263c2a 100644 --- a/packages/turf-rectangle-grid/index.ts +++ b/packages/turf-rectangle-grid/index.ts @@ -18,10 +18,10 @@ import { * * @name rectangleGrid * @param {Array} 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 of each cell, in units - * @param {number} cellHeight of each cell, in units + * @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'] the units the cellWidth and cellLenth values are expressed in, defaults to kilometers. Internally cellWidth and cellLength values are converted to degrees, regardless of input units. + * @param {string} [options.units='kilometers'] the units the cellWidth and cellLenth values are expressed in. Internally cellWidth and cellLength values are converted to degrees, regardless of units specified. * @param {Feature} [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/index.ts b/packages/turf-square-grid/index.ts index 6cd0b1d611..cc98a58c77 100644 --- a/packages/turf-square-grid/index.ts +++ b/packages/turf-square-grid/index.ts @@ -16,7 +16,7 @@ import { rectangleGrid } from "@turf/rectangle-grid"; * @param {Array} 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'] the units the cellSide value is expressed in, defaults to kilometers. Internally cellSide value is converted to degrees, regardless of input units. + * @param {string} [options.units='kilometers'] the units the cellSide value is expressed in. Internally cellSide value is converted to degrees, regardless of units specified. * radians, miles, or kilometers * @param {Feature} [options.mask] if passed a Polygon or MultiPolygon, * the grid Points will be created only inside it From c5fe4449e83c6e91e4f35a1b8acde47416699f8a Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Wed, 7 Aug 2024 00:50:48 -0700 Subject: [PATCH 04/10] update earthRadius, first crack at units link, other nits --- packages/turf-helpers/index.ts | 8 +++++--- packages/turf-point-grid/index.ts | 8 ++++---- packages/turf-rectangle-grid/index.ts | 4 ++-- packages/turf-square-grid/index.ts | 4 ++-- packages/turf-triangle-grid/index.ts | 8 ++++---- 5 files changed, 17 insertions(+), 15 deletions(-) diff --git a/packages/turf-helpers/index.ts b/packages/turf-helpers/index.ts index 6f22d110f1..dce32a5a1a 100644 --- a/packages/turf-helpers/index.ts +++ b/packages/turf-helpers/index.ts @@ -57,15 +57,17 @@ export type AllGeoJSON = */ /** - * Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth. - * + * The {@link https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius arithmetic mean radius} of the Earth. + * Used by Turf modules that model the Earth as a sphere. This radii value + * was chosen over others because it is {@link https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended recommended for use} with the Haversine formula, + * used by turf/distance. * @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 equatorial 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/index.ts b/packages/turf-point-grid/index.ts index 05e8d716e8..fdbea91f76 100644 --- 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} bbox extent in [minX, minY, maxX, maxY] order - * @param {number} cellSide the distance between points, in units + * @param {Array} 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 {string} [options.units='kilometers'] the units of the cellSide value. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units} * @param {Feature} [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} grid of points diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts index d52f263c2a..b88f4e4255 100644 --- a/packages/turf-rectangle-grid/index.ts +++ b/packages/turf-rectangle-grid/index.ts @@ -14,14 +14,14 @@ import { Units, } from "@turf/helpers"; /** - * Creates a rectangular grid, with polygon cells of equal width and height in degrees. + * Creates a grid of rectangular polygon cells of equal width and height in degrees. * * @name rectangleGrid * @param {Array} 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'] the units the cellWidth and cellLenth values are expressed in. Internally cellWidth and cellLength values are converted to degrees, regardless of units specified. + * @param {string} [options.units='kilometers'] the units of the cellWidth and cellLenth values. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units}. Internally cellWidth and cellLength values are converted to degrees, regardless of units specified. * @param {Feature} [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/index.ts b/packages/turf-square-grid/index.ts index cc98a58c77..a918602664 100644 --- a/packages/turf-square-grid/index.ts +++ b/packages/turf-square-grid/index.ts @@ -10,13 +10,13 @@ import { Units } from "@turf/helpers"; import { rectangleGrid } from "@turf/rectangle-grid"; /** - * Creates a square grid, with polygon cells with equal length sides in degrees. + * Creates a grid of square polygon cells with equal length sides in degrees. * * @name squareGrid * @param {Array} 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'] the units the cellSide value is expressed in. Internally cellSide value is converted to degrees, regardless of units specified. + * @param {string} [options.units='kilometers'] the units of the cellSide value. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units}. Internally cellSide value is converted to degrees, regardless of units specified. * radians, miles, or kilometers * @param {Feature} [options.mask] if passed a Polygon or MultiPolygon, * the grid Points will be created only inside it diff --git a/packages/turf-triangle-grid/index.ts b/packages/turf-triangle-grid/index.ts index cb8337c568..5764807744 100644 --- a/packages/turf-triangle-grid/index.ts +++ b/packages/turf-triangle-grid/index.ts @@ -10,13 +10,13 @@ import { intersect } from "@turf/intersect"; import { polygon, featureCollection, Units } from "@turf/helpers"; /** - * Takes a bounding box and a cell depth and returns a set of triangular {@link Polygon|polygons} in a grid. + * Creates a grid of triangular polygons. * * @name triangleGrid - * @param {Array} bbox extent in [minX, minY, maxX, maxY] order - * @param {number} cellSide dimension of each cell + * @param {Array} bbox extent of grid in [minX, minY, maxX, maxY] order + * @param {number} cellSide dimension of each grid cell. Two triangles are created in each cell. * @param {Object} [options={}] Optional parameters - * @param {string} [options.units='kilometers'] used in calculating cellSide, can be degrees, radians, miles, or kilometers + * @param {string} [options.units='kilometers'] used in calculating cellSide. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units} * @param {Feature} [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} grid of polygons From bcef65e1c3293b92d69d7cb92b1ad39554bd456c Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Thu, 8 Aug 2024 12:50:55 -0700 Subject: [PATCH 05/10] improve docs --- packages/turf-helpers/index.ts | 7 ++----- packages/turf-point-grid/index.ts | 4 ++-- packages/turf-rectangle-grid/index.ts | 9 ++++++--- packages/turf-square-grid/index.ts | 10 ++++++---- packages/turf-triangle-grid/index.ts | 4 ++-- 5 files changed, 18 insertions(+), 16 deletions(-) diff --git a/packages/turf-helpers/index.ts b/packages/turf-helpers/index.ts index dce32a5a1a..b53cc6bd6d 100644 --- a/packages/turf-helpers/index.ts +++ b/packages/turf-helpers/index.ts @@ -57,17 +57,14 @@ export type AllGeoJSON = */ /** - * The {@link https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius arithmetic mean radius} of the Earth. - * Used by Turf modules that model the Earth as a sphere. This radii value - * was chosen over others because it is {@link https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended recommended for use} with the Haversine formula, - * used by turf/distance. + * 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 based on equatorial earthRadius. + * 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/index.ts b/packages/turf-point-grid/index.ts index fdbea91f76..7dde71ec17 100644 --- a/packages/turf-point-grid/index.ts +++ b/packages/turf-point-grid/index.ts @@ -15,10 +15,10 @@ import { point, featureCollection, Units } from "@turf/helpers"; * Creates a grid of points * * @name pointGrid - * @param {Array} bbox extent of grid in [minX, minY, maxX, maxY] order + * @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'] the units of the cellSide value. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units} + * @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/index.ts Units} * @param {Feature} [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} grid of points diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts index b88f4e4255..90d8287f9d 100644 --- a/packages/turf-rectangle-grid/index.ts +++ b/packages/turf-rectangle-grid/index.ts @@ -14,14 +14,17 @@ import { Units, } from "@turf/helpers"; /** - * Creates a grid of rectangular polygon cells of equal width and height in degrees. + * Creates a grid of rectangular polygons with width and height in degrees * * @name rectangleGrid - * @param {Array} bbox extent of grid in [minX, minY, maxX, maxY] order. If the grid does not fill the bbox perfectly, it is centered. + * @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'] the units of the cellWidth and cellLenth values. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units}. Internally cellWidth and cellLength values are converted to degrees, regardless of units specified. + * @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/index.ts 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} [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/index.ts b/packages/turf-square-grid/index.ts index a918602664..ed290fd04a 100644 --- a/packages/turf-square-grid/index.ts +++ b/packages/turf-square-grid/index.ts @@ -10,14 +10,16 @@ import { Units } from "@turf/helpers"; import { rectangleGrid } from "@turf/rectangle-grid"; /** - * Creates a grid of square polygon cells with equal length sides in degrees. + * Creates a grid of square polygons with the same side length in degrees * * @name squareGrid - * @param {Array} bbox extent of grid in [minX, minY, maxX, maxY] order. If the grid does not fill the bbox perfectly, it is centered. + * @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'] the units of the cellSide value. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units}. Internally cellSide value is converted to degrees, regardless of units specified. - * 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/index.ts 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} [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-triangle-grid/index.ts b/packages/turf-triangle-grid/index.ts index 5764807744..a6dbb5b986 100644 --- a/packages/turf-triangle-grid/index.ts +++ b/packages/turf-triangle-grid/index.ts @@ -13,10 +13,10 @@ import { polygon, featureCollection, Units } from "@turf/helpers"; * Creates a grid of triangular polygons. * * @name triangleGrid - * @param {Array} bbox extent of grid in [minX, minY, maxX, maxY] order + * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order * @param {number} cellSide dimension of each grid cell. Two triangles are created in each cell. * @param {Object} [options={}] Optional parameters - * @param {string} [options.units='kilometers'] used in calculating cellSide. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units} + * @param {Units} [options.units='kilometers'] used in calculating cellSide. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units} * @param {Feature} [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} grid of polygons From e2170ce0be98d3b333c582b3b5656503dd028068 Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Thu, 8 Aug 2024 12:54:01 -0700 Subject: [PATCH 06/10] nit --- packages/turf-rectangle-grid/index.ts | 2 +- packages/turf-square-grid/index.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts index 90d8287f9d..6e868d08ca 100644 --- a/packages/turf-rectangle-grid/index.ts +++ b/packages/turf-rectangle-grid/index.ts @@ -14,7 +14,7 @@ import { Units, } from "@turf/helpers"; /** - * Creates a grid of rectangular polygons with width and height in degrees + * Creates a grid of rectangular polygons with width and height consistent in degrees * * @name rectangleGrid * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order. If the grid does not fill the bbox perfectly, it is centered. diff --git a/packages/turf-square-grid/index.ts b/packages/turf-square-grid/index.ts index ed290fd04a..15cbd5064b 100644 --- a/packages/turf-square-grid/index.ts +++ b/packages/turf-square-grid/index.ts @@ -10,7 +10,7 @@ import { Units } from "@turf/helpers"; import { rectangleGrid } from "@turf/rectangle-grid"; /** - * Creates a grid of square polygons with the same side length in degrees + * Creates a grid of square polygons with cell length consistent in degrees * * @name squareGrid * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order. If the grid does not fill the bbox perfectly, it is centered. From f9e7e60076788abc493540c01feedcb64bc55e56 Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Thu, 8 Aug 2024 20:42:21 -0700 Subject: [PATCH 07/10] add readme units file --- packages/turf-helpers/README_UNITS.md | 37 +++++++++++++++++++++++++++ packages/turf-point-grid/index.ts | 2 +- packages/turf-rectangle-grid/index.ts | 2 +- packages/turf-square-grid/index.ts | 2 +- packages/turf-triangle-grid/index.ts | 2 +- 5 files changed, 41 insertions(+), 4 deletions(-) create mode 100644 packages/turf-helpers/README_UNITS.md diff --git a/packages/turf-helpers/README_UNITS.md b/packages/turf-helpers/README_UNITS.md new file mode 100644 index 0000000000..6a4e500d71 --- /dev/null +++ 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 \ No newline at end of file diff --git a/packages/turf-point-grid/index.ts b/packages/turf-point-grid/index.ts index 7dde71ec17..408f47b64f 100644 --- a/packages/turf-point-grid/index.ts +++ b/packages/turf-point-grid/index.ts @@ -18,7 +18,7 @@ import { point, featureCollection, Units } from "@turf/helpers"; * @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 {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/index.ts Units} + * @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} [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} grid of points diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts index 6e868d08ca..f8034dc14e 100644 --- a/packages/turf-rectangle-grid/index.ts +++ b/packages/turf-rectangle-grid/index.ts @@ -22,7 +22,7 @@ import { * @param {number} cellHeight height of each cell, in units * @param {Object} [options={}] Optional parameters * @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/index.ts Units}. + * 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} [options.mask] if passed a Polygon or MultiPolygon, diff --git a/packages/turf-square-grid/index.ts b/packages/turf-square-grid/index.ts index 15cbd5064b..33a8a95e98 100644 --- a/packages/turf-square-grid/index.ts +++ b/packages/turf-square-grid/index.ts @@ -17,7 +17,7 @@ import { rectangleGrid } from "@turf/rectangle-grid"; * @param {number} cellSide length of each cell side. * @param {Object} [options={}] Optional parameters * @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/index.ts Units}. + * 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} [options.mask] if passed a Polygon or MultiPolygon, diff --git a/packages/turf-triangle-grid/index.ts b/packages/turf-triangle-grid/index.ts index a6dbb5b986..fc0f7b3f29 100644 --- a/packages/turf-triangle-grid/index.ts +++ b/packages/turf-triangle-grid/index.ts @@ -16,7 +16,7 @@ import { polygon, featureCollection, Units } from "@turf/helpers"; * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order * @param {number} cellSide dimension of each grid cell. Two triangles are created in each cell. * @param {Object} [options={}] Optional parameters - * @param {Units} [options.units='kilometers'] used in calculating cellSide. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units} + * @param {Units} [options.units='kilometers'] used in calculating cellSide. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units} * @param {Feature} [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} grid of polygons From 8bc44837353629f2d17034960e479162e469bc6e Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Fri, 9 Aug 2024 09:34:01 -0700 Subject: [PATCH 08/10] update area readme manually --- packages/turf-area/README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/packages/turf-area/README.md b/packages/turf-area/README.md index aeba55da93..a9568d0963 100644 --- 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 From 52fb34b603c8320e62256073698d80442c1c7011 Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Fri, 9 Aug 2024 09:39:22 -0700 Subject: [PATCH 09/10] one more readme --- packages/turf-helpers/README.md | 288 ++++++++++++++++---------------- 1 file changed, 146 insertions(+), 142 deletions(-) diff --git a/packages/turf-helpers/README.md b/packages/turf-helpers/README.md index d7711029f1..a232426adc 100644 --- a/packages/turf-helpers/README.md +++ b/packages/turf-helpers/README.md @@ -6,36 +6,36 @@ ### earthRadius -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 [mean radius][1] was selected because it is [recommended ][2] by the Haversine formula (used by turf/distance) to reduce error. -Type: [number][1] +Type: [number][3] ### factors -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 -Type: [Object][2] +Type: [Object][4] ### areaFactors Area of measurement factors based on 1 square meter. -Type: [Object][2] +Type: [Object][4] ## feature -Wraps a GeoJSON [Geometry][3] in a GeoJSON [Feature][4]. +Wraps a GeoJSON [Geometry][5] in a GeoJSON [Feature][6]. ### Parameters -* `geometry` **[Geometry][3]** input geometry -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `geometry` **[Geometry][5]** input geometry +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -50,18 +50,18 @@ var feature = turf.feature(geometry); //=feature ``` -Returns **[Feature][4]** a GeoJSON Feature +Returns **[Feature][6]** a GeoJSON Feature ## geometry -Creates a GeoJSON [Geometry][3] from a Geometry string type & coordinates. +Creates a GeoJSON [Geometry][5] from a Geometry string type & coordinates. For GeometryCollection type use `helpers.geometryCollection` ### Parameters -* `type` **[string][6]** Geometry Type -* `coordinates` **[Array][5]\** Coordinates -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `type` **[string][8]** Geometry Type +* `coordinates` **[Array][7]\** Coordinates +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) ### Examples @@ -72,20 +72,20 @@ var geometry = turf.geometry(type, coordinates); // => geometry ``` -Returns **[Geometry][3]** a GeoJSON Geometry +Returns **[Geometry][5]** a GeoJSON Geometry ## point -Creates a [Point][7] [Feature][4] from a Position. +Creates a [Point][9] [Feature][6] from a Position. ### Parameters -* `coordinates` **[Array][5]<[number][1]>** longitude, latitude position (each in decimal degrees) -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[number][3]>** longitude, latitude position (each in decimal degrees) +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -95,21 +95,21 @@ var point = turf.point([-75.343, 39.984]); //=point ``` -Returns **[Feature][4]<[Point][7]>** a Point feature +Returns **[Feature][6]<[Point][9]>** a Point feature ## points -Creates a [Point][7] [FeatureCollection][8] from an Array of Point coordinates. +Creates a [Point][9] [FeatureCollection][10] from an Array of Point coordinates. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[number][1]>>** an array of Points -* `properties` **[Object][2]** Translate these properties to each Feature (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[number][3]>>** an array of Points +* `properties` **[Object][4]** Translate these properties to each Feature (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the FeatureCollection - * `options.id` **([string][6] | [number][1])?** Identifier associated with the FeatureCollection + * `options.id` **([string][8] | [number][3])?** Identifier associated with the FeatureCollection ### Examples @@ -123,20 +123,20 @@ var points = turf.points([ //=points ``` -Returns **[FeatureCollection][8]<[Point][7]>** Point Feature +Returns **[FeatureCollection][10]<[Point][9]>** Point Feature ## polygon -Creates a [Polygon][9] [Feature][4] from an Array of LinearRings. +Creates a [Polygon][11] [Feature][6] from an Array of LinearRings. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[Array][5]<[number][1]>>>** an array of LinearRings -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[number][3]>>>** an array of LinearRings +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -146,20 +146,20 @@ var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], //=polygon ``` -Returns **[Feature][4]<[Polygon][9]>** Polygon Feature +Returns **[Feature][6]<[Polygon][11]>** Polygon Feature ## polygons -Creates a [Polygon][9] [FeatureCollection][8] from an Array of Polygon coordinates. +Creates a [Polygon][11] [FeatureCollection][10] from an Array of Polygon coordinates. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[Array][5]<[Array][5]<[number][1]>>>>** an array of Polygon coordinates -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[Array][7]<[number][3]>>>>** an array of Polygon coordinates +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the FeatureCollection + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the FeatureCollection ### Examples @@ -172,20 +172,20 @@ var polygons = turf.polygons([ //=polygons ``` -Returns **[FeatureCollection][8]<[Polygon][9]>** Polygon FeatureCollection +Returns **[FeatureCollection][10]<[Polygon][11]>** Polygon FeatureCollection ## lineString -Creates a [LineString][10] [Feature][4] from an Array of Positions. +Creates a [LineString][12] [Feature][6] from an Array of Positions. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[number][1]>>** an array of Positions -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[number][3]>>** an array of Positions +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -197,21 +197,21 @@ var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], //=linestring2 ``` -Returns **[Feature][4]<[LineString][10]>** LineString Feature +Returns **[Feature][6]<[LineString][12]>** LineString Feature ## lineStrings -Creates a [LineString][10] [FeatureCollection][8] from an Array of LineString coordinates. +Creates a [LineString][12] [FeatureCollection][10] from an Array of LineString coordinates. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[Array][5]<[number][1]>>>** an array of LinearRings -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[number][3]>>>** an array of LinearRings +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the FeatureCollection - * `options.id` **([string][6] | [number][1])?** Identifier associated with the FeatureCollection + * `options.id` **([string][8] | [number][3])?** Identifier associated with the FeatureCollection ### Examples @@ -224,19 +224,19 @@ var linestrings = turf.lineStrings([ //=linestrings ``` -Returns **[FeatureCollection][8]<[LineString][10]>** LineString FeatureCollection +Returns **[FeatureCollection][10]<[LineString][12]>** LineString FeatureCollection ## featureCollection -Takes one or more [Features][4] and creates a [FeatureCollection][8]. +Takes one or more [Features][6] and creates a [FeatureCollection][10]. ### Parameters -* `features` **[Array][5]<[Feature][4]>** input features -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `features` **[Array][7]<[Feature][6]>** input features +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -254,21 +254,21 @@ var collection = turf.featureCollection([ //=collection ``` -Returns **[FeatureCollection][8]** FeatureCollection of Features +Returns **[FeatureCollection][10]** FeatureCollection of Features ## multiLineString -Creates a [Feature\][11] based on a +Creates a [Feature\][13] based on a coordinate array. Properties can be added optionally. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[Array][5]<[number][1]>>>** an array of LineStrings -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[number][3]>>>** an array of LineStrings +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -278,23 +278,23 @@ var multiLine = turf.multiLineString([[[0,0],[10,10]]]); //=multiLine ``` -* Throws **[Error][12]** if no coordinates are passed +* Throws **[Error][14]** if no coordinates are passed -Returns **[Feature][4]<[MultiLineString][13]>** a MultiLineString feature +Returns **[Feature][6]<[MultiLineString][15]>** a MultiLineString feature ## multiPoint -Creates a [Feature\][14] based on a +Creates a [Feature\][16] based on a coordinate array. Properties can be added optionally. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[number][1]>>** an array of Positions -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[number][3]>>** an array of Positions +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -304,23 +304,23 @@ var multiPt = turf.multiPoint([[0,0],[10,10]]); //=multiPt ``` -* Throws **[Error][12]** if no coordinates are passed +* Throws **[Error][14]** if no coordinates are passed -Returns **[Feature][4]<[MultiPoint][15]>** a MultiPoint feature +Returns **[Feature][6]<[MultiPoint][17]>** a MultiPoint feature ## multiPolygon -Creates a [Feature\][16] based on a +Creates a [Feature\][18] based on a coordinate array. Properties can be added optionally. ### Parameters -* `coordinates` **[Array][5]<[Array][5]<[Array][5]<[Array][5]<[number][1]>>>>** an array of Polygons -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[Array][7]<[number][3]>>>>** an array of Polygons +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -330,23 +330,23 @@ var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]); //=multiPoly ``` -* Throws **[Error][12]** if no coordinates are passed +* Throws **[Error][14]** if no coordinates are passed -Returns **[Feature][4]<[MultiPolygon][17]>** a multipolygon feature +Returns **[Feature][6]<[MultiPolygon][19]>** a multipolygon feature ## geometryCollection -Creates a [Feature\][18] based on a +Creates a [Feature\][20] based on a coordinate array. Properties can be added optionally. ### Parameters -* `geometries` **[Array][5]<[Geometry][3]>** an array of GeoJSON Geometries -* `properties` **[Object][2]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][2]** Optional Parameters (optional, default `{}`) +* `geometries` **[Array][7]<[Geometry][5]>** an array of GeoJSON Geometries +* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][5]<[number][1]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][6] | [number][1])?** Identifier associated with the Feature + * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature ### Examples @@ -358,7 +358,7 @@ var collection = turf.geometryCollection([pt, line]); // => collection ``` -Returns **[Feature][4]<[GeometryCollection][19]>** a GeoJSON GeometryCollection Feature +Returns **[Feature][6]<[GeometryCollection][21]>** a GeoJSON GeometryCollection Feature ## round @@ -366,8 +366,8 @@ Round number to precision ### Parameters -* `num` **[number][1]** Number -* `precision` **[number][1]** Precision (optional, default `0`) +* `num` **[number][3]** Number +* `precision` **[number][3]** Precision (optional, default `0`) ### Examples @@ -379,7 +379,7 @@ turf.round(120.4321, 2) //=120.43 ``` -Returns **[number][1]** rounded number +Returns **[number][3]** rounded number ## radiansToLength @@ -388,11 +388,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, ce ### Parameters -* `radians` **[number][1]** in radians across the sphere -* `units` **[string][6]** can be degrees, radians, miles, inches, yards, metres, +* `radians` **[number][3]** in radians across the sphere +* `units` **[string][8]** can be degrees, radians, miles, inches, yards, metres, meters, kilometres, kilometers. (optional, default `"kilometers"`) -Returns **[number][1]** distance +Returns **[number][3]** distance ## lengthToRadians @@ -401,11 +401,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, ce ### Parameters -* `distance` **[number][1]** in real units -* `units` **[string][6]** can be degrees, radians, miles, inches, yards, metres, +* `distance` **[number][3]** in real units +* `units` **[string][8]** can be degrees, radians, miles, inches, yards, metres, meters, kilometres, kilometers. (optional, default `"kilometers"`) -Returns **[number][1]** radians +Returns **[number][3]** radians ## lengthToDegrees @@ -414,11 +414,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, k ### Parameters -* `distance` **[number][1]** in real units -* `units` **[string][6]** can be degrees, radians, miles, inches, yards, metres, +* `distance` **[number][3]** in real units +* `units` **[string][8]** can be degrees, radians, miles, inches, yards, metres, meters, kilometres, kilometers. (optional, default `"kilometers"`) -Returns **[number][1]** degrees +Returns **[number][3]** degrees ## bearingToAzimuth @@ -427,9 +427,9 @@ and returns an angle between 0-360 degrees (positive clockwise), 0 being the nor ### Parameters -* `bearing` **[number][1]** angle, between -180 and +180 degrees +* `bearing` **[number][3]** angle, between -180 and +180 degrees -Returns **[number][1]** angle between 0 and 360 degrees +Returns **[number][3]** angle between 0 and 360 degrees ## azimuthToBearing @@ -438,9 +438,9 @@ and returns an angle between -180 and +180 degrees (positive clockwise), 0 being ### Parameters -* `angle` **[number][1]** between 0 and 360 degrees +* `angle` **[number][3]** between 0 and 360 degrees -Returns **[number][1]** bearing between -180 and +180 degrees +Returns **[number][3]** bearing between -180 and +180 degrees ## radiansToDegrees @@ -448,9 +448,9 @@ Converts an angle in radians to degrees ### Parameters -* `radians` **[number][1]** angle in radians +* `radians` **[number][3]** angle in radians -Returns **[number][1]** degrees between 0 and 360 degrees +Returns **[number][3]** degrees between 0 and 360 degrees ## degreesToRadians @@ -458,9 +458,9 @@ Converts an angle in degrees to radians ### Parameters -* `degrees` **[number][1]** angle between 0 and 360 degrees +* `degrees` **[number][3]** angle between 0 and 360 degrees -Returns **[number][1]** angle in radians +Returns **[number][3]** angle in radians ## convertLength @@ -469,11 +469,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, ce ### Parameters -* `length` **[number][1]** to be converted +* `length` **[number][3]** to be converted * `originalUnit` **Units** of the length (optional, default `"kilometers"`) * `finalUnit` **Units** returned unit (optional, default `"kilometers"`) -Returns **[number][1]** the converted length +Returns **[number][3]** the converted length ## convertArea @@ -482,11 +482,11 @@ Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, a ### Parameters -* `area` **[number][1]** to be converted +* `area` **[number][3]** to be converted * `originalUnit` **Units** of the distance (optional, default `"meters"`) * `finalUnit` **Units** returned unit (optional, default `"kilometers"`) -Returns **[number][1]** the converted area +Returns **[number][3]** the converted area ## isNumber @@ -505,7 +505,7 @@ turf.isNumber('foo') //=false ``` -Returns **[boolean][20]** true/false +Returns **[boolean][22]** true/false ## isObject @@ -524,47 +524,51 @@ turf.isObject('foo') //=false ``` -Returns **[boolean][20]** true/false, including false for Arrays and Functions +Returns **[boolean][22]** true/false, including false for Arrays and Functions -[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[1]: https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius -[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[2]: https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended -[3]: https://tools.ietf.org/html/rfc7946#section-3.1 +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[4]: https://tools.ietf.org/html/rfc7946#section-3.2 +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[5]: https://tools.ietf.org/html/rfc7946#section-3.1 -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[6]: https://tools.ietf.org/html/rfc7946#section-3.2 -[7]: https://tools.ietf.org/html/rfc7946#section-3.1.2 +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[8]: https://tools.ietf.org/html/rfc7946#section-3.3 +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[9]: https://tools.ietf.org/html/rfc7946#section-3.1.6 +[9]: https://tools.ietf.org/html/rfc7946#section-3.1.2 -[10]: https://tools.ietf.org/html/rfc7946#section-3.1.4 +[10]: https://tools.ietf.org/html/rfc7946#section-3.3 -[11]: Feature +[11]: https://tools.ietf.org/html/rfc7946#section-3.1.6 -[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error +[12]: https://tools.ietf.org/html/rfc7946#section-3.1.4 -[13]: https://tools.ietf.org/html/rfc7946#section-3.1.5 +[13]: Feature -[14]: Feature +[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error -[15]: https://tools.ietf.org/html/rfc7946#section-3.1.3 +[15]: https://tools.ietf.org/html/rfc7946#section-3.1.5 -[16]: Feature +[16]: Feature -[17]: https://tools.ietf.org/html/rfc7946#section-3.1.7 +[17]: https://tools.ietf.org/html/rfc7946#section-3.1.3 -[18]: Feature +[18]: Feature -[19]: https://tools.ietf.org/html/rfc7946#section-3.1.8 +[19]: https://tools.ietf.org/html/rfc7946#section-3.1.7 -[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[20]: Feature + +[21]: https://tools.ietf.org/html/rfc7946#section-3.1.8 + +[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean From a91a0cfb9745b599d36b15bc122785eb2ae0aa6a Mon Sep 17 00:00:00 2001 From: Tim Welch Date: Fri, 9 Aug 2024 09:40:22 -0700 Subject: [PATCH 10/10] update all readmes --- packages/turf-point-grid/README.md | 34 +++++++++++------------ packages/turf-rectangle-grid/README.md | 38 ++++++++++++++------------ packages/turf-square-grid/README.md | 18 ++++++------ packages/turf-triangle-grid/README.md | 28 +++++++++---------- 4 files changed, 61 insertions(+), 57 deletions(-) diff --git a/packages/turf-point-grid/README.md b/packages/turf-point-grid/README.md index 6c409b727a..7ef41b043d 100644 --- 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 diff --git a/packages/turf-rectangle-grid/README.md b/packages/turf-rectangle-grid/README.md index 9ad5c99ff6..95540ea266 100644 --- 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 diff --git a/packages/turf-square-grid/README.md b/packages/turf-square-grid/README.md index 0a04b35359..28d11fbd05 100644 --- 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-triangle-grid/README.md b/packages/turf-triangle-grid/README.md index 10dcd092d5..0517776214 100644 --- 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