The ReferencedEnvelope interface is a bit of a olive branch between the JTS Geometry model (which is known and loved and simple) and the ISO Geometry model (which is starting to enter the library - if not common use).

Javadocs:

• ReferencedEnvelope

ReferencedEnvelope

ReferencedEnvelope is both:

• an Envelope - as defined by the JTS Topology System ( a Simple Feature for SQL concept)
• a BoundingRectangle - 2D bounds as defined by the GeoAPI project (an ISO 19107 Geometry idea)
• a BoundingBox - 3D bounds as defined by the GeoAPI project (an ISO 19107 Geometry idea)

In short this is the class to use when you want to represent a rectangle in GeoTools. The only other thing of note is the that the constructor expects the input in xMin,xMax,yMin,yMax order and expects a crs.

ReferencedEnvelope envelope =
   new ReferencedEnvelope(0, 10, 0, 20, CRS.decode("EPSG:4326"));

Why should you care

ReferencedEnvelope does one thing very well; it is an Envelope that has a CoordinateReferenceSystem. Because it has a CoordinateReferenceSystem you can quickly transform it between projections.

import org.geotools.geometry.jts.JTS;
import org.geotools.referencing.CRS;

CoordinateReferenceSystem sourceCRS = CRS.decode("EPSG:4326");
CoordinateReferenceSystem targetCRS = CRS.decode("EPSG:23032");

ReferencedEnvelope envelope  = new ReferencedEnvelope(0, 10, 0, 20, sourceCRS);

MathTransform transform = CRS.findMathTransform(sourceCRS, targetCRS);

// Sample 10 points around the envelope
ReferencedEnvelope result = envelope.transform( sourceCRS, true, 10 );

Other Rectangles used in GeoTools

You will find other "Rectangles" around as you make use of GeoTools in a real world application.

Java Rectangles

Java Rectangles record x,y,w,h:

• Rectangle2D
  • Rectangle2D.Double rectangle working with doubles
  • Rectangle2D.Float rectangle working with floats
    • Envelope2D we have a spatial specific version of Rectangle2D that implements GeoAPI Envelope; it is pretty useless since it only supports two axis
  • Rectangle the original rectangle for working on the screen, measured in integers

GeoAPI Rectangles

GeoAPI records a "rectangle" as a bounds along the axis mentioned by the CoordinateReferneceSystem object. You can use this idea to record a simple rectangle in space, a height range and and a range in time as needed.

• Envelope
  • DirectPosition1D - a "rectangle" of one dimension
  • GeneralEnvelope - a "rectangle" of any number of dimensions
  • BoundingBox a subclass of Envelope that assumes you are working an 2D CoordinateReference system with the axis in X/Y order.
    • ReferencedEnvelope

Note Envelope is just and interface, so we will use RefernecedEnvelope for the example:

CoordinateReferneceSystem wsg84 = CRS.decode( "EPSG:4326" );
Envelope envelope = new ReferencedEnvelope( 0, 10, 0, 20, wsg84 );
double xMin = envelope.getMinimum( 0 );
double yMin = envelope.getMinimum( 1 );

double xMax = envelope.getMaximum( 0 );
double yMax = envelope.getMaximum( 1 );

double width = envelope.getLength( 0 );
double height = envelope.getLength( 1 );

You can see even in a simple example we should be looking at the CRS to figure out what the axis is actually measuring.

If you are super confident that you are working with data in X/Y order you can directly make use of bounding box.

Note BoundBox is just and interface, so we will use RefernecedEnvelope for the example:

BoundingBox boundingBox = new ReferencedEnvelope( 0, 10, 0, 20, crs );
double xMin = boundingBox.getMinX();
double yMin = boundingBox.getMinY();

double xMax = boundingBox.getMaxX();
double yMax = boundingBox.getMaxY();

double width = boundingBox.getWidth(); // assuming axis 0 is easting
double height = boundingBox.getHeight(); // assuming axis 1 is nothing

JTS Topology Suite Rectangles

The JTS Topology Suite has the concept of an Envelope recorded in x1,x2, y1,y2 order.

• Envelope

You can see that the use of JTS Envelope has the same "assumptions" as the use of BoundingBox above.

Envelope envelope = new Envelope( 0, 10, 0, 20 );
double xMin = envelope.getMinX();
double yMin = envelope.getMinY();

double xMax = envelope.getMaxX();
double yMax = envelope.getMaxY();

double width = envelope.getWidth(); // assuming axis 0 is easting
double height = envelope.getHeight(); // assuming axis 1 is nothing

Where ReferencedEnvelope is Used

ReferencedEnvelope is used in a lot of GeoTools interfaces, basically anywhere we can get away with it. Simply put without knowing the the CoordinateReferenceSystem a raw JTS Envelope is not very useful to us.

You will find in some of our older interfaces that you are forced to read the javadocs in order to figure out the CoordinateReferenceSystem for a returned Envelope.

Using a FeatureSource without ReferencedEnvelope example:

Envelope bounds = featureSource.getBounds();

CoordinateReferenceSystem crs = featureSource.getSchema().getDefaultGeometry().getCoordinateSystem();

Using a FeatureSource with ReferencedEnvelope:

ReferencedEnvelope bounds = (ReferencedEnvelope) featureSource.getBounds();

CoordinateReferenceSystem crs = bounds.getCoordinateReferenceSystem();