Package: s2cell
s2cellMinimal PythonS2 Geometrycell ID, token and lat/lon conversion
library.Docs|PyPI|GitHubOverviewThis library does conversion between S2 cell ID, S2 token and latitude/longitude and was written as
a method to understand the way the S2 cell system works; hopefully this is useful to others as a
single-file reference on the process, where tracing the relevant parts from the reference C++
implementation can be somewhat daunting. All steps in the conversions are well commented and written
to be understandable and functional rather than strictly fast, although little is different from the
reference implementation.The library is checked against a test suite generated from thereference C++ implementationto ensure conformity with the
standard.Should you need more complete S2 Geometry functionality or a fast C-based implementation, please
consider using the Python extensionincluded in the s2geometry repositoryor the
pure-Pythons2sphereimplementation.Issues and PRs are very welcome to improve the implementation, descriptions or to correct any
misunderstandings of the S2 cell system. Please note that this library strives to be an easy to read
reference rather than aiming for peak performance (it is in Python after all), so PRs which reduce
readability of the implementation (such as for Python specific speed optimisations) are generally
discouraged. However, if you have optimisations that are applicable to S2 implementations across
many languages and can be described easily, please do consider making a PR.InstallationThis package can be installed fromPyPIwith pip or any
other Python package manager:pipinstalls2cellUsageThe full documentation, including the API Reference, is available atdocs.s2cell.aliddell.com. Below is a quick start guide for
the most common uses.The library is designed to be minimal, predictable and purely functional. Conversion from lat/lon
(in degrees) to a cell ID or token can be done with the following two functions:s2cell.lat_lon_to_cell_id(-10.490091,105.641318)# -> 3383782026967071427s2cell.lat_lon_to_token(-10.490091,105.641318)# -> '2ef59bd352b93ac3'By default, these conversions will give you a level 30 leaf-cell as output. If you require a lower
precision level, you can specify this:s2cell.lat_lon_to_cell_id(-10.490091,105.641318,10)# -> 3383781119341101056s2cell.lat_lon_to_token(-10.490091,105.641318,0)# -> '3'Conversion from a cell ID or token to lat/lon (in degrees) can be done with the following two
functions:s2cell.cell_id_to_lat_lon(3383781119341101056)# -> (-10.452552407574101, 105.6412526632361)s2cell.token_to_lat_lon('3')# -> (0.0, 90.0)The lat/lon returned will be the center of the cell at the level available in the provided cell ID
or token.There are also a few other useful functions for inspecting or converting a cell ID/token:# Conversion between cell ID and tokens2cell.cell_id_to_token(3383781119341101056)# -> '2ef59b's2cell.token_to_cell_id('3')# -> 3458764513820540928# Level extractions2cell.cell_id_to_level(3383781119341101056)# -> 10s2cell.token_to_level('3')# -> 0# Parent cell calculations2cell.cell_id_to_parent_cell_id(3383781119341101056)# -> 3383782218852728832s2cell.cell_id_to_parent_cell_id(3383781119341101056,2)# -> 3386706919782612992s2cell.token_to_parent_token('2ef59b')# -> '2ef59c's2cell.token_to_parent_token('2ef59b',2)# -> '2f'# Token canonicalisations2cell.token_to_canonical_token('2ef59BD352b90')# -> '2ef59bd352b9'Useful S2 Geometry LinksA list of useful links for S2 related concepts and projects can be foundhere.LicenseThis project is released under the same license as the reference C++ S2 Geometry implementation,
namely the Apache 2.0 License.