Grids¶
A grid system partitions geography into cells. A generator maps datasets onto those cells. H3ViewGenerator uses H3Hexagons. You only need these classes when you want the cells themselves.
from gigaspatial import H3Hexagons, S2Cells, MercatorTiles
from gigaspatial.grid import CountryH3Hexagons
Bases: BaseModel
Representation of a collection of H3 hexagons at a specific resolution.
Provides utility methods to create, filter, manipulate, and export H3 hexagonal grids for spatial analysis. Handles conversion between coordinate pairs, geometries, and H3 cell IDs.
Attributes:
| Name | Type | Description |
|---|---|---|
resolution | int | H3 resolution level (0-15). |
hexagons | List[str] | List of H3 cell ID strings. |
data_store | DataStore | Storage interface for I/O operations. |
logger | ClassVar | Class-level logger. |
average_hexagon_area property ¶
Calculates the average area of hexagons at the current resolution.
Returns:
| Type | Description |
|---|---|
float | Average area in square kilometers. |
average_hexagon_edge_length property ¶
Calculates the average edge length of hexagons at the current resolution.
Returns:
| Type | Description |
|---|---|
float | Average edge length in kilometers. |
filter_hexagons(hexagons) ¶
Filters the current collection against a provided set of hexagon IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hexagons | Iterable[str] | An iterable of H3 cell ID strings to keep. | required |
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance containing only the intersecting cells. |
from_bounds(xmin, ymin, xmax, ymax, resolution) classmethod ¶
Create H3Hexagons covering the specified geographic bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xmin | float | Minimum longitude. | required |
ymin | float | Minimum latitude. | required |
xmax | float | Maximum longitude. | required |
ymax | float | Maximum latitude. | required |
resolution | int | H3 resolution level. | required |
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance covering the bounds. |
from_geometry(geometry, resolution, contain='overlap', **kwargs) classmethod ¶
Create H3Hexagons from a Shapely geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geometry | BaseGeometry | Input geometry (Polygon, MultiPolygon, etc.). | required |
resolution | int | H3 resolution level. | required |
contain | Literal['center', 'full', 'overlap', 'bbox_overlap'] | Containment logic for H3 cell generation. | 'overlap' |
**kwargs | Additional metadata parameters. | {} |
Returns:
| Type | Description |
|---|---|
H3Hexagons | H3Hexagons instance covering the geometry. |
from_hexagons(hexagons) classmethod ¶
Create H3Hexagons from a list of H3 cell IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hexagons | List[str] | List of H3 cell hashes. | required |
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance. |
from_json(data_store, file, **kwargs) classmethod ¶
Load H3Hexagons from a JSON file in storage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data_store | DataStore | DataStore instance for the file. | required |
file | Union[str, Path] | Path to the JSON file. | required |
**kwargs | Metadata overrides. | {} |
Returns:
| Type | Description |
|---|---|
H3Hexagons | H3Hexagons instance loaded from file. |
from_points(points, resolution, **kwargs) classmethod ¶
Create H3Hexagons from a list of point coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points | List[Union[Point, Tuple[float, float]]] | List of points as Shapely Points or (lon, lat) tuples. | required |
resolution | int | H3 resolution level. | required |
**kwargs | Additional metadata parameters. | {} |
Returns:
| Type | Description |
|---|---|
H3Hexagons | H3Hexagons instance containing cells for all points. |
from_spatial(source, resolution, contain='overlap', **kwargs) classmethod ¶
Factory method to create H3Hexagons from various spatial sources.
Handles GeoDataFrames, Shapely geometries, and lists of coordinate points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source | Union[BaseGeometry, GeoDataFrame, List[Union[Point, Tuple[float, float]]]] | Spatial data source. | required |
resolution | int | Target H3 resolution. | required |
contain | Literal['center', 'full', 'overlap', 'bbox_overlap'] | H3 spatial containment logic. | 'overlap' |
**kwargs | Forwarded to specific factory methods (e.g., from_geometry). | {} |
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance. |
get_children(target_resolution) ¶
Generates all child hexagons at a higher resolution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_resolution | int | The target H3 resolution (must be > current). | required |
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance with children at the target resolution. |
Raises:
| Type | Description |
|---|---|
ValueError | If |
get_compact_representation() ¶
Merges adjacent hexagons into parent cells where possible (compacting).
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance in compacted form. Note that this may |
H3Hexagons | result in a set containing cells of multiple resolutions. |
get_hexagons_from_points(points, resolution) staticmethod ¶
Get list of H3 hexagon IDs for the provided points at specified resolution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points | List[Union[Point, Tuple[float, float]]] | List of points as either shapely Points or (lon, lat) tuples | required |
resolution | int | H3 resolution level | required |
Returns:
| Type | Description |
|---|---|
List[str] | List of H3 hexagon ID strings |
get_neighbors(k=1) ¶
Calculates k-ring neighbors for all hexagons in the collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
k | int | The distance of neighbors to retrieve (1 for immediate neighbors). Defaults to 1. | 1 |
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance containing the neighbors. |
get_parents(target_resolution) ¶
Retrieves parent hexagons at a lower resolution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_resolution | int | The target H3 resolution (must be < current). | required |
Returns:
| Type | Description |
|---|---|
H3Hexagons | A new H3Hexagons instance with parents at the target resolution. |
Raises:
| Type | Description |
|---|---|
ValueError | If |
save(file, format='json') ¶
Saves the H3Hexagons collection to persistent storage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file | Union[str, Path] | The destination file path. | required |
format | str | The output format. Supported: 'json', 'parquet', 'geojson'. Defaults to 'json'. | 'json' |
Raises:
| Type | Description |
|---|---|
ValueError | If an unsupported format is provided. |
to_dataframe() ¶
Converts the hexagon collection to a pandas DataFrame.
Returns:
| Type | Description |
|---|---|
DataFrame | A DataFrame with 'hexagon', 'latitude', and 'longitude' columns. |
to_geodataframe() ¶
Converts the hexagon collection to a GeoPandas GeoDataFrame.
Returns:
| Type | Description |
|---|---|
GeoDataFrame | A GeoDataFrame with 'h3' and 'geometry' columns. |
to_geoms() ¶
Converts hexagons to a list of Shapely Polygon geometries.
Returns:
| Type | Description |
|---|---|
List[Polygon] | A list of Polygons representing the cell boundaries. |
Bases: BaseModel
S2Cells class for generating and managing Google S2 cell grids.
S2 uses levels 0-30, where higher levels represent finer resolution. Level 0 covers the largest area and level 30 the smallest.
average_cell_area property ¶
Average area of cells at this level in square meters.
filter_cells(cells) ¶
Filter cells by a given set of cell IDs.
from_bounds(xmin, ymin, xmax, ymax, level, max_cells=100) classmethod ¶
Create S2Cells from boundary coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xmin, ymin, xmax, ymax | Bounding box coordinates in degrees | required | |
level | int | S2 level (0-30) | required |
max_cells | int | Maximum number of cells to generate | 100 |
from_cells(cells) classmethod ¶
Create S2Cells from list of S2 cell IDs (integers or tokens).
from_geometry(geometry, level, max_cells=1000, **kwargs) classmethod ¶
Create S2Cells from a geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geometry | BaseGeometry | Shapely geometry | required |
level | int | S2 level (0-30) | required |
max_cells | int | Maximum number of cells to generate | 1000 |
from_json(data_store, file, **kwargs) classmethod ¶
Load S2Cells from a JSON file.
from_points(points, level, **kwargs) classmethod ¶
Create S2Cells from a list of points or lat-lon pairs.
from_spatial(source, level, max_cells=1000, **kwargs) classmethod ¶
Create S2Cells from various spatial sources.
get_cells_from_points(points, level) staticmethod ¶
Get list of S2 cell IDs for the provided points at specified level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points | List[Union[Point, Tuple[float, float]]] | List of points as either shapely Points or (lon, lat) tuples | required |
level | int | S2 level | required |
Returns:
| Type | Description |
|---|---|
List[int] | List of S2 cell IDs as integers |
get_children(target_level) ¶
Get children cells at higher level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_level | int | Target level (must be higher than current) | required |
Returns:
| Type | Description |
|---|---|
S2Cells | New S2Cells instance with children at target level |
get_neighbors(direct_only=True) ¶
Get neighbors of all cells.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
direct_only | bool | If True, get only direct edge neighbors (4 per cell). If False, get all 8 neighbors including corners. | True |
Returns:
| Type | Description |
|---|---|
S2Cells | New S2Cells instance with neighbors included |
get_parents(target_level) ¶
Get parent cells at lower level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_level | int | Target level (must be lower than current) | required |
Returns:
| Type | Description |
|---|---|
S2Cells | New S2Cells instance with parents at target level |
save(file, format='json') ¶
Save S2Cells to file in specified format.
to_dataframe() ¶
Convert to pandas DataFrame with cell ID and centroid coordinates.
to_geodataframe() ¶
Convert to GeoPandas GeoDataFrame.
to_geoms() ¶
Convert cells to shapely Polygon geometries.
Bases: BaseModel
Representation of a collection of Web Mercator tiles as quadkeys.
Provides utility methods to create, filter, and manipulate Web Mercator grids for spatial analysis. Handles conversion between coordinate pairs, geometries, and quadkey strings.
Attributes:
| Name | Type | Description |
|---|---|---|
zoom_level | int | Web Mercator zoom level (0-20). |
quadkeys | List[str] | List of quadkey strings. |
data_store | DataStore | Storage interface for I/O operations. |
logger | ClassVar | Class-level logger. |
filter_quadkeys(quadkeys) ¶
Filters the current collection against a provided set of quadkeys.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
quadkeys | Iterable[str] | An iterable of quadkey strings to keep. | required |
Returns:
| Type | Description |
|---|---|
MercatorTiles | A new MercatorTiles instance containing only the intersecting tiles. |
from_bounds(xmin, ymin, xmax, ymax, zoom_level) classmethod ¶
Create MercatorTiles covering the specified geographic bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xmin | float | Minimum longitude. | required |
ymin | float | Minimum latitude. | required |
xmax | float | Maximum longitude. | required |
ymax | float | Maximum latitude. | required |
zoom_level | int | Web Mercator zoom level. | required |
Returns:
| Type | Description |
|---|---|
MercatorTiles | A new MercatorTiles instance covering the bounds. |
from_geometry(geometry, zoom_level, predicate='intersects', **kwargs) classmethod ¶
Create MercatorTiles from a Shapely geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geometry | BaseGeometry | Input geometry. | required |
zoom_level | int | Web Mercator zoom level. | required |
predicate | str | Spatial join predicate. | 'intersects' |
**kwargs | Additional metadata parameters. | {} |
Returns:
| Type | Description |
|---|---|
MercatorTiles | MercatorTiles instance covering the geometry. |
from_json(data_store, file, **kwargs) classmethod ¶
Load MercatorTiles from a JSON file in storage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data_store | DataStore | DataStore instance for the file. | required |
file | Union[str, Path] | Path to the JSON file. | required |
**kwargs | Metadata overrides. | {} |
Returns:
| Type | Description |
|---|---|
MercatorTiles | MercatorTiles instance loaded from file. |
from_points(points, zoom_level, **kwargs) classmethod ¶
Creates a MercatorTiles collection from a list of points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points | List[Union[Point, Tuple[float, float]]] | List of points as Shapely Points or (lon, lat) tuples. | required |
zoom_level | int | Web Mercator zoom level (0-20). | required |
**kwargs | Additional metadata parameters. | {} |
Returns:
| Type | Description |
|---|---|
MercatorTiles | A new MercatorTiles instance containing tiles for all points. |
from_quadkeys(quadkeys) classmethod ¶
Create MercatorTiles from a list of quadkeys.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
quadkeys | Iterable[Union[str, int]] | Iterable of quadkey strings or integers. | required |
Returns:
| Type | Description |
|---|---|
MercatorTiles | A new MercatorTiles instance. |
from_spatial(source, zoom_level, predicate='intersects', **kwargs) classmethod ¶
Factory method to create MercatorTiles from various spatial sources.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source | Union[BaseGeometry, GeoDataFrame, List[Union[Point, Tuple[float, float]]]] | Spatial data source (Geometry, GDF, or points). | required |
zoom_level | int | Web Mercator zoom level. | required |
predicate | str | Spatial predicate for containment ('intersects', 'within'). | 'intersects' |
**kwargs | Forwarded to specific factory methods. | {} |
Returns:
| Type | Description |
|---|---|
MercatorTiles | A new MercatorTiles instance. |
get_quadkeys_from_points(points, zoom_level) staticmethod ¶
Get list of quadkeys for the provided points at specified zoom level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points | List[Union[Point, Tuple[float, float]]] | List of points as either shapely Points or (lon, lat) tuples | required |
zoom_level | int | Zoom level for the quadkeys | required |
Returns:
| Type | Description |
|---|---|
List[str] | List of quadkey strings |
save(file, format='json') ¶
Saves the MercatorTiles collection to persistent storage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file | Union[str, Path] | The destination file path. | required |
format | str | The output format. Supported: 'json', 'parquet', 'geojson'. Defaults to 'json'. | 'json' |
Raises:
| Type | Description |
|---|---|
ValueError | If an unsupported format is provided. |
to_dataframe() ¶
Converts the tile collection to a pandas DataFrame.
Returns:
| Type | Description |
|---|---|
DataFrame | A DataFrame with 'quadkey', 'latitude', and 'longitude' columns. |
to_geodataframe() ¶
Converts the tile collection to a GeoPandas GeoDataFrame.
Returns:
| Type | Description |
|---|---|
GeoDataFrame | A GeoDataFrame with 'quadkey' and 'geometry' columns. |
to_geoms() ¶
Converts quadkeys into a list of Shapely box (polygon) geometries.
Returns:
| Type | Description |
|---|---|
List[box] | A list of boxes representing the tile boundaries. |