Functions for Working with S2 Index
S2 is a geographical indexing system where all geographical data is represented on a three-dimensional sphere (similar to a globe).
In the S2 library points are represented as the S2 Index - a specific number which encodes internally a point on the surface of a unit sphere, unlike traditional (latitude, longitude) pairs. To get the S2 point index for a given point specified in the format (latitude, longitude) use the geoToS2 function. Also, you can use the s2ToGeo function for getting geographical coordinates corresponding to the specified S2 point index.
geoToS2
Returns S2 point index corresponding to the provided coordinates (longitude, latitude).
Syntax
geoToS2(lon, lat)
Arguments
Returned values
- S2 point index.
Type: UInt64.
Example
Query:
SELECT geoToS2(37.79506683, 55.71290588) AS s2Index;
Result:
┌─────────────s2Index─┐
│ 4704772434919038107 │
└─────────────────────┘
s2ToGeo
Returns geo coordinates (longitude, latitude) corresponding to the provided S2 point index.
Syntax
s2ToGeo(s2index)
Arguments
s2index— S2 Index. UInt64.
Returned values
- A tuple consisting of two values:
tuple(lon,lat).
Type: lon — Float64. lat — Float64.
Example
Query:
SELECT s2ToGeo(4704772434919038107) AS s2Coodrinates;
Result:
┌─s2Coodrinates────────────────────────┐
│ (37.79506681471008,55.7129059052841) │
└──────────────────────────────────────┘
s2GetNeighbors
Returns S2 neighbor indexes corresponding to the provided S2. Each cell in the S2 system is a quadrilateral bounded by four geodesics. So, each cell has 4 neighbors.
Syntax
s2GetNeighbors(s2index)
Arguments
s2index— S2 Index. UInt64.
Returned values
- An array consisting of 4 neighbor indexes:
array[s2index1, s2index3, s2index2, s2index4].
Type: UInt64.
Example
Query:
SELECT s2GetNeighbors(5074766849661468672) AS s2Neighbors;
Result:
┌─s2Neighbors───────────────────────────────────────────────────────────────────────┐
│ [5074766987100422144,5074766712222515200,5074767536856236032,5074767261978329088] │
└───────────────────────────────────────────────────────────────────────────────────┘
s2CellsIntersect
Determines if the two provided S2 cells intersect or not.
Syntax
s2CellsIntersect(s2index1, s2index2)
Arguments
siIndex1,s2index2— S2 Index. UInt64.
Returned values
- 1 — If the cells intersect.
- 0 — If the cells don't intersect.
Type: UInt8.
Example
Query:
SELECT s2CellsIntersect(9926595209846587392, 9926594385212866560) AS intersect;
Result:
┌─intersect─┐
│ 1 │
└───────────┘
s2CapContains
Determines if a cap contains a S2 point. A cap represents a part of the sphere that has been cut off by a plane. It is defined by a point on a sphere and a radius in degrees.
Syntax
s2CapContains(center, degrees, point)
Arguments
center— S2 point index corresponding to the cap. UInt64.degrees— Radius of the cap in degrees. Float64.point— S2 point index. UInt64.
Returned values
- 1 — If the cap contains the S2 point index.
- 0 — If the cap doesn't contain the S2 point index.
Type: UInt8.
Example
Query:
SELECT s2CapContains(1157339245694594829, 1.0, 1157347770437378819) AS capContains;
Result:
┌─capContains─┐
│ 1 │
└─────────────┘
s2CapUnion
Determines the smallest cap that contains the given two input caps. A cap represents a portion of the sphere that has been cut off by a plane. It is defined by a point on a sphere and a radius in degrees.
Syntax
s2CapUnion(center1, radius1, center2, radius2)
Arguments
center1,center2— S2 point indexes corresponding to the two input caps. UInt64.radius1,radius2— Radius of the two input caps in degrees. Float64.
Returned values
center— S2 point index corresponding the center of the smallest cap containing the two input caps. Type: UInt64.radius— Radius of the smallest cap containing the two input caps. Type: Float64.
Example
Query:
SELECT s2CapUnion(3814912406305146967, 1.0, 1157347770437378819, 1.0) AS capUnion;
Result:
┌─capUnion───────────────────────────────┐
│ (4534655147792050737,60.2088283994957) │
└────────────────────────────────────────┘
s2RectAdd
Increases the size of the bounding rectangle to include the given S2 point. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.
Syntax
s2RectAdd(s2pointLow, s2pointHigh, s2Point)
Arguments
s2PointLow— Low S2 point index corresponding to the rectangle. UInt64.s2PointHigh— High S2 point index corresponding to the rectangle. UInt64.s2Point— Target S2 point index that the bound rectangle should be grown to include. UInt64.
Returned values
s2PointLow— Low S2 cell id corresponding to the grown rectangle. Type: UInt64.s2PointHigh— Height S2 cell id corresponding to the grown rectangle. Type: UInt64.
Example
Query:
SELECT s2RectAdd(5178914411069187297, 5177056748191934217, 5179056748191934217) AS rectAdd;
Result:
┌─rectAdd───────────────────────────────────┐
│ (5179062030687166815,5177056748191934217) │
└───────────────────────────────────────────┘
s2RectContains
Determines if a given rectangle contains a S2 point. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.
Syntax
s2RectContains(s2PointLow, s2PointHi, s2Point)
Arguments
s2PointLow— Low S2 point index corresponding to the rectangle. UInt64.s2PointHigh— High S2 point index corresponding to the rectangle. UInt64.s2Point— Target S2 point index. UInt64.
Returned values
- 1 — If the rectangle contains the given S2 point.
- 0 — If the rectangle doesn't contain the given S2 point.
Example
Query:
SELECT s2RectContains(5179062030687166815, 5177056748191934217, 5177914411069187297) AS rectContains;
Result:
┌─rectContains─┐
│ 0 │
└──────────────┘
s2RectUnion
Returns the smallest rectangle containing the union of this rectangle and the given rectangle. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.
Syntax
s2RectUnion(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)
Arguments
s2Rect1PointLow,s2Rect1PointHi— Low and High S2 point indexes corresponding to the first rectangle. UInt64.s2Rect2PointLow,s2Rect2PointHi— Low and High S2 point indexes corresponding to the second rectangle. UInt64.
Returned values
s2UnionRect2PointLow— Low S2 cell id corresponding to the union rectangle. Type: UInt64.s2UnionRect2PointHi— High S2 cell id corresponding to the union rectangle. Type: UInt64.
Example
Query:
SELECT s2RectUnion(5178914411069187297, 5177056748191934217, 5179062030687166815, 5177056748191934217) AS rectUnion;
Result:
┌─rectUnion─────────────────────────────────┐
│ (5179062030687166815,5177056748191934217) │
└───────────────────────────────────────────┘
s2RectIntersection
Returns the smallest rectangle containing the intersection of this rectangle and the given rectangle. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.
Syntax
s2RectIntersection(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)
Arguments
s2Rect1PointLow,s2Rect1PointHi— Low and High S2 point indexes corresponding to the first rectangle. UInt64.s2Rect2PointLow,s2Rect2PointHi— Low and High S2 point indexes corresponding to the second rectangle. UInt64.
Returned values
s2UnionRect2PointLow— Low S2 cell id corresponding to the rectangle containing the intersection of the given rectangles. Type: UInt64.s2UnionRect2PointHi— High S2 cell id corresponding to the rectangle containing the intersection of the given rectangles. Type: UInt64.
Example
Query:
SELECT s2RectIntersection(5178914411069187297, 5177056748191934217, 5179062030687166815, 5177056748191934217) AS rectIntersection;
Result:
┌─rectIntersection──────────────────────────┐
│ (5178914411069187297,5177056748191934217) │
└───────────────────────────────────────────┘