s2cell.s2cell module#

Minimal Python S2 Geometry cell ID, token and lat/lon conversion library.

exception s2cell.s2cell.InvalidCellID#

Bases: Exception

Exception type for invalid cell IDs.

exception s2cell.s2cell.InvalidToken#

Bases: Exception

Exception type for invalid tokens.

s2cell.s2cell.s2_cell_id_to_face_ij(cell_id: int) → Tuple[int, int, int]#

Convert S2 cell ID to face + IJ.

Parameters:

cell_id – The S2 cell ID integer.

Returns:

Tuple containing the face and IJ coordinates.

s2cell.s2cell.s2_face_ij_to_cell_id(face: int, i: int, j: int, level: int) → int#

Convert face + IJ to S2 cell ID.

Parameters:

  • face – The cell ID face.

  • i – The I component on the face.

  • j – The J component on the face.

  • level – The level of the resulting S2 cell ID.

Returns:

The S2 cell ID integer.

s2cell.s2cell.cell_id_to_token(cell_id: int) → str#

Convert S2 cell ID to a S2 token.

Converts the S2 cell ID to hex and strips any trailing zeros. The 0 cell ID token is represented as ‘X’ to prevent it being an empty string.

See s2geometry/blob/c59d0ca01ae3976db7f8abdc83fcc871a3a95186/src/s2/s2cell_id.cc#L204-L220

Parameters:

cell_id – The S2 cell ID integer.

Returns:

The S2 token string for the S2 cell ID.

Raises:

TypeError – If the cell_id is not int.

s2cell.s2cell.token_to_cell_id(token: str) → int#

Convert S2 token to S2 cell ID.

Restores the stripped 0 characters from the token and converts the hex string to integer.

See s2geometry/blob/c59d0ca01ae3976db7f8abdc83fcc871a3a95186/src/s2/s2cell_id.cc#L222-L239

Parameters:

token – The S2 token string. Can be upper or lower case hex string.

Returns:

The S2 cell ID for the S2 token.

Raises:

  • TypeError – If the token is not str.

  • InvalidToken – If the token length is over 16.

s2cell.s2cell.lat_lon_to_cell_id(lat: float, lon: float, level: int = 30) → int#

Convert lat/lon to a S2 cell ID.

It is expected that the lat/lon provided are normalised, with latitude in the range -90 to 90.

Parameters:

  • lat – The latitude to convert, in degrees.

  • lon – The longitude to convert, in degrees.

  • level – The level of the cell ID to generate, from 0 up to 30.

Returns:

The S2 cell ID for the lat/lon location.

Raises:

ValueError – When level is not an integer, is < 0 or is > 30.

s2cell.s2cell.lat_lon_to_token(lat: float, lon: float, level: int = 30) → str#

Convert lat/lon to a S2 token.

Converts the S2 cell ID to hex and strips any trailing zeros. The 0 cell ID token is represented as ‘X’ to prevent it being an empty string.

It is expected that the lat/lon provided are normalised, with latitude in the range -90 to 90.

See s2geometry/blob/c59d0ca01ae3976db7f8abdc83fcc871a3a95186/src/s2/s2cell_id.cc#L204-L220

Parameters:

  • lat – The latitude to convert, in degrees.

  • lon – The longitude to convert, in degrees.

  • level – The level of the cell ID to generate, from 0 up to 30.

Returns:

The S2 token string for the lat/lon location.

Raises:

ValueError – When level is not an integer, is < 0 or is > 30.

s2cell.s2cell.cell_id_to_lat_lon(cell_id: int) → Tuple[float, float]#

Convert S2 cell ID to lat/lon.

Parameters:

cell_id – The S2 cell ID integer.

Returns:

The lat/lon (in degrees) tuple generated from the S2 cell ID.

Raises:

  • TypeError – If the cell_id is not int.

  • InvalidCellID – If the cell_id is invalid.

s2cell.s2cell.token_to_lat_lon(token: str) → Tuple[float, float]#

Convert S2 token to lat/lon.

See s2geometry/blob/c59d0ca01ae3976db7f8abdc83fcc871a3a95186/src/s2/s2cell_id.cc#L222-L239

Parameters:

token – The S2 token string. Can be upper or lower case hex string.

Returns:

The lat/lon (in degrees) tuple generated from the S2 token.

Raises:

  • TypeError – If the token is not str.

  • InvalidToken – If the token length is over 16.

  • InvalidToken – If the token is invalid.

  • InvalidCellID – If the contained cell_id is invalid.

s2cell.s2cell.token_to_canonical_token(token: str) → str#

Convert S2 token to a canonicalised S2 token.

This produces a token that matches the form generated by the reference C++ implementation:

  • Lower case (except ‘X’ below)

  • No whitespace

  • Trailing ‘0’ characters stripped

  • Zero cell ID represented as ‘X’, not ‘x’ or ‘’

Parameters:

token – The S2 token string to canonicalise.

Returns:

The canonicalised S2 token.

s2cell.s2cell.cell_id_is_valid(cell_id: int) → bool#

Check that a S2 cell ID is valid.

Looks for valid face bits and a trailing 1 bit in one of the correct locations.

Parameters:

cell_id – The S2 cell integer to validate.

Returns:

True if the cell ID is valid, False otherwise.

Raises:

TypeError – If the cell_id is not int.

s2cell.s2cell.token_is_valid(token: str) → bool#

Check that a S2 token is valid.

Looks for valid characters, then checks that the contained S2 cell ID is also valid. Note that the ‘’, ‘x’ and ‘X’ tokens are considered invalid, since the cell IDs they represent are invalid.

Parameters:

token – The S2 token string to validate.

Returns:

True if the token is valid, False otherwise.

Raises:

TypeError – If the token is not str.

s2cell.s2cell.cell_id_to_level(cell_id: int) → int#

Get the level for a S2 cell ID.

See s2geometry/blob/c59d0ca01ae3976db7f8abdc83fcc871a3a95186/src/s2/s2cell_id.h#L543-L551

Parameters:

cell_id – The S2 cell ID integer.

Returns:

The level of the S2 cell ID.

Raises:

  • TypeError – If the cell_id is not int.

  • InvalidCellID – If the cell_id is invalid.

s2cell.s2cell.token_to_level(token: str) → int#

Get the level for a S2 token.

See s2geometry/blob/c59d0ca01ae3976db7f8abdc83fcc871a3a95186/src/s2/s2cell_id.h#L543-L551

Parameters:

token – The S2 token string. Can be upper or lower case hex string.

Returns:

The level of the S2 token.

Raises:

  • TypeError – If the token is not str.

  • InvalidToken – If the token length is over 16.

  • InvalidToken – If the token is invalid.

  • InvalidCellID – If the contained cell_id is invalid.

s2cell.s2cell.cell_id_to_parent_cell_id(cell_id: int, level: int | None = None) → int#

Get the parent cell ID of a S2 cell ID.

Parameters:

  • cell_id – The S2 cell ID integer.

  • level – The parent level to get the cell ID for. Must be less than or equal to the current level of the provided cell ID. If unspecified, or None, the direct parent cell ID will be returned.

Returns:

The parent cell ID at the specified level.

Raises:

  • TypeError – If the cell_id is not int.

  • InvalidCellID – If the cell_id is invalid.

  • ValueError – If cell ID is already level 0 and level is None.

  • ValueError – When level is not an integer, is < 0 or is > 30.

  • ValueError – If level is greater than the provided cell ID level.

s2cell.s2cell.token_to_parent_token(token: str, level: int | None = None) → str#

Get the parent token of a S2 token.

Parameters:

  • token – The S2 token string. Can be upper or lower case hex string.

  • level – The parent level to get the token for. Must be less than or equal to the current level of the provided toke. If unspecified, or None, the direct parent token will be returned.

Returns:

The parent token at the specified level.

Raises:

  • TypeError – If the token is not str.

  • InvalidToken – If the token length is over 16.

  • InvalidToken – If the token is invalid.

  • InvalidCellID – If the contained cell_id is invalid.

  • ValueError – If token is already level 0 and level is None.

  • ValueError – When level is not an integer, is < 0 or is > 30.

  • ValueError – If level is greater than the provided token level.

s2cell.s2cell.cell_id_to_neighbor_cell_ids(cell_id: int, edge: bool = True, corner: bool = False) → List[int]#

Get neighbor S2 cell ID for a given S2 cell ID.

There are two types of neighbors: edge neighbors and corner neighbors, which share either an edge or corner with the input cell respectively. Normally, there are 4 corner neighbors and 4 edge neighbors for each cell. However, at cube face corners, there are only 3 corner neighbors as there is not cell beyond the corner vertex that isn’t already represented by an edge neighbor.

By default, only edge neighbors are returned from this function, unless corner is True.

The order of the returned cell IDs is guaranteed to be in the order down, right, up, left from the input cell ID, If corner neighbors are requested, they will be interleaved correctly in that order. Note that face orientation may mean these directions are not where you expect on a globe.

See s2geometry/blob/2c02e21040e0b82aa5719e96033d02b8ce7c0eff/src/s2/s2cell_id.cc#L545-L586

Parameters:

  • cell_id – The S2 cell ID integer.

  • edge – If True, return edge neighbors in list.

  • corner – If True, return corner neighbors in list.

Returns:

List of neighbor S2 cell IDs.

Raises:

  • TypeError – If the cell_id is not int.

  • InvalidCellID – If the cell_id is invalid.