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.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: Optional[int] = 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: Optional[int] = 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.