Class 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.

class S2Cap
  : S2Region ;

For the most part, you can use a spherical cap wherever you would use a disc in planar geometry. The radius of the cap is measured along the surface of the sphere (rather than the straight-line distance through the interior). Thus a cap of radius Pi/2 is a hemisphere, and a cap of radius Pi covers the entire sphere.

A cap can also be defined by its center point and height. The height is simply the distance from the center point to the cutoff plane. There is also support for "empty" and "full" caps, which contain no points and all points respectively.

This class is intended to be copied by value as desired. It uses the default copy constructor and assignment operator, however it is not a "plain old datatype" (POD) because it has virtual functions.

Constructors

NameDescription
this () The default constructor returns an empty S2Cap.
this (center, radius) Constructs a cap with the given center and radius. A negative radius yields an empty cap; a radius of 180 degrees or more yields a full cap (containing the entire sphere). "center" should be unit length.
this (center, radius) Constructs a cap where the angle is expressed as an S1ChordAngle. This constructor is more efficient than the one above.

Methods

NameDescription
addCap (other) Increases the cap height if necessary to include "other". If the current cap is empty it is set to the given other cap.
addPoint (p) Increase the cap height if necessary to include the given point. If the cap is empty then the center is set to the given point, but otherwise the center is not changed. "p" should be a unit-length vector.
approxEquals (other, max_error_angle) Returns true if the cap center and height differ by at most "max_error" from the given cap "other".
clone ()
complement () Returns 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 because the complement of a singleton cap (containing a single point) is the same as the complement of an empty cap.
contains (other) Returns 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).
contains (p) The point "p" should be a unit-length vector.
decode (decoder) Decodes an S2Cap encoded with Encode(). Returns true on success.
empty () Returns an empty cap, i.e. a cap that contains no points.
encode (encoder) Appends a serialized representation of the S2Cap to "encoder".
expanded (distance) Returns a cap that contains all points within a given distance of this cap. Note that any expansion of the empty cap is still empty.
fromCenterArea (center, area) Returns a cap with the given center and surface area. Note that the area can also be interpreted as the solid angle subtended by the cap (because the sphere has unit radius). A negative area yields an empty cap; an area of 4*Pi or more yields a full cap. "center" should be unit length.
fromCenterHeight (center, height) Returns a cap with the given center and height (see comments above). A negative height yields an empty cap; a height of 2 or more yields a full cap. "center" should be unit length.
fromPoint (center) Convenience function that creates a cap containing a single point. This method is more efficient that the S2Cap(center, radius) constructor.
full () Returns a full cap, i.e. a cap that contains all points.
getArea () Returns the area of the cap.
getCellUnionBound (cell_ids) Computes a covering of the S2Cap. In general the covering consists of at most 4 cells except for very large caps, which may need up to 6 cells. The output is not sorted.
getCentroid () Returns the true centroid of the cap multiplied by its surface area (see s2centroids.h for details on centroids). The result lies on the ray from the origin through the cap's center, but it is not unit length. Note that if you just want the "surface centroid", i.e. the normalized result, then it is much simpler just to call center().
getRadius () Returns the cap radius as an S1Angle. (Note that the cap angle is stored internally as an S1ChordAngle, so this method requires a trigonometric operation and may yield a slightly different result than the value passed to the (S2Point, S1Angle) constructor.)
height () Returns the height of the cap, i.e. the distance from the center point to the cutoff plane.
interiorContains (p) Returns true if and only if the given point is contained in the interior of the cap (i.e. the cap excluding its boundary). "p" should be be a unit-length vector.
interiorIntersects (other) Returns 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.)
intersects (other) Returns true if and only if this cap intersects the given other cap, i.e. whether they have any points in common.
isEmpty () Returns true if the cap is empty, i.e. it contains no points.
isFull () Returns true if the cap is full, i.e. it contains all points.
isValid () We allow negative heights (to represent empty caps) but heights are normalized so that they do not exceed 2.
opEquals (o) Returns true if two caps are identical.
clone () Returns a deep copy of the region.
contains (p) Returns true if and only if the given point is contained by the region. The point 'p' is generally required to be unit length, although some subtypes may relax this restriction.
contains (cell) Returns true if the region completely contains the given cell, otherwise returns false.
getCapBound () Returns a bounding spherical cap that contains the region. The bound may not be tight.
getRectBound () Returns a bounding latitude-longitude rectangle that contains the region. The bound may not be tight.
mayIntersect (cell) If this method returns false, the region does not intersect the given cell. Otherwise, either region intersects the cell, or the intersection relationship could not be determined.