{"id":17490321,"url":"https://github.com/aaliddell/s2cell","last_synced_at":"2025-04-15T01:40:48.617Z","repository":{"id":43289816,"uuid":"323346688","full_name":"aaliddell/s2cell","owner":"aaliddell","description":"Minimal Python S2 Geometry cell ID, token and lat/lon conversion library","archived":false,"fork":false,"pushed_at":"2024-03-01T23:45:41.000Z","size":12030,"stargazers_count":29,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T10:46:00.764Z","etag":null,"topics":["geometry","python","python3","s2","spherical-geometry"],"latest_commit_sha":null,"homepage":"https://docs.s2cell.aliddell.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaliddell.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-21T13:38:14.000Z","updated_at":"2025-02-04T10:45:06.000Z","dependencies_parsed_at":"2022-08-23T21:50:09.686Z","dependency_job_id":"d52175b8-19b9-45e4-b1c3-aa2268f7f028","html_url":"https://github.com/aaliddell/s2cell","commit_stats":{"total_commits":186,"total_committers":2,"mean_commits":93.0,"dds":0.005376344086021501,"last_synced_commit":"6b53051721359e9c0c215313a401f782ad687799"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaliddell%2Fs2cell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaliddell%2Fs2cell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaliddell%2Fs2cell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaliddell%2Fs2cell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaliddell","download_url":"https://codeload.github.com/aaliddell/s2cell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991221,"owners_count":21194890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geometry","python","python3","s2","spherical-geometry"],"created_at":"2024-10-19T06:07:55.859Z","updated_at":"2025-04-15T01:40:48.591Z","avatar_url":"https://github.com/aaliddell.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://docs.s2cell.aliddell.com/_static/logo.min.svg\n   :width: 200\n   :height: 200\n   :alt: s2cell logo\n\ns2cell\n======\n\nMinimal Python `S2 Geometry \u003chttps://s2geometry.io/\u003e`__\n`cell ID \u003chttps://s2geometry.io/devguide/s2cell_hierarchy.html\u003e`__, token and lat/lon conversion\nlibrary.\n\n`Docs \u003chttps://docs.s2cell.aliddell.com\u003e`__ | `PyPI \u003chttps://pypi.org/project/s2cell\u003e`__ | `GitHub \u003chttps://github.com/aaliddell/s2cell\u003e`__\n\n\n.. image:: https://github.com/aaliddell/s2cell/workflows/CI/badge.svg\n   :alt: CI Status\n   :target: https://github.com/aaliddell/s2cell/actions\n\n.. image:: https://readthedocs.org/projects/s2cell/badge/?version=latest\n   :alt: Documentation Status\n   :target: https://docs.s2cell.aliddell.com/en/latest\n\n.. image:: https://img.shields.io/github/license/aaliddell/s2cell\n   :alt: License\n   :target: https://github.com/aaliddell/s2cell\n\n.. image:: https://img.shields.io/pypi/v/s2cell\n   :alt: PyPI Version\n   :target: https://pypi.org/project/s2cell/\n\n\nOverview\n--------\n\nThis library does conversion between S2 cell ID, S2 token and latitude/longitude and was written as\na method to understand the way the S2 cell system works; hopefully this is useful to others as a\nsingle-file reference on the process, where tracing the relevant parts from the reference C++\nimplementation can be somewhat daunting. All steps in the conversions are well commented and written\nto be understandable and functional rather than strictly fast, although little is different from the\nreference implementation.\n\nThe library is checked against a test suite generated from the\n`reference C++ implementation \u003chttps://github.com/google/s2geometry\u003e`__ to ensure conformity with the\nstandard.\n\nShould you need more complete S2 Geometry functionality or a fast C-based implementation, please\nconsider using the Python extension `included in the s2geometry repository\n\u003chttps://github.com/google/s2geometry/tree/master/src/python\u003e`__ or the\npure-Python `s2sphere \u003chttps://pypi.org/project/s2sphere/\u003e`__ implementation.\n\nIssues and PRs are very welcome to improve the implementation, descriptions or to correct any\nmisunderstandings of the S2 cell system. Please note that this library strives to be an easy to read\nreference rather than aiming for peak performance (it is in Python after all), so PRs which reduce\nreadability of the implementation (such as for Python specific speed optimisations) are generally\ndiscouraged. However, if you have optimisations that are applicable to S2 implementations across\nmany languages and can be described easily, please do consider making a PR.\n\n\nInstallation\n------------\n\nThis package can be installed from `PyPI \u003chttps://pypi.org/project/s2cell/\u003e`__ with pip or any\nother Python package manager:\n\n.. code-block:: bash\n\n   pip install s2cell\n\n\nUsage\n-----\n\nThe full documentation, including the API Reference, is available at\n`docs.s2cell.aliddell.com \u003chttps://docs.s2cell.aliddell.com\u003e`__. Below is a quick start guide for\nthe most common uses.\n\nThe library is designed to be minimal, predictable and purely functional. Conversion from lat/lon\n(in degrees) to a cell ID or token can be done with the following two functions:\n\n.. code-block:: python3\n\n   s2cell.lat_lon_to_cell_id(-10.490091, 105.641318)  # -\u003e 3383782026967071427\n   s2cell.lat_lon_to_token(-10.490091, 105.641318)    # -\u003e '2ef59bd352b93ac3'\n\nBy default, these conversions will give you a level 30 leaf-cell as output. If you require a lower\nprecision level, you can specify this:\n\n.. code-block:: python3\n\n   s2cell.lat_lon_to_cell_id(-10.490091, 105.641318, 10)  # -\u003e 3383781119341101056\n   s2cell.lat_lon_to_token(-10.490091, 105.641318, 0)     # -\u003e '3'\n\nConversion from a cell ID or token to lat/lon (in degrees) can be done with the following two\nfunctions:\n\n.. code-block:: python3\n\n   s2cell.cell_id_to_lat_lon(3383781119341101056)  # -\u003e (-10.452552407574101, 105.6412526632361)\n   s2cell.token_to_lat_lon('3')                    # -\u003e (0.0, 90.0)\n\nThe lat/lon returned will be the center of the cell at the level available in the provided cell ID\nor token.\n\nThere are also a few other useful functions for inspecting or converting a cell ID/token:\n\n.. code-block:: python3\n\n   # Conversion between cell ID and token\n   s2cell.cell_id_to_token(3383781119341101056)  # -\u003e '2ef59b'\n   s2cell.token_to_cell_id('3')                  # -\u003e 3458764513820540928\n\n.. code-block:: python3\n\n   # Level extraction\n   s2cell.cell_id_to_level(3383781119341101056)  # -\u003e 10\n   s2cell.token_to_level('3')                    # -\u003e 0\n\n.. code-block:: python3\n\n   # Parent cell calculation\n   s2cell.cell_id_to_parent_cell_id(3383781119341101056)     # -\u003e 3383782218852728832\n   s2cell.cell_id_to_parent_cell_id(3383781119341101056, 2)  # -\u003e 3386706919782612992\n\n   s2cell.token_to_parent_token('2ef59b')                    # -\u003e '2ef59c'\n   s2cell.token_to_parent_token('2ef59b', 2)                 # -\u003e '2f'\n\n.. code-block:: python3\n\n   # Token canonicalisation\n   s2cell.token_to_canonical_token('2ef59BD352b90') # -\u003e '2ef59bd352b9'\n\n\nUseful S2 Geometry Links\n------------------------\n\nA list of useful links for S2 related concepts and projects can be found\n`here \u003chttps://docs.s2cell.aliddell.com/useful_s2_links.html\u003e`__.\n\n\nLicense\n-------\n\nThis project is released under the same license as the reference C++ S2 Geometry implementation,\nnamely the Apache 2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaliddell%2Fs2cell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaliddell%2Fs2cell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaliddell%2Fs2cell/lists"}