Core

class h3ronpy.ContainmentMode

Containment mode used to decide if a cell is contained in a polygon or not.

Modes:

• ContainsCentroid: This mode will select every cells whose centroid are contained inside the polygon.

  This is the fasted option and ensures that every cell is uniquely assigned (e.g. two adjacent polygon with zero overlap also have zero overlapping cells).

  On the other hand, some cells may cover area outside of the polygon (overshooting) and some parts of the polygon may be left uncovered.

• ContainsBoundary: This mode will select every cells whose boundaries are entirely within the polygon.

  This ensures that every cell is uniquely assigned (e.g. two adjacent polygon with zero overlap also have zero overlapping cells) and avoids any coverage overshooting.

  Some parts of the polygon may be left uncovered (more than with ContainsCentroid).

• IntersectsBoundary: This mode will select every cells whose boundaries are within the polygon, even partially.

  This guarantees a complete coverage of the polygon, but some cells may belong to two different polygons if they are adjacent/close enough. Some cells may cover area outside of the polygon.

• Covers: This mode behaves the same as IntersectsBoundary, but also handles the case where the geometry is

  being covered by a cell without intersecting with its boundaries. In such cases, the covering cell is returned.

ContainsBoundary = ContainmentMode.ContainsBoundary

ContainsCentroid = ContainmentMode.ContainsCentroid

Covers = ContainmentMode.Covers

IntersectsBoundary = ContainmentMode.IntersectsBoundary

h3ronpy.cells_area_km2(cellarray) → Array

Return type:

Array

h3ronpy.cells_area_m2(cellarray) → Array

Return type:

Array

h3ronpy.cells_area_rads2(cellarray) → Array

Return type:

Array

h3ronpy.cells_parse(arr, set_failing_to_invalid: bool = False) → Array

Parse H3 cells from string arrays.

Setting set_failing_to_invalid to true will trigger setting the validity bitmap according the successful parsing of an individual element. Having this set to false will cause the method to fail upon encountering the first unparsable value.

This function is able to parse multiple representations of H3 cells:

• hexadecimal (Example: 8552dc63fffffff)

• numeric integer strings (Example: 600436454824345599)

• strings like [x], [y], [resolution] or [x]; [y]; [resolution]. (Example: 10.2,45.5,5)

Parameters:

set_failing_to_invalid (bool)

Return type:

Array

h3ronpy.cells_resolution(arr) → Array

Generates a new array containing the resolution of each cell of the input array.

Parameters:

arr

Returns:

Return type:

Array

h3ronpy.cells_to_localij(cellarray, anchor, set_failing_to_invalid: bool = False) → RecordBatch

Produces IJ coordinates for an index anchored by an origin anchor.

The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.

Coordinates are only comparable if they come from the same origin index.

The parameter anchor can be a single cell or an array of cells which serve as anchor for the cells of cellarray. In case it is an array, the length must match the length of the cell array.

The default behavior is for this function to fail when a single transformation can not be completed successfully. When set_failing_to_invalid is set to True, only the failing positions of the output arrays will be set to null.

Parameters:

set_failing_to_invalid (bool)

Return type:

RecordBatch

h3ronpy.cells_to_string(cellarray) → Array

Return type:

Array

h3ronpy.cells_valid(arr, booleanarray: bool = False) → Array

Validate an array of potentially invalid cell values by returning a new UInt64 array with the validity mask set accordingly.

If booleanarray is set to True, a boolean array describing the validity will be returned instead.

Parameters:

booleanarray (bool)

Return type:

Array

h3ronpy.change_resolution(arr, resolution: int) → Array

Change the H3 resolutions of all contained values to resolution.

In case of resolution increases all child indexes will be added, so the returned value may contain more indexes than the input.

Invalid/empty values are omitted.

Parameters:

resolution (int)

Return type:

Array

h3ronpy.change_resolution_list(arr, resolution: int) → Array

Change the H3 resolutions of all contained values to resolution.

The output list array has the same length as the input array, positions of the elements in input and output are corresponding to each other.

Invalid/empty values are preserved as such.

Parameters:

resolution (int)

Return type:

Array

h3ronpy.change_resolution_paired(arr, resolution: int) → RecordBatch

Returns a table/dataframe with two columns: cell_before and cell_after with the cells h3index before and after the resolution change.

This can be helpful when joining data in different resolutions via dataframe libraries

Parameters:

resolution (int)

Return type:

RecordBatch

h3ronpy.compact(arr, mixed_resolutions: bool = False) → Array

Compact the given cells

The cells are expected to be of the same resolution, otherwise this operation will fail unless mixed_resolutions is set to True. Setting this may lead to slight slow-downs.

Parameters:

mixed_resolutions (bool)

Return type:

Array

h3ronpy.directededges_parse(arr, set_failing_to_invalid: bool = False) → Array

Parse H3 directed edges from string arrays.

Setting set_failing_to_invalid to true will trigger setting the validity bitmap according the successful parsing of an individual element. Having this set to false will cause the method to fail upon encountering the first unparsable value.

Parameters:

set_failing_to_invalid (bool)

Return type:

Array

h3ronpy.directededges_to_string(directededgearray) → Array

Return type:

Array

h3ronpy.directededges_valid(arr, booleanarray: bool = False) → Array

Validate an array of potentially invalid directed edge values by returning a new UInt64 array with the validity mask set accordingly.

If booleanarray is set to True, a boolean array describing the validity will be returned instead.

Parameters:

booleanarray (bool)

Return type:

Array

h3ronpy.grid_disk(cellarray, k: int, flatten: bool = False) → Array

Parameters:

• k (int)

• flatten (bool)

Return type:

Array

h3ronpy.grid_disk_aggregate_k(cellarray, k: int, aggregation_method: str) → RecordBatch

Valid values for aggregation_method are “min” and “max”.

Parameters:

• k (int)

• aggregation_method (str)

Return type:

RecordBatch

h3ronpy.grid_disk_distances(cellarray, k: int, flatten: bool = False) → RecordBatch

Parameters:

• k (int)

• flatten (bool)

Return type:

RecordBatch

h3ronpy.grid_ring_distances(cellarray, k_min: int, k_max: int, flatten: bool = False) → RecordBatch

Parameters:

• k_min (int)

• k_max (int)

• flatten (bool)

Return type:

RecordBatch

h3ronpy.localij_to_cells(anchor, i, j, set_failing_to_invalid: bool = False) → Array

Produces cells from i and j coordinates and an anchor cell.

The default behavior is for this function to fail when a single transformation can not be completed successfully. When set_failing_to_invalid is set to True, only the failing positions of the output arrays will be set to null.

Parameters:

set_failing_to_invalid (bool)

Return type:

Array

h3ronpy.uncompact(arr, target_resolution: int) → Array

Uncompact the given cells to the resolution target_resolution.

All higher resolution cells contained in the input array than the given target_resolution will be omitted from the output.

Parameters:

target_resolution (int)

Return type:

Array

h3ronpy.version()

version of the module

h3ronpy.vertexes_parse(arr, set_failing_to_invalid: bool = False) → Array

Parse H3 vertexes from string arrays.

Setting set_failing_to_invalid to true will trigger setting the validity bitmap according the successful parsing of an individual element. Having this set to false will cause the method to fail upon encountering the first unparsable value.

Parameters:

set_failing_to_invalid (bool)

Return type:

Array

h3ronpy.vertexes_to_string(vertexesarray) → Array

Return type:

Array

h3ronpy.vertexes_valid(arr, booleanarray: bool = False) → Array

Validate an array of potentially invalid vertex values by returning a new UInt64 array with the validity mask set accordingly.

If booleanarray is set to True, a boolean array describing the validity will be returned instead.

Parameters:

booleanarray (bool)

Return type:

Array

Vector

h3ronpy.vector.cells_bounds(arr) → tuple | None

Bounds of the complete array as a tuple (minx, miny, maxx, maxy).

Return type:

tuple | None

h3ronpy.vector.cells_bounds_arrays(arr) → RecordBatch

Build a table/dataframe with the columns minx, miny, maxx and maxy containing the bounds of the individual cells from the input array.

Return type:

RecordBatch

h3ronpy.vector.cells_to_coordinates(arr, radians: bool = False) → RecordBatch

convert to point coordinates in degrees

Parameters:

radians (bool)

Return type:

RecordBatch

h3ronpy.vector.cells_to_wkb_points(arr, radians: bool = False) → Array

Convert cells to points using their centroids.

The returned geometries in the output array will match the order of the input array.

Param:

arr: The cell array

Parameters:

radians (bool) – Generate geometries using radians instead of degrees

Return type:

Array

h3ronpy.vector.cells_to_wkb_polygons(arr, radians: bool = False, link_cells: bool = False) → Array

Convert cells to polygons.

The returned geometries in the output array will match the order of the input array - unless link_cells is set to True.

Param:

arr: The cell array

Parameters:

• radians (bool) – Generate geometries using radians instead of degrees

• link_cells (bool) – Combine neighboring cells into a single polygon geometry. All cell indexes must have the same resolution.

Return type:

Array

h3ronpy.vector.coordinates_to_cells(latarray, lngarray, resarray, radians: bool = False) → Array

Convert coordinates arrays to cells.

Parameters:

• latarray – array of lat values

• lngarray – array of lng values

• resarray – Either an array of resolutions or a single resolution as an integer to apply to all coordinates.

• radians (bool) – Set to True to pass lat and lng in radians

Returns:

cell array

Return type:

Array

h3ronpy.vector.directededges_to_wkb_linestrings(arr, radians: bool = False) → Array

Convert directed edges to linestrings.

The returned geometries in the output array will match the order of the input array.

Param:

arr: The directed edge array

Parameters:

radians (bool) – Generate geometries using radians instead of degrees

Return type:

Array

h3ronpy.vector.geometry_to_cells(geom, resolution: int, containment_mode: ContainmentMode = ContainmentMode.ContainsCentroid, compact: bool = False) → Array

Convert a single object which supports the python __geo_interface__ protocol to H3 cells

Parameters:

• geom – geometry

• resolution (int) – H3 resolution

• containment_mode (ContainmentMode) – Containment mode used to decide if a cell is contained in a polygon or not. See the ContainmentMode class.

• compact (bool) – Compact the returned cells by replacing cells with their parent cells when all children of that cell are part of the set.

Return type:

Array

h3ronpy.vector.vertexes_to_wkb_points(arr, radians: bool = False) → Array

Convert vertexes to points.

The returned geometries in the output array will match the order of the input array.

Param:

arr: The vertex array

Parameters:

radians (bool) – Generate geometries using radians instead of degrees

Return type:

Array

h3ronpy.vector.wkb_to_cells(arr, resolution: int, containment_mode: ContainmentMode = ContainmentMode.ContainsCentroid, compact: bool = False, flatten: bool = False) → Array

Convert a Series/Array/List of WKB values to H3 cells.

Unless flatten is set to True a list array will be returned, with the cells generated from a geometry being located at the same position as the geometry in the input array.

Parameters:

• arr – The input array.

• resolution (int) – H3 resolution

• containment_mode (ContainmentMode) – Containment mode used to decide if a cell is contained in a polygon or not. See the ContainmentMode class.

• compact (bool) – Compact the returned cells by replacing cells with their parent cells when all children of that cell are part of the set.

• flatten (bool) – Return a non-nested cell array instead of a list array.

Return type:

Array

Raster

Conversion of 2D numpy arrays to H3 cells.

The geo-context is passed to this library using a coordinate transformation matrix - this can be either a GDAL-like array of six float values, or a Affine-object as used by rasterio.

Note

As H3 itself used WGS84 (EPSG:4326) Lat/Lon coordinates, the coordinate transformation matrix used in this module must be based on WGS84 as well. Raster data using other coordinate systems need to be reprojected accordingly.

While H3 cells are hexagons and pentagons, this raster conversion process only takes the raster value under the centroid of the cell into account. When the data shall be aggregated, use any of these methods:

1. Make use the nearest_h3_resolution function to convert to the H3 resolution nearest to the pixel size of the raster. After that the cell resolution can be changed using the change_resolution function and dataframe libraries can be used to perform the desired aggregations. This can be a rather memory-intensive process.

2. Scale the raster down using an interpolation algorithm. After that use method 1. This can save a lot of memory, but may not be applicable to all datasets - for example dataset with absolute values per pixel like population counts.

Resolution search modes of nearest_h3_resolution:

• “min_diff”: chose the H3 resolution where the difference in the area of a pixel and the h3index is as small as possible.

• “smaller_than_pixel”: chose the H3 resolution where the area of the h3index is smaller than the area of a pixel.

h3ronpy.raster.nearest_h3_resolution(shape, transform, axis_order='yx', search_mode='min_diff') → int

Find the H3 resolution closest to the size of a pixel in an array of the given shape with the given transform

Parameters:

• shape – dimensions of the 2d array

• transform – the affine transformation

• axis_order – axis order of the 2d array. Either “xy” or “yx”

• search_mode – resolution search mode (see documentation of this module)

Returns:

Return type:

int

h3ronpy.raster.raster_to_dataframe(in_raster: ndarray, transform, h3_resolution: int, nodata_value=None, axis_order: str = 'yx', compact: bool = True) → Table

Convert a raster/array to a pandas DataFrame containing H3 cell indexes

This function is parallelized and uses the available CPUs by distributing tiles to a thread pool.

The input geometry must be in WGS84.

Parameters:

• in_raster (ndarray) – Input 2D array

• transform – The affine transformation

• nodata_value – The nodata value. For these cells of the array there will be no h3 indexes generated

• axis_order (str) – Axis order of the 2d array. Either “xy” or “yx”

• h3_resolution (int) – Target h3 resolution

• compact (bool) – Return compacted h3 indexes (see H3 docs). This results in mixed H3 resolutions, but also can reduce the amount of required memory.

Returns:

Tuple of arrow arrays

Return type:

Table

h3ronpy.raster.rasterize_cells(cells, values, size: int | tuple[int, int], nodata_value=0) → tuple[ndarray, tuple[float, float, float, float, float, float]]

Generate a raster numpy array from arrays of cells and values.

This function requires the rasterio and shapely libraries to be installed.

Parameters:

• cells – array with H3 cells

• values – array with the values which shall be written into the raster

• size (int | tuple[int, int]) – The desired output size of the raster. Maybe a tuple of ints (width, height) or a single int. In case of the latter, the other dimension is interpolated from the bounds of the input data.

• nodata_value – The nodata value for the output array

Returns:

2D numpy array typed accordingly to the passed in values array, and the geotransform (WGS84 coordinate system, ordering used by the affine library and rasterio)

Return type:

tuple[ndarray, tuple[float, float, float, float, float, float]]