s2sphere

library0.2.5pypypi✓ verified 85d ago

s2sphere is a Python implementation of a part of Google's C++ S2 Geometry Library. It provides tools for working with spherical geometry, such as mapping points and regions on a sphere to a 1D index, enabling scalable proximity searches on distributed indexes. The current version is 0.2.5, and it maintains an active release cadence, primarily via updates to its GitHub repository and PyPI package. [1, 2, 3]

data database

pip install s2sphere

package ↗homepage ↗

INSTALL

IMPORT

SIG · S2SPHERE

s2sphere

datapythonv0.2.5

Install

2.1s avg

Import

43ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.046s · 22MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.041s · 22MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

s2sphere

✓ import s2sphere

All core classes and functions are typically accessed via the top-level s2sphere module.

LatLon

✓ s2sphere.LatLon.from_degrees(latitude, longitude)

✗ from s2sphere.sphere import LatLon

Direct imports from submodules like `s2sphere.sphere` are generally discouraged and may change between versions; prefer accessing through the main `s2sphere` module.

This quickstart demonstrates how to use `s2sphere` to find S2 cells covering a geographical region defined by two latitude-longitude points. It then shows how to convert one of these cell IDs back to its center latitude and longitude. [1, 3]

import s2sphere # Define two points using latitude and longitude p1 = s2sphere.LatLon.from_degrees(33, -122) p2 = s2sphere.LatLon.from_degrees(33.1, -122.1) # Create a region coverer r = s2sphere.RegionCoverer() # Get the S2 cells covering a LatLon rectangle defined by the two points cell_ids = r.get_covering(s2sphere.LatLonRect.from_point_pair(p1, p2)) # Print the resulting cell IDs print(f"S2 Cell IDs covering the region: {cell_ids}") # Example: Convert a CellId to LatLon if cell_ids: first_cell_id = cell_ids[0] center_latlon = s2sphere.LatLng.from_point(s2sphere.Cell(first_cell_id).get_center()) print(f"Center of the first cell ({first_cell_id.to_token()}): {center_latlon.degrees()}, {center_latlon.lngdegrees()}")

Debug

Known issues

breakingThe underlying C++ S2 Geometry Library, which `s2sphere` partially implements or binds to, explicitly states that its Python API is unstable and may be replaced. Future versions could introduce breaking changes due to a planned migration from SWIG to pybind11 for more Pythonic names and complete functionality. [5]

fix

Monitor official `s2sphere` and `google/s2geometry` repositories for announcements regarding API changes. Pin library versions in `requirements.txt` to mitigate unexpected updates.

affects: All 0.x versions and potentially future major versions.

gotchaThe `s2sphere.CellId.walk_hilbert_curve` method internally mutates a single `CellId` instance to yield subsequent IDs. If you store or save the `CellId` object returned by the iterator directly, its value will change out from underneath you in subsequent iterations. [12]

fix

When iterating with `walk_hilbert_curve`, ensure you explicitly create a *copy* of the `CellId` instance if you need to retain its value outside the current iteration. E.g., `for cell_id_obj in cell.walk_hilbert_curve(level): current_id = s2sphere.CellId(cell_id_obj.id) # Create a new instance`

affects: 0.2.5

gotchaThe `s2sphere` library is designed for spherical geometry. Applying assumptions from planar Euclidean geometry (e.g., straight-line distance, simple bounding boxes) can lead to incorrect results, especially over large distances or near poles. [3, 5, 9, 10]

fix

Always remember the spherical nature of S2 geometry. Utilize `s2sphere`'s dedicated methods for distance calculations, region coverings, and geometric operations that correctly account for Earth's curvature. Convert latitude/longitude pairs to `s2sphere.LatLng` and `s2sphere.Point` for accurate operations.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'str' object has no attribute 'get_center'

Users often obtain S2 Cell IDs as hex-encoded string 'tokens' (e.g., from databases or APIs). Attempting to directly use `Cell` or `CellId` object methods like `get_center()` or `get_vertex()` on such a string will result in an `AttributeError` because these methods belong to `s2sphere.CellId` or `s2sphere.Cell` objects, not strings. [17]

fix

Before using `CellId` or `Cell` methods, convert the hex-encoded string token into an `s2sphere.CellId` object using `s2sphere.CellId.from_token('your_hex_token_string')`.

TypeError: argument of type 'int' is not iterable

Some S2 sphere functions, particularly those dealing with collections of CellIds (like a RegionCoverer's output), expect iterable inputs or return lists of `CellId` objects. Trying to pass a single integer or non-iterable where a collection is expected, or conversely, attempting to iterate over a single `CellId`'s internal 'id' attribute (which is an integer) will raise this error.

fix

Ensure that inputs to `s2sphere` functions match the expected type (e.g., lists of `CellId` objects, `LatLonRect` objects). If you have a single `CellId` and a function expects an iterable, wrap it in a list `[my_cell_id]`. Remember that `CellId` objects have an `id` attribute which is an integer, and the `CellId` object itself is what is typically passed around.

Upgrade

Version history

0.2.5latest on PyPI · released Nov 16, 2017

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/s2sphere/ ↗

homepagehttp://s2sphere.readthedocs.io ↗