org.geotoolkit.coverage.sql
Class CoverageEnvelope

Object
  AbstractEnvelope
      CoverageEnvelope

All Implemented Interfaces:

Cloneable, Envelope

public class CoverageEnvelope
extends AbstractEnvelope
implements Cloneable

An envelope holding the spatio-temporal extent and preferred resolution of a coverage. The envelope Coordinate Reference System (CRS) is determined by the CoverageDatabase instance associated with this object and can not be changed. The CoverageDatabase may define different CRS, but the following axes can be considered typical:

• The longitude in decimal degrees relative to Greenwich meridian.
• The latitude in decimal degrees.
• Altitude in metres above the WGS 84 ellipsoid.
• Time in fractional days since epoch.

This class provides convenience methods for fetching and setting the horizontal rectangle, vertical range and temporal range of the envelope.

Conventions
In this class, the lower and upper bounds are both inclusive. This is consistent with OGC/ISO conventions but different than typical Java conventions, where the upper bounds is often exclusive.

Since:

3.10 (derived from Seagis)

Version:

3.10

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

coverage/geotk-coverage-sql (download)

View source code for this class

Method Summary

boolean	clear() Resets all envelope attributes to their initial state, which is an infinite envelope.
CoverageEnvelope	clone() Returns a clone of this coverage envelope.
boolean	equals(Object other) Compares this extent with the given object for equality.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the spatio-temporal CRS of this envelope.
CoordinateReferenceSystem	getCoordinateReferenceSystem(boolean horizontal, boolean vertical, boolean temporal) Returns the CRS of this envelope containing only the requested dimensions.
int	getDimension() Returns the number of dimension in this envelope, which is usually 4.
Rectangle2D	getHorizontalRange() Returns the horizontal bounding box of the elements to be read.
double	getLower(int dimension) Returns the minimal ordinate along the specified dimension.
double	getMedian(int dimension) Returns the median ordinate along the specified dimension.
Dimension	getPreferredImageSize() Returns the approximative size of the desired image, or null if unknown.
Dimension2D	getPreferredResolution() Returns the approximative resolution desired, or null for best resolution.
double	getSpan(int dimension) Returns the envelope span along the specified dimension.
DateRange	getTimeRange() Returns the time range of the elements to be read.
double	getUpper(int dimension) Returns the maximal ordinate along the specified dimension.
NumberRange<Double>	getVerticalRange() Returns the vertical range of the elements to be read.
int	hashCode() Returns a hash code value for this extent.
boolean	setEnvelope(Envelope envelope) Sets the spatio-temporal envelope.
boolean	setHorizontalRange(Rectangle2D area) Sets the horizontal bounding box of the elements to be read.
boolean	setPreferredImageSize(Dimension size) Sets the approximative size of the desired image.
boolean	setPreferredResolution(Dimension2D resolution) Sets the preferred resolution in units of the horizontal envelope.
boolean	setTimeRange(Date startTime, Date endTime) Sets the time range of the elements to be read by this table.
boolean	setTimeRange(DateRange timeRange) Sets the time range of the elements to be read.
boolean	setVerticalRange(double minimum, double maximum) Sets the vertical range of the elements to be read.
boolean	setVerticalRange(NumberRange<?> range) Sets the vertical range of the elements to be read.

Methods inherited from class AbstractEnvelope

castOrCopy, contains, contains, equals, getLowerCorner, getMaximum, getMedian, getMinimum, getSpan, getUpperCorner, intersects, isEmpty, isNull, toPolygonString, toRectangle2D, toString

Methods inherited from class Object

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

Method Detail

clear

public boolean clear()

Resets all envelope attributes to their initial state, which is an infinite envelope.

Returns:

true if this envelope changed as a result of this method call.

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the spatio-temporal CRS of this envelope.

Specified by:

getCoordinateReferenceSystem in interface Envelope

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem(boolean horizontal,
                                                              boolean vertical,
                                                              boolean temporal)

Returns the CRS of this envelope containing only the requested dimensions. If an argument is true, then the returned CRS will contain the corresponding dimension if the database CRS has such dimension. If an argument is false, then the returned CRS is guaranteed to not have the corresponding dimension. If all arguments are false, then this method returns null.

Parameters:

horizontal - false for excluding the horizontal component in the returned CRS.

vertical - false for excluding the vertical component in the returned CRS.

temporal - false for excluding the temporal component in the returned CRS.

Returns:

The envelope CRS excluding the components specified by false argument value, or null if there is no CRS for the remaining components.

getDimension

public int getDimension()

Returns the number of dimension in this envelope, which is usually 4.

Specified by:

getDimension in interface Envelope

setEnvelope

public boolean setEnvelope(Envelope envelope)
                    throws TransformException

Sets the spatio-temporal envelope. The default implementation delegates to setHorizontalRange(Rectangle2D), setVerticalRange(NumberRange) and setTimeRange(DateRange), applying a coordinate transformation if needed.

If the given envelope has more dimensions than this envelope dimension, then the extra dimensions will be ignored. If the given envelope has less dimensions, then the CoverageEnvelope dimensions not present in the given envelope will be left unchanged.

Example: If the given envelope is two-dimensional and its CRS is horizontal, then only the setHorizontalRange(Rectangle2D) method will be invoked on this CoverageEnvelope - the vertical and temporal ordinate values will be unchanged.

Parameters:

envelope - The envelope, or null to reset to full coverage.

Returns:

true if the envelope changed as a result of this call, or false if the specified envelope is equals to the one already set.

Throws:

TransformException - if an error occurred during coordinate transformation.

getHorizontalRange

public Rectangle2D getHorizontalRange()

Returns the horizontal bounding box of the elements to be read. The returned rectangle may contains infinite values.

Returns:

The horizontal bounding box of the elements to be read.

See Also:

getVerticalRange(), getTimeRange()

setHorizontalRange

public boolean setHorizontalRange(Rectangle2D area)

Sets the horizontal bounding box of the elements to be read.

Parameters:

area - The horizontal bounding box of the elements to be read.

Returns:

true if the bounding box changed as a result of this call, or false if the specified box is equals to the one already set.

getVerticalRange

public NumberRange<Double> getVerticalRange()

Returns the vertical range of the elements to be read.

Returns:

The vertical range of the elements to be read.

See Also:

getHorizontalRange(), getTimeRange()

setVerticalRange

public final boolean setVerticalRange(NumberRange<?> range)

Sets the vertical range of the elements to be read. This convenience method delegates to setVerticalRange(double, double).

Parameters:

range - The vertical range, or null for full coverage.

Returns:

true if the vertical range changed as a result of this call, or false if the specified range is equals to the one already set.

setVerticalRange

public boolean setVerticalRange(double minimum,
                                double maximum)

Sets the vertical range of the elements to be read.

Parameters:

minimum - The minimal z value, inclusive.

maximum - The maximal z value, inclusive.

Returns:

true if the vertical range changed as a result of this call, or false if the specified range is equals to the one already set.

getTimeRange

public DateRange getTimeRange()

Returns the time range of the elements to be read.

Returns:

The time range of the elements to be read.

See Also:

getHorizontalRange(), getVerticalRange()

setTimeRange

public final boolean setTimeRange(DateRange timeRange)

Sets the time range of the elements to be read. This convenience method delegates to setTimeRange(Date, Date).

Parameters:

timeRange - The time range.

Returns:

true if the time range changed as a result of this call, or false if the specified range is equals to the one already set.

setTimeRange

public boolean setTimeRange(Date startTime,
                            Date endTime)

Sets the time range of the elements to be read by this table.

Parameters:

startTime - The start time, inclusive.

endTime - The end time, inclusive.

Returns:

true if the time range changed as a result of this call, or false if the specified range is equals to the one already set.

getPreferredResolution

public Dimension2D getPreferredResolution()

Returns the approximative resolution desired, or null for best resolution. The units are the same than for the horizontal envelope.

Returns:

The resolution, or null for the best resolution available.

setPreferredResolution

public boolean setPreferredResolution(Dimension2D resolution)

Sets the preferred resolution in units of the horizontal envelope. This is only an approximative hint, since there is no guarantee that an image will be read with that resolution. A null values means that the best available resolution should be used.

Parameters:

resolution - The preferred geographic resolution, or null for best resolution.

Returns:

true if the resolution changed as a result of this call, or false if the specified resolution is equals to the one already set.

getPreferredImageSize

public Dimension getPreferredImageSize()

Returns the approximative size of the desired image, or null if unknown. This is computed from the horizontal range and the preferred resolution.

Returns:

The image size computed from the horizontal range and the resolution, or null if the size can not be computed.

setPreferredImageSize

public boolean setPreferredImageSize(Dimension size)
                              throws IllegalStateException

Sets the approximative size of the desired image. This is a convenience method which set the preferred resolution to a value computed from the horizontal range and the given size.

The setHorizontalRange(Rectangle2D) or setEnvelope(Envelope) method must have been invoked with a finite envelope before this setPreferredImageSize method. The previous preferred resolution, if any, is discarded.

Parameters:

size - The new preferred image size, or null.

Returns:

true if the resolution changed as a result of this call, or false if the specified resolution is equals to the one computed by this method.

Throws:

IllegalStateException - If the current horizontal range is not finite.

getLower

public double getLower(int dimension)
                throws IndexOutOfBoundsException

Returns the minimal ordinate along the specified dimension.

Specified by:

getLower in class AbstractEnvelope

Parameters:

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

Returns:

The minimal ordinate 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 maximal ordinate along the specified dimension.

Specified by:

getUpper in class AbstractEnvelope

Parameters:

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

Returns:

The maximal ordinate 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.

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.

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 along the specified dimension.

Specified by:

getSpan in interface Envelope

Overrides:

getSpan in class AbstractEnvelope

Parameters:

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

Returns:

The envelope span along the given dimension.

Throws:

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

clone

public CoverageEnvelope clone()

Returns a clone of this coverage envelope.

Overrides:

clone in class Object

Returns:

A copy of this object.

See Also:

Object.clone()

hashCode

public int hashCode()

Returns a hash code value for this extent.

Overrides:

hashCode in class AbstractEnvelope

equals

public boolean equals(Object other)

Compares this extent with the given object for equality.

Overrides:

equals in class AbstractEnvelope

Parameters:

other - The object to compare with this one.

Returns:

true if the given object is equal to this envelope.