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.