From 1dec2f2474ba37ca3cb40e492ba85f70aecd055a Mon Sep 17 00:00:00 2001 From: James Beard Date: Sun, 27 Oct 2024 09:52:30 +1100 Subject: [PATCH] Fixed union documentation where types out of sync with function. Reworded some of the descriptions as well. (#2732) Co-authored-by: Tim Welch --- packages/turf-union/README.md | 67 ++++++++++++++++++++++------------- packages/turf-union/index.ts | 59 +++++++++++++++++++----------- 2 files changed, 81 insertions(+), 45 deletions(-) diff --git a/packages/turf-union/README.md b/packages/turf-union/README.md index 64b85b567..ed82325d7 100644 --- a/packages/turf-union/README.md +++ b/packages/turf-union/README.md @@ -4,47 +4,64 @@ ## union -Takes input [(Multi)Polygon(s)][1] and returns a combined polygon. If the input polygons are not contiguous, this function returns a [MultiPolygon][2] feature. +Takes a collection of input polygons and returns a combined polygon. If the +input polygons are not contiguous, this function returns a multi-polygon +feature. ### Parameters -* `features` **[FeatureCollection][3]<([Polygon][1] | [MultiPolygon][2])>** +* `features` **[FeatureCollection][1]<([Polygon][2] | [MultiPolygon][3])>** input polygon features * `options` **[Object][4]** Optional Parameters (optional, default `{}`) - * `options.properties` **[Object][4]** Translate Properties to output Feature (optional, default `{}`) -* `polygon1` **[Feature][5]<([Polygon][1] | [MultiPolygon][2])>** input Polygon features + * `options.properties` **[GeoJsonProperties][5]** properties to assign to output feature (optional, default `{}`) ### Examples ```javascript -var poly1 = turf.polygon([[ - [-82.574787, 35.594087], - [-82.574787, 35.615581], - [-82.545261, 35.615581], - [-82.545261, 35.594087], - [-82.574787, 35.594087] -]], {"fill": "#0f0"}); -var poly2 = turf.polygon([[ - [-82.560024, 35.585153], - [-82.560024, 35.602602], - [-82.52964, 35.602602], - [-82.52964, 35.585153], - [-82.560024, 35.585153] -]], {"fill": "#00f"}); - -var union = turf.union(turf.featureCollection([poly1, poly2])); +const poly1 = turf.polygon( + [ + [ + [-82.574787, 35.594087], + [-82.574787, 35.615581], + [-82.545261, 35.615581], + [-82.545261, 35.594087], + [-82.574787, 35.594087], + ], + ], + { fill: "#0f0" } +); + +const poly2 = turf.polygon( + [ + [ + [-82.560024, 35.585153], + [-82.560024, 35.602602], + [-82.52964, 35.602602], + [-82.52964, 35.585153], + [-82.560024, 35.585153], + ], + ], +); + +const union = turf.union(turf.featureCollection([poly1, poly2])); //addToMap -var addToMap = [poly1, poly2, union]; +const addToMap = { poly1, poly2, union }; + +poly1.properties.fill = "#0f0"; +poly2.properties.fill = "#00f"; +union.properties.stroke = "red"; +union.properties["stroke-width"] = 4; +union.properties.fill = "transparent"; ``` -Returns **[Feature][5]<([Polygon][1] | [MultiPolygon][2])>** a combined [Polygon][1] or [MultiPolygon][2] feature, or null if the inputs are empty +Returns **([Feature][5]<([Polygon][2] | [MultiPolygon][3])> | null)** a combined polygon or multi-polygon feature, or null if there were no input polygons to combine -[1]: https://tools.ietf.org/html/rfc7946#section-3.1.6 +[1]: https://tools.ietf.org/html/rfc7946#section-3.3 -[2]: https://tools.ietf.org/html/rfc7946#section-3.1.7 +[2]: https://tools.ietf.org/html/rfc7946#section-3.1.6 -[3]: https://tools.ietf.org/html/rfc7946#section-3.3 +[3]: https://tools.ietf.org/html/rfc7946#section-3.1.7 [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object diff --git a/packages/turf-union/index.ts b/packages/turf-union/index.ts index 4c0b6d662..5c1aadce5 100644 --- a/packages/turf-union/index.ts +++ b/packages/turf-union/index.ts @@ -10,33 +10,52 @@ import { } from "geojson"; /** - * Takes input {@link (Multi)Polygon(s)} and returns a combined polygon. If the input polygons are not contiguous, this function returns a {@link MultiPolygon} feature. + * Takes a collection of input polygons and returns a combined polygon. If the + * input polygons are not contiguous, this function returns a multi-polygon + * feature. * * @function - * @param {Feature} polygon1 input Polygon features + * @param {FeatureCollection} features input polygon features * @param {Object} [options={}] Optional Parameters - * @param {Object} [options.properties={}] Translate Properties to output Feature - * @returns {Feature<(Polygon|MultiPolygon)>} a combined {@link Polygon} or {@link MultiPolygon} feature, or null if the inputs are empty + * @param {GeoJsonProperties} [options.properties={}] properties to assign to output feature + * @returns {Feature<(Polygon|MultiPolygon)>|null} a combined polygon or multi-polygon feature, or null if there were no input polygons to combine * @example - * var poly1 = turf.polygon([[ - * [-82.574787, 35.594087], - * [-82.574787, 35.615581], - * [-82.545261, 35.615581], - * [-82.545261, 35.594087], - * [-82.574787, 35.594087] - * ]], {"fill": "#0f0"}); - * var poly2 = turf.polygon([[ - * [-82.560024, 35.585153], - * [-82.560024, 35.602602], - * [-82.52964, 35.602602], - * [-82.52964, 35.585153], - * [-82.560024, 35.585153] - * ]], {"fill": "#00f"}); * - * var union = turf.union(turf.featureCollection([poly1, poly2])); + * const poly1 = turf.polygon( + * [ + * [ + * [-82.574787, 35.594087], + * [-82.574787, 35.615581], + * [-82.545261, 35.615581], + * [-82.545261, 35.594087], + * [-82.574787, 35.594087], + * ], + * ], + * { fill: "#0f0" } + * ); + * + * const poly2 = turf.polygon( + * [ + * [ + * [-82.560024, 35.585153], + * [-82.560024, 35.602602], + * [-82.52964, 35.602602], + * [-82.52964, 35.585153], + * [-82.560024, 35.585153], + * ], + * ], + * ); + * + * const union = turf.union(turf.featureCollection([poly1, poly2])); * * //addToMap - * var addToMap = [poly1, poly2, union]; + * const addToMap = { poly1, poly2, union }; + * + * poly1.properties.fill = "#0f0"; + * poly2.properties.fill = "#00f"; + * union.properties.stroke = "red"; + * union.properties["stroke-width"] = 4; + * union.properties.fill = "transparent"; */ function union

( features: FeatureCollection,