From 8446278038838cc8822c3c475577ccfc8e7aa469 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 24 Dec 2024 13:43:18 -0800 Subject: [PATCH] add docs for polygonToCellsExperimental --- website/docs/api/regions.mdx | 183 +++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) diff --git a/website/docs/api/regions.mdx b/website/docs/api/regions.mdx index 19a518e4f..df7524dfd 100644 --- a/website/docs/api/regions.mdx +++ b/website/docs/api/regions.mdx @@ -182,6 +182,189 @@ $ h3 maxPolygonToCellsSize -r 7 -p "[[37.813318999983238, -122.4089866999972145] +## polygonToCellsExperimental + +Each binding's version of `polygonToCellsExperimental` takes as input a +GeoJSON-like data structure describing a polygon (i.e., an outer ring and +optional holes) and a target cell resolution. +It produces a collection of cells that are contained within the polygon. + +Containment is determined by centroids of the cells, so that a partitioning +of polygons (covering an area without overlaps) will result in +a partitioning of H3 cells. + +This function differs from `polygonToCells` in that it uses an experimental +new algorithm which supports center-based, fully-contained, and +overlapping containment modes. + + + + +```c +H3Error polygonToCellsExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, int64_t size, H3Index *out); +``` + +In C, `polygonToCellsExperimental` takes a `GeoPolygon` struct and preallocated, +zeroed memory, and fills it with the covering cells. + +`size` should be the size in number of `H3Index`s of `out`. + +The valid values for `flags` are: + +| Enum name | Integer value | Description +| --------- | ------------- | ----------- +| `CONTAINMENT_CENTER` | 0 | Cell center is contained in the shape +| `CONTAINMENT_FULL` | 1 | Cell is fully contained in the shape +| `CONTAINMENT_OVERLAPPING` | 2 | Cell overlaps the shape at any point +| `CONTAINMENT_OVERLAPPING_BBOX` | 3 | Cell bounding box overlaps shape + +Returns 0 (`E_SUCCESS`) on success. + + + + +```java +List polygonToCellsExperimental(List points, List> holes, PolygonToCellsFlags flags, int res); +List polygonToCellExperimentalAddresses(List points, List> holes, PolygonToCellsFlags flags, int res); +``` + +The valid values for `flags` are: + +| Enum name | Description +| --------- | ----------- +| `PolygonToCellsFlags.containment_center` | Cell center is contained in the shape +| `PolygonToCellsFlags.containment_full` | Cell is fully contained in the shape +| `PolygonToCellsFlags.containment_overlapping` | Cell overlaps the shape at any point +| `PolygonToCellsFlags.containment_overlapping_bbox` | Cell bounding box overlaps shape + + + + +```js +h3.polygonToCellsExperimental(polygon, res, flags, isGeoJson) +``` + +```js live +function example() { + const polygon = [ + [37.813318999983238, -122.4089866999972145], + [37.7198061999978478, -122.3544736999993603], + [37.8151571999998453, -122.4798767000009008] + ]; + const res = 7; + return h3.polygonToCellsExperimental(polygon, h3.POLYGON_TO_CELLS_FLAGS.containmentOverlapping, res); +} +``` + +The valid values for `flags` are: + +| Enum name | Description +| --------- | ----------- +| `POLYGON_TO_CELLS_FLAGS.containment_center` | Cell center is contained in the shape +| `POLYGON_TO_CELLS_FLAGS.containment_full` | Cell is fully contained in the shape +| `POLYGON_TO_CELLS_FLAGS.containment_overlapping` | Cell overlaps the shape at any point +| `POLYGON_TO_CELLS_FLAGS.containment_overlapping_bbox` | Cell bounding box overlaps shape + + + + +```py +h3.polygon_to_cells_experimental(h3shape, res, flags='containment_overlapping') +h3.h3shape_to_cells_experimental(h3shape, res, flags='containment_overlapping') +``` + +In Python, `h3shape_to_cells` takes an `H3Shape` object +(`LatLngPoly` or `LatLngMultiPoly`). +Note that `polygon_to_cells` is an alias for `h3shape_to_cells`. +For more info, see the [`h3-py` docs](https://uber.github.io/h3-py/api_quick.html#polygon-interface). + +The valid values for `flags` are: + +| String value | Description +| ------------ | ----------- +| `"containment_center"` | Cell center is contained in the shape +| `"containment_full"` | Cell is fully contained in the shape +| `"containment_overlapping"` | Cell overlaps the shape at any point +| `"containment_overlapping_bbox"` | Cell bounding box overlaps shape + + + + +This function is not exposed in the CLI bindings. + + + + + +## maxPolygonToCellsExperimentalSize + +Provides an upper bound on the number of cells needed for memory allocation +purposes when computing `polygonToCellsExperimental` on the given GeoJSON-like data structure. + + + + +```c +H3Error maxPolygonToCellsExperimentalSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, int64_t *out); +``` + +Returns 0 (`E_SUCCESS`) on success. + + + + +:::note + +This function exists for memory management and is not exposed. + +::: + + + + +:::note + +This function exists for memory management and is not exposed. + +::: + + + + +:::note + +This function exists for memory management and is not exposed. + +::: + + + + +This function is not exposed in the CLI bindings. + + + + ## cellsToLinkedMultiPolygon / cellsToMultiPolygon