Package com.google.common.geometry
Class S2Cap
- java.lang.Object
-
- com.google.common.geometry.S2Cap
-
- All Implemented Interfaces:
S2Region
,java.io.Serializable
@GwtCompatible(serializable=true) public final class S2Cap extends java.lang.Object implements S2Region, java.io.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:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description private S2Point
axis
private S1ChordAngle
radius
-
Constructor Summary
Constructors Modifier Constructor Description private
S2Cap(S2Point axis, S1ChordAngle radius)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description S2Cap
addCap(S2Cap other)
Increase the cap radius if necessary to include the given cap.S2Cap
addPoint(S2Point p)
Increase the cap radius if necessary to include the given point.S1Angle
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()
S2Point
axis()
S2Cap
complement()
Return the complement of the interior of the cap.boolean
contains(S2Cap other)
Return true if and only if this cap contains the given other cap (in a set containment sense, e.g.boolean
contains(S2Cell cell)
If this method returns true, the region completely contains the given cell.boolean
contains(S2Point p)
Returns true if and only if the given point is contained by the region.(package private) static S2Cap
decode(LittleEndianInput is)
Returns a new S2Cap decoded from the given little endian input stream.static S2Cap
decode(java.io.InputStream is)
Returns a new S2Cap decoded from the given input stream.static S2Cap
empty()
Return an empty cap, i.e.(package private) void
encode(LittleEndianOutput os)
Writes this cap to the given little endian output stream.void
encode(java.io.OutputStream os)
Writes this cap to the given output stream.boolean
equals(java.lang.Object that)
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.S2Cap
getCapBound()
Return a bounding spherical cap.S2LatLngRect
getRectBound()
Return a bounding latitude-longitude rectangle.int
hashCode()
double
height()
Returns the height of the cap, i.e.boolean
interiorContains(S2Point p)
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.S1ChordAngle
radius()
java.lang.String
toString()
-
-
-
Field Detail
-
axis
private final S2Point axis
-
radius
private final S1ChordAngle radius
-
-
Constructor Detail
-
S2Cap
private S2Cap(S2Point axis, S1ChordAngle radius)
-
-
Method Detail
-
fromAxisChord
public static S2Cap fromAxisChord(S2Point center, S1ChordAngle radius)
Creates a cap where the radius is expressed as an S1ChordAngle. This constructor is more efficient thanfromAxisAngle(S2Point, S1Angle)
.
-
fromAxisHeight
public static S2Cap fromAxisHeight(S2Point axis, double height)
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
public static S2Cap fromAxisAngle(S2Point axis, S1Angle angle)
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
public static S2Cap fromAxisArea(S2Point axis, double area)
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
public static S2Cap empty()
Return an empty cap, i.e. a cap that contains no points.
-
full
public static S2Cap full()
Return a full cap, i.e. a cap that contains all points.
-
axis
public S2Point axis()
-
radius
public S1ChordAngle 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
public S1Angle 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
@CheckReturnValue public S2Cap 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
public boolean contains(S2Cap other)
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
public boolean interiorIntersects(S2Cap other)
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
public boolean interiorContains(S2Point p)
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
@CheckReturnValue public S2Cap addPoint(S2Point p)
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
@CheckReturnValue public S2Cap addCap(S2Cap other)
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
public S2Cap getCapBound()
Description copied from interface:S2Region
Return a bounding spherical cap.- Specified by:
getCapBound
in interfaceS2Region
-
getRectBound
public S2LatLngRect getRectBound()
Description copied from interface:S2Region
Return a bounding latitude-longitude rectangle.- Specified by:
getRectBound
in interfaceS2Region
-
contains
public boolean contains(S2Cell cell)
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
public boolean mayIntersect(S2Cell cell)
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
public boolean intersects(S2Cell cell, S2Point[] vertices)
Return true if the cap intersects 'cell', given that the cap vertices have already been checked.
-
contains
public boolean contains(S2Point p)
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
public boolean equals(java.lang.Object that)
Return true if two caps are identical.- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
approxEquals
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'.
-
approxEquals
boolean approxEquals(S2Cap other)
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
encode
public void encode(java.io.OutputStream os) throws java.io.IOException
Writes this cap to the given output stream.- Throws:
java.io.IOException
-
encode
void encode(LittleEndianOutput os) throws java.io.IOException
Writes this cap to the given little endian output stream.- Throws:
java.io.IOException
-
decode
public static S2Cap decode(java.io.InputStream is) throws java.io.IOException
Returns a new S2Cap decoded from the given input stream.- Throws:
java.io.IOException
-
decode
static S2Cap decode(LittleEndianInput is) throws java.io.IOException
Returns a new S2Cap decoded from the given little endian input stream.- Throws:
java.io.IOException
-
-