org.geotoolkit.geometry
Class ImmutableEnvelope

Object
  AbstractEnvelope
      ImmutableEnvelope

All Implemented Interfaces:

Serializable, Envelope

@Immutable
public final class ImmutableEnvelope
extends AbstractEnvelope
implements Serializable

Immutable representation of an envelope. This class is final in order to ensure that the immutability contract can not be broken (assuming not using Java Native Interface or reflections).

Since:

3.00

Version:

3.20

Author:

Cédric Briançon (Geomatys), Martin Desruisseaux (Geomatys)

See Also:

Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Constructor Summary

ImmutableEnvelope(CoordinateReferenceSystem crs, double xmin, double xmax, double ymin, double ymax)
Builds a two-dimensional envelope with the specified bounds.

ImmutableEnvelope(CoordinateReferenceSystem crs, Envelope envelope)
Creates an immutable envelope with the ordinate values of the given envelope but a different CRS.

ImmutableEnvelope(CoordinateReferenceSystem crs, String wkt)
Constructs a new envelope initialized to the values parsed from the given string in Well Known Text (WKT) format.

ImmutableEnvelope(Envelope envelope)
Creates an immutable envelope with the values of the given envelope.

ImmutableEnvelope(GeographicBoundingBox box)
Constructs a new envelope with the same data than the specified geographic bounding box.

Method Summary

static ImmutableEnvelope	castOrCopy(Envelope envelope) Returns the given envelope as an ImmutableEnvelope instance.
boolean	equals(Object object) Compares the specified object with this envelope for equality.
CoordinateReferenceSystem	getCoordinateReferenceSystem()
int	getDimension()
double	getLower(int dimension) Returns the limit in the direction of decreasing ordinate values in the specified dimension.
DirectPosition	getLowerCorner() A coordinate position consisting of all the lower ordinates.
double	getMaximum(int dimension) Returns the maximal ordinate value for the specified dimension.
double	getMedian(int dimension) Returns the median ordinate along the specified dimension.
double	getMinimum(int dimension) Returns the minimal ordinate value for the specified dimension.
double	getSpan(int dimension) Returns the envelope span (typically width or height) along the specified dimension.
double	getUpper(int dimension) Returns the limit in the direction of increasing ordinate values in the specified dimension.
DirectPosition	getUpperCorner() A coordinate position consisting of all the upper ordinates.
int	hashCode() Returns a hash value for this envelope.
boolean	isEmpty() Determines whether or not this envelope is empty.
boolean	isNull() Returns false if at least one ordinate value is not NaN.

Methods inherited from class AbstractEnvelope

contains, contains, equals, getMedian, getSpan, intersects, toPolygonString, toRectangle2D, toString

Methods inherited from class Object

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

Constructor Detail

ImmutableEnvelope

public ImmutableEnvelope(Envelope envelope)

Creates an immutable envelope with the values of the given envelope.

Parameters:

envelope - The envelope to copy.

ImmutableEnvelope

public ImmutableEnvelope(GeographicBoundingBox box)

Constructs a new envelope with the same data than the specified geographic bounding box. The coordinate reference system is set to WGS84.

Parameters:

box - The bounding box to copy.

Since:

3.20

ImmutableEnvelope

public ImmutableEnvelope(CoordinateReferenceSystem crs,
                         Envelope envelope)
                  throws MismatchedDimensionException

Creates an immutable envelope with the ordinate values of the given envelope but a different CRS. This method does not reproject the given envelope. It just assign the given CRS to this envelope without any check, except for the CRS dimension.

The main purpose of this method is to assign a non-null CRS when the envelope to copy has a null CRS.

Parameters:

crs - The CRS to assign to this envelope, or null.

envelope - The envelope from which to copy ordinate values.

Throws:

MismatchedDimensionException - If the dimension of the given CRS is not equals to the dimension of the given envelope.

Since:

3.20

ImmutableEnvelope

public ImmutableEnvelope(CoordinateReferenceSystem crs,
                         double xmin,
                         double xmax,
                         double ymin,
                         double ymax)
                  throws MismatchedDimensionException

Builds a two-dimensional envelope with the specified bounds.

Parameters:

crs - The coordinate reference system, or null if none.

xmin - The lower value for the first ordinate.

xmax - The upper value for the first ordinate.

ymin - The lower value for the second ordinate.

ymax - The upper value for the second ordinate.

Throws:

MismatchedDimensionException - If the dimension of the given CRS is not equals to 2.

ImmutableEnvelope

public ImmutableEnvelope(CoordinateReferenceSystem crs,
                         String wkt)
                  throws NumberFormatException,
                         IllegalArgumentException,
                         MismatchedDimensionException

Constructs a new envelope initialized to the values parsed from the given string in Well Known Text (WKT) format. The given string is typically a BOX element like below:

BOX(-180 -90, 180 90)

However this constructor is lenient to other geometry types like POLYGON. See the javadoc of the GeneralEnvelope constructor for more information.

Parameters:

crs - The coordinate reference system, or null if none.

wkt - The BOX, POLYGON or other kind of element to parse.

Throws:

NumberFormatException - If a number can not be parsed.

IllegalArgumentException - If the parenthesis are not balanced.

MismatchedDimensionException - If the dimension of the given CRS is not equals to the dimension of the parsed envelope.

Since:

3.20

Method Detail

castOrCopy

public static ImmutableEnvelope castOrCopy(Envelope envelope)

Returns the given envelope as an ImmutableEnvelope instance. If the given envelope is already an instance of ImmutableEnvelope, then it is returned unchanged. Otherwise the coordinate values and the CRS of the given envelope are copied in a new envelope.

Parameters:

envelope - The envelope to cast, or null.

Returns:

The values of the given envelope as an ImmutableEnvelope instance.

Since:

3.20

See Also:

GeneralEnvelope.castOrCopy(Envelope)

getDimension

public int getDimension()

Specified by:

getDimension in interface Envelope

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Specified by:

getCoordinateReferenceSystem in interface Envelope

getLowerCorner

public DirectPosition getLowerCorner()

A coordinate position consisting of all the lower ordinates. The default implementation returns a unmodifiable direct position backed by this envelope, so changes in this envelope will be immediately reflected in the direct position.

Note: The Web Coverage Service (WCS) 1.1 specification uses an extended interpretation of the bounding box definition. In a WCS 1.1 data structure, the lower corner defines the edges region in the directions of decreasing coordinate values in the envelope CRS. This is usually the algebraic minimum coordinates, but not always. For example, an envelope crossing the anti-meridian could have a lower corner longitude greater than the upper corner longitude. Such extended interpretation applies mostly to axes having WRAPAROUND range meaning.

Specified by:

getLowerCorner in interface Envelope

Overrides:

getLowerCorner in class AbstractEnvelope

Returns:

The lower corner, typically (but not necessarily) containing minimal ordinate values.

getUpperCorner

public DirectPosition getUpperCorner()

A coordinate position consisting of all the upper ordinates. The default implementation returns a unmodifiable direct position backed by this envelope, so changes in this envelope will be immediately reflected in the direct position.

Note: The Web Coverage Service (WCS) 1.1 specification uses an extended interpretation of the bounding box definition. In a WCS 1.1 data structure, the upper corner defines the edges region in the directions of increasing coordinate values in the envelope CRS. This is usually the algebraic maximum coordinates, but not always. For example, an envelope crossing the anti-meridian could have an upper corner longitude less than the lower corner longitude. Such extended interpretation applies mostly to axes having WRAPAROUND range meaning.

Specified by:

getUpperCorner in interface Envelope

Overrides:

getUpperCorner in class AbstractEnvelope

Returns:

The upper corner, typically (but not necessarily) containing maximal ordinate values.

getLower

public double getLower(int dimension)
                throws IndexOutOfBoundsException

Returns the limit in the direction of decreasing ordinate values in the specified dimension. This is usually the algebraic minimum, except if this envelope spans the anti-meridian.

Specified by:

getLower in class AbstractEnvelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The starting ordinate value at the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

getUpper

public double getUpper(int dimension)
                throws IndexOutOfBoundsException

Returns the limit in the direction of increasing ordinate values in the specified dimension. This is usually the algebraic maximum, except if this envelope spans the anti-meridian.

Specified by:

getUpper in class AbstractEnvelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The starting ordinate value at the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

getMinimum

public double getMinimum(int dimension)
                  throws IndexOutOfBoundsException

Returns the minimal ordinate value for the specified dimension. In the typical case of envelopes not spanning the anti-meridian, this method returns the AbstractEnvelope.getLower(int) value verbatim. In the case of envelope spanning the anti-meridian, this method returns the axis minimum value.

Specified by:

getMinimum in interface Envelope

Overrides:

getMinimum in class AbstractEnvelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The minimal ordinate value at the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

getMaximum

public double getMaximum(int dimension)
                  throws IndexOutOfBoundsException

Returns the maximal ordinate value for the specified dimension. In the typical case of envelopes not spanning the anti-meridian, this method returns the AbstractEnvelope.getUpper(int) value verbatim. In the case of envelope spanning the anti-meridian, this method returns the axis maximum value.

Specified by:

getMaximum in interface Envelope

Overrides:

getMaximum in class AbstractEnvelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The maximal ordinate value at the given dimension.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

getMedian

public double getMedian(int dimension)
                 throws IndexOutOfBoundsException

Returns the median ordinate along the specified dimension. In most cases, the result is equals (minus rounding error) to:

median = (getUpper(dimension) + getLower(dimension)) / 2;

Spanning the anti-meridian of a Geographic CRS
If upper < lower and the range meaning for the requested dimension is wraparound, then the median calculated above is actually in the middle of the space outside the envelope. In such cases, this method shifts the median value by half of the periodicity (180° in the longitude case) in order to switch from outer space to inner space. If the axis range meaning is not WRAPAROUND, then this method returns NaN.

Specified by:

getMedian in interface Envelope

Overrides:

getMedian in class AbstractEnvelope

Parameters:

dimension - The dimension for which to obtain the ordinate value.

Returns:

The median ordinate at the given dimension, or Double.NaN.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

getSpan

public double getSpan(int dimension)
               throws IndexOutOfBoundsException

Returns the envelope span (typically width or height) along the specified dimension. In most cases, the result is equals (minus rounding error) to:

span = getUpper(dimension) - getLower(dimension);

Spanning the anti-meridian of a Geographic CRS
If upper < lower and the range meaning for the requested dimension is wraparound, then the span calculated above is negative. In such cases, this method adds the periodicity (typically 360° of longitude) to the span. If the result is a positive number, it is returned. Otherwise this method returns NaN.

Specified by:

getSpan in interface Envelope

Overrides:

getSpan in class AbstractEnvelope

Parameters:

dimension - The dimension for which to obtain the span.

Returns:

The span (typically width or height) at the given dimension, or Double.NaN.

Throws:

IndexOutOfBoundsException - If the given index is negative or is equals or greater than the envelope dimension.

isEmpty

public boolean isEmpty()

Determines whether or not this envelope is empty. An envelope is non-empty only if it has at least one dimension, and the span is greater than 0 along all dimensions. Note that a non-empty envelope is always non-null, but the converse is not always true.

Overrides:

isEmpty in class AbstractEnvelope

Returns:

true if this envelope is empty.

See Also:

DefaultGeographicBoundingBox.isEmpty(), RectangularShape.isEmpty()

isNull

public boolean isNull()

Returns false if at least one ordinate value is not NaN. The isNull() check is a little bit different than AbstractEnvelope.isEmpty() since it returns false for a partially initialized envelope, while isEmpty() returns false only after all dimensions have been initialized. More specifically, the following rules apply:

• If isNull() == true, then AbstractEnvelope.isEmpty() == true
• If AbstractEnvelope.isEmpty() == false, then isNull() == false
• The converse of the above-cited rules are not always true.

Overrides:

isNull in class AbstractEnvelope

Returns:

true if this envelope has NaN values.

See Also:

GeneralEnvelope.setToNull()

hashCode

public int hashCode()

Returns a hash value for this envelope.

Overrides:

hashCode in class AbstractEnvelope

equals

public boolean equals(Object object)

Compares the specified object with this envelope for equality.

Overrides:

equals in class AbstractEnvelope

Parameters:

object - The object to compare with this envelope.

Returns:

true if the given object is equal to this envelope.