The conversion Module

Two maps of the same polygon over New Zealand filled with cells. Left: 518 cells, all at resolution 5. Right: the same coverage after compact_cells, 182 cells of mixed resolutions, with large low-resolution cells in the interior and small high-resolution cells along the edges.

Fig. 23 compact_cells: a uniform resolution 5 polyfill of a polygon (left) and the same set of cells after compaction (right), where any nine siblings all present in the set are replaced by their parent, repeatedly. The interior collapses to coarse cells while the edge detail is preserved exactly – here 518 cells become 182. The change of texture partway down is the boundary between the equatorial Q cells (longitude-latitude rectangles) and the south polar S cells (skew quads and darts, which are not).

cells_from_linestring(geometry, resolution, ...)

Return the index strings of the resolution resolution cells that the Shapely line geometry passes through, in order along it, a cell appearing again each time the line re-enters it, read as cells of rdggs.

cells_from_polygon(geometry, resolution, ...)

Return the index strings of the cells of the Shapely polygon geometry, read as cells of rdggs, as a sorted numpy string array without duplicates.

compact_cells(cells[, N_side])

Compact a set of rHEALPix DGGS cells by repeatedly merging complete groups of N_side ** 2 siblings into their parent until no further merging is possible.

compress_order_cells(cells[, recursive, N_side])

Compress and sort a collection of cells.

get_finest_containing_cell(polygon, rdggs)

Finds the finest DGGS Cell containing a given cartesian polygon

zones_from_query(zone_level, bbox, ...)

Interpret and execute a zone query of OGC API - DGGS (OGC 21-038r1, clause 12) on rdggs: return the identifiers of the zones the query selects, the zones array of its response.

rhealpixdggs.conversion.cells_from_linestring(geometry: LineString | MultiLineString, resolution: int, plane: bool = True, wrap_antimeridian: bool = False, line: Literal['plane', 'plate_carree', 'geodesic'] | None=None, rdggs: RHEALPixDGGS = <rhealpixdggs.dggs.RHEALPixDGGS object>) → list[str][source]

Return the index strings of the resolution resolution cells that the Shapely line geometry passes through, in order along it, a cell appearing again each time the line re-enters it, read as cells of rdggs. Each segment is traced by RHEALPixDGGS.cells_from_line, which describes plane, wrap_antimeridian and line: by default a segment is straight in the input coordinates, planar x and y if plane = True, else longitude and latitude, where it does not wrap around the antimeridian.

Return an empty list for an empty geometry. Raise TypeError unless geometry is a LineString or MultiLineString, and ValueError if it is invalid.

EXAMPLES:

>>> from shapely import LineString
>>> line = LineString([(-176.260506, -43.738058), (-176.258807, -43.738379)])
>>> cells_from_linestring(line, 9, plane=False)
['S001450634', 'S001450635']
rhealpixdggs.conversion.cells_from_polygon(geometry: Polygon | MultiPolygon, resolution: int, plane: bool = True, containment: Literal['center', 'full', 'overlapping']='center', compress: bool = False, min_res: int = 0, rdggs: RHEALPixDGGS = <rhealpixdggs.dggs.RHEALPixDGGS object>) → ndarray[source]

Return the index strings of the cells of the Shapely polygon geometry, read as cells of rdggs, as a sorted numpy string array without duplicates. The polygon’s coordinates are planar x and y if plane = True, else longitude and latitude. Its edges are straight in those coordinates and do not wrap around the antimeridian: split a region that straddles it into a MultiPolygon first.

containment chooses the cells at resolution resolution:

  • "center": the cell’s centroid is inside the geometry.

  • "full": the whole cell lies within the geometry (their boundaries may touch).

  • "overlapping": any part of the cell meets the geometry, so the result covers it.

full and overlapping test the cell’s boundary polygon, which is exact in the plane and for equatorial cells; the curved edges of polar cells are represented by 6 points each. A cap cell is fully inside only a geometry that covers the whole band from the cap’s boundary to the pole.

The fill descends from resolution min_res, keeping whole each cell wholly inside the geometry, dropping each cell clear of it and splitting only the cells its boundary passes through, so the work grows with the length of the boundary and not the area. With compress = False the kept cells are expanded to resolution. With compress = True the result is a mixed-resolution cover with no cell coarser than min_res and no complete group of siblings left unmerged; a coarse cell sorts where its descendants would.

Return an empty array for an empty geometry or one with no area. Raise TypeError unless geometry is a Polygon or MultiPolygon, and ValueError if it is invalid, if containment is not one of the three rules or if min_res is not between 0 and resolution.

EXAMPLES:

>>> from shapely import Polygon
>>> polygon = Polygon([(0, 0), (0, 1), (1, 1), (1, 0)])
>>> cells_from_polygon(polygon, 4, plane=False).tolist()
['Q3330']
>>> len(cells_from_polygon(polygon, 6, plane=False))
80
>>> len(cells_from_polygon(polygon, 6, plane=False, compress=True))
48
rhealpixdggs.conversion.compact_cells(cells: Iterable[str], N_side: int = 3) → set[str][source]

Compact a set of rHEALPix DGGS cells by repeatedly merging complete groups of N_side ** 2 siblings into their parent until no further merging is possible. N_side defaults to 3 (the default for RHEALPixDGGS and most presets, e.g. WGS84_003); pass the N_side of the DGGS the cells actually belong to if it’s not 3 (e.g. 2 for WGS84_002), otherwise a complete sibling group will never be recognised as complete and nothing will compact.

All input cells must be at the same resolution (equal string length). Raises ValueError if the input contains cells at mixed resolutions. Returns a set; if the caller needs ordering, sort the result separately.

rhealpixdggs.conversion.compress_order_cells(cells: list[str], recursive: bool = False, N_side: int = 3) → list[str][source]

Compress and sort a collection of cells.

Each complete group of N_side ** 2 siblings is replaced by their parent cell. N_side defaults to 3 (the default for RHEALPixDGGS and most presets, e.g. WGS84_003); pass the N_side of the DGGS the cells actually belong to if it’s not 3 (e.g. 2 for WGS84_002), otherwise a complete sibling group will never be recognised as complete and nothing will compress. By default only one level of compression is performed. Pass recursive=True to repeat until no further compression is possible. The result is always deduplicated and sorted alphanumerically.

rhealpixdggs.conversion.get_finest_containing_cell(polygon: Polygon | MultiPolygon, rdggs: RHEALPixDGGS = <rhealpixdggs.dggs.RHEALPixDGGS object>) → Cell | None[source]

Finds the finest DGGS Cell containing a given cartesian polygon

rhealpixdggs.conversion.zones_from_query(zone_level: int, bbox: Sequence[float] | None = None, parent_zone: str | None = None, compact_zones: bool = True, rdggs: RHEALPixDGGS = <rhealpixdggs.dggs.RHEALPixDGGS object>) → list[str][source]

Interpret and execute a zone query of OGC API - DGGS (OGC 21-038r1, clause 12) on rdggs: return the identifiers of the zones the query selects, the zones array of its response. The arguments are the query parameters zone-level, bbox, parent-zone and compact-zones, with the defaults the standard gives them.

  • zone_level: the resolution of the zones.

  • bbox: west, south, east and north bounds in longitude and latitude degrees (CRS84), selecting the zones inside or intersecting the box. A box whose west bound exceeds its east bound crosses the antimeridian. Six numbers are read as a box with heights, which are ignored. Without bbox every zone is selected.

  • parent_zone: only this zone and its sub-zones are returned.

  • compact_zones: if True, zones that together cover a parent are replaced by it, repeatedly, so the list stands for the zones at zone_level in fewer identifiers; it is ordered coarsest first.

The library holds no data, so every zone of the grid counts as having data, and the parameters that select by data (datetime, subset, filter) are left to the service that holds it.

Raise ValueError for a zone_level outside the grid’s resolutions, a parent_zone that is not a zone of the grid, or a bbox that is not four or six numbers bounding an area.

EXAMPLES:

>>> zones_from_query(1, parent_zone='N', compact_zones=False)
['N0', 'N1', 'N2', 'N3', 'N4', 'N5', 'N6', 'N7', 'N8']
>>> zones_from_query(2)
['N', 'O', 'P', 'Q', 'R', 'S']
>>> zones_from_query(2, bbox=(170, -10, -170, 10), compact_zones=False)
['O30', 'O33', 'O36', 'R52', 'R55', 'R58']
>>> zones_from_query(3, bbox=(165, -48, 179, -34))[:4]
['R88', 'R871', 'R872', 'R874']