Class Extents

public final class Extents extends Static
Convenience static methods for extracting information fromExtent
objects. This class provides methods for: Fetching geographic, vertical or temporal components in a convenient form.
 Computing intersection of bounding boxes
 Computing area estimations.
 Since:
 0.3
 See Also:
Envelopes
Defined in the
sismetadata
module


Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static double
area(GeographicBoundingBox box)
Returns an estimation of the area (in square metres) of the given bounding box.static DirectPosition
centroid(GeographicBoundingBox bbox)
Returns the position at the median longitude and latitude values of the given bounding box.static Date
getDate(Extent extent, double location)
Returns an instant in the temporal elements of the given extent, ornull
if none.static GeographicBoundingBox
getGeographicBoundingBox(Extent extent)
Returns a single geographic bounding box from the specified extent.static Range<Date>
getTimeRange(Extent extent)
Returns the union of all time ranges found in the given extent, ornull
if none.static MeasurementRange<Double>
getVerticalRange(Extent extent)
Returns the union of chosen vertical ranges found in the given extent, ornull
if none.static Extent
intersection(Extent e1, Extent e2)
Returns the intersection of the given extents.static GeographicBoundingBox
intersection(GeographicBoundingBox b1, GeographicBoundingBox b2)
Returns the intersection of the given geographic bounding boxes.static TemporalExtent
intersection(TemporalExtent e1, TemporalExtent e2)
Returns the intersection of the given temporal extents.static VerticalExtent
intersection(VerticalExtent e1, VerticalExtent e2)
Returns the intersection of the given vertical extents.



Field Detail

WORLD
public static final Extent WORLD
A geographic extent ranging from 180°W to 180°E and 90°S to 90°N. This extent has no vertical and no temporal components.


Method Detail

getGeographicBoundingBox
public static GeographicBoundingBox getGeographicBoundingBox(Extent extent)
Returns a single geographic bounding box from the specified extent. This method tries to find the bounding box in the cheapest way before to fallback on more expansive computations: First, this method searches geographic elements that are instance of
GeographicBoundingBox
. If exactly one such instance is found, then this method returns that instance directly (no copy).
 If more than one instance is found, then this method computes and returns the union of all bounding boxes.
 If above step found no
GeographicBoundingBox
, then this method inspects geographic elements that are instance ofBoundingPolygon
, taking in account only the envelopes associated to a coordinate reference system of kindGeographicCRS
. If such envelopes are found, then this method computes and returns their union.  If above step found no polygon's envelope associated to a geographic CRS, then in last resort this method uses all polygon's envelopes regardless their coordinate reference system (provided that the CRS is not null), applying coordinate transformations if needed.
 If above step found no polygon's envelope, then this method returns
null
.
 Parameters:
extent
 the extent to convert to a geographic bounding box, ornull
. Returns:
 a geographic bounding box extracted from the given extent, or
null
if none.  See Also:
CRS.getDomainOfValidity(CoordinateReferenceSystem)
 First, this method searches geographic elements that are instance of

getVerticalRange
public static MeasurementRange<Double> getVerticalRange(Extent extent)
Returns the union of chosen vertical ranges found in the given extent, ornull
if none. This method gives preference to heights above the Mean Sea Level when possible. Depths have negative height values: if the axis direction is toward down, then this method reverses the sign of minimum and maximum values.MultioccurrencesIf the givenExtent
object contains more than one vertical extent, then this method performs a choice based on the vertical datum and the unit of measurement:Choice based on vertical datum
Only the extents associated (indirectly, through their CRS) to the same nonnullVerticalDatumType
will be taken in account. If all datum types are null, then this method conservatively uses only the first vertical extent. Otherwise the datum type used for filtering the vertical extents is:VerticalDatumType.GEOIDAL
orDEPTH
if at least one extent uses those datum types. For this method,DEPTH
is considered as equivalent toGEOIDAL
except for the axis direction. Otherwise, the first nonnull datum type found in iteration order.
Rational: like geographic bounding box, the vertical range is an approximated information; the range returned by this method does not carry any information about the vertical CRS and this method does not attempt to perform coordinate transformation. But this method is more useful if the returned ranges are close to a frequently used surface, like the Mean Sea Level. The same simplification is applied in theVerticalExtent
element of Well Known Text (WKT) format, which specifies that “Vertical extent is an approximate description of location; heights are relative to an unspecified mean sea level.”Choice based on units of measurement
If, after the choice based on the vertical datum described above, there is still more than one vertical extent to consider, then the next criterion checks for the units of measurement. If no range specify a unit of measurement, return the first range and ignore all others.
 Otherwise take the first range having a unit of measurement. Then:
 All other ranges having an incompatible unit of measurement will be ignored.
 All other ranges having a compatible unit of measurement will be converted to the unit of the first retained range, and their union will be computed.
Example: Heights or depths are often measured using some pressure units, for example hectopascals (hPa). AnExtent
could contain two vertical elements: one with the height measurements in hPa, and the other element with heights transformed to metres using an empirical formula. In such case this method will select the first vertical element on the assumption that it is the "main" one that the metadata producer intended to show. Next, this method will search for other vertical elements using pressure unit. In our example there is none, but if such elements were found, this method would compute their union.
 Parameters:
extent
 the extent to convert to a vertical measurement range, ornull
. Returns:
 a vertical measurement range created from the given extent, or
null
if none.  Since:
 0.4

getTimeRange
public static Range<Date> getTimeRange(Extent extent)
Returns the union of all time ranges found in the given extent, ornull
if none. Parameters:
extent
 the extent to convert to a time range, ornull
. Returns:
 a time range created from the given extent, or
null
if none.  Since:
 0.4

getDate
public static Date getDate(Extent extent, double location)
Returns an instant in the temporal elements of the given extent, ornull
if none. First, this method computes the union of all temporal elements. Then this method computes the linear interpolation between the start and end time as in the following pseudocode:
Special cases:return new Date(startTime + (endTime  startTime) * location);
 If
location
is 0, then this method returns the start time.  If
location
is 1, then this method returns the end time.  If
location
is 0.5, then this method returns the average of start time and end time.  If
location
is outside the [0 … 1] range, then the result will be outside the temporal extent.
 Parameters:
extent
 the extent from which to get an instant, ornull
.location
 0 for the start time, 1 for the end time, 0.5 for the average time, or the coefficient (usually in the [0 … 1] range) for interpolating an instant. Returns:
 an instant interpolated at the given location, or
null
if none.  Since:
 0.4
 If

centroid
public static DirectPosition centroid(GeographicBoundingBox bbox)
Returns the position at the median longitude and latitude values of the given bounding box. This method does not check the inclusion status. This method takes in account bounding boxes that cross the antimeridian. Parameters:
bbox
 the bounding box for which to get the median longitude and latitude values, ornull
. Returns:
 a median position of the given bounding box, or
null
if none.

area
public static double area(GeographicBoundingBox box)
Returns an estimation of the area (in square metres) of the given bounding box. SinceGeographicBoundingBox
provides only approximated information (for example it does not specify the datum), the value returned by this method is also approximated.The current implementation performs its computation on the GRS 1980 Authalic Sphere. However this may change in any future SIS version.
 Parameters:
box
 the geographic bounding box for which to compute the area, ornull
. Returns:
 an estimation of the area in the given bounding box (m²), or NaN if the given box was null.
 Since:
 0.4

intersection
public static GeographicBoundingBox intersection(GeographicBoundingBox b1, GeographicBoundingBox b2)
Returns the intersection of the given geographic bounding boxes. If any of the arguments isnull
, then this method returns the other argument (which may be null). Otherwise this method returns a box which is the intersection of the two given boxes.This method never modify the given boxes, but may return directly one of the given arguments if it already represents the intersection result.
 Parameters:
b1
 the first bounding box, ornull
.b2
 the second bounding box, ornull
. Returns:
 the intersection (may be any of the
b1
orb2
argument if unchanged), ornull
if the two given boxes are null.  Throws:
IllegalArgumentException
 if the inclusion status is not the same for both boxes. Since:
 0.4
 See Also:
DefaultGeographicBoundingBox.intersect(GeographicBoundingBox)

intersection
public static VerticalExtent intersection(VerticalExtent e1, VerticalExtent e2)
Returns the intersection of the given vertical extents. If any of the arguments isnull
, then this method returns the other argument (which may be null). Otherwise this method returns a vertical extent which is the intersection of the two given extents.This method never modify the given extents, but may return directly one of the given arguments if it already represents the intersection result.
Advantage and inconvenient of this methodThis method can not intersect extents defined with different datums because height transformations generally require the geodetic positions (latitudes and longitudes) of the heights to transform. For more general transformations, it is better to convert all extent components into a single envelope, then transform the envelope at once. On the other hand, thisintersect(…)
method preserves better theNilReason
(if any). Parameters:
e1
 the first extent, ornull
.e2
 the second extent, ornull
. Returns:
 the intersection (may be any of the
e1
ore2
argument if unchanged), ornull
if the two given extents are null.  Throws:
IllegalArgumentException
 if the two extents do not use the same datum, ignoring metadata. Since:
 0.8
 See Also:
DefaultVerticalExtent.intersect(VerticalExtent)

intersection
public static TemporalExtent intersection(TemporalExtent e1, TemporalExtent e2)
Returns the intersection of the given temporal extents. If any of the arguments isnull
, then this method returns the other argument (which may be null). Otherwise this method returns a temporal extent which is the intersection of the two given extents.This method never modify the given extents, but may return directly one of the given arguments if it already represents the intersection result.
 Parameters:
e1
 the first extent, ornull
.e2
 the second extent, ornull
. Returns:
 the intersection (may be any of the
e1
ore2
argument if unchanged), ornull
if the two given extents are null.  Throws:
UnsupportedOperationException
 if no implementation ofTemporalFactory
has been found on the classpath. Since:
 0.8
 See Also:
DefaultTemporalExtent.intersect(TemporalExtent)

intersection
public static Extent intersection(Extent e1, Extent e2)
Returns the intersection of the given extents. If any of the arguments isnull
, then this method returns the other argument (which may be null). Otherwise this method returns an extent which is the intersection of all geographic, vertical and temporal elements in the two given extents.This method never modify the given extents, but may return directly one of the given arguments if it already represents the intersection result.
 Parameters:
e1
 the first extent, ornull
.e2
 the second extent, ornull
. Returns:
 the intersection (may be any of the
e1
ore2
argument if unchanged), ornull
if the two given extents are null.  Throws:
IllegalArgumentException
 if two elements to intersect are not compatible (e.g. mismatched bounding box inclusion status or mismatched vertical datum).UnsupportedOperationException
 if aTemporalFactory
is required but no implementation has been found on the classpath. Since:
 0.8
 See Also:
DefaultExtent.intersect(Extent)

