Package com.google.common.geometry
Class S2Cap
java.lang.Object
com.google.common.geometry.S2Cap
- All Implemented Interfaces:
S2Region
,Serializable
@GwtCompatible(serializable=true)
public final class S2Cap
extends Object
implements S2Region, Serializable
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.
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.
- See Also:
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionIncrease the cap radius if necessary to include the given cap.Increase the cap radius if necessary to include the given point.angle()
Returns the cap radius as an S1Angle.(package private) boolean
approxEquals
(S2Cap other) (package private) boolean
approxEquals
(S2Cap other, double maxError) Returns true if the radian angle between axes of this and 'other' is at most 'maxError', and the chord distance radius between this and 'other' is at most 'maxError'.double
area()
axis()
Return the complement of the interior of the cap.boolean
Return true if and only if this cap contains the given other cap (in a set containment sense, e.g.boolean
If this method returns true, the region completely contains the given cell.boolean
Returns true if and only if the given point is contained by the region.(package private) static S2Cap
Returns a new S2Cap decoded from the given little endian input stream.static S2Cap
decode
(InputStream is) Returns a new S2Cap decoded from the given input stream.static S2Cap
empty()
Return an empty cap, i.e.(package private) void
Writes this cap to the given little endian output stream.void
encode
(OutputStream os) Writes this cap to the given output stream.boolean
Return true if two caps are identical.static S2Cap
fromAxisAngle
(S2Point axis, S1Angle angle) Create a cap given its axis and the cap opening angle, i.e.static S2Cap
fromAxisArea
(S2Point axis, double area) Create a cap given its axis and its area in steradians.static S2Cap
fromAxisChord
(S2Point center, S1ChordAngle radius) Creates a cap where the radius is expressed as an S1ChordAngle.static S2Cap
fromAxisHeight
(S2Point axis, double height) Create a cap given its axis and the cap height, i.e.static S2Cap
full()
Return a full cap, i.e.Return a bounding spherical cap.Return a bounding latitude-longitude rectangle.int
hashCode()
double
height()
Returns the height of the cap, i.e.boolean
Return true if and only if the given point is contained in the interior of the region (i.e.boolean
interiorIntersects
(S2Cap other) Return true if and only if the interior of this cap intersects the given other cap.boolean
intersects
(S2Cell cell, S2Point[] vertices) Return true if the cap intersects 'cell', given that the cap vertices have already been checked.boolean
isEmpty()
Return true if the cap is empty, i.e.boolean
isFull()
Return true if the cap is full, i.e.boolean
isValid()
Returns true if the axis isunit length
, and the angle is less than Pi.boolean
mayIntersect
(S2Cell cell) If this method returns false, the region does not intersect the given cell.radius()
toString()
-
Field Details
-
axis
-
radius
-
-
Constructor Details
-
S2Cap
-
-
Method Details
-
fromAxisChord
Creates a cap where the radius is expressed as an S1ChordAngle. This constructor is more efficient thanfromAxisAngle(S2Point, S1Angle)
. -
fromAxisHeight
Create a cap given its axis and the cap height, i.e. the maximum projected distance along the cap axis from the cap center. 'axis' should be a unit-length vector. -
fromAxisAngle
Create a cap given its axis and the cap opening angle, i.e. maximum angle between the axis and a point on the cap. 'axis' should be a unit-length vector, and 'angle' should be between 0 and 180 degrees. -
fromAxisArea
Create a cap given its axis and its area in steradians. 'axis' should be a unit-length vector, and 'area' should be between 0 and 4 * M_PI. -
empty
Return an empty cap, i.e. a cap that contains no points. -
full
Return a full cap, i.e. a cap that contains all points. -
axis
-
radius
-
height
public double height()Returns the height of the cap, i.e. the distance from the center point to the cutoff plane. -
area
public double area() -
angle
Returns the cap radius as an S1Angle. Since the cap angle is stored internally as an S1ChordAngle, this method requires a trigonometric operation and may yield a slightly different result than the value passed tofromAxisAngle(S2Point, S1Angle)
. -
isValid
public boolean isValid()Returns true if the axis isunit length
, and the angle is less than Pi.Negative angles or heights are valid, and represent empty caps.
-
isEmpty
public boolean isEmpty()Return true if the cap is empty, i.e. it contains no points. -
isFull
public boolean isFull()Return true if the cap is full, i.e. it contains all points. -
complement
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. -
contains
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). -
interiorIntersects
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.) -
interiorContains
Return true if and only if the given point is contained in the interior of the region (i.e. the region excluding its boundary). 'p' should be a unit-length vector. -
addPoint
Increase the cap radius if necessary to include the given point. If the cap is empty the axis is set to the given point, but otherwise it is left unchanged.- Parameters:
p
- must beunit length
-
addCap
Increase the cap radius if necessary to include the given cap. If the current cap is empty, it is set to the given other cap. -
getCapBound
Description copied from interface:S2Region
Return a bounding spherical cap.- Specified by:
getCapBound
in interfaceS2Region
-
getRectBound
Description copied from interface:S2Region
Return a bounding latitude-longitude rectangle.- Specified by:
getRectBound
in interfaceS2Region
-
contains
Description copied from interface:S2Region
If this method returns true, the region completely contains the given cell. Otherwise, either the region does not contain the cell or the containment relationship could not be determined. -
mayIntersect
Description copied from interface:S2Region
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.- Specified by:
mayIntersect
in interfaceS2Region
-
intersects
Return true if the cap intersects 'cell', given that the cap vertices have already been checked. -
contains
Description copied from interface:S2Region
Returns true if and only if the given point is contained by the region.p
is generally required to be unit length, although some subtypes may relax this restriction. -
equals
Return true if two caps are identical. -
hashCode
public int hashCode() -
approxEquals
Returns true if the radian angle between axes of this and 'other' is at most 'maxError', and the chord distance radius between this and 'other' is at most 'maxError'. -
approxEquals
-
toString
-
encode
Writes this cap to the given output stream.- Throws:
IOException
-
encode
Writes this cap to the given little endian output stream.- Throws:
IOException
-
decode
Returns a new S2Cap decoded from the given input stream.- Throws:
IOException
-
decode
Returns a new S2Cap decoded from the given little endian input stream.- Throws:
IOException
-