Package com.google.common.geometry
Class S2Cell
- java.lang.Object
-
- com.google.common.geometry.S2Cell
-
- All Implemented Interfaces:
S2Region
,java.io.Serializable
@GwtCompatible(serializable=true) public final class S2Cell extends java.lang.Object implements S2Region, java.io.Serializable
An S2Cell is an S2Region object that represents a cell. Unlike S2CellIds, it supports efficient containment and intersection tests. However, it is also a more expensive representation.- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static interface
S2Cell.DoubleBinaryOperator
-
Field Summary
Fields Modifier and Type Field Description (package private) S2CellId
cellId
(package private) byte
face
(package private) byte
level
(package private) byte
orientation
private static double
POLE_MIN_LAT
The 4 cells around the equator extend to +/-45 degrees latitude at the midpoints of their top and bottom edges.(package private) double
uMax
(package private) double
uMin
(package private) double
vMax
(package private) double
vMin
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description double
approxArea()
Return the approximate area of this cell in steradians.double
averageArea()
Return the average area in steradians of cells at this level.static double
averageArea(int level)
Return the average area in steradians for cells at the given level.private static double
chordDist2(S2Point uvw, double u, double v)
Returns the squared chord distance fromuvw
to positionuv
.S2Region
clone()
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.private static double
edgeDistance(double dirIJ, double uv)
Given the dot product of a point P with the normal of a u- or v-edge at the given coordinate value, returns the distance from P to that edge.boolean
equals(java.lang.Object that)
double
exactArea()
Return the area in steradians of this cell as accurately as possible.int
face()
static S2Cell
fromFace(int face)
Returns the cell corresponding to the given S2 cube face.static S2Cell
fromFacePosLevel(int face, long pos, int level)
Returns a cell given its face (range 0..5), Hilbert curve position within that face (an unsigned integer withS2CellId.POS_BITS
bits), and level (range 0..kMaxLevel).S1ChordAngle
getBoundaryDistance(S2Point target)
Returns the distance from the cell boundary to the given point.R2Rect
getBoundUV()
Returns the bounds of this cell in (u,v)-space.S2Cap
getCapBound()
Return a bounding spherical cap.S2Point
getCenter()
Return the direction vector corresponding to the center in (s,t)-space of the given cell.S2Point
getCenterRaw()
R2Vector
getCenterUV()
Return the center of the cell in (u,v) coordinates (seeS2Projections
).S1ChordAngle
getDistance(S2Cell target)
Returns the distance to the given cell.S1ChordAngle
getDistance(S2Point targetXyz)
Returns the distance from the given point to the cell.private double
getDistanceInternal(S2Point targetXyz, boolean toInterior)
Returns the chord distance to targetXyz, with interior distance 0 iff toInterior is true.S1ChordAngle
getDistanceToEdge(S2Point a, S2Point b)
Returns the minimum distance from the cell to the given edge AB, or zero if the edge intersects the cell interior.S2Point
getEdge(int k)
AsgetEdgeRaw(int)
, except the point is normalized to unit length.S2Point
getEdgeRaw(int k)
Returns the inward-facing normal of the great circle passing through the edge from vertex k to vertex k+1 (mod 4).S1ChordAngle
getMaxDistance(S2Cell target)
Returns the maximum distance from the cell, including interior, to the given target cell.S1ChordAngle
getMaxDistance(S2Point target)
Returns the maximum distance from the cell (including its interior) to the given point.S1ChordAngle
getMaxDistance(S2Point a, S2Point b)
Returns the maximum distance from the cell (including its interior) to the given edge AB.private S2Point
getPoint(int i, int j)
S2LatLngRect
getRectBound()
Return a bounding latitude-longitude rectangle.int
getSizeIJ()
AsS2CellId.getSizeIJ(int)
, using the level of this cell.S2Point
getVertex(int k)
AsgetVertexRaw(int)
, except the point is normalized to unit length.S2Point
getVertexRaw(int k)
Returns the kth vertex of the cell (k = 0,1,2,3).int
hashCode()
S2CellId
id()
private void
init(S2CellId id)
boolean
isLeaf()
Returns true if this cell is a leaf-cell, i.e.byte
level()
boolean
mayIntersect(S2Cell cell)
If this method returns false, the region does not intersect the given cell.byte
orientation()
(package private) void
setBoundUV(R2Rect bound)
Sets the bounds of this cell in (u,v)-space into 'bound'.boolean
subdivide(S2Cell[] children)
Returns true if this is not a leaf cell, in which case the array, which must contain at least four non-null cells in indices 0..3, will be set to the four children of this cell in traversal order.java.lang.String
toString()
private boolean
uEdgeIsClosest(S2Point p, boolean vEnd)
Given a pointp
and either the lower or upper edge of theS2Cell
(specified by settingvEnd
to false or true respectively), returns true ifp
is closer to the interior of that edge than it is to either endpoint.private boolean
vEdgeIsClosest(S2Point p, boolean uEnd)
Given a pointp
and either the left or right edge of theS2Cell
(specified by settinguEnd
to false or true respectively), returns true ifp
is closer to the interior of that edge than it is to either endpoint.private double
vertexChordDist2(S2Point uvw, S2Cell.DoubleBinaryOperator reducer)
-
-
-
Field Detail
-
face
byte face
-
level
byte level
-
orientation
byte orientation
-
cellId
S2CellId cellId
-
uMin
double uMin
-
uMax
double uMax
-
vMin
double vMin
-
vMax
double vMax
-
POLE_MIN_LAT
private static final double POLE_MIN_LAT
The 4 cells around the equator extend to +/-45 degrees latitude at the midpoints of their top and bottom edges. The two cells covering the poles extend down to +/-35.26 degrees at their vertices. The maximum error in this calculation is 0.5 * DBL_EPSILON.
-
-
Method Detail
-
fromFace
public static S2Cell fromFace(int face)
Returns the cell corresponding to the given S2 cube face.
-
fromFacePosLevel
public static S2Cell fromFacePosLevel(int face, long pos, int level)
Returns a cell given its face (range 0..5), Hilbert curve position within that face (an unsigned integer withS2CellId.POS_BITS
bits), and level (range 0..kMaxLevel). The given position will be modified to correspond to the Hilbert curve position at the center of the returned cell. This is a static function rather than a constructor in order to indicate what the arguments represent.
-
id
public S2CellId id()
-
face
public int face()
-
level
public byte level()
-
orientation
public byte orientation()
-
isLeaf
public boolean isLeaf()
Returns true if this cell is a leaf-cell, i.e. it has no children.
-
getVertex
public S2Point getVertex(int k)
AsgetVertexRaw(int)
, except the point is normalized to unit length.
-
getVertexRaw
public S2Point getVertexRaw(int k)
Returns the kth vertex of the cell (k = 0,1,2,3). Vertices are returned in CCW order (lower left, lower right, upper right, upper left in the UV plane). The points are not necessarily unit length.
-
getEdge
public S2Point getEdge(int k)
AsgetEdgeRaw(int)
, except the point is normalized to unit length.
-
getEdgeRaw
public S2Point getEdgeRaw(int k)
Returns the inward-facing normal of the great circle passing through the edge from vertex k to vertex k+1 (mod 4). The normals returned by getEdgeRaw are not necessarily unit length.
-
getSizeIJ
public int getSizeIJ()
AsS2CellId.getSizeIJ(int)
, using the level of this cell.
-
subdivide
public boolean subdivide(S2Cell[] children)
Returns true if this is not a leaf cell, in which case the array, which must contain at least four non-null cells in indices 0..3, will be set to the four children of this cell in traversal order. Otherwise, if this is a leaf cell, false is returned without touching the array.This method is equivalent to the following:
for (pos=0, id=childBegin(); !id.equals(childEnd()); id = id.next(), ++pos) { children[i].init(id); }
except that it is more than two times faster.
-
getCenter
public S2Point getCenter()
Return the direction vector corresponding to the center in (s,t)-space of the given cell. This is the point at which the cell is divided into four subcells; it is not necessarily the centroid of the cell in (u,v)-space or (x,y,z)-space. The point returned by GetCenterRaw is not necessarily unit length.
-
getCenterRaw
public S2Point getCenterRaw()
-
getBoundUV
public R2Rect getBoundUV()
Returns the bounds of this cell in (u,v)-space.
-
setBoundUV
void setBoundUV(R2Rect bound)
Sets the bounds of this cell in (u,v)-space into 'bound'.Package private to avoid leaking object mutation outside the api.
-
getCenterUV
public R2Vector getCenterUV()
Return the center of the cell in (u,v) coordinates (seeS2Projections
). Note that the center of the cell is defined as the point at which it is recursively subdivided into four children; in general, it is not at the midpoint of the (u,v) rectangle covered by the cell
-
averageArea
public static double averageArea(int level)
Return the average area in steradians for cells at the given level.
-
averageArea
public double averageArea()
Return the average area in steradians of cells at this level. This is accurate to within a factor of 1.7 (for S2_QUADRATIC_PROJECTION) and is extremely cheap to compute.
-
approxArea
public double approxArea()
Return the approximate area of this cell in steradians. This method is accurate to within 3% percent for all cell sizes and accurate to within 0.1% for cells at level 5 or higher (i.e. 300km square or smaller). It is moderately cheap to compute.
-
exactArea
public double exactArea()
Return the area in steradians of this cell as accurately as possible. This method is more expensive but it is accurate to 6 digits of precision even for leaf cells (whose area is approximately 1e-18).
-
clone
public S2Region clone()
- Overrides:
clone
in classjava.lang.Object
-
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
-
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
-
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.
-
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.
-
vertexChordDist2
private double vertexChordDist2(S2Point uvw, S2Cell.DoubleBinaryOperator reducer)
-
chordDist2
private static double chordDist2(S2Point uvw, double u, double v)
Returns the squared chord distance fromuvw
to positionuv
.
-
uEdgeIsClosest
private boolean uEdgeIsClosest(S2Point p, boolean vEnd)
Given a pointp
and either the lower or upper edge of theS2Cell
(specified by settingvEnd
to false or true respectively), returns true ifp
is closer to the interior of that edge than it is to either endpoint.
-
vEdgeIsClosest
private boolean vEdgeIsClosest(S2Point p, boolean uEnd)
Given a pointp
and either the left or right edge of theS2Cell
(specified by settinguEnd
to false or true respectively), returns true ifp
is closer to the interior of that edge than it is to either endpoint.
-
edgeDistance
private static double edgeDistance(double dirIJ, double uv)
Given the dot product of a point P with the normal of a u- or v-edge at the given coordinate value, returns the distance from P to that edge.
-
getDistance
public S1ChordAngle getDistance(S2Point targetXyz)
Returns the distance from the given point to the cell. Returns zero if the point is inside the cell.
-
getDistance
public S1ChordAngle getDistance(S2Cell target)
Returns the distance to the given cell. Returns zero if one cell contains the other.
-
getDistanceInternal
private double getDistanceInternal(S2Point targetXyz, boolean toInterior)
Returns the chord distance to targetXyz, with interior distance 0 iff toInterior is true.
-
getMaxDistance
public S1ChordAngle getMaxDistance(S2Point target)
Returns the maximum distance from the cell (including its interior) to the given point.
-
getMaxDistance
public S1ChordAngle getMaxDistance(S2Point a, S2Point b)
Returns the maximum distance from the cell (including its interior) to the given edge AB.
-
getMaxDistance
public S1ChordAngle getMaxDistance(S2Cell target)
Returns the maximum distance from the cell, including interior, to the given target cell.
-
getDistanceToEdge
public S1ChordAngle getDistanceToEdge(S2Point a, S2Point b)
Returns the minimum distance from the cell to the given edge AB, or zero if the edge intersects the cell interior.
-
getBoundaryDistance
public S1ChordAngle getBoundaryDistance(S2Point target)
Returns the distance from the cell boundary to the given point.
-
init
private void init(S2CellId id)
-
getPoint
private S2Point getPoint(int i, int j)
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object that)
- Overrides:
equals
in classjava.lang.Object
-
-