Class 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 a 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:
    Serialized Form
    • 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. If lo.lng() > hi.lng(), the rectangle spans the 180 degree longitude line. Both points must be normalized, with lo.lat() <= hi.lat(). The rectangle contains all the points p such that lo <= 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 of b.
    • 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, but size 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 the S2LatLngRect(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.
      • 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 class java.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 this S2LatLngRect into an efficient, lossless binary representation, which can be decoded by calling decode(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 an S2LatLngRect that was encoded using encode(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.