geo-infer-space

name	geo-infer-space
description	H3 hexagonal spatial indexing and multi-backend spatial operations. Use when working with H3 cells, spatial indexing, coordinate systems, raster/vector operations, or any spatial backend dispatch (H3, SRAI, PostGIS).
prerequisites	{"required":["geo-infer-math"],"recommended":["geo-infer-data"]}
difficulty	intermediate
estimated_time	45min
examples_dir	../GEO-INFER-EXAMPLES/examples/

GEO-INFER-SPACE

Instructions

Core Capabilities

• H3 v4.5 indexing: Cell operations, hierarchical resolution, k-ring neighbors
• Nested H3 hierarchies: Parent/child closure, same-resolution adjacency, and deterministic aggregation for ordered H3 resolutions
• Backend dispatch: Interface pattern for H3, SRAI, PostGIS backends
• Coordinate systems: CRS transformations, EPSG management
• Spatial operations: Buffers, intersections, unions, containment
• Visualization: Choropleth maps, heatmaps, spatial dashboards

Key Imports

from geo_infer_space.backends.h3 import H3Backend
from geo_infer_space.core.spatial_operations import SpatialEngine
from geo_infer_space.core.coordinate_systems import CRSManager
from geo_infer_space.nested import NestedH3Grid

H3 v4.5 API (Critical)

import h3
# CORRECT (v4):
cell = h3.latlng_to_cell(lat, lng, resolution)
lat, lng = h3.cell_to_latlng(cell)
neighbors = h3.grid_disk(cell, k)

# WRONG (legacy v3 — never use):
# h3.geo_to_h3(), h3.h3_to_geo(), h3.k_ring()

Examples

from geo_infer_space.backends.h3 import H3Backend

backend = H3Backend()

# Index a point to an H3 cell at resolution 7
cell = backend.latlng_to_cell(45.5231, -122.6765, resolution=7)
print(f"H3 cell: {cell}")

# Get neighbors
neighbors = backend.grid_disk(cell, k=2)
print(f"Neighbors (k=2): {len(neighbors)} cells")

# Tessellate a region
from shapely.geometry import box
region = box(-122.8, 45.4, -122.5, 45.6)
cells = backend.tessellate(region, resolution=8)
print(f"Tessellation: {len(cells)} cells")

from geo_infer_space.nested import NestedH3Grid

grid = NestedH3Grid("sf_nested")
hierarchy = grid.build_h3_hierarchy_from_cells(
    ["89283082803ffff"],
    resolutions=[7, 8, 9],
)

assert hierarchy["validation"]["is_valid"]
assert hierarchy["validation"]["orphan_count"] == 0

from geo_infer_space.core.coordinate_systems import CRSManager

crs = CRSManager()
x, y = crs.transform(45.5, -122.6, from_epsg=4326, to_epsg=32610)
print(f"UTM Zone 10N: ({x:.0f}, {y:.0f})")

Guidelines

• Always use H3 v4 API — zero legacy calls allowed
• Runtime and dependency metadata must use real h3>=4.5.0,<5.
• Backend-agnostic: use the dispatcher pattern, not direct H3 calls
• For nested H3, construct hierarchies through NestedH3Grid; validate parent_child_map, child_parent_map, same_level_neighbors, and validation["orphan_count"] == 0 before handing cells to ACT.
• EPSG:4326 (WGS84) is the default CRS
• Test: uv run pytest GEO-INFER-SPACE/tests/unit/test_nested_h3_contract.py -q and uv run python -m pytest GEO-INFER-SPACE/tests/ -v

Integrations

• MATH → Spatial weights for statistics
• TIME → Spatio-temporal analysis
• DATA → Spatial indexing of datasets
• PLACE → Boundary tessellation with H3
• Nearly every module depends on SPACE for geographic indexing