Cell Identifiers

A cell can be named in several ways. Each names a cell only together with its grid: the same identifier names different cells in grids with a different N_side or different polar squares, so data exchanged by identifier should say which grid it uses, by its codespace, the uri of the registered grid or the one a grid is constructed with, which should resolve to the grid’s to_dggrs_definition(). The rHEALPix DGGRS that OGC registers (OGC rHEALPix, the preset WGS84_003_OGC) declares two of them as its identifiers. The grammar of the index strings is in the conformance chapter.

Representations

Representation

Example (WGS84_003_OGC)

Notes

Index string

'R553110'

A face letter and one digit per resolution, up to max_resolution, for N_side 2 and 3 only. The text identifier of OGC rHEALPix.

suid

('R', 5, 5, 3, 1, 1, 0)

The same as a tuple. Every grid has one.

Position

(6, 1080, 2847)

Level, row and column among all cells of that level in the planar grid, counted from the top left.

uint64

3458765673461713695

The position packed as level << 59 | row << 30 | column. The integer identifier of OGC rHEALPix. Every grid has one.

Level-row-col text

'6-438-B1F'

The position in hexadecimal, the text form of OGC 2D tile matrix sets. OGC rHEALPix does not declare it as an identifier.

Converting between them

For one cell, each representation is an attribute of the Cell, and the grid builds the cell back:

Representation

From a cell

To a cell

Index string

str(cell)

parse_index(), then cell()

suid

cell.suid

cell()

Position

level_row_col

cell_from_level_row_col()

uint64

uint64

cell_from_uint64()

Level-row-col text

level_row_col_text

cell_from_level_row_col_text()

For many cells, the grid converts arrays without building cells, in under a microsecond per cell for the integer forms. Positions are the hub, three int64 arrays of level, row and column:

rhp_to_uint64() and rhp_from_uint64() convert single index strings, returning None for invalid input like the other wrappers.

Sub-zone orders

Data laid out by position rather than by identifier, as in OGC API - DGGS and DGGS-JSON, depends on the order of a cell’s subcells. The orders take their names from OGC’s DGGRS definitions: "mortonCurve" (the order of the digits), "scanline" (rows across the whole cell), "hilbertCurve" (N_side a power of 2) and "spiralFromCenter" (odd N_side). Each grid declares one order, given by sub_zone_order: OGC rHEALPix declares "scanline", and other grids use "mortonCurve". That order is the default of subcells(), sub_zone_index() (a cell’s position among an ancestor’s subcells) and sub_zone_at() (the subcell at a position).

The identifiers module

Cell identifiers of an rHEALPix grid and the arithmetic behind them: index strings, the orders of a cell’s subcells, a cell’s level, row and column in the planar grid, and the uint64 and level-row-col text forms of that position. All of it depends only on a grid’s layout (N_side, the polar squares and max_resolution), not on its ellipsoid or projection. The supported API is the RHEALPixDGGS and Cell methods built on it.

rhealpixdggs.identifiers.CELLS0 = ['N', 'O', 'P', 'Q', 'R', 'S']

The resolution 0 cells, the faces of the cube, which begin every identifier.

rhealpixdggs.identifiers.INDEX_STRING_N_SIDES = (2, 3)

The N_side values whose grids have index strings (issue #146).

rhealpixdggs.identifiers.SUB_ZONE_ORDERS: tuple[str, ...] = ('mortonCurve', 'scanline', 'hilbertCurve', 'spiralFromCenter')

The names in SubZoneOrder.

rhealpixdggs.identifiers.SubZoneOrder

The orders of a cell’s subcells, by their names in OGC’s DGGRS definition schema; see Cell.subcells.

alias of Literal[‘mortonCurve’, ‘scanline’, ‘hilbertCurve’, ‘spiralFromCenter’]