Module s2 

All S2 tooling

Structs

Metric

The following are various constants that describe the shapes and sizes of S2Cells (see s2coords.h and s2cell_id.h). They are useful for deciding which cell level to use in order to satisfy a given condition (e.g. that cell vertices must be no further than “x” apart). All of the raw constants are differential quantities; you can use the getValue(level) method to compute the corresponding length or area on the unit sphere for cells at a given level. The minimum and maximum bounds are valid for cells at all levels, but they may be somewhat conservative for very large cells (e.g. face cells).

S2Cap

S2Cap represents a disc-shaped region defined by a center and radius. Technically this shape is called a “spherical cap” (rather than disc) because it is not planar; the cap represents a portion of the sphere that has been cut off by a plane. The boundary of the cap is the circle defined by the intersection of the sphere and the plane. For containment purposes, the cap is a closed set, i.e. it contains its boundary.

S2Point

An S2Point represents a point on the unit sphere as a 3D vector. Usually points are normalized to be unit length, but some methods do not require this. See util/math/vector.h for the methods available. Among other things, there are overloaded operators that make it convenient to write arithmetic expressions (e.g. p1 + p2).

ST

Convert a direction vector (not necessarily unit length) to an (s,t) point.

UV

A U-V coordinate pair.

Enums

S2Projection

We have implemented three different projections from cell-space (s,t) to cube-space (u,v): linear, quadratic, and tangent. They have the following tradeoffs:

Constants

K_AVG_ANGLE_SPAN

Each cell is bounded by four planes passing through its four edges and the center of the sphere. These metrics relate to the angle between each pair of opposite bounding planes, or equivalently, between the planes corresponding to two different s-values or two different t-values. For example, the maximum angle between opposite bounding planes for a cell at level k is kMaxAngleSpan.GetValue(k), and the average angle span for all cells at level k is approximately kAvgAngleSpan.GetValue(k).

K_AVG_AREA

returns the AreaMetric of 4 * Math.PI / 6) (true for all projections)

K_AVG_DIAG

Linear -> 2.031817866418812674Tan -> 2.063623197195635753Quadratic -> 2.060422738998471683 Default

K_AVG_EDGE

Average edge length

K_AVG_WIDTH

Linear -> 1.411459345844456965Tan -> 1.437318638925160885Quadratic -> 1.434523672886099389

K_FACE_UVW_AXES

The precomputed neighbors of each face (see GetUVWFace).

K_FACE_UVW_FACES

The U,V,W axes for each face.

K_IJTO_POS

kIJtoPos[orientation][ij] -> pos

K_INVERT_MASK

‘kInvertMask’ is true, then the traversal order is rotated by 180 degrees (i.e. the bits of i and j are inverted, or equivalently, the axis directions are reversed).

K_LIMIT_IJ

The maximum index of a valid leaf cell plus one. The range of valid leaf cell indices is [0..kLimitIJ-1].

K_MAX_ANGLE_SPAN

Each cell is bounded by four planes passing through its four edges and the center of the sphere. These metrics relate to the angle between each pair of opposite bounding planes, or equivalently, between the planes corresponding to two different s-values or two different t-values. For example, the maximum angle between opposite bounding planes for a cell at level k is kMaxAngleSpan.GetValue(k), and the average angle span for all cells at level k is approximately kAvgAngleSpan.GetValue(k).

K_MAX_AREA

Max Area Metric

K_MAX_CELL_LEVEL

This is the number of levels needed to specify a leaf cell. This constant is defined here so that the S2::Metric class and the conversion functions below can be implemented without including s2cell_id.h. Please see s2cell_id.h for other useful constants and conversion functions.

K_MAX_DIAG

Linear -> 2.0 * @sqrt(2.0) (2.828)Tan -> pi * @sqrt(2.0 / 3.0) (2.565)Quadratic -> 2.438654594434021032 Default

K_MAX_DIAG_ASPECT

The maximum aspect ratio of a diagonal of a cell. NOTE: This is SQRT_3, but currently its behind a flag in rust

K_MAX_EDGE

The same as kMaxAngleSpan’s derivative.

K_MAX_EDGE_ASPECTquadratic

This is the maximum edge aspect ratio over all cells at any level, where the edge aspect ratio of a cell is defined as the ratio of its longest edge length to its shortest edge length.

K_MAX_SI_TI

The maximum value of an si- or ti-coordinate. The range of valid (si,ti) values is [0..kMaxSiTi].

K_MAX_WIDTH

The same as kMaxAngleSpan’s derivative.

K_MIN_ANGLE_SPANquadratic or tan or linear

Each cell is bounded by four planes passing through its four edges and the center of the sphere. These metrics relate to the angle between each pair of opposite bounding planes, or equivalently, between the planes corresponding to two different s-values or two different t-values. For example, the maximum angle between opposite bounding planes for a cell at level k is kMaxAngleSpan.GetValue(k), and the average angle span for all cells at level k is approximately kAvgAngleSpan.GetValue(k).

K_MIN_AREA

The minimum area of any cell at level k is at least kMinArea.getValue(k), and the maximum is at most kMaxArea.getValue(k). The average area of all cells at level k is exactly kAvgArea.getValue(k).

K_MIN_DIAG

The minimum diagonal length of any cell at level k is at least kMinDiag.getValue(k), and the maximum is at most kMaxDiag.getValue(k). The average diagonal length is approximately kAvgDiag.getValue(k).

K_MIN_EDGE

The minimum edge length of any cell at level k is at least kMinEdge.getValue(k), and the maximum is at most kMaxEdge.getValue(k). The average edge length is approximately kAvgEdge.getValue(k).

K_MIN_WIDTH

The width of geometric figure is defined as the distance between two parallel bounding lines in a given direction. For cells, the minimum width is always attained between two opposite edges, and the maximum width is attained between two opposite vertices. However, for our purposes we redefine the width of a cell as the perpendicular distance between a pair of opposite edges. A cell therefore has two widths, one in each direction. The minimum width according to this definition agrees with the classic geometric one, but the maximum width is different. (The maximum geometric width corresponds to kMaxDiag defined below.)

K_POS_TO_IJ

kPosToIJ[orientation][pos] -> ij

K_POS_TO_ORIENTATION

K_POS_TO_ORIENTATION[pos] -> orientation_modifier

K_SWAP_MASK

Together these flags define a cell orientation. If ‘kSwapMask’ is true, then canonical traversal order is flipped around the diagonal (i.e. i and j are swapped with each other). If

LOOKUP_IJ

[1 << (2 * kLookupBits + 2)]u16;

LOOKUP_POS

[1 << (2 * kLookupBits + 2)]u16;

ST_TO_UVquadratic

The default projection is quadratic

UV_TO_STquadratic

The default projection is quadratic

Traits

ConvertVectorFeatureS2

Underlying conversion mechanic to move S2 Geometry to GeoJSON Geometry

Functions

face_uv_to_xyz

Convert (face, u, v) coordinates to a direction vector (not necessarily unit length).

face_xyz_to_uv

If the dot product of p with the given face normal is positive, set the corresponding u and v values (which may lie outside the range [-1,1]) and return true. Otherwise return false.

face_xyz_to_uvw

Transform the given point P to the (u,v,w) coordinate frame of the given face (where the w-axis represents the face normal).

get_face

Return the face containing the given direction vector. (For points on the boundary between faces, the result is arbitrary but repeatable.)

get_norm

Return the unit-length normal for the given face.

get_u_axis

Return the u-axis for the given face.

get_u_norm

Return 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.)

get_uvw_axis

Return the given axis of the given face (u=0, v=1, w=2).

get_v_axis

Return the v-axis for the given face.

get_v_norm

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.

ij_to_st

Convert the i- or j-index of a leaf cell to the minimum corresponding s- or t-value contained by that cell. The argument must be in the range [0..2**30], i.e. up to one position beyond the normal range of valid leaf cell indices.

si_ti_to_st

Convert an si- or ti-value to the corresponding s- or t-value.

st_to_ij

Return the i- or j-index of the leaf cell containing the given s- or t-value. If the argument is outside the range spanned by valid leaf cell indices, return the index of the closest valid leaf cell (i.e., return values are clamped to the range of valid leaf cell indices).

st_to_si_ti

Return the si- or ti-coordinate that is nearest to the given s- or t-value. The result may be outside the range of valid (si,ti)-values.

st_to_uvlinear

Convert an s- or t-value to the corresponding u- or v-value. This is a non-linear transformation from [0,1] to [-1,1] that attempts to make the cell sizes more uniform.

st_to_uvquadratic

Convert an s- or t-value to the corresponding u- or v-value. This is a non-linear transformation from [0,1] to [-1,1] that attempts to make the cell sizes more uniform.

st_to_uvtan

Convert an s- or t-value to the corresponding u- or v-value. This is a non-linear transformation from [0,1] to [-1,1] that attempts to make the cell sizes more uniform.

to_face_st

Convert an S2Point to an (s,t) point.

to_face_uv

Convert an S2Point to an (u,v) point.

uv_to_st_quadratic

The inverse of the STtoUV transformation. Note that it is not always true that UV_TO_ST(STtoUV(x)) == x due to numerical errors.

uv_to_st_tan

The inverse of the STtoUV transformation. Note that it is not always true that UV_TO_ST(STtoUV(x)) == x due to numerical errors.

uv_to_stlinear

The inverse of the STtoUV transformation. Note that it is not always true that UV_TO_ST(STtoUV(x)) == x due to numerical errors.

valid_face_xyz_to_uv

Given a valid face for the given point p (meaning that dot product of p with the face normal is positive), return the corresponding u and v values (which may lie outside the range [-1,1]). Returns (pu, pv).

xyz_to_face_st

Convert a direction vector (not necessarily unit length) to (face, u, v) coordinates. Returns (face, ps, pt)

xyz_to_face_uv

Convert a direction vector (not necessarily unit length) to (face, u, v) coordinates. Returns (face, pu, pv)

Type Aliases

AreaMetric

Area based metrics

LengthMetric

Length based metrics