geo_polygon_to_h3cells()
Converts polygon to H3 cells. This function is a useful geospatial join and visualization tool.
Syntax
geo_polygon_to_h3cells(polygon [, resolution[, radius]])
Learn more about syntax conventions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| polygon | dynamic |
✔️ | Polygon or multipolygon in the GeoJSON format. |
| resolution | int |
Defines the requested cell resolution. Supported values are in the range [0, 15]. If unspecified, the default value 6 is used. |
|
| radius | real |
Buffer radius in meters. If unspecified, the default value 0 is used. |
Returns
Array of H3 cell token strings of the same resolution that represet a polygon or a multipolygon. If radius is set to a positive value, then the polygon will be enlarged such that all points within the given radius of the input polygon or multipolygon will be contained inside and the newly calculated polygon that will be converted to H3 cells. If polygon, resolution, radius is invalid, or the cell count exceeds the limit, the query will produce a null result.
Note
- Converting polygon to H3 cell tokens can be useful in matching coordinates to polygons that might include these coordinates and matching polygons to polygons.
- The maximum count of tokens per polygon is 61680.
- Polygon edges are straight lines.
- A polygon is represented by the cells whose centroids are inside the polygon. This means that the cells are not exactly the same as the polygon, but they get closer as the resolution increases. To make sure that every point in the polygon is covered by a cell, the polygon can be buffered. This also ensures that neighboring polygons that touch each other will have separate cells, so no cell will belong to more than one polygon.
Seel also geo_polygon_to_s2cells().
Examples
The following example calculates H3 cells that approximate the polygon.
let polygon = dynamic({"type":"Polygon","coordinates":[[[-3.659,40.553],[-3.913,40.409],[-3.729,40.273],[-3.524,40.440],[-3.659,40.553]]]});
print h3_cells = geo_polygon_to_h3cells(polygon)
Output
| h3_cells |
|---|
| ["86390cb57ffffff","86390cb0fffffff","86390ca27ffffff","86390cb87ffffff","86390cb07ffffff","86390ca2fffffff","86390ca37ffffff","86390cb17ffffff","86390cb1fffffff","86390cb8fffffff","86390cba7ffffff","86390ca07ffffff","86390cbafffffff"] |
The following example demonstrates a multipolygon that consists of H3 cells that approximate the above polygon. Specifing a higher resolution will improve polygon approximation.
let polygon = dynamic({"type":"Polygon","coordinates":[[[-3.659,40.553],[-3.913,40.409],[-3.729,40.273],[-3.524,40.440],[-3.659,40.553]]]});
print h3_cells = geo_polygon_to_h3cells(polygon)
| mv-expand cell = h3_cells to typeof(string) // extract cell to a separate row
| project polygon_cell = geo_h3cell_to_polygon(cell) // convert each cell to a polygon
| project individual_polygon_coordinates = pack_array(polygon_cell.coordinates)
| summarize multipolygon_coordinates = make_list(individual_polygon_coordinates)
| project multipolygon = bag_pack("type","MultiPolygon", "coordinates", multipolygon_coordinates)
Output
| multipolygon |
|---|
| {"type": "MultiPolygon", "coordinates": [ ... ]} |
The following example return null because the polygon is invalid.
let polygon = dynamic({"type":"Polygon","coordinates":[[[0,0],[1,1]]]});
print is_null = isnull(geo_polygon_to_h3cells(polygon))
Output
| is_null |
|---|
| True |