Class S2LatLngRect
- java.lang.Object
-
- com.google.common.geometry.S2LatLngRectBase
-
- com.google.common.geometry.S2LatLngRect
-
- All Implemented Interfaces:
S2Region
,java.io.Serializable
@GwtCompatible(serializable=true) public final class S2LatLngRect extends S2LatLngRectBase
S2LatLngRect represents a latitude-longitude rectangle. It is capable of representing the empty and full rectangles as well as single points. Rectangles may be constructed via aS2LatLngRect.Builder
, or more commonly viaS2Region.getRectBound()
.Note that the latitude-longitude space is considered to have a cylindrical topology rather than a spherical one, i.e. the poles have multiple lat/lng representations. An S2LatLngRect may be defined so that it includes some representations of a pole but not others. Use the polarClosure() method if you want to expand a rectangle so that it contains all possible representations of any contained poles.
Because S2LatLngRect uses S1Interval to store the longitude range, longitudes of -180 degrees are treated specially. Except for empty and full longitude spans, -180 degree longitudes will turn into +180 degrees. This sign flip causes lng.lo() to be greater than lng.hi(), indicating that the rectangle will wrap around through -180 instead of through +179. Thus the math is consistent with the library, but the sign flip can be surprising, especially when working with map projections where -180 and +180 are at opposite ends of the flattened map. See
S1Interval
for more details.S2LatLngRect is immutable, so all methods that change the boundary return a new instance. To efficiently make numerous alterations to the bounds, use a
S2LatLngRect.Builder
instead, mutate it to compute the desired bounds, and then callS2LatLngRect.Builder.build()
to convert it to an immutable S2LatLngRect.- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
S2LatLngRect.Builder
This class is a builder for S2LatLngRect instances.
-
Field Summary
Fields Modifier and Type Field Description private static byte
LOSSLESS_ENCODING_VERSION
Version number of the lossless encoding format for S2LatLngRect.-
Fields inherited from class com.google.common.geometry.S2LatLngRectBase
lat, lng
-
-
Constructor Summary
Constructors Constructor Description S2LatLngRect(R1Interval lat, S1Interval lng)
Constructs a rectangle from latitude and longitude intervals.S2LatLngRect(S2LatLng lo, S2LatLng hi)
Constructs a rectangle from minimum and maximum latitudes and longitudes.S2LatLngRect(S2LatLngRectBase b)
Creates a new S2LatLngRect as a copy ofb
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description S2LatLngRect
addPoint(S2LatLng ll)
Returns a new rectangle that includes this rectangle and the given S2LatLng, expanding this rectangle to include the point by the minimum amount possible.S2LatLngRect
addPoint(S2Point p)
Returns a new rectangle that includes this rectangle and the given point, expanding this rectangle to include the point by the minimum amount possible.S2Region
clone()
S2LatLngRect
convolveWithCap(S1Angle angle)
Returns a rectangle that contains the convolution of this rectangle with a cap of the given angle.(package private) static S2LatLngRect
decode(LittleEndianInput decoder)
static S2LatLngRect
decode(java.io.InputStream input)
Decodes anS2LatLngRect
that was encoded usingencode(java.io.OutputStream)
.static S2LatLngRect
empty()
The canonical empty rectangle, as derived from the empty R1 and S1 intervals.(package private) void
encode(LittleEndianOutput encoder)
void
encode(java.io.OutputStream output)
Encodes thisS2LatLngRect
into an efficient, lossless binary representation, which can be decoded by callingdecode(java.io.InputStream)
.S2LatLngRect
expanded(S2LatLng margin)
Returns a rectangle that contains all points whose latitude distance from this rectangle is at most margin.lat(), and whose longitude distance from this rectangle is at most margin.lng().S2LatLngRect
expandedByDistance(S1Angle distance)
Expands this rectangle so that it contains all points within the given distance of the boundary, and return the smallest such rectangle.static S2LatLngRect
fromCenterSize(S2LatLng center, S2LatLng size)
Constructs a rectangle of the given size centered around the given point.static S2LatLngRect
fromEdge(S2Point a, S2Point b)
Returns a latitude-longitude rectangle that contains the edge from "a" to "b".static S2LatLngRect
fromPoint(S2LatLng p)
Convenience method to construct a rectangle containing a single point.static S2LatLngRect
fromPointPair(S2LatLng p1, S2LatLng p2)
Convenience method to construct the minimal bounding rectangle containing the two given normalized points.static S2LatLngRect
full()
The canonical full rectangle.static R1Interval
fullLat()
The full allowable range of latitudes.static S1Interval
fullLng()
The full allowable range of longitudes.S2LatLngRect
getRectBound()
Return a bounding latitude-longitude rectangle.S2LatLngRect
intersection(S2LatLngRectBase other)
Returns the smallest rectangle containing the intersection of this rectangle and the given rectangle.R1Interval
lat()
Returns the latitude range of this rectangle.S1Interval
lng()
Returns the longitude range of this rectangle.S2LatLngRect
polarClosure()
If the rectangle does not include either pole, return it unmodified.S2LatLngRect.Builder
toBuilder()
Returns a newS2LatLngRect.Builder
initialized as a copy ofr
.S2LatLngRect
union(S2LatLngRectBase other)
Returns the smallest rectangle containing the union of this rectangle and the given rectangle.-
Methods inherited from class com.google.common.geometry.S2LatLngRectBase
approxEquals, approxEquals, approxEquals, area, boundaryIntersects, contains, contains, contains, contains, equals, getCapBound, getCenter, getCentroid, getDirectedHausdorffDistance, getDistance, getDistance, getHausdorffDistance, getSize, getVertex, hashCode, hi, interiorContains, interiorContains, interiorContains, interiorIntersects, intersects, intersects, intersectsLatEdge, intersectsLngEdge, isEmpty, isFull, isInverted, isPoint, isValid, latHi, latLo, lngHi, lngLo, lo, mayIntersect, toString, toStringDegrees
-
-
-
-
Field Detail
-
LOSSLESS_ENCODING_VERSION
private static final byte LOSSLESS_ENCODING_VERSION
Version number of the lossless encoding format for S2LatLngRect.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
S2LatLngRect
public S2LatLngRect(S2LatLng lo, S2LatLng hi)
Constructs a rectangle from minimum and maximum latitudes and longitudes. Iflo.lng() > hi.lng()
, the rectangle spans the 180 degree longitude line. Both points must be normalized, withlo.lat() <= hi.lat()
. The rectangle contains all the points p such thatlo <= p && p <= hi
, where '<=' is defined in the obvious way.
-
S2LatLngRect
public S2LatLngRect(R1Interval lat, S1Interval lng)
Constructs a rectangle from latitude and longitude intervals.
-
S2LatLngRect
public S2LatLngRect(S2LatLngRectBase b)
Creates a new S2LatLngRect as a copy ofb
.
-
-
Method Detail
-
empty
public static S2LatLngRect empty()
The canonical empty rectangle, as derived from the empty R1 and S1 intervals. Empty: lat.lo = 1, lat.hi = 0, lng.lo = Pi, lng.hi = -Pi (radians).
-
full
public static S2LatLngRect full()
The canonical full rectangle.
-
fullLat
public static R1Interval fullLat()
The full allowable range of latitudes.
-
fullLng
public static S1Interval fullLng()
The full allowable range of longitudes.
-
fromCenterSize
public static S2LatLngRect fromCenterSize(S2LatLng center, S2LatLng size)
Constructs a rectangle of the given size centered around the given point.center
needs to be normalized, butsize
does not. The latitude interval of the result is clamped to [-90, 90] degrees, and the longitude interval of the result is full() if and only if the longitude size is 360 degrees or more. Examples of clamping (in degrees):center = (80, 170), size = (40, 60) -> lat = [60, 100], lng = [140, -160]
center = (10, 40), size = (210, 400) -> lat = [-90, 90], lng = [-180, 180]
center = (-90, 180), size = (20, 50) -> lat = [-90, -80], lng = [155, -155]
-
fromPoint
public static S2LatLngRect fromPoint(S2LatLng p)
Convenience method to construct a rectangle containing a single point.
-
fromPointPair
public static S2LatLngRect fromPointPair(S2LatLng p1, S2LatLng p2)
Convenience method to construct the minimal bounding rectangle containing the two given normalized points. This is equivalent to starting with an empty rectangle and calling addPoint() twice. Note that it is different than theS2LatLngRect(S2LatLng, S2LatLng)
constructor, where the first point is always used as the lower-left corner of the resulting rectangle.
-
fromEdge
public static S2LatLngRect fromEdge(S2Point a, S2Point b)
Returns a latitude-longitude rectangle that contains the edge from "a" to "b". Both points must be unit-length. Note that the bounding rectangle of an edge can be larger than the bounding rectangle of its endpoints.
-
lat
public final R1Interval lat()
Description copied from class:S2LatLngRectBase
Returns the latitude range of this rectangle.- Specified by:
lat
in classS2LatLngRectBase
-
lng
public final S1Interval lng()
Description copied from class:S2LatLngRectBase
Returns the longitude range of this rectangle.- Specified by:
lng
in classS2LatLngRectBase
-
toBuilder
public S2LatLngRect.Builder toBuilder()
Returns a newS2LatLngRect.Builder
initialized as a copy ofr
.
-
addPoint
@CheckReturnValue public S2LatLngRect addPoint(S2Point p)
Returns a new rectangle that includes this rectangle and the given point, expanding this rectangle to include the point by the minimum amount possible.
-
addPoint
@CheckReturnValue public S2LatLngRect addPoint(S2LatLng ll)
Returns a new rectangle that includes this rectangle and the given S2LatLng, expanding this rectangle to include the point by the minimum amount possible. The S2LatLng argument must be normalized.
-
expanded
@CheckReturnValue public S2LatLngRect expanded(S2LatLng margin)
Returns a rectangle that contains all points whose latitude distance from this rectangle is at most margin.lat(), and whose longitude distance from this rectangle is at most margin.lng(). In particular, latitudes are clamped while longitudes are wrapped. Note that any expansion of an empty interval remains empty, and both components of the given margin must be non-negative.Note that if an expanded rectangle contains a pole, it may not contain all possible lat/lng representations of that pole. Use polarClosure() if you do not want this behavior.
NOTE: If you are trying to grow a rectangle by a certain *distance* on the sphere (e.g. 5km), use the convolveWithCap() method instead.
-
expandedByDistance
@CheckReturnValue public S2LatLngRect expandedByDistance(S1Angle distance)
Expands this rectangle so that it contains all points within the given distance of the boundary, and return the smallest such rectangle. If the distance is negative, then instead shrinks this rectangle so that it excludes all points within the given absolute distance of the boundary, and returns the largest such rectangle.Unlike
expanded(com.google.common.geometry.S2LatLng)
, this method treats the rectangle as a set of points on the sphere, and measures distances on the sphere. For example, you can use this method to find a rectangle that contains all points within 5km of a given rectangle. Because this method uses the topology of the sphere, note the following:- The full and empty rectangles have no boundary on the sphere. Any expansion (positive or negative) of these rectangles leaves them unchanged.
- Any rectangle that covers the full longitude range does not have an east or west boundary, therefore no expansion (positive or negative) will occur in that direction.
- Any rectangle that covers the full longitude range and also includes a pole will not be expanded or contracted at that pole, because it does not have a boundary there.
- If a rectangle is within the given distance of a pole, the result will include the full longitude range (because all longitudes are present at the poles).
Expansion and contraction are defined such that they are inverses whenever possible, i.e.
rect.expandedByDistance(x).expandedByDistance(-x) == rect
(approximately), so long as the first operation does not cause a rectangle boundary to disappear (i.e., the longitude range newly becomes full or empty, or the latitude range expands to include a pole).
-
polarClosure
@CheckReturnValue public S2LatLngRect polarClosure()
If the rectangle does not include either pole, return it unmodified. Otherwise expand the longitude range to full() so that the rectangle contains all possible representations of the contained pole(s).
-
union
@CheckReturnValue public S2LatLngRect union(S2LatLngRectBase other)
Returns the smallest rectangle containing the union of this rectangle and the given rectangle.
-
intersection
@CheckReturnValue public S2LatLngRect intersection(S2LatLngRectBase other)
Returns the smallest rectangle containing the intersection of this rectangle and the given rectangle. Note that the region of intersection may consist of two disjoint rectangles, in which case a single rectangle spanning both of them is returned.
-
convolveWithCap
@CheckReturnValue public S2LatLngRect convolveWithCap(S1Angle angle)
Returns a rectangle that contains the convolution of this rectangle with a cap of the given angle. This expands the rectangle by a fixed distance (as opposed to growing the rectangle in latitude-longitude space). The returned rectangle includes all points whose minimum distance to the original rectangle is at most the given angle.
-
clone
public S2Region clone()
- Overrides:
clone
in classjava.lang.Object
-
getRectBound
public S2LatLngRect getRectBound()
Description copied from interface:S2Region
Return a bounding latitude-longitude rectangle.
-
encode
public void encode(java.io.OutputStream output) throws java.io.IOException
Encodes thisS2LatLngRect
into an efficient, lossless binary representation, which can be decoded by callingdecode(java.io.InputStream)
. The encoding is byte-compatible with the C++ version of the S2 library.- Parameters:
output
- The output stream into which the encoding should be written.- Throws:
java.io.IOException
- if there was a problem writing into the output stream.
-
encode
void encode(LittleEndianOutput encoder) throws java.io.IOException
- Throws:
java.io.IOException
-
decode
public static S2LatLngRect decode(java.io.InputStream input) throws java.io.IOException
Decodes anS2LatLngRect
that was encoded usingencode(java.io.OutputStream)
.- Parameters:
input
- The input stream containing the encoded rectangle data.- Returns:
- the decoded
S2LatLngRect
. - Throws:
java.io.IOException
- if there was a problem reading from the input stream, or the contents are malformed.
-
decode
static S2LatLngRect decode(LittleEndianInput decoder) throws java.io.IOException
- Throws:
java.io.IOException
-
-