org.geotoolkit.geometry
Class GeneralEnvelope

Object
  extended by AbstractEnvelope
      extended by AbstractEnvelope
          extended by GeneralEnvelope
All Implemented Interfaces:
Serializable, Cloneable, Envelope

Deprecated. Moved to Apache SIS as GeneralEnvelope.

@Deprecated
public class GeneralEnvelope
extends AbstractEnvelope
implements Cloneable, Serializable

A minimum bounding box or rectangle. Regardless of dimension, an Envelope can be represented without ambiguity as two direct positions (coordinate points). To encode an Envelope, it is sufficient to encode these two points.

Note: Envelope uses an arbitrary Coordinate Reference System, which doesn't need to be geographic. This is different than the GeographicBoundingBox class provided in the metadata package, which can be used as a kind of envelope restricted to a Geographic CRS having Greenwich prime meridian.
This particular implementation of Envelope is said "General" because it uses coordinates of an arbitrary dimension. This is in contrast with Envelope2D, which can use only two-dimensional coordinates.

A GeneralEnvelope can be created in various ways:


Spanning the anti-meridian of a Geographic CRS
The Web Coverage Service (WCS) specification authorizes (with special treatment) cases where upper < lower at least in the longitude case. They are envelopes crossing the anti-meridian, like the red box below (the green box is the usual case). The default implementation of methods listed in the right column can handle such cases.

Supported methods:

Since:
1.2
Version:
3.21
Author:
Martin Desruisseaux (IRD, Geomatys), Simone Giannecchini (Geosolutions), Johann Sorel (Geomatys)
See Also:
Envelope2D, org.geotoolkit.geometry.jts.ReferencedEnvelope, DefaultGeographicBoundingBox, Serialized Form
Module:
referencing/geotk-referencing (download)    View source code for this class

Constructor Summary
GeneralEnvelope(CoordinateReferenceSystem crs)
          Deprecated. Constructs an empty envelope with the specified coordinate reference system.
GeneralEnvelope(double[] minDP, double[] maxDP)
          Deprecated. Constructs a envelope defined by two positions.
GeneralEnvelope(double min, double max)
          Deprecated. Constructs one-dimensional envelope defined by a range of values.
GeneralEnvelope(Envelope envelope)
          Deprecated. Constructs a new envelope with the same data than the specified envelope.
GeneralEnvelope(GeneralDirectPosition lower, GeneralDirectPosition upper)
          Deprecated. Constructs a envelope defined by two positions.
GeneralEnvelope(GeographicBoundingBox box)
          Deprecated. Constructs a new envelope with the same data than the specified geographic bounding box.
GeneralEnvelope(GridEnvelope gridEnvelope, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs)
          Deprecated. Constructs a georeferenced envelope from a grid envelope transformed using the specified math transform.
GeneralEnvelope(int dimension)
          Deprecated. Constructs an empty envelope of the specified dimension.
GeneralEnvelope(Rectangle2D rect)
          Deprecated. Constructs two-dimensional envelope defined by a Rectangle2D.
GeneralEnvelope(String wkt)
          Deprecated. Constructs a new envelope initialized to the values parsed from the given string in Well Known Text (WKT) format.
 
Method Summary
 void add(DirectPosition position)
          Deprecated. Adds a point to this envelope.
 void add(Envelope envelope)
          Deprecated. Adds an envelope object to this envelope.
static GeneralEnvelope castOrCopy(Envelope envelope)
          Deprecated. Returns the given envelope as a GeneralEnvelope instance.
 GeneralEnvelope clone()
          Deprecated. Returns a deep copy of this envelope.
 boolean equals(Object object)
          Compares the specified object with this envelope for equality.
 CoordinateReferenceSystem getCoordinateReferenceSystem()
          Deprecated. Returns the envelope coordinate reference system, or null if unknown.
 int getDimension()
          Deprecated. Returns the length of coordinate sequence (the number of entries) in this envelope.
 double getLower(int dimension)
          
 DirectPosition getLowerCorner()
          
 double getMaximum(int dimension)
          
 double getMedian(int dimension)
          
 double getMinimum(int dimension)
          
 double getSpan(int dimension)
          
 GeneralEnvelope getSubEnvelope(int lower, int upper)
          Deprecated. Returns an envelope that encompass only some dimensions of this envelope.
 double getUpper(int dimension)
          
 DirectPosition getUpperCorner()
          
 int hashCode()
          Returns a hash value for this envelope.
 void intersect(Envelope envelope)
          Deprecated. Sets this envelope to the intersection if this envelope with the specified one.
 boolean isAllNaN()
          
 boolean isEmpty()
          
 boolean isInfinite()
          Deprecated. Returns true if at least one ordinate has an infinite value.
 boolean reduceToDomain(boolean useDomainOfCRS)
          Deprecated. Restricts this envelope to the CS or CRS domain of validity.
 boolean reorderCorners()
          Deprecated. Ensures that lower <= upper for every dimensions.
 void roundIfAlmostInteger(double factor, int maxULP)
          Deprecated. Fixes rounding errors up to a given tolerance level.
 void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
          Deprecated. Sets the coordinate reference system in which the coordinate are given.
 void setEnvelope(double... ordinates)
          Deprecated. Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates.
 void setEnvelope(Envelope envelope)
          Deprecated. Sets this envelope to the same coordinate values than the specified envelope.
 void setRange(int dimension, double minimum, double maximum)
          Deprecated. Sets the envelope range along the specified dimension.
 void setSubEnvelope(Envelope envelope, int offset)
          Deprecated. Sets a sub-domain of this envelope to the same coordinate values than the specified envelope.
 void setToInfinite()
          Deprecated. Sets the lower corner to negative infinity and the upper corner to positive infinity.
 void setToNull()
          Deprecated. Sets all ordinate values to NaN.
 
Methods inherited from class AbstractEnvelope
isNull, toRectangle2D
 
Methods inherited from class AbstractEnvelope
contains, contains, equals, getMedian, getSpan, intersects, toString
 
Methods inherited from class Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

GeneralEnvelope

public GeneralEnvelope(int dimension)
Deprecated. 
Constructs an empty envelope of the specified dimension. All ordinates are initialized to 0 and the coordinate reference system is undefined.

Parameters:
dimension - The envelope dimension.

GeneralEnvelope

public GeneralEnvelope(double min,
                       double max)
Deprecated. 
Constructs one-dimensional envelope defined by a range of values.

Parameters:
min - The lower value.
max - The upper value.

GeneralEnvelope

public GeneralEnvelope(double[] minDP,
                       double[] maxDP)
Deprecated. 
Constructs a envelope defined by two positions.

Parameters:
minDP - Lower ordinate values.
maxDP - Upper ordinate values.
Throws:
MismatchedDimensionException - if the two positions don't have the same dimension.

GeneralEnvelope

public GeneralEnvelope(GeneralDirectPosition lower,
                       GeneralDirectPosition upper)
                throws MismatchedReferenceSystemException
Deprecated. 
Constructs a envelope defined by two positions. The coordinate reference system is inferred from the supplied direct position.

Parameters:
lower - Point containing the starting ordinate values.
upper - Point containing the ending ordinate values.
Throws:
MismatchedDimensionException - if the two positions don't have the same dimension.
MismatchedReferenceSystemException - if the two positions don't use the same CRS.
See Also:
Envelope2D.Envelope2D(DirectPosition, DirectPosition)

GeneralEnvelope

public GeneralEnvelope(CoordinateReferenceSystem crs)
Deprecated. 
Constructs an empty envelope with the specified coordinate reference system. All ordinates are initialized to 0.

Parameters:
crs - The coordinate reference system.
Since:
2.2

GeneralEnvelope

public GeneralEnvelope(Envelope envelope)
Deprecated. 
Constructs a new envelope with the same data than the specified envelope.

Parameters:
envelope - The envelope to copy.
See Also:
Envelope2D.Envelope2D(Envelope)

GeneralEnvelope

public GeneralEnvelope(GeographicBoundingBox box)
Deprecated. 
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:
2.4
See Also:
Envelope2D.Envelope2D(GeographicBoundingBox)

GeneralEnvelope

public GeneralEnvelope(Rectangle2D rect)
Deprecated. 
Constructs two-dimensional envelope defined by a Rectangle2D. The coordinate reference system is initially undefined.

Parameters:
rect - The rectangle to copy.
See Also:
Envelope2D.Envelope2D(CoordinateReferenceSystem, Rectangle2D)

GeneralEnvelope

public GeneralEnvelope(GridEnvelope gridEnvelope,
                       PixelInCell anchor,
                       MathTransform gridToCRS,
                       CoordinateReferenceSystem crs)
                throws IllegalArgumentException
Deprecated. 
Constructs a georeferenced envelope from a grid envelope transformed using the specified math transform. The grid to CRS transform should map either the cell center (as in OGC convention) or cell corner (as in Java2D/JAI convention) depending on the anchor value. This constructor creates an envelope containing entirely all pixels on a best effort basis - usually accurate for affine transforms.

Note: The convention is specified as a PixelInCell code instead than the more detailed PixelOrientation, because the later is restricted to the two-dimensional case while the former can be used for any number of dimensions.

Parameters:
gridEnvelope - The grid envelope in integer coordinates.
anchor - Whatever grid coordinates map to pixel center or pixel corner.
gridToCRS - The transform (usually affine) from grid envelope to the CRS.
crs - The CRS for the envelope to be created, or null if unknown.
Throws:
MismatchedDimensionException - If one of the supplied object doesn't have a dimension compatible with the other objects.
IllegalArgumentException - if an argument is illegal for some other raisons, including failure to use the provided math transform.
Since:
2.3
See Also:
GridToEnvelopeMapper, GeneralGridEnvelope.GeneralGridEnvelope(Envelope,PixelInCell,boolean)

GeneralEnvelope

public GeneralEnvelope(String wkt)
                throws NumberFormatException,
                       IllegalArgumentException
Deprecated. 
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. Actually this constructor ignores the geometry type and just applies the following simple rules:

This constructor does not check the consistency of the provided WKT. For example it doesn't check that every points in a LINESTRING have the same dimension. However this constructor ensures that the parenthesis are balanced, in order to catch some malformed WKT.

The following examples can be parsed by this constructor in addition of the standard BOX element. This constructor creates the bounding box of those geometries:

Parameters:
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.
Since:
3.09
See Also:
Envelopes.parseWKT(String), Envelopes.toWKT(Envelope)
Method Detail

castOrCopy

public static GeneralEnvelope castOrCopy(Envelope envelope)
Deprecated. 
Returns the given envelope as a GeneralEnvelope instance. If the given envelope is already an instance of GeneralEnvelope, then it is returned unchanged. Otherwise the coordinate values and the CRS of the given envelope are copied in a new GeneralEnvelope.

Parameters:
envelope - The envelope to cast, or null.
Returns:
The values of the given envelope as a GeneralEnvelope instance.
Since:
3.19
See Also:
AbstractEnvelope.castOrCopy(Envelope)

getDimension

public final int getDimension()
Deprecated. 
Returns the length of coordinate sequence (the number of entries) in this envelope. This information is available even when the coordinate reference system is unknown.

Specified by:
getDimension in interface Envelope
Returns:
The dimensionality of this envelope.

getCoordinateReferenceSystem

public final CoordinateReferenceSystem getCoordinateReferenceSystem()
Deprecated. 
Returns the envelope coordinate reference system, or null if unknown. If non-null, it shall be the same as lower corner and upper corner CRS.

Specified by:
getCoordinateReferenceSystem in interface Envelope
Returns:
The envelope CRS, or null if unknown.

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
                                  throws MismatchedDimensionException
Deprecated. 
Sets the coordinate reference system in which the coordinate are given. This method does not reproject the envelope, and do not check if the envelope is contained in the new domain of validity. The later can be enforced by a call to reduceToDomain(boolean).

If the envelope coordinates need to be transformed to the new CRS, consider using Envelopes.transform(Envelope, CoordinateReferenceSystem) instead.

Parameters:
crs - The new coordinate reference system, or null.
Throws:
MismatchedDimensionException - if the specified CRS doesn't have the expected number of dimensions.

reduceToDomain

public boolean reduceToDomain(boolean useDomainOfCRS)
Deprecated. 
Restricts this envelope to the CS or CRS domain of validity. This method performs two steps:
  1. First, ensure that the envelope is contained in the coordinate system domain. If some ordinates are out of range, then there is a choice depending on the range meaning:

    • If RangeMeaning.EXACT (typically latitudes ordinates), then values greater than the maximum value are replaced by the maximum, and values smaller than the minimum value are replaced by the minimum.

    • If RangeMeaning.WRAPAROUND (typically longitudes ordinates), then a multiple of the range (e.g. 360° for longitudes) is added or subtracted. Example:

      • the [190 … 200]° longitude range is converted to [-170 … -160]°,
      • the [170 … 200]° longitude range is converted to [+170 … -160]°.
      See Spanning the anti-meridian of a Geographic CRS in the class javadoc for more information about the meaning of such range.

  2. If crsDomain is true, then the envelope from the previous step is intersected with the CRS domain of validity, if any.

Spanning the anti-meridian of a Geographic CRS
Note that if the envelope is spanning the anti-meridian, then some lower ordinate values may become greater than the upper ordinate values even if it was not the case before this method call. If this is not acceptable, consider invoking reorderCorners() after this method call.

Choosing the range of longitude values
Geographic CRS typically have longitude values in the [-180 … +180]° range, but the [0 … 360]° range is also occasionally used. Callers need to ensure that this envelope CRS is associated to axes having the desired minimum and maximum value. The AxisRangeType enumeration can be used for shifting a geographic CRS to the desired range.

Usage
This method is sometime useful before to compute the union or intersection of envelopes, in order to ensure that both envelopes are defined in the same domain. This method may also be invoked before to project an envelope, since some projections produce Double.NaN numbers when given an ordinate value out of bounds.

Parameters:
useDomainOfCRS - true if the envelope should be restricted to the CRS domain of validity in addition to the CS domain.
Returns:
true if this envelope has been modified as a result of this method call, or false if no change was done.
Since:
3.11 (derived from 2.5)
See Also:
ReferenceSystem.getDomainOfValidity(), AxisRangeType

reorderCorners

public boolean reorderCorners()
                       throws IllegalStateException
Deprecated. 
Ensures that lower <= upper for every dimensions. If a upper ordinate value is less than a lower ordinate value, then there is a choice:

This method is useful when the envelope needs to be used with library that doesn't support envelopes spanning the anti-meridian.

Returns:
true if this envelope has been modified as a result of this method call, or false if no change was done.
Throws:
IllegalStateException - If a upper ordinate value is less than a lower ordinate value on an axis which doesn't have the WRAPAROUND range meaning.
Since:
3.20

roundIfAlmostInteger

public void roundIfAlmostInteger(double factor,
                                 int maxULP)
Deprecated. 
Fixes rounding errors up to a given tolerance level. For each value ordinates[i] at dimension i, this method multiplies the ordinate value by the given factor, then round the result only if the product is close to an integer value. The threshold is defined by the maxULP argument in ULP units (Unit in the Last Place). If and only if the product has been rounded, it is divided by the factor and stored in this envelope in place of the original ordinate.

This method is useful after envelope calculations subject to rounding errors, like the GeneralEnvelope(GridEnvelope, PixelInCell, MathTransform, CoordinateReferenceSystem) constructor.

Parameters:
factor - The factor by which to multiply ordinates before rounding and divide after rounding. A recommended value is 360.
maxULP - The maximal change allowed in ULPs (Unit in the Last Place).
Since:
3.11

setRange

public void setRange(int dimension,
                     double minimum,
                     double maximum)
              throws IndexOutOfBoundsException
Deprecated. 
Sets the envelope range along the specified dimension.

Parameters:
dimension - The dimension to set.
minimum - The minimum value along the specified dimension.
maximum - The maximum value along the specified dimension.
Throws:
IndexOutOfBoundsException - If the given index is out of bounds.

setEnvelope

public void setEnvelope(double... ordinates)
Deprecated. 
Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates. The number of arguments provided shall be twice this envelope dimension, and minimum shall not be greater than maximum.

Example: (xmin, ymin, zmin, xmax, ymax, zmax)

Parameters:
ordinates - The new ordinate values.
Since:
2.5

setEnvelope

public void setEnvelope(Envelope envelope)
                 throws MismatchedDimensionException
Deprecated. 
Sets this envelope to the same coordinate values than the specified envelope. If the given envelope has a non-null Coordinate Reference System (CRS), then the CRS of this envelope will be set to the CRS of the given envelope.

Parameters:
envelope - The envelope to copy coordinates from.
Throws:
MismatchedDimensionException - if the specified envelope doesn't have the expected number of dimensions.
Since:
2.2

setSubEnvelope

public void setSubEnvelope(Envelope envelope,
                           int offset)
                    throws IndexOutOfBoundsException
Deprecated. 
Sets a sub-domain of this envelope to the same coordinate values than the specified envelope. This method copies the ordinate values of all dimensions from the given envelope to some dimensions of this envelope. The target dimensions in this envelope range from offset inclusive to lower + Envelope.getDimension() exclusive.

This method ignores the Coordinate Reference System of this and the given envelope.

Parameters:
envelope - The envelope to copy coordinates from.
offset - Index of the first dimension to write in this envelope.
Throws:
IndexOutOfBoundsException - If the given offset is negative, or is greater than getDimension() - envelope.getDimension().
Since:
3.16

getSubEnvelope

public GeneralEnvelope getSubEnvelope(int lower,
                                      int upper)
                               throws IndexOutOfBoundsException
Deprecated. 
Returns an envelope that encompass only some dimensions of this envelope. This method performs the following choice:

Parameters:
lower - The first dimension to copy, inclusive.
upper - The last dimension to copy, exclusive.
Returns:
The sub-envelope of dimension upper-lower, which may be this.
Throws:
IndexOutOfBoundsException - if an index is out of bounds.

setToInfinite

public void setToInfinite()
Deprecated. 
Sets the lower corner to negative infinity and the upper corner to positive infinity. The coordinate reference system (if any) stay unchanged.

Since:
2.2

isInfinite

public boolean isInfinite()
Deprecated. 
Returns true if at least one ordinate has an infinite value.

Returns:
true if this envelope has infinite value.
Since:
2.2

setToNull

public void setToNull()
Deprecated. 
Sets all ordinate values to NaN. The coordinate reference system (if any) stay unchanged.

Since:
2.2
See Also:
isAllNaN()

add

public void add(DirectPosition position)
         throws MismatchedDimensionException,
                AssertionError
Deprecated. 
Adds a point to this envelope. The resulting envelope is the smallest envelope that contains both the original envelope and the specified point.

After adding a point, a call to contains(DirectPosition) with the added point as an argument will return true, except if one of the point ordinates was Double.NaN in which case the corresponding ordinate has been ignored.

Note: This method assumes that the specified point uses the same CRS than this envelope. For performance raisons, it will no be verified unless Java assertions are enabled.

Spanning the anti-meridian of a Geographic CRS
This method supports envelopes spanning the anti-meridian. In such cases it is possible to move both envelope borders in order to encompass the given point, as illustrated below (the new point is represented by the + symbol):

─────┐   + ┌─────
─────┘     └─────
The default implementation moves only the border which is closest to the given point.

Parameters:
position - The point to add.
Throws:
MismatchedDimensionException - if the specified point doesn't have the expected dimension.
AssertionError - If assertions are enabled and the envelopes have mismatched CRS.

add

public void add(Envelope envelope)
         throws MismatchedDimensionException,
                AssertionError
Deprecated. 
Adds an envelope object to this envelope. The resulting envelope is the union of the two Envelope objects.
Note: This method assumes that the specified envelope uses the same CRS than this envelope. For performance raisons, it will no be verified unless Java assertions are enabled.

Spanning the anti-meridian of a Geographic CRS
This method supports envelopes spanning the anti-meridian. If one or both envelopes span the anti-meridian, then the result of the add operation may be an envelope expanding to infinities. In such case, the ordinate range will be either [-∞…∞] or [0…-0] depending on whatever the original range span the anti-meridian or not.

Parameters:
envelope - the Envelope to add to this envelope.
Throws:
MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.
AssertionError - If assertions are enabled and the envelopes have mismatched CRS.

intersect

public void intersect(Envelope envelope)
               throws MismatchedDimensionException,
                      AssertionError
Deprecated. 
Sets this envelope to the intersection if this envelope with the specified one.
Note: This method assumes that the specified envelope uses the same CRS than this envelope. For performance raisons, it will no be verified unless Java assertions are enabled.

Spanning the anti-meridian of a Geographic CRS
This method supports envelopes spanning the anti-meridian.

Parameters:
envelope - the Envelope to intersect to this envelope.
Throws:
MismatchedDimensionException - if the specified envelope doesn't have the expected dimension.
AssertionError - If assertions are enabled and the envelopes have mismatched CRS.

clone

public GeneralEnvelope clone()
Deprecated. 
Returns a deep copy of this envelope.

Overrides:
clone in class Object
Returns:
A clone of this envelope.
See Also:
Object.clone()

getLowerCorner

public DirectPosition getLowerCorner()

Specified by:
getLowerCorner in interface Envelope
Overrides:
getLowerCorner in class AbstractEnvelope

getUpperCorner

public DirectPosition getUpperCorner()

Specified by:
getUpperCorner in interface Envelope
Overrides:
getUpperCorner in class AbstractEnvelope

getLower

public double getLower(int dimension)
                throws IndexOutOfBoundsException

Specified by:
getLower in class AbstractEnvelope
Throws:
IndexOutOfBoundsException

getUpper

public double getUpper(int dimension)
                throws IndexOutOfBoundsException

Specified by:
getUpper in class AbstractEnvelope
Throws:
IndexOutOfBoundsException

getMinimum

public double getMinimum(int dimension)
                  throws IndexOutOfBoundsException

Specified by:
getMinimum in interface Envelope
Overrides:
getMinimum in class AbstractEnvelope
Throws:
IndexOutOfBoundsException

getMaximum

public double getMaximum(int dimension)
                  throws IndexOutOfBoundsException

Specified by:
getMaximum in interface Envelope
Overrides:
getMaximum in class AbstractEnvelope
Throws:
IndexOutOfBoundsException

getMedian

public double getMedian(int dimension)
                 throws IndexOutOfBoundsException

Specified by:
getMedian in interface Envelope
Overrides:
getMedian in class AbstractEnvelope
Throws:
IndexOutOfBoundsException

getSpan

public double getSpan(int dimension)
               throws IndexOutOfBoundsException

Specified by:
getSpan in interface Envelope
Overrides:
getSpan in class AbstractEnvelope
Throws:
IndexOutOfBoundsException

isEmpty

public boolean isEmpty()

Overrides:
isEmpty in class AbstractEnvelope

isAllNaN

public boolean isAllNaN()

Overrides:
isAllNaN in class AbstractEnvelope

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


Copyright © 2009-2013 Geotoolkit.org. All Rights Reserved.