From 8446278038838cc8822c3c475577ccfc8e7aa469 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 24 Dec 2024 13:43:18 -0800 Subject: [PATCH 1/4] 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 From ed5852f8971949fd75bbe6eafea30be712f944e6 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 24 Dec 2024 14:05:49 -0800 Subject: [PATCH 2/4] remove --- website/docs/api/regions.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/website/docs/api/regions.mdx b/website/docs/api/regions.mdx index df7524dfd..082d2a08f 100644 --- a/website/docs/api/regions.mdx +++ b/website/docs/api/regions.mdx @@ -189,10 +189,6 @@ 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. From 3f030b482e486bd379a9cb1ac45949a2a97f6ca6 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 24 Dec 2024 14:08:41 -0800 Subject: [PATCH 3/4] python flags --- website/docs/api/regions.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/docs/api/regions.mdx b/website/docs/api/regions.mdx index 082d2a08f..ea557a51f 100644 --- a/website/docs/api/regions.mdx +++ b/website/docs/api/regions.mdx @@ -275,8 +275,8 @@ The valid values for `flags` are: ```py -h3.polygon_to_cells_experimental(h3shape, res, flags='containment_overlapping') -h3.h3shape_to_cells_experimental(h3shape, res, flags='containment_overlapping') +h3.polygon_to_cells_experimental(h3shape, res, flags=h3.ContainmentMode.containment_overlapping) +h3.h3shape_to_cells_experimental(h3shape, res, flags=h3.ContainmentMode.containment_overlapping) ``` In Python, `h3shape_to_cells` takes an `H3Shape` object @@ -286,12 +286,12 @@ For more info, see the [`h3-py` docs](https://uber.github.io/h3-py/api_quick.htm 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 +| Enum name | Integer value | Description +| --------- | ------------- | ----------- +| `ContainmentMode.containment_center` | 0 | Cell center is contained in the shape +| `ContainmentMode.containment_full` | 1 | Cell is fully contained in the shape +| `ContainmentMode.containment_overlapping` | 2 | Cell overlaps the shape at any point +| `ContainmentMode.containment_overlapping_bbox` | 3 | Cell bounding box overlaps shape From 0a1eebaca4c6de53c3923618ffddad5c18452595 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Fri, 24 Jan 2025 14:35:48 -0800 Subject: [PATCH 4/4] update for uber/h3-py#436 --- website/docs/api/regions.mdx | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/website/docs/api/regions.mdx b/website/docs/api/regions.mdx index ea557a51f..04a2474aa 100644 --- a/website/docs/api/regions.mdx +++ b/website/docs/api/regions.mdx @@ -275,23 +275,21 @@ The valid values for `flags` are: ```py -h3.polygon_to_cells_experimental(h3shape, res, flags=h3.ContainmentMode.containment_overlapping) -h3.h3shape_to_cells_experimental(h3shape, res, flags=h3.ContainmentMode.containment_overlapping) +h3.h3shape_to_cells_experimental(h3shape, res, contain='overlap') ``` -In Python, `h3shape_to_cells` takes an `H3Shape` object +In Python, `h3shape_to_cells_experimental` 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: +The valid values for `contain` are: -| Enum name | Integer value | Description -| --------- | ------------- | ----------- -| `ContainmentMode.containment_center` | 0 | Cell center is contained in the shape -| `ContainmentMode.containment_full` | 1 | Cell is fully contained in the shape -| `ContainmentMode.containment_overlapping` | 2 | Cell overlaps the shape at any point -| `ContainmentMode.containment_overlapping_bbox` | 3 | Cell bounding box overlaps shape +| String value | Description +| ------------ | ----------- +| `center` | Cell center is contained in the shape (default) +| `full` | Cell is fully contained in the shape +| `overlap` | Cell overlaps the shape at any point +| `bbox_overlap` | Cell bounding box overlaps shape