API

class s2sphere.Angle(radians=0)

A one-dimensional angle (as opposed to a two-dimensional solid angle).

It has methods for converting angles to or from radians and degrees.

Parameters:radians (float) – angle in radians

see S1Angle

classmethod from_degrees(degrees)

class generator

Parameters:degrees (float) – degrees

classmethod from_radians(radians)

radians

degrees

class s2sphere.AreaMetric(deriv)

Area metric. A 2D specialization of s2sphere.Metric (check for API).

Preconfigured instances of this class are s2sphere.AVG_AREA, s2sphere.MIN_AREA, s2sphere.MAX_AREA.

See C++ docs at S2::AreaMetric.

s2sphere.MIN_AREA = <s2sphere.sphere.AreaMetric object>

Minimum cell area for quadratic projections.

s2sphere.AVG_AREA = <s2sphere.sphere.AreaMetric object>

Average cell area for all projections.

s2sphere.MAX_AREA = <s2sphere.sphere.AreaMetric object>

Maximum cell area for quadratic projections.

class s2sphere.Cap(axis=Point: (1, 0, 0), height=-1)

A spherical cap, which is a portion of a sphere cut off by a plane.

see S2Cap

ROUND_UP = 1.0000000000000002

classmethod from_axis_height(axis, height)

classmethod from_axis_angle(axis, angle)

classmethod get_height_for_angle(radians)

classmethod from_axis_area(axis, area)

classmethod empty()

classmethod full()

height()

axis()

area()

2 * pi * height

angle()

is_valid()

is_empty()

is_full()

get_cap_bound()

add_point(point)

complement()

contains(other)

interior_contains(other)

intersects(*args)

may_intersect(other)

interior_intersects(other)

get_rect_bound()

approx_equals(other, max_error=1e-14)

expanded(distance)

class s2sphere.Cell(cell_id=None)

Cell

see S2Cell

classmethod from_lat_lng(lat_lng)

classmethod from_point(point)

classmethod from_face_pos_level(face, pos, level)

id()

face()

level()

orientation()

is_leaf()

get_edge(k)

the k-th edge

Return the inward-facing normal of the great circle passing through the edge from vertex k to vertex k+1 (mod 4). The normals returned by GetEdgeRaw are not necessarily unit length.

get_edge_raw(k)

get_vertex(k)

Return the k-th vertex of the cell (k = 0,1,2,3).

Vertices are returned in CCW order. The points returned by GetVertexRaw are not necessarily unit length.

get_vertex_raw(k)

exact_area()

cell area in steradians accurate to 6 digits but slow to compute

Return the area of this cell as accurately as possible. This method is more expensive but it is accurate to 6 digits of precision even for leaf cells (whose area is approximately 1e-18).

average_area()

cell area in steradians

approx_area()

approximate cell area in steradians accurate to within 3%

For cells at level 5 or higher (cells with edge length 350km or smaller), it is accurate to within 0.1%.

subdivide()

get_center()

get_center_raw()

contains(other)

may_intersect(cell)

get_latitude(i, j)

get_longitude(i, j)

get_cap_bound()

get_rect_bound()

class s2sphere.CellId(id_=0)

S2 cell id

The 64-bit ID has:

• 3 bits to encode the face
• 0-60 bits to encode the position
• a 1

The final 1 is the least significant bit (lsb) in the underlying integer representation and is returned with s2sphere.CellId.lsb().

see S2CellId

LINEAR_PROJECTION = 0

TAN_PROJECTION = 1

QUADRATIC_PROJECTION = 2

PROJECTION = 2

FACE_BITS = 3

NUM_FACES = 6

MAX_LEVEL = 30

POS_BITS = 61

MAX_SIZE = 1073741824

WRAP_OFFSET = 13835058055282163712L

classmethod from_lat_lng(ll)

classmethod from_point(p)

classmethod from_face_pos_level(face, pos, level)

classmethod from_face_ij(face, i, j)

classmethod from_face_ij_wrap(face, i, j)

classmethod from_face_ij_same(face, i, j, same_face)

classmethod st_to_ij(s)

classmethod lsb_for_level(level)

parent(*args)

child(pos)

contains(other)

intersects(other)

is_face()

id()

is_valid()

lsb()

face()

pos()

is_leaf()

level()

child_begin(*args)

child_end(*args)

prev()

next()

children(*args)

range_min()

range_max()

classmethod begin(level)

classmethod end(level)

classmethod walk(level)

Walk along a Hilbert curve at the given level.

This function does not exist in the SWIG bindings of the original C++ library. It provides a more Pythonic way to iterate over cells.

Returns:Iterator over instances of CellId s.

classmethod walk_fast(level)

Walk along a Hilbert curve at the given level.

This function does not exist in the SWIG bindings of the original C++ library. It provides a more Pythonic way to iterate over cells.

Use with caution: this repeatedly mutates a single instance with a changing id. If you save the object, it will change out from underneath you.

Returns:Iterator over ids in the same instance of CellId.

classmethod none()

prev_wrap()

next_wrap()

advance_wrap(steps)

advance(steps)

to_lat_lng()

to_point_raw()

to_point()

get_center_si_ti()

get_center_uv()

center of the cell in (u, v) coordinates

Return type:pair

to_face_ij_orientation()

get_edge_neighbors()

get_vertex_neighbors(level)

Return the neighbors of closest vertex to this cell.

Normally there are four neighbors, but the closest vertex may only have three neighbors if it is one of the 8 cube vertices.

get_all_neighbors(nbr_level)

get_size_ij(*args)

to_token()

A unique string token for this cell id.

This is a hex encoded version of the cell id with the right zeros stripped of.

classmethod from_token(token)

Creates a CellId from a hex encoded cell id string, called a token.

Parameters:token (str) – A hex representation of the cell id. If the input is shorter than 16 characters, zeros are appended on the right.

classmethod st_to_uv(s)

classmethod uv_to_st(u)

classmethod max_edge()

classmethod max_angle_span()

classmethod max_diag()

classmethod min_width()

class s2sphere.CellUnion(cell_ids=None, raw=True)

Cell Union

see S2CellUnion

classmethod get_union(x, y)

classmethod get_intersection(*args)

expand(*args)

classmethod get_difference(x, y)

num_cells()

cell_id(i)

cell_ids()

normalize()

denormalize(min_level, level_mod)

contains(*args)

intersects(*args)

get_rect_bound()

rectangular bound

class s2sphere.Interval(lo, hi)

Interval interface

lo()

hi()

bound(i)

bounds()

classmethod empty()

class s2sphere.LatLng(lat, lng)

A point on a sphere in latitute-longitude coordinates.

see S2LatLng

classmethod from_degrees(lat, lng)

classmethod from_radians(lat, lng)

classmethod from_point(point)

classmethod from_angles(lat, lng)

classmethod default()

classmethod invalid()

static latitude(point)

static longitude(point)

lat()

lng()

is_valid()

to_point()

normalized()

approx_equals(other, max_error=1e-15)

get_distance(other)

class s2sphere.LatLngRect(*args)

A rectangle in latitude-longitude space.

see S2LatLngRect

lat()

lng()

lat_lo()

lat_hi()

lng_lo()

lng_hi()

lo()

hi()

classmethod from_center_size(center, size)

classmethod from_point(p)

classmethod from_point_pair(a, b)

classmethod full_lat()

classmethod full_lng()

classmethod full()

is_full()

is_valid()

classmethod empty()

get_center()

get_size()

get_vertex(k)

area()

Area in steradians.

is_empty()

is_point()

convolve_with_cap(angle)

contains(other)

interior_contains(other)

may_intersect(cell)

intersects(*args)

classmethod intersects_lng_edge(a, b, lat, lng)

classmethod intersects_lat_edge(a, b, lat, lng)

interior_intersects(*args)

union(other)

intersection(other)

expanded(margin)

approx_equals(other, max_error=1e-15)

get_cap_bound()

class s2sphere.LengthMetric(deriv)

Length metric. A 1D specialization of s2sphere.Metric.

Preconfigured instances of this class are s2sphere.AVG_ANGLE_SPAN, s2sphere.MIN_ANGLE_SPAN, s2sphere.MAX_ANGLE_SPAN, s2sphere.AVG_EDGE, s2sphere.MIN_EDGE, s2sphere.MAX_EDGE, s2sphere.AVG_DIAG, s2sphere.MIN_DIAG, s2sphere.MAX_DIAG, s2sphere.AVG_WIDTH, s2sphere.MIN_WIDTH and s2sphere.MAX_WIDTH.

see S2::LengthMetric

class s2sphere.LineInterval(lo=1, hi=0)

Line Interval in R1

see R1Interval

classmethod from_point_pair(a, b)

contains(other)

interior_contains(other)

intersects(other)

interior_intersects(other)

union(other)

intersection(other)

expanded(radius)

get_center()

get_length()

is_empty()

approx_equals(other, max_error=1e-15)

class s2sphere.Metric(deriv, dim)

Metric

The classes s2sphere.LengthMetric and s2sphere.AreaMetric are specializations of this class.

see S2::Metric

deriv()

get_value(level)

The value of this metric at a given level.

Returns:Depending on whether this is used in one or two dimensions, this is an angle in radians or a solid angle in steradians.

get_closest_level(value)

Closest cell level according to the given value.

Return the level at which the metric has approximately the given value. For example, s2sphere.AVG_EDGE.get_closest_level(0.1) returns the level at which the average cell edge length is approximately 0.1. The return value is always a valid level.

Parameters:value – Depending on whether this is used in one or two dimensions, this is an angle in radians or a solid angle in steradians.

get_min_level(value)

Minimum cell level for given value.

Return the minimum level such that the metric is at most the given value, or s2sphere.CellId.MAX_LEVEL if there is no such level. For example, s2sphere.MAX_DIAG.get_min_level(0.1) returns the minimum level such that all cell diagonal lengths are 0.1 or smaller. The return value is always a valid level.

Parameters:value – Depending on whether this is used in one or two dimensions, this is an angle in radians or a solid angle in steradians.

get_max_level(value)

Maximum cell level for given value.

Return the maximum level such that the metric is at least the given value, or zero if there is no such level. For example, s2sphere.MIN_WIDTH.get_max_level(0.1) returns the maximum level such that all cells have a minimum width of 0.1 or larger. The return value is always a valid level.

Parameters:value – Depending on whether this is used in one or two dimensions, this is an angle in radians or a solid angle in steradians.

class s2sphere.Point(x, y, z)

A point in 3d Euclidean space.

“Normalized” points are points on the unit sphere.

see S2Point

abs()

largest_abs_component()

angle(other)

cross_prod(other)

dot_prod(other)

norm2()

norm()

normalize()

class s2sphere.RegionCoverer

Region Coverer

see S2RegionCoverer

class Candidate

num_children

min_level

max_level

level_mod

max_cells

get_covering(region)

get_interior_covering(region)

classmethod flood_fill(region, start)

classmethod get_simple_covering(region, start, level)

class s2sphere.SphereInterval(lo=3.141592653589793, hi=-3.141592653589793, args_checked=False)

Interval in S1

see S1Interval

classmethod from_point_pair(a, b)

classmethod positive_distance(a, b)

classmethod full()

is_full()

is_valid()

is_inverted()

is_empty()

get_center()

get_length()

complement()

Return the complement of the interior of the interval.

An interval and its complement have the same boundary but do not share any interior values. The complement operator is not a bijection, since the complement of a singleton interval (containing a single value) is the same as the complement of an empty interval.

approx_equals(other, max_error=1e-15)

fast_contains(other)

contains(other)

interior_contains(other)

intersects(other)

interior_intersects(other)

union(other)

intersection(other)

expanded(radius)

get_complement_center()

get_directed_hausdorff_distance(other)

Utilities

s2sphere.area(a, b, c)

Area of the triangle (a, b, c).

see S2::Area()

s2sphere.drem(x, y)

Like fmod but rounds to nearest integer instead of floor.

s2sphere.face_uv_to_xyz(face, u, v)

(face, u, v) to xyz

see S2::FaceUVtoXYZ()

s2sphere.face_xyz_to_uv(face, p)

(face, XYZ) to UV

see S2::FaceXYZtoUV()

s2sphere.get_norm(face)

s2sphere.get_u_axis(face)

s2sphere.get_u_norm(face, u)

Vector normal to the positive v-axis and the plane through the origin.

The vector is normal to the positive v-axis and a plane that contains the origin and the v-axis.

The right-handed normal (not necessarily unit length) for an edge in the direction of the positive v-axis at the given u-value on the given face. (This vector is perpendicular to the plane through the sphere origin that contains the given edge.)

Return type:Point

see S2::GetUNorm()

s2sphere.get_v_axis(face)

s2sphere.get_v_norm(face, v)

Vector normal to the positive u-axis and the plane through the origin.

The vector is normal to the positive u-axis and a plane that contains the origin and the u-axis.

Return the right-handed normal (not necessarily unit length) for an edge in the direction of the positive u-axis at the given v-value on the given face.

see S2::GetVNorm()

s2sphere.girard_area(a, b, c)

see S2::GirardArea()

s2sphere.is_unit_length(p)

s2sphere.origin()

A unique and empirically chosen reference point.

see S2::Origin()

s2sphere.ortho(a)

see S2::Ortho()

s2sphere.robust_cross_prod(a, b)

A numerically more robust cross product.

The direction of \(a \times b\) becomes unstable as \((a + b)\) or \((a - b)\) approaches zero. This leads to situations where \(a \times b\) is not very orthogonal to \(a\) and/or \(b\). We could fix this using Gram-Schmidt, but we also want \(b \times a = - a \times b\).

The easiest fix is to just compute the cross product of \((b+a)\) and \((b-a)\). Mathematically, this cross product is exactly twice the cross product of \(a\) and \(b\), but it has the numerical advantage that \((b+a)\) and \((b-a)\) are always perpendicular (since \(a\) and \(b\) are unit length). This yields a result that is nearly orthogonal to both \(a\) and \(b\) even if these two values differ only in the lowest bit of one component.

see S2::RobustCrossProd()

s2sphere.simple_ccw(a, b, c)

Simple Counterclockwise test.

Return true if the points A, B, C are strictly counterclockwise. Return false if the points are clockwise or collinear (i.e. if they are all contained on some great circle).

Due to numerical errors, situations may arise that are mathematically impossible, e.g. ABC may be considered strictly CCW while BCA is not. However, the implementation guarantees the following:

If simple_ccw(a,b,c), then !simple_ccw(c,b,a) for all a,b,c.

see S2::SimpleCCW()

s2sphere.simple_crossing(a, b, c, d)

see S2EdgeUtil::SimpleCrossing()

s2sphere.valid_face_xyz_to_uv(face, p)

s2sphere.xyz_to_face_uv(p)