Class Envelope

java.lang.Object
org.locationtech.jts.geom.Envelope
All Implemented Interfaces:
Serializable, Comparable
public class Envelope extends Object implements Comparable, Serializable
Defines a rectangular region of the 2D coordinate plane. It is often used to represent the bounding box of a Geometry, e.g. the minimum and maximum x and y values of the Coordinates.

Envelopes support infinite or half-infinite regions, by using the values of Double.POSITIVE_INFINITY and Double.NEGATIVE_INFINITY. Envelope objects may have a null value.

When Envelope objects are created or initialized, the supplies extent values are automatically sorted into the correct order.

Version:
1.7
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Envelope()
    Creates a null Envelope.
    Envelope(double x1, double x2, double y1, double y2)
    Creates an Envelope for a region defined by maximum and minimum values.
    Envelope(Coordinate p)
    Creates an Envelope for a region defined by a single Coordinate.
    Envelope(Coordinate p1, Coordinate p2)
    Creates an Envelope for a region defined by two Coordinates.
    Envelope(Envelope env)
    Create an Envelope from an existing Envelope.

  • Method Summary

    Modifier and Type
    Method
    Description
    Coordinate
    centre()
    Computes the coordinate of the centre of this envelope (as long as it is non-null
    int
    compareTo(Object o)
    Compares two envelopes using lexicographic ordering.
    boolean
    contains(double x, double y)
    Tests if the given point lies in or on the envelope.
    boolean
    contains(Coordinate p)
    Tests if the given point lies in or on the envelope.
    boolean
    contains(Envelope other)
    Tests if the Envelope other lies wholely inside this Envelope (inclusive of the boundary).
    boolean
    containsProperly(Envelope other)
    Tests if an envelope is properly contained in this one.
    Envelope
    copy()
    Creates a copy of this envelope object.
    boolean
    covers(double x, double y)
    Tests if the given point lies in or on the envelope.
    boolean
    covers(Coordinate p)
    Tests if the given point lies in or on the envelope.
    boolean
    covers(Envelope other)
    Tests if the Envelope other lies wholely inside this Envelope (inclusive of the boundary).
    boolean
    disjoint(Envelope other)
    Tests if the region defined by other is disjoint from the region of this Envelope.
    double
    distance(Envelope env)
    Computes the distance between this and another Envelope.
    boolean
    equals(Object other)
     
    void
    expandBy(double distance)
    Expands this envelope by a given distance in all directions.
    void
    expandBy(double deltaX, double deltaY)
    Expands this envelope by a given distance in all directions.
    void
    expandToInclude(double x, double y)
    Enlarges this Envelope so that it contains the given point.
    void
    expandToInclude(Coordinate p)
    Enlarges this Envelope so that it contains the given Coordinate.
    void
    expandToInclude(Envelope other)
    Enlarges this Envelope so that it contains the other Envelope.
    double
    getArea()
    Gets the area of this envelope.
    double
    getDiameter()
    Gets the length of the diameter (diagonal) of the envelope.
    double
    getHeight()
    Returns the difference between the maximum and minimum y values.
    double
    getMaxX()
    Returns the Envelopes maximum x-value. min x > max x indicates that this is a null Envelope.
    double
    getMaxY()
    Returns the Envelopes maximum y-value. min y > max y indicates that this is a null Envelope.
    double
    getMinX()
    Returns the Envelopes minimum x-value. min x > max x indicates that this is a null Envelope.
    double
    getMinY()
    Returns the Envelopes minimum y-value. min y > max y indicates that this is a null Envelope.
    double
    getWidth()
    Returns the difference between the maximum and minimum x values.
    int
    hashCode()
     
    void
    init()
    Initialize to a null Envelope.
    void
    init(double x1, double x2, double y1, double y2)
    Initialize an Envelope for a region defined by maximum and minimum values.
    void
    init(Coordinate p)
    Initialize an Envelope to a region defined by a single Coordinate.
    void
    init(Coordinate p1, Coordinate p2)
    Initialize an Envelope to a region defined by two Coordinates.
    void
    init(Envelope env)
    Initialize an Envelope from an existing Envelope.
    Envelope
    intersection(Envelope env)
    Computes the intersection of two Envelopes.
    boolean
    intersects(double x, double y)
    Check if the point (x, y) intersects (lies inside) the region of this Envelope.
    boolean
    intersects(Coordinate p)
    Tests if the point p intersects (lies inside) the region of this Envelope.
    boolean
    intersects(Coordinate a, Coordinate b)
    Tests if the extent defined by two extremal points intersects the extent of this Envelope.
    static boolean
    intersects(Coordinate p1, Coordinate p2, Coordinate q)
    Test the point q to see whether it intersects the Envelope defined by p1-p2
    static boolean
    intersects(Coordinate p1, Coordinate p2, Coordinate q1, Coordinate q2)
    Tests whether the envelope defined by p1-p2 and the envelope defined by q1-q2 intersect.
    boolean
    intersects(Envelope other)
    Tests if the region defined by other intersects the region of this Envelope.
    boolean
    isNull()
    Returns true if this Envelope is a "null" envelope.
    double
    maxExtent()
    Gets the maximum extent of this envelope across both dimensions.
    double
    minExtent()
    Gets the minimum extent of this envelope across both dimensions.
    boolean
    overlaps(double x, double y)
    Deprecated.
    Use #intersects instead.
    boolean
    overlaps(Coordinate p)
    Deprecated.
    Use #intersects instead.
    boolean
    overlaps(Envelope other)
    Deprecated.
    Use #intersects instead.
    void
    setToNull()
    Makes this Envelope a "null" envelope, that is, the envelope of the empty geometry.
    String
    toString()
     
    void
    translate(double transX, double transY)
    Translates this envelope by given amounts in the X and Y direction.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Envelope

      public Envelope()
      Creates a null Envelope.

    • Envelope

      public Envelope(double x1, double x2, double y1, double y2)
      Creates an Envelope for a region defined by maximum and minimum values.
      Parameters:
      x1 - the first x-value
      x2 - the second x-value
      y1 - the first y-value
      y2 - the second y-value

    • Envelope

      public Envelope(Coordinate p1, Coordinate p2)
      Creates an Envelope for a region defined by two Coordinates.
      Parameters:
      p1 - the first Coordinate
      p2 - the second Coordinate

    • Envelope

      public Envelope(Coordinate p)
      Creates an Envelope for a region defined by a single Coordinate.
      Parameters:
      p - the Coordinate

    • Envelope

      public Envelope(Envelope env)
      Create an Envelope from an existing Envelope.
      Parameters:
      env - the Envelope to initialize from

  • Method Details

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • intersects

      public static boolean intersects(Coordinate p1, Coordinate p2, Coordinate q)
      Test the point q to see whether it intersects the Envelope defined by p1-p2
      Parameters:
      p1 - one extremal point of the envelope
      p2 - another extremal point of the envelope
      q - the point to test for intersection
      Returns:
      true if q intersects the envelope p1-p2

    • intersects

      public static boolean intersects(Coordinate p1, Coordinate p2, Coordinate q1, Coordinate q2)
      Tests whether the envelope defined by p1-p2 and the envelope defined by q1-q2 intersect.
      Parameters:
      p1 - one extremal point of the envelope P
      p2 - another extremal point of the envelope P
      q1 - one extremal point of the envelope Q
      q2 - another extremal point of the envelope Q
      Returns:
      true if Q intersects P

    • init

      public void init()
      Initialize to a null Envelope.

    • init

      public void init(double x1, double x2, double y1, double y2)
      Initialize an Envelope for a region defined by maximum and minimum values.
      Parameters:
      x1 - the first x-value
      x2 - the second x-value
      y1 - the first y-value
      y2 - the second y-value

    • copy

      public Envelope copy()
      Creates a copy of this envelope object.
      Returns:
      a copy of this envelope

    • init

      public void init(Coordinate p1, Coordinate p2)
      Initialize an Envelope to a region defined by two Coordinates.
      Parameters:
      p1 - the first Coordinate
      p2 - the second Coordinate

    • init

      public void init(Coordinate p)
      Initialize an Envelope to a region defined by a single Coordinate.
      Parameters:
      p - the coordinate

    • init

      public void init(Envelope env)
      Initialize an Envelope from an existing Envelope.
      Parameters:
      env - the Envelope to initialize from

    • setToNull

      public void setToNull()
      Makes this Envelope a "null" envelope, that is, the envelope of the empty geometry.

    • isNull

      public boolean isNull()
      Returns true if this Envelope is a "null" envelope.
      Returns:
      true if this Envelope is uninitialized or is the envelope of the empty geometry.

    • getWidth

      public double getWidth()
      Returns the difference between the maximum and minimum x values.
      Returns:
      max x - min x, or 0 if this is a null Envelope

    • getHeight

      public double getHeight()
      Returns the difference between the maximum and minimum y values.
      Returns:
      max y - min y, or 0 if this is a null Envelope

    • getDiameter

      public double getDiameter()
      Gets the length of the diameter (diagonal) of the envelope.
      Returns:
      the diameter length

    • getMinX

      public double getMinX()
      Returns the Envelopes minimum x-value. min x > max x indicates that this is a null Envelope.
      Returns:
      the minimum x-coordinate

    • getMaxX

      public double getMaxX()
      Returns the Envelopes maximum x-value. min x > max x indicates that this is a null Envelope.
      Returns:
      the maximum x-coordinate

    • getMinY

      public double getMinY()
      Returns the Envelopes minimum y-value. min y > max y indicates that this is a null Envelope.
      Returns:
      the minimum y-coordinate

    • getMaxY

      public double getMaxY()
      Returns the Envelopes maximum y-value. min y > max y indicates that this is a null Envelope.
      Returns:
      the maximum y-coordinate

    • getArea

      public double getArea()
      Gets the area of this envelope.
      Returns:
      the area of the envelope

    • minExtent

      public double minExtent()
      Gets the minimum extent of this envelope across both dimensions.
      Returns:
      the minimum extent of this envelope

    • maxExtent

      public double maxExtent()
      Gets the maximum extent of this envelope across both dimensions.
      Returns:
      the maximum extent of this envelope

    • expandToInclude

      public void expandToInclude(Coordinate p)
      Enlarges this Envelope so that it contains the given Coordinate. Has no effect if the point is already on or within the envelope.
      Parameters:
      p - the Coordinate to expand to include

    • expandBy

      public void expandBy(double distance)
      Expands this envelope by a given distance in all directions. Both positive and negative distances are supported.
      Parameters:
      distance - the distance to expand the envelope

    • expandBy

      public void expandBy(double deltaX, double deltaY)
      Expands this envelope by a given distance in all directions. Both positive and negative distances are supported.
      Parameters:
      deltaX - the distance to expand the envelope along the the X axis
      deltaY - the distance to expand the envelope along the the Y axis

    • expandToInclude

      public void expandToInclude(double x, double y)
      Enlarges this Envelope so that it contains the given point. Has no effect if the point is already on or within the envelope.
      Parameters:
      x - the value to lower the minimum x to or to raise the maximum x to
      y - the value to lower the minimum y to or to raise the maximum y to

    • expandToInclude

      public void expandToInclude(Envelope other)
      Enlarges this Envelope so that it contains the other Envelope. Has no effect if other is wholly on or within the envelope.
      Parameters:
      other - the Envelope to expand to include

    • translate

      public void translate(double transX, double transY)
      Translates this envelope by given amounts in the X and Y direction.
      Parameters:
      transX - the amount to translate along the X axis
      transY - the amount to translate along the Y axis

    • centre

      public Coordinate centre()
      Computes the coordinate of the centre of this envelope (as long as it is non-null
      Returns:
      the centre coordinate of this envelope null if the envelope is null

    • intersection

      public Envelope intersection(Envelope env)
      Computes the intersection of two Envelopes.
      Parameters:
      env - the envelope to intersect with
      Returns:
      a new Envelope representing the intersection of the envelopes (this will be the null envelope if either argument is null, or they do not intersect

    • intersects

      public boolean intersects(Envelope other)
      Tests if the region defined by other intersects the region of this Envelope.

      A null envelope never intersects.

      Parameters:
      other - the Envelope which this Envelope is being checked for intersecting
      Returns:
      true if the Envelopes intersect

    • intersects

      public boolean intersects(Coordinate a, Coordinate b)
      Tests if the extent defined by two extremal points intersects the extent of this Envelope.
      Parameters:
      a - a point
      b - another point
      Returns:
      true if the extents intersect

    • disjoint

      public boolean disjoint(Envelope other)
      Tests if the region defined by other is disjoint from the region of this Envelope.

      A null envelope is always disjoint.

      Parameters:
      other - the Envelope being checked for disjointness
      Returns:
      true if the Envelopes are disjoint
      See Also:

    • overlaps

      public boolean overlaps(Envelope other)
      Deprecated.
      Use #intersects instead. In the future, #overlaps may be changed to be a true overlap check; that is, whether the intersection is two-dimensional.

    • intersects

      public boolean intersects(Coordinate p)
      Tests if the point p intersects (lies inside) the region of this Envelope.
      Parameters:
      p - the Coordinate to be tested
      Returns:
      true if the point intersects this Envelope

    • overlaps

      public boolean overlaps(Coordinate p)
      Deprecated.
      Use #intersects instead.

    • intersects

      public boolean intersects(double x, double y)
      Check if the point (x, y) intersects (lies inside) the region of this Envelope.
      Parameters:
      x - the x-ordinate of the point
      y - the y-ordinate of the point
      Returns:
      true if the point overlaps this Envelope

    • overlaps

      public boolean overlaps(double x, double y)
      Deprecated.
      Use #intersects instead.

    • contains

      public boolean contains(Envelope other)
      Tests if the Envelope other lies wholely inside this Envelope (inclusive of the boundary).

      Note that this is not the same definition as the SFS contains, which would exclude the envelope boundary.

      Parameters:
      other - the Envelope to check
      Returns:
      true if other is contained in this Envelope
      See Also:

    • contains

      public boolean contains(Coordinate p)
      Tests if the given point lies in or on the envelope.

      Note that this is not the same definition as the SFS contains, which would exclude the envelope boundary.

      Parameters:
      p - the point which this Envelope is being checked for containing
      Returns:
      true if the point lies in the interior or on the boundary of this Envelope.
      See Also:

    • contains

      public boolean contains(double x, double y)
      Tests if the given point lies in or on the envelope.

      Note that this is not the same definition as the SFS contains, which would exclude the envelope boundary.

      Parameters:
      x - the x-coordinate of the point which this Envelope is being checked for containing
      y - the y-coordinate of the point which this Envelope is being checked for containing
      Returns:
      true if (x, y) lies in the interior or on the boundary of this Envelope.
      See Also:

    • containsProperly

      public boolean containsProperly(Envelope other)
      Tests if an envelope is properly contained in this one. The envelope is properly contained if it is contained by this one but not equal to it.
      Parameters:
      other - the envelope to test
      Returns:
      true if the envelope is properly contained

    • covers

      public boolean covers(double x, double y)
      Tests if the given point lies in or on the envelope.
      Parameters:
      x - the x-coordinate of the point which this Envelope is being checked for containing
      y - the y-coordinate of the point which this Envelope is being checked for containing
      Returns:
      true if (x, y) lies in the interior or on the boundary of this Envelope.

    • covers

      public boolean covers(Coordinate p)
      Tests if the given point lies in or on the envelope.
      Parameters:
      p - the point which this Envelope is being checked for containing
      Returns:
      true if the point lies in the interior or on the boundary of this Envelope.

    • covers

      public boolean covers(Envelope other)
      Tests if the Envelope other lies wholely inside this Envelope (inclusive of the boundary).
      Parameters:
      other - the Envelope to check
      Returns:
      true if this Envelope covers the other

    • distance

      public double distance(Envelope env)
      Computes the distance between this and another Envelope. The distance between overlapping Envelopes is 0. Otherwise, the distance is the Euclidean distance between the closest points.

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • compareTo

      public int compareTo(Object o)
      Compares two envelopes using lexicographic ordering. The ordering comparison is based on the usual numerical comparison between the sequence of ordinates. Null envelopes are less than all non-null envelopes.
      Specified by:
      compareTo in interface Comparable
      Parameters:
      o - an Envelope object