Exposes S2 objects and methods.
The S2 library is mostly composed of datatypes and methods for converting one to another - a single point on Earth can be expressed by the library in several different ways, as can an area.
S2LatLng: the most familiar type of storage, this contains latitude &
longitude, stored internally as radians
rather than degrees.
S2Point: an x,y,z coordinate on a sphere. this is basically a vector
representation of any point. Not very relevant to any GIS theory, but this
is what's used most directly for converting into Cells.
S2Cap: a spherical cap - an
area from a single point on Earth to a specific radius around it. Both being
area representations, S2Cells and S2Caps can represent similar amounts of areas.
Also, for proximity searches, like "all points around this by 90m", S2Cap
provides a quick and geodesy-accurate way to compute.
S2Cell: a chunk of the tesselation S2 creates at a certain place. Cells
represent both points and areas, since they have four corners but also an
easily-computed centerpoint.
S2CellId: a minimal representation of an S2Cell. While S2Cell is the useful
data type for manipulating cell positions, ids are used for serializing
these cells into strings and numbers that are suitable for storage and
lookup in an index.
For anything beyond a single point, S2 pushes you to the idea of a covering.
A covering is a set of S2Cells that, combined, cover up the given shape.
They usually overestimate the shape - the boundary of these cells will
be ragged and slightly large than the Polygon itself. S2 has very special
math for computing coverings that is smart enough to take a budget of how
many cells at which levels, and to compute the covering that uses the least
but is the most accurate.
Coverings can be computed on anything that's an S2Region subclass. In these
bindings, that means (so far)
- S2LatLng[]
- S2LatLngRect
- S2Cap
- S2Cell
S2Point: an x,y,z coordinate on a sphere. this is basically a vector
representation of any point. These representations should be normalized -
they should be unit vectors of length 1.
Returns an [x, y, z] array serialization of this point.
Returns the stringification of this point as an array.
S2LatLng: the most familiar type of storage, this contains latitude &
longitude, stored internally as radians
rather than degrees..
Return true if the latitude is between -90 and 90 degrees inclusive and the longitude is between -180 and 180 degrees inclusive.
Convert a normalized S2LatLng to the equivalent unit-length vector.
Clamps the latitude to the range [-90, 90] degrees, and adds or subtracts a multiple of 360 degrees to the longitude if necessary to reduce it to the range [-180, 180].
Return a Point geometry of this latlng object
An S2Cell is an S2Region object that represents a cell. Unlike S2CellIds, it supports efficient containment and intersection tests. However, it is also a more expensive representation (currently 48 bytes rather than 8).
Return a Polygon geometry of this cell object
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).
Return the average area of cells at this level. This is accurate to
within a factor of 1.7 (for S2_QUADRATIC_PROJECTION) and is extremely
cheap to compute.
Return the direction vector corresponding to the center in (s,t)-space of the given cell. This is the point at which the cell is divided into four subcells; it is not necessarily the centroid of the cell in (u,v)-space or (x,y,z)-space. The point returned by GetCenterRaw is not necessarily unit length.
An S2LatLngRect represents a closed latitude-longitude rectangle. It is capable of representing the empty and full rectangles as well as single points.
Return a Polygon geometry of this latlngrect object
Returns the surface area of this rectangle on the unit sphere.
Return the center of the rectangle in latitude-longitude space (in general this is not the center of the region on the sphere).
Return true if the latitude and longitude intervals of the two rectangles are the same up to the given tolerance (see r1interval.h and s1interval.h for details).
Return the smallest rectangle containing the union of this rectangle and the given rectangle.
Return the smallest rectangle containing the intersection of this rectangle and the given rectangle. Note that the region of intersection may consist of two disjoint rectangles, in which case a single rectangle spanning both of them is returned.
Return the k-th vertex of the rectangle (k = 0,1,2,3) in CCW order.
Return true if the rectangle is empty, i.e. it contains no points at all.
Return true if the rectangle is valid, which essentially just means that the latitude bounds do not exceed Pi/2 in absolute value and the longitude bounds do not exceed Pi in absolute value. Also, if either the latitude or longitude bound is empty then both must be.
Return true if the rectangle is a point, i.e. lo() == hi()
This class represents a spherical cap, i.e. a portion of a sphere cut off by a plane. The cap is defined by its axis and height. This representation has good numerical accuracy for very small caps (unlike the (axis, min-distance-from-origin) representation), and is also efficient for containment tests (unlike the (axis, angle) representation).
Here are some useful relationships between the cap height (h), the cap opening angle (theta), the maximum chord length from the cap's center (d), and the radius of cap's base (a). All formulas assume a unit radius.
h = 1 - cos(theta)
= 2 sin^2(theta/2)
d^2 = 2 h
= a^2 + h^2
Caps may be constructed from either an axis and a height, or an axis and an angle. To avoid ambiguity, there are no public constructors except the default constructor.
node-s2 uses the FromAxisHeight constructor by default.
Return the complement of the interior of the cap. A cap and its complement have the same boundary but do not share any interior points. The complement operator is not a bijection, since the complement of a singleton cap (containing a single point) is the same as the complement of an empty cap.
Return true if and only if this cap contains the given other cap (in a set containment sense, e.g. every cap contains the empty cap).
Return true if and only if this cap intersects the given other cap, i.e. whether they have any points in common.
Return true if and only if the interior of this cap intersects the given other cap. (This relationship is not symmetric, since only the interior of this cap is used.)
This class represents a one-dimensional angle (as opposed to a two-dimensional solid angle). It has methods for converting angles to or from radians, degrees, and the E5/E6/E7 representations (i.e. degrees multiplied by 1e5/1e6/1e7 and rounded to the nearest integer).
This class has built-in support for the E5, E6, and E7
representations. An E5 is the measure of an angle in degrees,
multiplied by 10**5.
An S1Interval represents a closed interval on a unit circle (also known as a 1-dimensional sphere). It is capable of representing the empty interval (containing no points), the full interval (containing all points), and zero-length intervals (containing a single point).
Points are represented by the angle they make with the positive x-axis in the range [-Pi, Pi]. An interval is represented by its lower and upper bounds (both inclusive, since the interval is closed). The lower bound may be greater than the upper bound, in which case the interval is "inverted" (i.e. it passes through the point (-1, 0)).
Note that the point (-1, 0) has two valid representations, Pi and -Pi. The normalized representation of this point internally is Pi, so that endpoints of normal intervals are in the range (-Pi, Pi]. However, we take advantage of the point -Pi to construct two special intervals: the Full() interval is [-Pi, Pi], and the Empty() interval is [Pi, -Pi].
Return the length of the interval. The length of an empty interval is negative.
Return true if the interval (which is closed) contains the point 'p'.
An S2CellId is a 64-bit unsigned integer that uniquely identifies a cell in the S2 cell decomposition. It has the following format:
id = [face][face_pos]
face: a 3-bit number (range 0..5) encoding the cube face.
face_pos: a 61-bit number encoding the position of the center of this
cell along the Hilbert curve over this face (see the Wiki
pages for details).
Sequentially increasing cell ids follow a continuous space-filling curve over the entire sphere. They have the following properties:
-
The id of a cell at level k consists of a 3-bit face number followed by k bit pairs that recursively select one of the four children of each cell. The next bit is always 1, and all other bits are 0. Therefore, the level of a cell is determined by the position of its lowest-numbered bit that is turned on (for a cell at level k, this position is 2 * (kMaxLevel - k).)
-
The id of a parent cell is at the midpoint of the range of ids spanned by its children (or by its descendants at any level).
Leaf cells are often used to represent points on the unit sphere, and this class provides methods for converting directly between these two representations. For cells that represent 2D regions rather than discrete point, it is better to use the S2Cell class.
Return the direction vector corresponding to the center of the given cell. The vector returned by ToPointRaw is not necessarily unit length.
Creates a debug human readable string. Used for << and available for direct usage as well.
Methods to encode and decode cell ids to compact text strings suitable for display or indexing. Cells at lower levels (i.e. larger cells) are encoded into fewer characters. The maximum token length is 16.
ToToken() returns a string by value for convenience; the compiler does this without intermediate copying in most cases.
These methods guarantee that FromToken(ToToken(x)) == x even when "x" is an invalid cell id. All tokens are alphanumeric strings. FromToken() returns S2CellId::None() for malformed inputs.
Return the cell at the previous level or at the given level (which must be less than or equal to the current level).
Initialze this cell id with a given string token.
child is from 0 to 3, the cell's child at each location.
Methods that return the range of cell ids that are contained within this cell (including itself). The range is inclusive (i.e. test using >= and <=) and the return values of both methods are valid leaf cell ids.
These methods should not be used for iteration. If you want to iterate through all the leaf cells, call child_begin(kMaxLevel) and child_end(kMaxLevel) instead.
It would in fact be error-prone to define a range_end() method, because (range_max().id() + 1) is not always a valid cell id, and the iterator would need to be tested using "<" rather that the usual "!=".
The 64-bit unique identifier for this cell.
Get a covering, expressed as CellIds, for a given region. If an array of S2LatLng objects is provided, they will be turned into a S2Loop internally. Options is an optional object that includes:
| option | desc | default | note |
|---|---|---|---|
| min | minimum level | 1 | min option will override max_cells to cover the input region |
| max | maximum level | 30 | |
| max_cells | max number of cells to be computed | null | |
| level_mod | modulo for skipping levels | 1 | defines branch velocity. 1:4x; 2:16x; 3:64x |
| result_type | encoding of cells | cell | one of cell, cellId, string, token, point |