Class DefaultGeographicBoundingBox
- All Implemented Interfaces:
Serializable
,Emptiable
,LenientComparable
,IdentifiedObject
,org.opengis.metadata.extent.GeographicBoundingBox
,org.opengis.metadata.extent.GeographicExtent
The following properties are mandatory in a well-formed metadata according ISO 19115:
EX_GeographicBoundingBox
├─westBoundLongitude……
The western-most coordinate of the limit of the dataset extent.
├─eastBoundLongitude……
The eastern-most coordinate of the limit of the dataset extent.
├─southBoundLatitude……
The southern-most coordinate of the limit of the dataset extent.
└─northBoundLatitude……
The northern-most, coordinate of the limit of the dataset extent.setBounds(double, double, double, double)
for setting the extent from (λ,φ) values.setBounds(Envelope)
for setting the extent from the given envelope.setBounds(GeographicBoundingBox)
for setting the extent from another bounding box.add(GeographicBoundingBox)
for expanding this extent to include another bounding box.intersect(GeographicBoundingBox)
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.
Relationship with Envelope classes
Theorg.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, GeographicBoundingBox
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
- Version:
- 1.0
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.sis.metadata.ModifiableMetadata
ModifiableMetadata.State
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate double
The eastern-most coordinate of the limit of the dataset extent.private double
The northern-most, coordinate of the limit of the dataset extent.private static final long
Serial number for inter-operability with different versions.private double
The southern-most coordinate of the limit of the dataset extent.private double
The western-most coordinate of the limit of the dataset extent.Fields inherited from class org.apache.sis.metadata.iso.ISOMetadata
identifiers
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs an initially empty geographic bounding box.DefaultGeographicBoundingBox
(double westBoundLongitude, double eastBoundLongitude, double southBoundLatitude, double northBoundLatitude) Creates a geographic bounding box initialized to the specified values.DefaultGeographicBoundingBox
(org.opengis.metadata.extent.GeographicBoundingBox object) Constructs a new instance initialized with the values from the specified metadata object. -
Method Summary
Modifier and TypeMethodDescriptionvoid
add
(org.opengis.metadata.extent.GeographicBoundingBox box) Adds a geographic bounding box to this box.static DefaultGeographicBoundingBox
castOrCopy
(org.opengis.metadata.extent.GeographicBoundingBox object) Returns a SIS metadata implementation with the values of the given arbitrary implementation.private int
denormalize
(double λmin, double λmax) Returns a code telling how to denormalize this box and/or the other box before to compute union or intersection.boolean
equals
(Object object, ComparisonMode mode) Compares this geographic bounding box with the specified object for equality.double
Returns the eastern-most coordinate of the limit of the dataset extent.(package private) static boolean
getInclusion
(Boolean value) Makes sure that the given inclusion is non-nil, then returns its value.double
Returns the northern-most, coordinate of the limit of the dataset extent.double
Returns the southern-most coordinate of the limit of the dataset extent.double
Returns the western-most coordinate of the limit of the dataset extent.void
intersect
(org.opengis.metadata.extent.GeographicBoundingBox box) Sets this bounding box to the intersection of this box with the specified one.boolean
isEmpty()
Returnstrue
if this metadata is empty.private Angle
Returns an arbitrary non-null value if this bounding box is non-empty.private void
Clamps the latitudes and normalizes the longitudes.void
setBounds
(double westBoundLongitude, double eastBoundLongitude, double southBoundLatitude, double northBoundLatitude) Sets the bounding box to the specified values.void
setBounds
(org.opengis.geometry.Envelope envelope) Sets the bounding box to the specified envelope.void
setBounds
(org.opengis.metadata.extent.GeographicBoundingBox box) Sets the bounding box to the same values than the specified box.void
setEastBoundLongitude
(double newValue) Sets the eastern-most coordinate of the limit of the dataset extent.void
setNorthBoundLatitude
(double newValue) Sets the northern-most, coordinate of the limit of the dataset extent.void
setSouthBoundLatitude
(double newValue) Sets the southern-most coordinate of the limit of the dataset extent.void
setWestBoundLongitude
(double newValue) Sets the western-most coordinate of the limit of the dataset extent.private static Angle
valueIfDefined
(double value, boolean latitude) Returns the given value if it defined, ornull
if NaN.private static void
verifyBounds
(double southBoundLatitude, double northBoundLatitude) Verifies that the given bounding box is valid.Methods inherited from class org.apache.sis.metadata.iso.extent.AbstractGeographicExtent
castOrCopy, getInclusion, setInclusion
Methods inherited from class org.apache.sis.metadata.iso.ISOMetadata
getIdentifier, getIdentifierMap, getIdentifiers, getStandard, setIdentifier, transitionTo
Methods inherited from class org.apache.sis.metadata.ModifiableMetadata
checkWritePermission, collectionType, copyCollection, copyList, copyMap, copySet, deepCopy, nonNullCollection, nonNullList, nonNullMap, nonNullSet, singleton, state, writeCollection, writeList, writeMap, writeSet
Methods inherited from class org.apache.sis.metadata.AbstractMetadata
asMap, asTreeTable, equals, getInterface, hashCode, prune, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.opengis.metadata.extent.GeographicExtent
getInclusion
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
westBoundLongitude
private double westBoundLongitudeThe western-most coordinate of the limit of the dataset extent. The value is expressed in longitude in decimal degrees (positive east). -
eastBoundLongitude
private double eastBoundLongitudeThe eastern-most coordinate of the limit of the dataset extent. The value is expressed in longitude in decimal degrees (positive east). -
southBoundLatitude
private double southBoundLatitudeThe southern-most coordinate of the limit of the dataset extent. The value is expressed in latitude in decimal degrees (positive north). -
northBoundLatitude
private double northBoundLatitudeThe northern-most, coordinate of the limit of the dataset extent. The value is expressed in latitude in decimal degrees (positive north).
-
-
Constructor Details
-
DefaultGeographicBoundingBox
public DefaultGeographicBoundingBox()Constructs an initially empty geographic bounding box. All longitude and latitude values are initialized toDouble.NaN
. -
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 totrue
.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 (xmin, ymin, xmax, ymax).
- Parameters:
westBoundLongitude
- the minimal λ value.eastBoundLongitude
- the maximal λ value.southBoundLatitude
- the minimal φ value.northBoundLatitude
- the maximal φ value.- Throws:
IllegalArgumentException
- if (south bound > north bound). Note that NaN values are allowed.- See Also:
-
DefaultGeographicBoundingBox
public DefaultGeographicBoundingBox(org.opengis.metadata.extent.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, ornull
if none.- See Also:
-
-
Method Details
-
castOrCopy
public static DefaultGeographicBoundingBox castOrCopy(org.opengis.metadata.extent.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 returnsnull
. - Otherwise if the given object is already an instance of
DefaultGeographicBoundingBox
, then it is returned unchanged. - Otherwise a new
DefaultGeographicBoundingBox
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, ornull
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.
- If the given object is
-
getInclusion
Makes sure that the given inclusion is non-nil, then returns its value. If the given inclusion isnull
, then the default value istrue
.- Parameters:
value
- theGeographicExtent.getInclusion()
value.- Returns:
- the given value as a primitive type.
- Throws:
InvalidMetadataException
- if the given value is nil.
-
valueIfDefined
Returns the given value if it defined, ornull
if NaN.- Parameters:
value
- the numeric value.latitude
-true
if latitude,false
if longitude.- Returns:
- the given value if it is non-NaN.
-
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:
getWestBoundLongitude
in interfaceorg.opengis.metadata.extent.GeographicBoundingBox
- 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:
newValue
- the western-most longitude between -180° and +180° inclusive, or NaN to undefine.
-
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:
getEastBoundLongitude
in interfaceorg.opengis.metadata.extent.GeographicBoundingBox
- 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:
newValue
- the eastern-most longitude between -180° and +180° inclusive, or NaN to undefine.
-
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:
getSouthBoundLatitude
in interfaceorg.opengis.metadata.extent.GeographicBoundingBox
- 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 toDouble.NaN
.- Parameters:
newValue
- the southern-most latitude between -90° and +90° inclusive, or NaN to undefine.
-
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:
getNorthBoundLatitude
in interfaceorg.opengis.metadata.extent.GeographicBoundingBox
- 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 toDouble.NaN
.- Parameters:
newValue
- the northern-most latitude between -90° and +90° inclusive, or NaN to undefine.
-
verifyBounds
private static void verifyBounds(double southBoundLatitude, double northBoundLatitude) throws IllegalArgumentException Verifies that the given bounding box is valid. This method verifies only the latitude values, because we allow the west bound longitude to be greater then east bound longitude (they are boxes crossing the anti-meridian).This method should be invoked before
normalize()
.- Throws:
IllegalArgumentException
- if (south bound > north bound). Note that NaN values are allowed.
-
normalize
private void normalize()Clamps the latitudes and normalizes the longitudes.- See Also:
-
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 (xmin, ymin, xmax, ymax).
- Parameters:
westBoundLongitude
- the minimal λ value.eastBoundLongitude
- the maximal λ value.southBoundLatitude
- the minimal φ value.northBoundLatitude
- the maximal φ value.- Throws:
IllegalArgumentException
- if (south bound > north bound). Note that NaN values are allowed.
-
setBounds
public void setBounds(org.opengis.geometry.Envelope envelope) throws org.opengis.referencing.operation.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 classpath.
- Parameters:
envelope
- the envelope to use for setting this geographic bounding box.- Throws:
UnsupportedOperationException
- if the referencing module is not on the classpath.org.opengis.referencing.operation.TransformException
- if the envelope cannot be transformed to a geographic extent.- See Also:
-
setBounds
public void setBounds(org.opengis.metadata.extent.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.
-
denormalize
private int denormalize(double λmin, double λmax) Returns a code telling how to denormalize this box and/or the other box before to compute union or intersection. This method may also modify thewestBoundLongitude
andeastBoundLongitude
. The codes are:- 0 : Do nothing - both boxes are normal.
- 3 : Do nothing - both boxes are crossing the anti-meridian.
- -1 : Caller will need to subtract 360° from
λmin
. - +1 : Caller will need to add 360° to
λmax
. - -2 : This method has subtracted 360° from
westBoundLongitude
. - +2 : This method has added 360° to
eastBoundLongitude
.
- See Also:
-
add
public void add(org.opengis.metadata.extent.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.
Rational: this class is stricter about NaN values than other classes likeGeneralEnvelope
. The reason is that computations onGeographicBoundingBox
instances are rare (Envelope
instances are preferred for this purpose). Usually,GeographicBoundingBox
values come directly from some metadata structure. Consequently, NaN values inGeographicBoundingBox
means "information is unknown" more often than "not yet calculated".- Parameters:
box
- the geographic bounding box to add to this box.- See Also:
-
intersect
public void intersect(org.opengis.metadata.extent.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:
IllegalArgumentException
- if the inclusion status is not the same for both boxes.- See Also:
-
isNonEmpty
Returns an arbitrary non-null value if this bounding box is non-empty. The return value can be given toModifiableMetadata.checkWritePermission(Object)
before to set the bounds of this geographic extent. -
isEmpty
public boolean isEmpty()Returnstrue
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:
isEmpty
in interfaceEmptiable
- Overrides:
isEmpty
in classAbstractMetadata
- Returns:
true
if this metadata does not define any bound value.- See Also:
-
equals
Compares this geographic bounding box with the specified object for equality.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classAbstractMetadata
- 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:
-