The conversion Module¶
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).¶
|
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. |
|
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 a set of rHEALPix DGGS cells by repeatedly merging complete groups of |
|
Compress and sort a collection of cells. |
|
Finds the finest DGGS Cell containing a given cartesian polygon |
|
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 |
- 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.
fullandoverlappingtest 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 ** 2siblings into their parent until no further merging is possible.N_sidedefaults to 3 (the default for RHEALPixDGGS and most presets, e.g.WGS84_003); pass theN_sideof the DGGS the cells actually belong to if it’s not 3 (e.g. 2 forWGS84_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 ** 2siblings is replaced by their parent cell.N_sidedefaults to 3 (the default for RHEALPixDGGS and most presets, e.g.WGS84_003); pass theN_sideof the DGGS the cells actually belong to if it’s not 3 (e.g. 2 forWGS84_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. Passrecursive=Trueto 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
zonesarray of its response. The arguments are the query parameterszone-level,bbox,parent-zoneandcompact-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']