Class GeneralBounds
 Object

 AbstractBounds

 GeneralBounds

public class GeneralBounds extends AbstractBounds implements Cloneable, Serializable
A minimum bounding box or rectangle. Regardless of dimension, anEnvelope
can be represented without ambiguity as two direct positions (coordinate points). To encode anEnvelope
, it is sufficient to encode these two points.This particular implementation of
Envelope
is said "General" because it uses coordinates of an arbitrary dimension.Tip: The metadata package provides a
GeographicBoundingBox
, which can be used as a kind of envelope with a coordinate reference system fixed to WGS 84 (EPSG:4326). Since:
 2.0
 Author:
 Martin Desruisseaux (IRD), Simone Giannecchini
 See Also:
Envelope2D
,ReferencedEnvelope
,GeographicBoundingBox
, Serialized Form


Constructor Summary
Constructors Constructor Description GeneralBounds(double[] minDP, double[] maxDP)
Constructs a envelope defined by two positions.GeneralBounds(double min, double max)
Constructs onedimensional envelope defined by a range of values.GeneralBounds(int dimension)
Constructs an empty envelope of the specified dimension.GeneralBounds(Rectangle2D rect)
Constructs twodimensional envelope defined by aRectangle2D
.GeneralBounds(Rectangle2D rect, CoordinateReferenceSystem crs)
Constructs twodimensional envelope defined by aRectangle2D
.GeneralBounds(GridEnvelope gridRange, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs)
Creates an envelope for a grid range transformed to an envelope using the specified math transform.GeneralBounds(Bounds envelope)
Constructs new bounds with the same data as the specified envelope.GeneralBounds(GeographicBoundingBox box)
Constructs a new envelope with the same data than the specified geographic bounding box.GeneralBounds(CoordinateReferenceSystem crs)
Constructs an empty envelope with the specified coordinate reference system.GeneralBounds(CoordinateReferenceSystem crs, double xMin, double yMin, double width, double height)
Constructs an empty envelope with the specified coordinate reference system.GeneralBounds(GeneralPosition minDP, GeneralPosition maxDP)
Constructs a envelope defined by two positions.

Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(double x, double y)
Adds a position to this bounds.void
add(Bounds envelope)
Adds an envelope object to this envelope.void
add(Position position)
Adds a position to this bounds.GeneralBounds
clone()
Returns a deep copy of this envelope.boolean
contains(Bounds envelope, boolean edgesInclusive)
Returnstrue
if this envelope completly encloses the specified envelope.boolean
contains(Position position)
Tests if a specified coordinate is inside the boundary of this envelope.boolean
equals(Object object)
Compares the specified object with this envelope for equality.boolean
equals(Bounds envelope, double eps, boolean epsIsRelative)
Compares to the specified envelope for equality up to the specified tolerance value.CoordinateReferenceSystem
getCoordinateReferenceSystem()
Returns the coordinate reference system in which the coordinates are given.int
getDimension()
Returns the number of dimensions.Position
getLowerCorner()
A coordinate position consisting of all the minimal ordinates for each dimension for all points within theEnvelope
.double
getMaximum(int dimension)
Returns the maximal ordinate along the specified dimension.Position
getMedian()
A coordinate position consisting of all the middle ordinates for each dimension for all points within theEnvelope
.double
getMedian(int dimension)
Returns the median ordinate along the specified dimension.double
getMinimum(int dimension)
Returns the minimal ordinate along the specified dimension.GeneralBounds
getReducedEnvelope(int lower, int upper)
Returns a new envelope with the same values than this envelope minus the specified range of dimensions.double
getSpan(int dimension)
Returns the envelope span (typically width or height) along the specified dimension.double
getSpan(int dimension, Unit<?> unit)
Returns the envelope span along the specified dimension, in terms of the given units.GeneralBounds
getSubEnvelope(int lower, int upper)
Returns a new envelope that encompass only some dimensions of this envelope.Position
getUpperCorner()
A coordinate position consisting of all the maximal ordinates for each dimension for all points within theEnvelope
.int
hashCode()
Returns a hash value for this envelope.void
intersect(Bounds envelope)
Sets this envelope to the intersection if this envelope with the specified one.boolean
intersects(Bounds envelope, boolean edgesInclusive)
Returnstrue
if this envelope intersects the specified envelope.boolean
isEmpty()
Determines whether or not this envelope is empty.boolean
isInfinite()
Returnstrue
if at least one ordinate has an infinite value.boolean
isNull()
Returnsfalse
if at least one ordinate value is not NaN.boolean
normalize(boolean crsDomain)
Restricts this envelope to the CS or CRS domain of validity.void
setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
Sets the coordinate reference system in which the coordinate are given.void
setEnvelope(double... ordinates)
Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates.void
setEnvelope(GeneralBounds envelope)
Sets this envelope to the same coordinate values than the specified envelope.void
setRange(int dimension, double minimum, double maximum)
Sets the envelope's range along the specified dimension.void
setToInfinite()
Sets the lower corner to negative infinity and the upper corner to positive infinity.void
setToNull()
Sets all ordinate values to NaN.static GeneralBounds
toGeneralEnvelope(Bounds envelope)
Converts the envelope to a general envelope, avoiding the construction of a new object in case the input envelope is already a GeneralEnvelopeRectangle2D
toRectangle2D()
Returns aRectangle2D
with the same bounds as thisEnvelope
.
Methods inherited from class AbstractBounds
toString




Constructor Detail

GeneralBounds
public GeneralBounds(int dimension)
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.

GeneralBounds
public GeneralBounds(double min, double max)
Constructs onedimensional envelope defined by a range of values. Parameters:
min
 The minimal value.max
 The maximal value.

GeneralBounds
public GeneralBounds(double[] minDP, double[] maxDP) throws IllegalArgumentException
Constructs a envelope defined by two positions. Parameters:
minDP
 Minimum ordinate values.maxDP
 Maximum ordinate values. Throws:
MismatchedDimensionException
 if the two positions don't have the same dimension.IllegalArgumentException
 if an ordinate value in the minimum point is not less than or equal to the corresponding ordinate value in the maximum point.

GeneralBounds
public GeneralBounds(GeneralPosition minDP, GeneralPosition maxDP) throws MismatchedReferenceSystemException, IllegalArgumentException
Constructs a envelope defined by two positions. The coordinate reference system is inferred from the supplied direct position. Parameters:
minDP
 Point containing minimum ordinate values.maxDP
 Point containing maximum 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.IllegalArgumentException
 if an ordinate value in the minimum point is not less than or equal to the corresponding ordinate value in the maximum point.

GeneralBounds
public GeneralBounds(CoordinateReferenceSystem crs)
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

GeneralBounds
public GeneralBounds(CoordinateReferenceSystem crs, double xMin, double yMin, double width, double height)
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

GeneralBounds
public GeneralBounds(Bounds envelope)
Constructs new bounds with the same data as the specified envelope. Parameters:
envelope
 The envelope to copy.

GeneralBounds
public GeneralBounds(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:
 2.4

GeneralBounds
public GeneralBounds(Rectangle2D rect)
Constructs twodimensional envelope defined by aRectangle2D
. The coordinate reference system is initially undefined. Parameters:
rect
 The rectangle to copy.

GeneralBounds
public GeneralBounds(Rectangle2D rect, CoordinateReferenceSystem crs)
Constructs twodimensional envelope defined by aRectangle2D
. The coordinate reference system is initially undefined. Parameters:
rect
 The rectangle to copy.crs
 Since:
 30

GeneralBounds
public GeneralBounds(GridEnvelope gridRange, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs) throws IllegalArgumentException
Creates an envelope for a grid range transformed to an envelope 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 theanchor
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 detailledPixelOrientation
, because the later is restricted to the twodimensional case while the former can be used for any number of dimensions. Parameters:
gridRange
 The grid range.anchor
 Whatever grid range coordinates map to pixel center or pixel corner.gridToCRS
 The transform (usually affine) from grid range to the envelope CRS.crs
 The envelope CRS, ornull
if unknow. 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 reason, including failure to use the provided math transform. Since:
 2.3
 See Also:
GeneralGridEnvelope(Bounds,PixelInCell,boolean)


Method Detail

toGeneralEnvelope
public static GeneralBounds toGeneralEnvelope(Bounds envelope)
Converts the envelope to a general envelope, avoiding the construction of a new object in case the input envelope is already a GeneralEnvelope

getCoordinateReferenceSystem
public final CoordinateReferenceSystem getCoordinateReferenceSystem()
Returns the coordinate reference system in which the coordinates are given. Specified by:
getCoordinateReferenceSystem
in interfaceBounds
 Returns:
 The coordinate reference system, or
null
.

setCoordinateReferenceSystem
public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs) throws MismatchedDimensionException
Sets the coordinate reference system in which the coordinate are given. This method do 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 tonormalize(boolean)
. Parameters:
crs
 The new coordinate reference system, ornull
. Throws:
MismatchedDimensionException
 if the specified CRS doesn't have the expected number of dimensions.

normalize
public boolean normalize(boolean crsDomain)
Restricts this envelope to the CS or CRS domain of validity. This method performs two steps:
First, it ensures that the envelope is contained in the coordinate system domain. Out of range ordinates are validated in a way that depends on the range meaning:
 If EXACT (typically latitudes ordinates), values greater than the maximum value are replaced by the maximum, and values smaller than the minimum value are replaced by the minimum.
 If WRAPAROUND (typically longitudes
ordinates), a multiple of the range (e.g. 360° for longitudes) is added or
subtracted. If a value stay out of range after this correction, then the
ordinates are set to the full [ minimum ... maximum] range.
Example: [185° ... 190°] of longitude is equivalent to [175° ... 170°]. But [175° ... 185°] would be equivalent to [175° ... 175°], which is likely to mislead most users of
Bounds
since the lower bounds is numerically greater than the upper bounds. Reordering as [175° ... 175°] would interchange the meaning of what is "inside" and "outside" the envelope. So this implementation conservatively expands the range to [180° ... 180°] in order to ensure that the validated envelope fully contains the original envelope.

Second and only if
crsDomain
istrue
, the envelope normalized in the previous step is intersected with the CRS domain of validity, if any.
 Parameters:
crsDomain
true
if the envelope should be restricted to the CRS domain in addition of the CS domain. Returns:
true
if this envelope has been modified, orfalse
if no change was done. Since:
 2.5


getDimension
public final int getDimension()
Returns the number of dimensions. Specified by:
getDimension
in interfaceBounds
 Returns:
 The dimensionality of this envelope.

getLowerCorner
public Position getLowerCorner()
A coordinate position consisting of all the minimal ordinates for each dimension for all points within theEnvelope
. Specified by:
getLowerCorner
in interfaceBounds
 Overrides:
getLowerCorner
in classAbstractBounds
 Returns:
 The lower corner.

getUpperCorner
public Position getUpperCorner()
A coordinate position consisting of all the maximal ordinates for each dimension for all points within theEnvelope
. Specified by:
getUpperCorner
in interfaceBounds
 Overrides:
getUpperCorner
in classAbstractBounds
 Returns:
 The upper corner.

getMedian
public Position getMedian()
A coordinate position consisting of all the middle ordinates for each dimension for all points within theEnvelope
. Returns:
 The median coordinates.
 Since:
 2.5

getMinimum
public final double getMinimum(int dimension) throws IndexOutOfBoundsException
Returns the minimal ordinate along the specified dimension. Specified by:
getMinimum
in interfaceBounds
 Parameters:
dimension
 The dimension to query. Returns:
 The minimal ordinate value along the given dimension.
 Throws:
IndexOutOfBoundsException
 If the given index is out of bounds. See Also:
RectangularShape.getMinX()
,RectangularShape.getMinY()

getMaximum
public final double getMaximum(int dimension) throws IndexOutOfBoundsException
Returns the maximal ordinate along the specified dimension. Specified by:
getMaximum
in interfaceBounds
 Parameters:
dimension
 The dimension to query. Returns:
 The maximal ordinate value along the given dimension.
 Throws:
IndexOutOfBoundsException
 If the given index is out of bounds. See Also:
RectangularShape.getMaxX()
,RectangularShape.getMaxY()

getMedian
public final double getMedian(int dimension) throws IndexOutOfBoundsException
Returns the median ordinate along the specified dimension. The result should be equals (minus rounding error) to(getMaximum(dimension)  getMinimum(dimension)) / 2
.

getSpan
public final double getSpan(int dimension) throws IndexOutOfBoundsException
Returns the envelope span (typically width or height) along the specified dimension. The result should be equals (minus rounding error) togetMaximum(dimension)  getMinimum(dimension)
. Specified by:
getSpan
in interfaceBounds
 Parameters:
dimension
 The dimension to query. Returns:
 The difference along maximal and minimal ordinates in the given dimension.
 Throws:
IndexOutOfBoundsException
 If the given index is out of bounds. See Also:
RectangularShape.getWidth()
,RectangularShape.getHeight()

getSpan
public double getSpan(int dimension, Unit<?> unit) throws IndexOutOfBoundsException
Returns the envelope span along the specified dimension, in terms of the given units. Parameters:
dimension
 The dimension to query.unit
 The unit for the return value. Returns:
 The span in terms of the given unit.
 Throws:
IndexOutOfBoundsException
 If the given index is out of bounds.ConversionException
 if the length can't be converted to the specified units.IllegalArgumentException
 if the target units are not compatible with the units of the provideddimension
 Since:
 2.5

setRange
public void setRange(int dimension, double minimum, double maximum) throws IndexOutOfBoundsException
Sets the envelope's 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)
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: (x_{min}, y_{min}, z_{min}, x_{max}, y_{max}, z_{max})
 Parameters:
ordinates
 The new ordinate values. Since:
 2.5

setEnvelope
public void setEnvelope(GeneralBounds envelope) throws MismatchedDimensionException
Sets this envelope to the same coordinate values than the specified envelope. Parameters:
envelope
 The new envelope to copy coordinates from. Throws:
MismatchedDimensionException
 if the specified envelope doesn't have the expected number of dimensions. Since:
 2.2

setToInfinite
public void setToInfinite()
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()
Returnstrue
if at least one ordinate has an infinite value. Returns:
true
if this envelope has infinite value. Since:
 2.2

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

isNull
public boolean isNull()
Returnsfalse
if at least one ordinate value is not NaN. TheisNull()
check is a little bit different thanisEmpty()
since it returnsfalse
for a partially initialized envelope, whileisEmpty()
returnsfalse
only after all dimensions have been initialized. More specifically, the following rules apply: Returns:
true
if this envelope has NaN values. Since:
 2.2

isEmpty
public boolean isEmpty()
Determines whether or not this envelope is empty. An envelope is nonempty only if it has at least one dimension, and the length is greater than 0 along all dimensions. Note that a nonempty envelope is always non null, but the converse is not always true. Returns:
true
if this envelope is empty.

add
public void add(double x, double y) throws MismatchedDimensionException
Adds a position to this bounds. The resulting bounds is the smallest bounds that contains both the original bounds and the specified position. After adding a position, a call tocontains(org.geotools.api.geometry.Position)
with the added position as an argument will returntrue
, except if one of the position's ordinates wasDouble.NaN
(in which case the corresponding ordinate have been ignored).This method assumes that the specified position uses the same CRS than this envelope. For performance reason, it will not be verified unless J2SE assertions are enabled.
 Parameters:
x
 Position first ordinatey
 Position first ordinate Throws:
MismatchedDimensionException
 if the specified point doesn't have the expected dimension.

add
public void add(Position position) throws MismatchedDimensionException
Adds a position to this bounds. The resulting bounds is the smallest bounds that contains both the original bounds and the specified position. After adding a position, a call tocontains(org.geotools.api.geometry.Position)
with the added position as an argument will returntrue
, except if one of the position's ordinates wasDouble.NaN
(in which case the corresponding ordinate have been ignored).This method position that the specified position uses the same CRS than this envelope. For performance reason, it will not be verified unless J2SE assertions are enabled.
 Parameters:
position
 The point to add. Throws:
MismatchedDimensionException
 if the specified point doesn't have the expected dimension.

add
public void add(Bounds envelope) throws MismatchedDimensionException
Adds an envelope object to this envelope. The resulting envelope is the union of the twoEnvelope
objects.This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
 Parameters:
envelope
 theEnvelope
to add to this envelope. Throws:
MismatchedDimensionException
 if the specified envelope doesn't have the expected dimension.

contains
public boolean contains(Position position) throws MismatchedDimensionException
Tests if a specified coordinate is inside the boundary of this envelope.This method assumes that the specified point uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
 Parameters:
position
 The point to text. Returns:
true
if the specified coordinates are inside the boundary of this envelope;false
otherwise. Throws:
MismatchedDimensionException
 if the specified point doesn't have the expected dimension.

contains
public boolean contains(Bounds envelope, boolean edgesInclusive) throws MismatchedDimensionException
Returnstrue
if this envelope completly encloses the specified envelope. If one or more edges from the specified envelope coincide with an edge from this envelope, then this method returnstrue
only ifedgesInclusive
istrue
.This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
 Parameters:
envelope
 The envelope to test for inclusion.edgesInclusive
true
if this envelope edges are inclusive. Returns:
true
if this envelope completly encloses the specified one. Throws:
MismatchedDimensionException
 if the specified envelope doesn't have the expected dimension. Since:
 2.2
 See Also:
intersects(Bounds, boolean)
,#equals(Bounds, double)

intersects
public boolean intersects(Bounds envelope, boolean edgesInclusive) throws MismatchedDimensionException
Returnstrue
if this envelope intersects the specified envelope. If one or more edges from the specified envelope coincide with an edge from this envelope, then this method returnstrue
only ifedgesInclusive
istrue
.This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
 Parameters:
envelope
 The envelope to test for intersection.edgesInclusive
true
if this envelope edges are inclusive. Returns:
true
if this envelope intersects the specified one. Throws:
MismatchedDimensionException
 if the specified envelope doesn't have the expected dimension. Since:
 2.2
 See Also:
contains(Bounds, boolean)
,#equals(Bounds, double)

intersect
public void intersect(Bounds envelope) throws MismatchedDimensionException
Sets this envelope to the intersection if this envelope with the specified one.This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
 Parameters:
envelope
 theEnvelope
to intersect to this envelope. Throws:
MismatchedDimensionException
 if the specified envelope doesn't have the expected dimension.

getSubEnvelope
public GeneralBounds getSubEnvelope(int lower, int upper) throws IndexOutOfBoundsException
Returns a new envelope that encompass only some dimensions of this envelope. This method copy this envelope's ordinates into a new envelope, beginning at dimensionlower
and extending to dimensionupper1
. Thus the dimension of the subenvelope isupperlower
. Parameters:
lower
 The first dimension to copy, inclusive.upper
 The last dimension to copy, exclusive. Returns:
 The subenvelope.
 Throws:
IndexOutOfBoundsException
 if an index is out of bounds.

getReducedEnvelope
public GeneralBounds getReducedEnvelope(int lower, int upper) throws IndexOutOfBoundsException
Returns a new envelope with the same values than this envelope minus the specified range of dimensions. Parameters:
lower
 The first dimension to omit, inclusive.upper
 The last dimension to omit, exclusive. Returns:
 The subenvelope.
 Throws:
IndexOutOfBoundsException
 if an index is out of bounds.

toRectangle2D
public Rectangle2D toRectangle2D() throws IllegalStateException
Returns aRectangle2D
with the same bounds as thisEnvelope
. This is a convenience method for interoperability with Java2D. Returns:
 This envelope as a twpdimensional rectangle.
 Throws:
IllegalStateException
 if this envelope is not twodimensional.

hashCode
public int hashCode()
Returns a hash value for this envelope. Overrides:
hashCode
in classAbstractBounds

equals
public boolean equals(Object object)
Compares the specified object with this envelope for equality. Overrides:
equals
in classAbstractBounds
 Parameters:
object
 The object to compare with this envelope. Returns:
true
if the given object is equals to this envelope.

equals
public boolean equals(Bounds envelope, double eps, boolean epsIsRelative)
Compares to the specified envelope for equality up to the specified tolerance value. The tolerance valueeps
can be either relative to the envelope length along each dimension or can be an absolute value (as for example some ground resolution of a grid coverage).If
relativeToLength
is set totrue
, the actual tolerance value for a given dimension i iseps
×length
wherelength
is the maximum of this envelope length and the specified envelope length along dimension i.If
relativeToLength
is set tofalse
, the actual tolerance value for a given dimension i iseps
.Relative tolerance value (as opposed to absolute tolerance value) help to workaround the fact that tolerance value are CRS dependent. For example the tolerance value need to be smaller for geographic CRS than for UTM projections, because the former typically has a range of 180 to 180° while the later can have a range of thousands of meters.
This method assumes that the specified envelope uses the same CRS than this envelope. For performance reason, it will no be verified unless J2SE assertions are enabled.
 Parameters:
envelope
 The envelope to compare with.eps
 The tolerance value to use for numerical comparaisons.epsIsRelative
true
if the tolerance value should be relative to axis length, orfalse
if it is an absolute value. Returns:
true
if the given object is equals to this envelope up to the given tolerance value. Since:
 2.4
 See Also:
contains(Bounds, boolean)
,intersects(Bounds, boolean)

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

