Class ReferencedEnvelope

Object
Envelope
ReferencedEnvelope
All Implemented Interfaces:
Serializable, Comparable, BoundingBox, Bounds
Direct Known Subclasses:
ReferencedEnvelope3D

public class ReferencedEnvelope extends Envelope implements Bounds, BoundingBox
A JTS envelope associated with a coordinate reference system. In addition, this JTS envelope also implements the GeoAPI envelope interface for interoperability with GeoAPI.
Since:
2.2
Author:
Jody Garnett, Martin Desruisseaux, Simone Giannecchini
See Also:
  • Field Details

  • Constructor Details

  • Method Details

    • init

      public void init(BoundingBox bounds)
      Sets this envelope to the specified bounding box.
    • checkCoordinateReferenceSystemDimension

      protected void checkCoordinateReferenceSystemDimension() throws MismatchedDimensionException
      Convenience method for checking coordinate reference system validity.
      Throws:
      IllegalArgumentException - if the CRS dimension is not valid.
      MismatchedDimensionException
    • ensureCompatibleReferenceSystem

      protected void ensureCompatibleReferenceSystem(BoundingBox bbox) throws MismatchedReferenceSystemException
      Make sure that the specified bounding box uses the same CRS than this one.
      Parameters:
      bbox - The other bounding box to test for compatibility.
      Throws:
      MismatchedReferenceSystemException - if the CRS are incompatible.
    • ensureCompatibleReferenceSystem

      protected void ensureCompatibleReferenceSystem(Position location)
      Make sure that the specified location uses the same CRS as this one.
      Throws:
      MismatchedReferenceSystemException - if the CRS are incompatible.
    • getCoordinateReferenceSystem

      public CoordinateReferenceSystem getCoordinateReferenceSystem()
      Returns the coordinate reference system associated with this envelope.
      Specified by:
      getCoordinateReferenceSystem in interface Bounds
      Returns:
      The envelope CRS, or null if unknown.
    • setCoordinateReferenceSystem

      public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
      Set the coordinate reference system in which the coordinate are given.
      Parameters:
      crs - The new coordinate reference system, or null.
    • getDimension

      public int getDimension()
      Returns the number of dimensions.
      Specified by:
      getDimension in interface Bounds
      Returns:
      The dimensionality of this envelope.
    • getMinimum

      public double getMinimum(int dimension)
      Returns the minimal ordinate along the specified dimension.
      Specified by:
      getMinimum in interface Bounds
      Parameters:
      dimension - The dimension for which to obtain the ordinate value.
      Returns:
      The minimal ordinate at the given dimension.
      See Also:
    • getMaximum

      public double getMaximum(int dimension)
      Returns the maximal ordinate along the specified dimension.
      Specified by:
      getMaximum in interface Bounds
      Parameters:
      dimension - The dimension for which to obtain the ordinate value.
      Returns:
      The maximal ordinate at the given dimension.
      See Also:
    • getMedian

      public double getMedian(int dimension)
      Returns the center ordinate along the specified dimension.
      Specified by:
      getMedian in interface Bounds
      Parameters:
      dimension - The dimension for which to obtain the ordinate value.
      Returns:
      The median ordinate at the given dimension.
      See Also:
    • getSpan

      public double getSpan(int dimension)
      Returns the envelope length along the specified dimension. This length is equals to the maximum ordinate minus the minimal ordinate.
      Specified by:
      getSpan in interface Bounds
      Parameters:
      dimension - The dimension for which to obtain the ordinate value.
      Returns:
      The span (typically width or height) at the given dimension.
      See Also:
    • getLowerCorner

      public Position getLowerCorner()
      A coordinate position consisting of all the minimal ordinates for each dimension for all points within the Envelope.
      Specified by:
      getLowerCorner in interface Bounds
      Returns:
      The lower corner.
    • getUpperCorner

      public Position getUpperCorner()
      A coordinate position consisting of all the maximal ordinates for each dimension for all points within the Envelope.
      Specified by:
      getUpperCorner in interface Bounds
      Returns:
      The upper corner.
    • isEmpty

      public boolean isEmpty()
      Returns true if lengths along all dimension are zero.
      Specified by:
      isEmpty in interface BoundingBox
      Returns:
      true if this bounding box is empty.
      Since:
      2.4
    • contains

      public boolean contains(Position pos)
      Returns true if the provided location is contained by this bounding box.
      Specified by:
      contains in interface BoundingBox
      Parameters:
      pos - The direct position to test for inclusion.
      Returns:
      true if the given position is inside this bounds.
      Since:
      2.4
    • contains

      public boolean contains(ReferencedEnvelope bounds)
      Check if provided bounds are contained by this ReferencedEnvelope.
      Parameters:
      bounds -
      Returns:
      true if bounds are contained by this ReferencedEnvelope
    • contains

      public boolean contains(BoundingBox bbox)
      Check if provided bbox is contained by this ReferencedEnvelope.
      Specified by:
      contains in interface BoundingBox
      Parameters:
      bbox -
      Returns:
      true if bbox is contained by this ReferencedEnvelope
      Since:
      2.4
    • intersects

      public boolean intersects(BoundingBox bbox)
      Check if this bounding box intersects the provided bounds.
      Specified by:
      intersects in interface BoundingBox
      Parameters:
      bbox - The bounds to test for intersection.
      Returns:
      true if the two bounds intersect.
      Since:
      2.4
    • intersection

      public ReferencedEnvelope intersection(Envelope env)
      Check if this bounding box intersects the provided bounds.
      Overrides:
      intersection in class Envelope
    • include

      public void include(BoundingBox bbox)
      Include the provided bounding box, expanding as necessary.
      Specified by:
      include in interface BoundingBox
      Parameters:
      bbox - The bounds to add to this geographic bounding box.
      Since:
      2.4
    • expandToInclude

      public void expandToInclude(Position pt)
      Expand to include the provided DirectPosition
    • expandToInclude

      public void expandToInclude(Point2D pt)
    • getCenterX

      public double getCenterX()
      Returns the X coordinate of the center of the rectangle.

      Method compatibility with XRectangle2D.getCenterX()

    • getCenterY

      public double getCenterY()
      Returns the Y coordinate of the center of the rectangle.

      Method compatibility with XRectangle2D.getCenterY()

    • expandToInclude

      public void expandToInclude(Envelope other)
      Include the provided envelope, expanding as necessary.
      Overrides:
      expandToInclude in class Envelope
    • include

      public void include(double x, double y)
      Include the provided coordinates, expanding as necessary.
      Specified by:
      include in interface BoundingBox
      Parameters:
      x - The first ordinate value.
      y - The second ordinate value.
      Since:
      2.4
    • setBounds

      public void setBounds(BoundingBox bbox)
      Initialize the bounding box with another bounding box.
      Specified by:
      setBounds in interface BoundingBox
      Parameters:
      bbox - The new bounds.
      Since:
      2.4
    • setFrameFromCenter

      public void setFrameFromCenter(Point2D center, Point2D corner)
      Initialize the bounding box using a line from the center to a corner.
      Parameters:
      center - location of the new bounding box
      corner - location of a corner establishing the extent of the bounding box
    • setFrameFromDiagonal

      public void setFrameFromDiagonal(Point2D lowerLeft, Point2D upperRight)
      Initialize the bounding box using a line from the lower left to upper right corners.
      Parameters:
      lowerLeft - Lower left extent of the new bounding box
      upperRight - Upper right extent of the new bounding box
    • setFrame

      public void setFrame(double x, double y, double width, double height)
      Rectangle style x,y,width,height bounds definition
    • toBounds

      public BoundingBox toBounds(CoordinateReferenceSystem targetCRS) throws TransformException
      Returns a new bounding box which contains the transformed shape of this bounding box. This is a convenience method that delegate its work to the transform method.
      Specified by:
      toBounds in interface BoundingBox
      Parameters:
      targetCRS - The target CRS for the bounding box to be returned.
      Returns:
      A new bounding box wich includes the shape of this box transformed to the specified target CRS.
      Throws:
      TransformException - if no transformation path has been found from this box CRS to the specified target CRS, or if the transformation failed for an other reason.
      Since:
      2.4
    • transform

      public ReferencedEnvelope transform(CoordinateReferenceSystem targetCRS, boolean lenient) throws TransformException, FactoryException
      Transforms the referenced envelope to the specified coordinate reference system.

      This method can handle the case where the envelope contains the North or South pole, or when it cross the ±180� longitude.

      Parameters:
      targetCRS - The target coordinate reference system.
      lenient - true if datum shift should be applied even if there is insuffisient information. Otherwise (if false), an exception is thrown in such case.
      Returns:
      The transformed envelope.
      Throws:
      FactoryException - if the math transform can't be determined.
      TransformException - if at least one coordinate can't be transformed.
      See Also:
    • transform

      public ReferencedEnvelope transform(CoordinateReferenceSystem targetCRS, boolean lenient, int numPointsForTransformation) throws TransformException, FactoryException
      Transforms the referenced envelope to the specified coordinate reference system using the specified amount of points.

      This method can handle the case where the envelope contains the North or South pole, or when it cross the ±180� longitude.

      Parameters:
      targetCRS - The target coordinate reference system.
      lenient - true if datum shift should be applied even if there is insuffisient information. Otherwise (if false), an exception is thrown in such case.
      numPointsForTransformation - The number of points to use for sampling the envelope.
      Returns:
      The transformed envelope.
      Throws:
      FactoryException - if the math transform can't be determined.
      TransformException - if at least one coordinate can't be transformed.
      Since:
      2.3
      See Also:
    • hashCode

      public int hashCode()
      Returns a hash value for this envelope. This value need not remain consistent between different implementations of the same class.
      Overrides:
      hashCode in class Envelope
    • equals

      public boolean equals(Object object)
      Compares the specified object with this envelope for equality.
      Overrides:
      equals in class Envelope
    • boundsEquals2D

      public boolean boundsEquals2D(Bounds other, double eps)
      Compare the bounds of this envelope with those of another.

      Note: in this test:

      • the coordinate reference systems of the envelopes are not examined
      • only the first two dimensions of the envelopes are compared
      • it is assumed that each dimension equates to the same axis for both envelopes
      Parameters:
      other - other envelope
      eps - a small tolerance factor (e.g. 1.0e-6d) which will be scaled relative to this envlope's width and height
      Returns:
      true if all bounding coordinates are equal within the set tolerance; false otherwise
    • boundsEquals2D

      public boolean boundsEquals2D(Rectangle2D other, double eps)
      Compare the bounds of this envelope with those of another.

      Note: in this test:

      • the coordinate reference systems of the envelopes are not examined
      • only the first two dimensions of the envelopes are compared
      • it is assumed that each dimension equates to the same axis for both envelopes
      Parameters:
      other - other envelope
      eps - a small tolerance factor (e.g. 1.0e-6d) which will be scaled relative to this envlope's width and height
      Returns:
      true if all bounding coordinates are equal within the set tolerance; false otherwise
    • boundsEquals

      public boolean boundsEquals(Bounds that, int xDim, int yDim, double eps)
      Returns true if this envelope bounds is equals to that envelope bounds in two specified dimensions. The coordinate reference system is not compared, since it doesn't need to have the same number of dimensions.
      Parameters:
      that - The envelope to compare to.
      xDim - The dimension of that envelope to compare to the x dimension of this envelope.
      yDim - The dimension of that envelope to compare to the y dimension of this envelope.
      eps - A small tolerance number for floating point number comparaisons. This value will be scaled according this envelope width and height.
      Returns:
      true if the envelope bounds are the same (up to the specified tolerance level) in the specified dimensions, or false otherwise.
    • toString

      public String toString()
      Returns a string representation of this envelope. The default implementation is okay for occasional formatting (for example for debugging purpose).
      Overrides:
      toString in class Envelope
    • create

      public static ReferencedEnvelope create(ReferencedEnvelope original)
      Factory method to create the correct ReferencedEnvelope.
      Parameters:
      original - ReferencedEnvelope being duplicated
      Returns:
      ReferencedEnvelope, ReferencedEnvelope3D if it is 3d
    • create

      public static ReferencedEnvelope create(CoordinateReferenceSystem crs)
      Factory method to create the correct ReferencedEnvelope implementation for the provided CoordinateReferenceSystem.
      Parameters:
      crs - CoordinateReferenceSystem used to select ReferencedEnvelope implementation
      Returns:
      ReferencedEnvelope, ReferencedEnvelope3D if it is 3d
    • create

      public static ReferencedEnvelope create(Bounds bounds)
      Utility method to create a ReferencedEnvelope from an opengis Envelope class, supporting 2d as well as 3d envelopes (returning the right class).
      Parameters:
      bounds - The opgenis Envelope object
      Returns:
      ReferencedEnvelope, ReferencedEnvelope3D if it is 3d,
      results in a null/an empty envelope, if input envelope was a null/an empty envelope
    • create

      public static ReferencedEnvelope create(Bounds env, CoordinateReferenceSystem crs)
      Utility method to create a ReferencedEnvelope from provided Bounds.

      Uses crs to determine if ReferencedEnvelope or ReferencedEnvelope3D is required.

      Parameters:
      env - Bounds representing extent
      crs - CRS
      Returns:
      ReferencedEnvelope, ReferencedEnvelope3D if crs is 3d,
      results in a null/an empty envelope, if input envelope was a null/an empty envelope.
    • rect

      public static ReferencedEnvelope rect(Rectangle2D rectangle)
      Construct 2D WGS84 referenced envelope using rectangle conventions using width and height.
      Parameters:
      rectangle - Rectangle defining extend of Referenced Envelope.
    • rect

      public static ReferencedEnvelope rect(Rectangle2D rectangle, CoordinateReferenceSystem crs)
      Construct referenced envelope using rectangle conventions using width and height.
      Parameters:
      rectangle - Rectangle defining extend of Referenced Envelope.
    • rect

      public static ReferencedEnvelope rect(double x, double y, double width, double height)
      Construct 2D WGS84 referenced envelope using rectangle conventions using width and height.

      Migration method, previously new Envelope2D(crs,x,y,w,h).

      Parameters:
      x -
      y -
      width -
      height -
    • rect

      public static ReferencedEnvelope rect(double x, double y, double width, double height, CoordinateReferenceSystem crs)
      Construct referenced envelope using rectangle conventions using width and height.

      Migration method, previously new Envelope2D(crs,x,y,w,h).

      Parameters:
      x -
      y -
      width -
      height -
      Returns:
      ReferencedEnvelope WGS84
    • envelope

      public static ReferencedEnvelope envelope(Envelope env, CoordinateReferenceSystem crs)
      Utility method to create a ReferencedEnvelope a plain JTS Envelope class, supporting 2d as well as 3d envelopes (returning the right class).
      Parameters:
      env - The JTS Envelope object
      Returns:
      ReferencedEnvelope, ReferencedEnvelope3D if it is 3d,
      results in a null/an empty envelope, if input envelope was a null/an empty envelope
    • reference

      public static ReferencedEnvelope reference(Envelope e)
      Cast to a ReferencedEnvelope (used to ensure that an Envelope is a ReferencedEnvelope).

      This method first checks if e is an instanceof ReferencedEnvelope, if it is, itself is returned. If not new ReferencedEnvelpe(e,null) is returned.

      If e is null, null is returned.

      Parameters:
      e - The envelope. Can be null.
      Returns:
      A ReferencedEnvelope using the specified envelope, or null if the envelope was null.
    • reference

      public static ReferencedEnvelope reference(ReferencedEnvelope e)
      Utility method to ensure that an BoundingBox in a ReferencedEnvelope.

      This method first checks if e is an instanceof ReferencedEnvelope, if it is, itself is returned. If not new ReferencedEnvelpe(e) is returned.

      Parameters:
      e - The envelope.
    • reference

      public static ReferencedEnvelope reference(Bounds env)
      Cast to a ReferencedEnvelope (used to ensure that an Envelope if a ReferencedEnvelope). Supporting 2d as well as 3d envelopes (returning the right class).
      Parameters:
      env - The opgenis Envelope object
      Returns:
      ReferencedEnvelope, ReferencedEnvelope3D if it is 3d,
      results in a null/an empty envelope, if input envelope was a null/an empty envelope (by JTS Envelope definition: getMaximum(0) < getMinimum(0))
    • create

      public static ReferencedEnvelope create(Rectangle2D rectangle, CoordinateReferenceSystem crs)
      Utility method to create a ReferencedEnvelope from a Java2D Rectangle class, supporting empty rectangles.
      Parameters:
      rectangle - The Java2D Rectangle object
      Returns:
      ReferencedEnvelope,
      results in a null/an empty envelope, if input rectangle was empty