Class S2LatLngRect
- All Implemented Interfaces:
S2Region
,Serializable
S2LatLngRect.Builder
, or more commonly via S2Region.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 call S2LatLngRect.Builder.build()
to convert it to an immutable
S2LatLngRect.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
This class is a builder for S2LatLngRect instances. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final byte
Version number of the lossless encoding format for S2LatLngRect.Fields inherited from class com.google.common.geometry.S2LatLngRectBase
lat, lng
-
Constructor Summary
ConstructorsConstructorDescriptionS2LatLngRect
(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.Creates a new S2LatLngRect as a copy ofb
. -
Method Summary
Modifier and TypeMethodDescriptionReturns a new rectangle that includes this rectangle and the given S2LatLng, expanding this rectangle to include the point by the minimum amount possible.Returns a new rectangle that includes this rectangle and the given point, expanding this rectangle to include the point by the minimum amount possible.clone()
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
(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
(OutputStream output) Encodes thisS2LatLngRect
into an efficient, lossless binary representation, which can be decoded by callingdecode(java.io.InputStream)
.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().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
Returns a latitude-longitude rectangle that contains the edge from "a" to "b".static S2LatLngRect
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.Return a bounding latitude-longitude rectangle.intersection
(S2LatLngRectBase other) Returns the smallest rectangle containing the intersection of this rectangle and the given rectangle.final R1Interval
lat()
Returns the latitude range of this rectangle.final S1Interval
lng()
Returns the longitude range of this rectangle.If the rectangle does not include either pole, return it unmodified.Returns a newS2LatLngRect.Builder
initialized as a copy ofr
.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 Details
-
LOSSLESS_ENCODING_VERSION
private static final byte LOSSLESS_ENCODING_VERSIONVersion number of the lossless encoding format for S2LatLngRect.- See Also:
-
-
Constructor Details
-
S2LatLngRect
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 'invalid input: '<'=' is defined in the obvious way. -
S2LatLngRect
Constructs a rectangle from latitude and longitude intervals. -
S2LatLngRect
Creates a new S2LatLngRect as a copy ofb
.
-
-
Method Details
-
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
The canonical full rectangle. -
fullLat
The full allowable range of latitudes. -
fullLng
The full allowable range of longitudes. -
fromCenterSize
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
Convenience method to construct a rectangle containing a single point. -
fromPointPair
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
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
Description copied from class:S2LatLngRectBase
Returns the latitude range of this rectangle.- Specified by:
lat
in classS2LatLngRectBase
-
lng
Description copied from class:S2LatLngRectBase
Returns the longitude range of this rectangle.- Specified by:
lng
in classS2LatLngRectBase
-
toBuilder
Returns a newS2LatLngRect.Builder
initialized as a copy ofr
. -
addPoint
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
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
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
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
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
Returns the smallest rectangle containing the union of this rectangle and the given rectangle. -
intersection
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
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
-
getRectBound
Description copied from interface:S2Region
Return a bounding latitude-longitude rectangle. -
encode
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:
IOException
- if there was a problem writing into the output stream.
-
encode
- Throws:
IOException
-
decode
Decodes anS2LatLngRect
that was encoded usingencode(java.io.OutputStream)
.- Parameters:
input
- The input stream containing the encoded rectangle data.- Returns:
- the decoded
S2LatLngRect
. - Throws:
IOException
- if there was a problem reading from the input stream, or the contents are malformed.
-
decode
- Throws:
IOException
-