API¶
-
class
s2sphere.
Angle
(radians=0)[source]¶ 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
-
radians
¶
-
degrees
¶
-
-
class
s2sphere.
AreaMetric
(deriv)[source]¶ 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)[source]¶ A spherical cap, which is a portion of a sphere cut off by a plane.
see
S2Cap
-
ROUND_UP
= 1.0000000000000002¶
-
-
class
s2sphere.
Cell
(cell_id=None)[source]¶ Cell
see
S2Cell
-
get_edge
(k)[source]¶ 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_vertex
(k)[source]¶ 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.
-
exact_area
()[source]¶ 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).
-
-
class
s2sphere.
CellId
(id_=0)[source]¶ 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
walk
(level)[source]¶ 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)[source]¶ 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
.
-
get_vertex_neighbors
(level)[source]¶ 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.
-
to_token
()[source]¶ A unique string token for this cell id.
This is a hex encoded version of the cell id with the right zeros stripped of.
-
class
s2sphere.
CellUnion
(cell_ids=None, raw=True)[source]¶ Cell Union
see
S2CellUnion
-
class
s2sphere.
LatLng
(lat, lng)[source]¶ A point on a sphere in latitute-longitude coordinates.
see
S2LatLng
-
class
s2sphere.
LatLngRect
(*args)[source]¶ A rectangle in latitude-longitude space.
see
S2LatLngRect
-
class
s2sphere.
LengthMetric
(deriv)[source]¶ 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
ands2sphere.MAX_WIDTH
.see
S2::LengthMetric
-
class
s2sphere.
LineInterval
(lo=1, hi=0)[source]¶ Line Interval in R1
see
R1Interval
-
class
s2sphere.
Metric
(deriv, dim)[source]¶ Metric
The classes
s2sphere.LengthMetric
ands2sphere.AreaMetric
are specializations of this class.see
S2::Metric
-
get_value
(level)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ A point in 3d Euclidean space.
“Normalized” points are points on the unit sphere.
see
S2Point
-
class
s2sphere.
RegionCoverer
[source]¶ Region Coverer
see
S2RegionCoverer
-
min_level
¶
-
max_level
¶
-
level_mod
¶
-
max_cells
¶
-
-
class
s2sphere.
SphereInterval
(lo=3.141592653589793, hi=-3.141592653589793, args_checked=False)[source]¶ Interval in S1
see
S1Interval
-
complement
()[source]¶ 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.
-
Utilities¶
-
s2sphere.
area
(a, b, c)[source]¶ Area of the triangle (a, b, c).
see
S2::Area()
-
s2sphere.
get_u_norm
(face, u)[source]¶ 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_norm
(face, v)[source]¶ 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)[source]¶ see
S2::GirardArea()
-
s2sphere.
origin
()[source]¶ A unique and empirically chosen reference point.
see
S2::Origin()
-
s2sphere.
ortho
(a)[source]¶ see
S2::Ortho()
-
s2sphere.
robust_cross_prod
(a, b)[source]¶ 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.
-
s2sphere.
simple_ccw
(a, b, c)[source]¶ 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()