Module org.apache.sis.metadata

Package org.apache.sis.metadata.iso.extent

Class DefaultGeographicBoundingBox

Object

AbstractMetadata

ModifiableMetadata

ISOMetadata

AbstractGeographicExtent

DefaultGeographicBoundingBox

All Implemented Interfaces:

Serializable, Emptiable, Lenient­Comparable, Identified­Object, Geographic­Bounding­Box, Geographic­Extent

public class DefaultGeographicBoundingBox
extends AbstractGeographicExtent
implements GeographicBoundingBox

Geographic position of the dataset. This is only an approximate so specifying the coordinate reference system is unnecessary. The CRS shall be geographic with Greenwich prime meridian, but the datum doesn't need to be WGS84.

The following properties are mandatory in a well-formed metadata according ISO 19115:

EX_Geographic­Bounding­Box ├─west­Bound­Longitude…… The western-most coordinate of the limit of the dataset extent. ├─east­Bound­Longitude…… The eastern-most coordinate of the limit of the dataset extent. ├─south­Bound­Latitude…… The southern-most coordinate of the limit of the dataset extent. └─north­Bound­Latitude…… The northern-most, coordinate of the limit of the dataset extent.

In addition to the standard properties, SIS provides the following methods:

• set­Bounds(double, double, double, double) for setting the extent from (λ,φ) values.
• set­Bounds(Envelope) for setting the extent from the given envelope.
• set­Bounds(Geographic­Bounding­Box) for setting the extent from another bounding box.
• add(Geographic­Bounding­Box) for expanding this extent to include another bounding box.
• intersect(Geographic­Bounding­Box) for the intersection between the two bounding boxes.

Validation and normalization

All constructors and setter methods in this class perform the following argument validation or normalization:

• If the south bound latitude is greater than the north bound latitude, then an exception is thrown.
• If any latitude is set to a value outside the [-90 … 90]° range, then that latitude will be clamped.
• If any longitude is set to a value outside the [-180 … 180]° range, then a multiple of 360° will be added or subtracted to that longitude in order to bring it back inside the range.

If the west bound longitude is greater than the east bound longitude, then the box spans the anti-meridian. See GeneralEnvelope for more information about crossing the anti-meridian.

Relationship with Envelope classes

The org.apache.sis.geometry package provides various Envelope classes serving a similar purpose. The main difference is that envelopes can be expressed in any Coordinate Reference System (for example using any map projection), may have any number of dimensions, axes may have any direction (some maps are south-oriented) and may use any units of measurement. By contrast, geographic bounding box are restricted to two-dimensional geographic CRS with latitude and longitude in decimal degrees, inside the [-90 … +90]° and [-180 … +180]° range respectively, increasing toward north and east respectively, and longitude measured from the international reference meridian (Greenwich on Earth). However, Geographic­Bounding­Box said nothing about the geodetic datum. Consequently, this bounding box should be used only as a convenient way to give an approximate description of a location. Users can assume a precision of about 0.01° for the latitude and longitude values in this class. If more precision is desired, an Envelope should be considered instead.

Limitations

• Instances of this class are not synchronized for multi-threading. Synchronization, if needed, is caller's responsibility.
• Serialized objects of this class are not guaranteed to be compatible with future Apache SIS releases. Serialization support is appropriate for short term storage or RMI between applications running the same version of Apache SIS. For long term storage, use XML instead.

Since:

0.3

See Also:

• General­Envelope
• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class ModifiableMetadata

Modifiable­Metadata.State

Field Summary

Fields inherited from class ISOMetadata

identifiers

Constructor Summary

Constructors

Constructor	Description
Default­Geographic­Bounding­Box()	Constructs an initially empty geographic bounding box.
Default­Geographic­Bounding­Box(double west­Bound­Longitude, double east­Bound­Longitude, double south­Bound­Latitude, double north­Bound­Latitude)	Creates a geographic bounding box initialized to the specified values.
Default­Geographic­Bounding­Box(Geographic­Bounding­Box object)	Constructs a new instance initialized with the values from the specified metadata object.

Method Summary

Modifier and Type	Method	Description
void	add(Geographic­Bounding­Box box)	Adds a geographic bounding box to this box.
static Default­Geographic­Bounding­Box	cast­Or­Copy(Geographic­Bounding­Box object)	Returns a SIS metadata implementation with the values of the given arbitrary implementation.
boolean	equals(Object object, Comparison­Mode mode)	Compares this geographic bounding box with the specified object for equality.
double	get­East­Bound­Longitude()	Returns the eastern-most coordinate of the limit of the dataset extent.
double	get­North­Bound­Latitude()	Returns the northern-most, coordinate of the limit of the dataset extent.
double	get­South­Bound­Latitude()	Returns the southern-most coordinate of the limit of the dataset extent.
double	get­West­Bound­Longitude()	Returns the western-most coordinate of the limit of the dataset extent.
void	intersect(Geographic­Bounding­Box box)	Sets this bounding box to the intersection of this box with the specified one.
boolean	is­Empty()	Returns true if this metadata is empty.
void	set­Bounds(double west­Bound­Longitude, double east­Bound­Longitude, double south­Bound­Latitude, double north­Bound­Latitude)	Sets the bounding box to the specified values.
void	set­Bounds(Envelope envelope)	Sets the bounding box to the specified envelope.
void	set­Bounds(Geographic­Bounding­Box box)	Sets the bounding box to the same values than the specified box.
void	set­East­Bound­Longitude(double new­Value)	Sets the eastern-most coordinate of the limit of the dataset extent.
void	set­North­Bound­Latitude(double new­Value)	Sets the northern-most, coordinate of the limit of the dataset extent.
void	set­South­Bound­Latitude(double new­Value)	Sets the southern-most coordinate of the limit of the dataset extent.
void	set­West­Bound­Longitude(double new­Value)	Sets the western-most coordinate of the limit of the dataset extent.

Methods inherited from class AbstractGeographicExtent

cast­Or­Copy, get­Inclusion, set­Inclusion

Methods inherited from class ISOMetadata

get­Identifier, get­Identifier­Map, get­Identifiers, get­Standard, set­Identifier, transition­To

Methods inherited from class ModifiableMetadata

check­Write­Permission, collection­Type, copy­Collection, copy­List, copy­Map, copy­Set, deep­Copy, non­Null­Collection, non­Null­List, non­Null­Map, non­Null­Set, singleton, state, write­Collection, write­List, write­Map, write­Set

Methods inherited from class AbstractMetadata

as­Map, as­Tree­Table, equals, get­Interface, hash­Code, prune, to­String

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Methods inherited from interface GeographicExtent

get­Inclusion

Constructor Details

DefaultGeographicBoundingBox

public DefaultGeographicBoundingBox()

Constructs an initially empty geographic bounding box. All longitude and latitude values are initialized to Double.Na­N.

DefaultGeographicBoundingBox

public DefaultGeographicBoundingBox(double westBoundLongitude,
 double eastBoundLongitude,
 double southBoundLatitude,
 double northBoundLatitude)
                             throws IllegalArgumentException

Creates a geographic bounding box initialized to the specified values. The inclusion property is set to true.

Caution: Arguments are expected in the same order than they appear in the ISO 19115 specification. This is different than the order commonly found in the Java2D world, which is rather (x_min, y_min, x_max, y_max).

Parameters:

west­Bound­Longitude - the minimal λ value.

east­Bound­Longitude - the maximal λ value.

south­Bound­Latitude - the minimal φ value.

north­Bound­Latitude - the maximal φ value.

Throws:

Illegal­Argument­Exception - if (south bound > north bound). Note that NaN values are allowed.

See Also:

• set­Bounds(double, double, double, double)

DefaultGeographicBoundingBox

public DefaultGeographicBoundingBox(GeographicBoundingBox object)

Constructs a new instance initialized with the values from the specified metadata object. This is a shallow copy constructor, because the other metadata contained in the given object are not recursively copied.

Parameters:

object - the metadata to copy values from, or null if none.

See Also:

• cast­Or­Copy(Geographic­Bounding­Box)
• set­Bounds(Geographic­Bounding­Box)

Method Details

castOrCopy

public static DefaultGeographicBoundingBox castOrCopy(GeographicBoundingBox object)

Returns a SIS metadata implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:

• If the given object is null, then this method returns null.
• Otherwise if the given object is already an instance of Default­Geographic­Bounding­Box, then it is returned unchanged.
• Otherwise a new Default­Geographic­Bounding­Box instance is created using the copy constructor and returned. Note that this is a shallow copy operation, because the other metadata contained in the given object are not recursively copied.

Parameters:

object - the object to get as a SIS implementation, or null if none.

Returns:

a SIS implementation containing the values of the given object (may be the given object itself), or null if the argument was null.

getWestBoundLongitude

@ValueRange(minimum=-180.0,
            maximum=180.0)
public double getWestBoundLongitude()

Returns the western-most coordinate of the limit of the dataset extent. The value is expressed in longitude in decimal degrees (positive east).

Note that the returned value is greater than the east bound longitude if this box is crossing the anti-meridian.

Specified by:

get­West­Bound­Longitude in interface Geographic­Bounding­Box

Returns:

the western-most longitude between -180° and +180° inclusive, or NaN if undefined.

setWestBoundLongitude

public void setWestBoundLongitude(double newValue)

Sets the western-most coordinate of the limit of the dataset extent. The value is expressed in longitude in decimal degrees (positive east). Values outside the [-180 … 180]° range are normalized.

Parameters:

new­Value - the western-most longitude between -180° and +180° inclusive, or NaN to undefine.

getEastBoundLongitude

@ValueRange(minimum=-180.0,
            maximum=180.0)
public double getEastBoundLongitude()

Returns the eastern-most coordinate of the limit of the dataset extent. The value is expressed in longitude in decimal degrees (positive east).

Note that the returned value is smaller than the west bound longitude if this box is crossing the anti-meridian.

Specified by:

get­East­Bound­Longitude in interface Geographic­Bounding­Box

Returns:

the eastern-most longitude between -180° and +180° inclusive, or NaN if undefined.

setEastBoundLongitude

public void setEastBoundLongitude(double newValue)

Sets the eastern-most coordinate of the limit of the dataset extent. The value is expressed in longitude in decimal degrees (positive east). Values outside the [-180 … 180]° range are normalized.

Parameters:

new­Value - the eastern-most longitude between -180° and +180° inclusive, or NaN to undefine.

getSouthBoundLatitude

@ValueRange(minimum=-90.0,
            maximum=90.0)
public double getSouthBoundLatitude()

Returns the southern-most coordinate of the limit of the dataset extent. The value is expressed in latitude in decimal degrees (positive north).

Specified by:

get­South­Bound­Latitude in interface Geographic­Bounding­Box

Returns:

the southern-most latitude between -90° and +90° inclusive, or NaN if undefined.

setSouthBoundLatitude

public void setSouthBoundLatitude(double newValue)

Sets the southern-most coordinate of the limit of the dataset extent. The value is expressed in latitude in decimal degrees (positive north). Values outside the [-90 … 90]° range are clamped. If the result is greater than the north bound latitude, then the north bound is set to Double.Na­N.

Parameters:

new­Value - the southern-most latitude between -90° and +90° inclusive, or NaN to undefine.

getNorthBoundLatitude

@ValueRange(minimum=-90.0,
            maximum=90.0)
public double getNorthBoundLatitude()

Returns the northern-most, coordinate of the limit of the dataset extent. The value is expressed in latitude in decimal degrees (positive north).

Specified by:

get­North­Bound­Latitude in interface Geographic­Bounding­Box

Returns:

the northern-most latitude between -90° and +90° inclusive, or NaN if undefined.

setNorthBoundLatitude

public void setNorthBoundLatitude(double newValue)

Sets the northern-most, coordinate of the limit of the dataset extent. The value is expressed in latitude in decimal degrees (positive north). Values outside the [-90 … 90]° range are clamped. If the result is smaller than the south bound latitude, then the south bound is set to Double.Na­N.

Parameters:

new­Value - the northern-most latitude between -90° and +90° inclusive, or NaN to undefine.

setBounds

public void setBounds(double westBoundLongitude,
 double eastBoundLongitude,
 double southBoundLatitude,
 double northBoundLatitude)
               throws IllegalArgumentException

Sets the bounding box to the specified values. The inclusion property is left unchanged.

Caution: Arguments are expected in the same order than they appear in the ISO 19115 specification. This is different than the order commonly found in the Java2D world, which is rather (x_min, y_min, x_max, y_max).

Parameters:

west­Bound­Longitude - the minimal λ value.

east­Bound­Longitude - the maximal λ value.

south­Bound­Latitude - the minimal φ value.

north­Bound­Latitude - the maximal φ value.

Throws:

Illegal­Argument­Exception - if (south bound > north bound). Note that NaN values are allowed.

setBounds

public void setBounds(Envelope envelope)
               throws TransformException

Sets the bounding box to the specified envelope. If the envelope contains a CRS, then the bounding box may be projected to a geographic CRS. Otherwise, the envelope is assumed already in appropriate CRS.

When coordinate transformation is required, the target geographic CRS is not necessarily WGS84. This method preserves the same ellipsoid than in the envelope CRS when possible. This is because geographic bounding box are only approximated and the ISO specification does not mandates a particular CRS, so we avoid transformations that are not strictly necessary.

Note: this method is available only if the referencing module is on the module path.

Parameters:

envelope - the envelope to use for setting this geographic bounding box.

Throws:

Unsupported­Operation­Exception - if the referencing module is not on the module path.

Transform­Exception - if the envelope cannot be transformed to a geographic extent.

See Also:

• Default­Extent.add­Elements(Envelope)
• Default­Vertical­Extent.set­Bounds(Envelope)
• Default­Temporal­Extent.set­Bounds(Envelope)

setBounds

public void setBounds(GeographicBoundingBox box)

Sets the bounding box to the same values than the specified box.

Parameters:

box - the geographic bounding box to use for setting the values of this box.

add

public void add(GeographicBoundingBox box)

Adds a geographic bounding box to this box. This method behavior depends on whether the bounding boxes encompass an area covered by the data (inclusion) or an area where data is not present (exclusion):

• If the inclusion status is the same for this box and the box to be added, then the resulting bounding box is the union of the two boxes.
• If the inclusion/exclusion status are opposite, then this method attempts to exclude some area of the specified box from this box. The resulting bounding box is smaller if the exclusion can be performed without ambiguity.

In both cases, if either this box or the specified box has NaN bounds, then the corresponding bounds of the result will bet set to NaN.

Comparison with other API

This class is stricter about NaN values than other classes like General­Envelope. The reason is that computations on Geographic­Bounding­Box instances are rare (Envelope instances are preferred for this purpose). Usually, Geographic­Bounding­Box values come directly from some metadata structure. Consequently, NaN values in Geographic­Bounding­Box means "information is unknown" more often than "not yet calculated".

Parameters:

box - the geographic bounding box to add to this box.

See Also:

• General­Envelope.add(Envelope)

intersect

public void intersect(GeographicBoundingBox box)
               throws IllegalArgumentException

Sets this bounding box to the intersection of this box with the specified one. The inclusion status must be the same for both boxes.

If there is no intersection between the two bounding boxes, then this method sets both longitudes and/or both latitudes to NaN. If either this box or the specified box has NaN bounds, then the corresponding bounds of the intersection result will bet set to NaN.

Parameters:

box - the geographic bounding box to intersect with this box.

Throws:

Illegal­Argument­Exception - if the inclusion status is not the same for both boxes.

See Also:

• Extents.intersection(Geographic­Bounding­Box, Geographic­Bounding­Box)
• General­Envelope.intersect(Envelope)

isEmpty

public boolean isEmpty()

Returns true if this metadata is empty. This metadata is considered empty if every bound values are NaN. Note that this is different than the Java2D or envelope definition of "emptiness", since we don't test if the area is greater than zero - this method is a metadata test, not a geometric test.

Specified by:

is­Empty in interface Emptiable

Overrides:

is­Empty in class Abstract­Metadata

Returns:

true if this metadata does not define any bound value.

See Also:

• Abstract­Envelope.is­All­Na­N()

equals

public boolean equals(Object object,
 ComparisonMode mode)

Compares this geographic bounding box with the specified object for equality.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Abstract­Metadata

Parameters:

object - the object to compare for equality.

mode - the strictness level of the comparison.

Returns:

true if the given object is equal to this box.

See Also:

• Utilities.deep­Equals(Object, Object, Comparison­Mode)