Class DatumOrEnsemble

Object

Static

DatumOrEnsemble

public final class DatumOrEnsemble
extends Static

Utility methods for working on objects that may be Datum or Datum­Ensemble. The methods in this class view an ensemble as if it was a datum for the sake of simplicity. For example, Datum­Or­Ensemble.of(crs) allows to compare the datum name without the need to check which one of the get­Datum() or get­Datum­Ensemble() methods returns a non-null value.

Since:

1.5

Method Summary

Modifier and Type	Method	Description
static Engineering­Datum	as­Datum(Engineering­CRS crs)	Returns the datum (preferred) or ensemble (fallback) of the given engineering CRS.
static Geodetic­Datum	as­Datum(Geodetic­CRS crs)	Returns the datum (preferred) or ensemble (fallback) of the given geodetic CRS.
static Temporal­Datum	as­Datum(Temporal­CRS crs)	Returns the datum (preferred) or ensemble (fallback) of the given temporal CRS.
static Vertical­Datum	as­Datum(Vertical­CRS crs)	Returns the datum (preferred) or ensemble (fallback) of the given vertical CRS.
static Optional<Default­Datum­Ensemble<Engineering­Datum>>	as­Ensemble(Engineering­Datum datum)	If the given object is a pseudo-datum for a engineering ensemble, returns that ensemble.
static Optional<Default­Datum­Ensemble<Geodetic­Datum>>	as­Ensemble(Geodetic­Datum datum)	If the given object is a pseudo-datum for a geodetic ensemble, returns that ensemble.
static Optional<Default­Datum­Ensemble<Temporal­Datum>>	as­Ensemble(Temporal­Datum datum)	If the given object is a pseudo-datum for a temporal ensemble, returns that ensemble.
static Optional<Default­Datum­Ensemble<Vertical­Datum>>	as­Ensemble(Vertical­Datum datum)	If the given object is a pseudo-datum for a vertical ensemble, returns that ensemble.
static Optional<Engineering­Datum>	as­Target­Datum(Engineering­CRS source, Engineering­CRS target)	Returns the datum or pseudo-datum of the result of an operation between the given engineering CRSs.
static Optional<Geodetic­Datum>	as­Target­Datum(Geodetic­CRS source, Geodetic­CRS target)	Returns the datum or pseudo-datum of the result of an operation between the given geodetic CRSs.
static Optional<Temporal­Datum>	as­Target­Datum(Temporal­CRS source, Temporal­CRS target)	Returns the datum or pseudo-datum of the result of an operation between the given temporal CRSs.
static Optional<Vertical­Datum>	as­Target­Datum(Vertical­CRS source, Vertical­CRS target)	Returns the datum or pseudo-datum of the result of an operation between the given vertical CRSs.
static Optional<Positional­Accuracy>	get­Accuracy(Identified­Object object)	If the given object is a datum ensemble or a CRS associated to a datum ensemble, returns its accuracy.
static Optional<Ellipsoid>	get­Ellipsoid(Coordinate­Reference­System crs)	Returns the ellipsoid used by the given coordinate reference system.
static Optional<Prime­Meridian>	get­Prime­Meridian(Coordinate­Reference­System crs)	Returns the prime meridian used by the given coordinate reference system.
static boolean	is­Legacy­Datum(Default­Datum­Ensemble<?> ensemble, Datum datum, Comparison­Mode mode)	Returns whether a legacy definition of a datum may be considered as equivalent to the given datum ensemble.
static Identified­Object	of(Single­CRS crs)	Returns the datum of the given CRS if presents, or the datum ensemble otherwise.
static Optional<Identified­Object>	of­Target(Single­CRS source, Single­CRS target)	Returns the datum or ensemble of a coordinate operation from source to target.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Method Details

of

public static IdentifiedObject of(SingleCRS crs)

Returns the datum of the given CRS if presents, or the datum ensemble otherwise. This is an alternative to the as­Datum(…) methods when the caller does not need to view the returned object as a datum.

Parameters:

crs - the CRS from which to get the datum or ensemble, or null.

Returns:

the datum if present, or the datum ensemble otherwise, or null.

ofTarget

public static Optional<IdentifiedObject> ofTarget(SingleCRS source,
 SingleCRS target)

Returns the datum or ensemble of a coordinate operation from source to target. If the two given coordinate reference systems are associated to equal datum (ignoring metadata), then this method returns the target datum. Otherwise, this method returns the largest ensemble which fully contains the datum or datum ensemble of the other CRS. That largest common ensemble is interpreted as the new target of the operation result. If none of the source or target datum ensembles met the above criteria, then this method returns an empty value. A non-empty value means that it is okay, for low accuracy requirements, to ignore the datum shift.

This is an alternative to the as­Target­Datum(…) methods when the caller does not need to view the returned object as a datum.

Parameters:

source - the source CRS of a coordinate operation.

target - the target CRS of a coordinate operation.

Returns:

datum or datum ensemble of the coordinate operation result if it is okay to ignore datum shift.

Throws:

Null­Pointer­Exception - if any argument is null.

asDatum

public static GeodeticDatum asDatum(GeodeticCRS crs)

Returns the datum (preferred) or ensemble (fallback) of the given geodetic CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.

Common properties

If an ensemble is viewed as a pseudo-datum, then the implementation of the Geodetic­Datum.get­Ellipsoid() and Geodetic­Datum.get­Prime­Meridian() methods will verify that all members have the same ellipsoid or prime meridian respectively. If this condition does not hold, then a Geodetic­Exception will be thrown. Note that this verification is done when the above-cited methods are invoked, not when this as­Datum(…) method is invoked.

Parameters:

crs - the coordinate reference system for which to get the datum or datum ensemble, or null.

Returns:

the datum or pseudo-datum of the given CRS, or null.

asDatum

public static VerticalDatum asDatum(VerticalCRS crs)

Returns the datum (preferred) or ensemble (fallback) of the given vertical CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.

Parameters:

crs - the coordinate reference system for which to get the datum or datum ensemble, or null.

Returns:

the datum or pseudo-datum of the given CRS, or null.

asDatum

public static TemporalDatum asDatum(TemporalCRS crs)

Returns the datum (preferred) or ensemble (fallback) of the given temporal CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.

Common property

If an ensemble is viewed as a pseudo-datum, then the implementation of the Temporal­Datum.get­Origin() method will verify that all members have the same origin. If this condition does not hold, then a Geodetic­Exception will be thrown. Note that this verification is done when the above-cited method is invoked, not when this as­Datum(…) method is invoked.

Parameters:

crs - the coordinate reference system for which to get the datum or datum ensemble, or null.

Returns:

the datum or pseudo-datum of the given CRS, or null.

asDatum

public static EngineeringDatum asDatum(EngineeringCRS crs)

Returns the datum (preferred) or ensemble (fallback) of the given engineering CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.

Parameters:

crs - the coordinate reference system for which to get the datum or datum ensemble, or null.

Returns:

the datum or pseudo-datum of the given CRS, or null.

asTargetDatum

public static Optional<GeodeticDatum> asTargetDatum(GeodeticCRS source,
 GeodeticCRS target)

Returns the datum or pseudo-datum of the result of an operation between the given geodetic CRSs. If the two given coordinate reference systems are associated to equal (ignoring metadata) datum, then this method returns the target datum. Otherwise, this method returns a pseudo-datum for the largest ensemble which fully contains the datum or datum ensemble of the other CRS. That largest common ensemble is interpreted as the new target of the operation result. If none of the source or target datum ensembles met the above criteria, then this method returns an empty value. A non-empty value means that it is okay, for low accuracy requirements, to ignore the datum shift.

Parameters:

source - the source CRS of a coordinate operation.

target - the target CRS of a coordinate operation.

Returns:

datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.

Throws:

Null­Pointer­Exception - if any argument is null.

asTargetDatum

public static Optional<VerticalDatum> asTargetDatum(VerticalCRS source,
 VerticalCRS target)

Returns the datum or pseudo-datum of the result of an operation between the given vertical CRSs. See as­Target­Datum(Geodetic­CRS, Geodetic­CRS) for more information.

Parameters:

source - the source CRS of a coordinate operation.

target - the target CRS of a coordinate operation.

Returns:

datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.

Throws:

Null­Pointer­Exception - if any argument is null.

asTargetDatum

public static Optional<TemporalDatum> asTargetDatum(TemporalCRS source,
 TemporalCRS target)

Returns the datum or pseudo-datum of the result of an operation between the given temporal CRSs. See as­Target­Datum(Geodetic­CRS, Geodetic­CRS) for more information.

Parameters:

source - the source CRS of a coordinate operation.

target - the target CRS of a coordinate operation.

Returns:

datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.

Throws:

Null­Pointer­Exception - if any argument is null.

asTargetDatum

public static Optional<EngineeringDatum> asTargetDatum(EngineeringCRS source,
 EngineeringCRS target)

Returns the datum or pseudo-datum of the result of an operation between the given engineering CRSs. See as­Target­Datum(Geodetic­CRS, Geodetic­CRS) for more information.

Parameters:

source - the source CRS of a coordinate operation.

target - the target CRS of a coordinate operation.

Returns:

datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.

Throws:

Null­Pointer­Exception - if any argument is null.

asEnsemble

public static Optional<DefaultDatumEnsemble<GeodeticDatum>> asEnsemble(GeodeticDatum datum)

If the given object is a pseudo-datum for a geodetic ensemble, returns that ensemble. This method is the converse of as­Datum(Geodetic­CRS) and recognizes only the pseudo-datum created by this class of by Default­Datum­Ensemble static methods.

Parameters:

datum - the object which may be a pseudo-datum for an ensemble, or null.

Returns:

the given object cast to a datum ensemble if the cast is valid.

asEnsemble

public static Optional<DefaultDatumEnsemble<VerticalDatum>> asEnsemble(VerticalDatum datum)

If the given object is a pseudo-datum for a vertical ensemble, returns that ensemble. This method is the converse of as­Datum(Vertical­CRS) and recognizes only the pseudo-datum created by this class of by Default­Datum­Ensemble static methods.

Parameters:

datum - the object which may be a pseudo-datum for an ensemble, or null.

Returns:

the given object cast to a datum ensemble if the cast is valid.

asEnsemble

public static Optional<DefaultDatumEnsemble<TemporalDatum>> asEnsemble(TemporalDatum datum)

If the given object is a pseudo-datum for a temporal ensemble, returns that ensemble. This method is the converse of as­Datum(Temporal­CRS) and recognizes only the pseudo-datum created by this class of by Default­Datum­Ensemble static methods.

Parameters:

datum - the object which may be a pseudo-datum for an ensemble, or null.

Returns:

the given object cast to a datum ensemble if the cast is valid.

asEnsemble

public static Optional<DefaultDatumEnsemble<EngineeringDatum>> asEnsemble(EngineeringDatum datum)

If the given object is a pseudo-datum for a engineering ensemble, returns that ensemble. This method is the converse of as­Datum(Engineering­CRS) and recognizes only the pseudo-datum created by this class of by Default­Datum­Ensemble static methods.

Parameters:

datum - the object which may be a pseudo-datum for an ensemble, or null.

Returns:

the given object cast to a datum ensemble if the cast is valid.

isLegacyDatum

public static boolean isLegacyDatum(DefaultDatumEnsemble<?> ensemble,
 Datum datum,
 ComparisonMode mode)

Returns whether a legacy definition of a datum may be considered as equivalent to the given datum ensemble. This is true if all reference frames (both the specified datum and the ensemble members) have the same properties (ellipsoid and prime meridians in the geodetic case), and the datum and datum ensemble either have a common identifier or an heuristic match of name.

This method does not verify if the given datum is a member of the given ensemble. If the datum was a member, then the two objects would not be conceptually equal. We would rather have one object clearly identified as more accurate than the other.

Use case

This method is for interoperability between the old and new definitions of WGS 1984 (EPSG:4326). Before ISO 19111:2019, the datum ensemble concept did not existed in the OGC/ISO standards and WGS 1984 was defined as a Datum. In recent standards, WGS 1984 is defined as a Datum­Ensemble, but the old definition is still encountered. For example, a CRS may have been parsed from a GML document, or from a WKT 1 string, or from a ISO 19162:2015 string, etc. This method can be used for detecting such situations. While WGS 1984 is the main use case, this method can be used for any datum in the same situation.

Parameters:

ensemble - the datum ensemble, or null.

datum - the datum, or null.

mode - the criterion for comparing ellipsoids and prime meridians.

Returns:

whether the two objects could be considered as equal if the concept of datum ensemble did not existed.

getEllipsoid

public static Optional<Ellipsoid> getEllipsoid(CoordinateReferenceSystem crs)

Returns the ellipsoid used by the given coordinate reference system. This method searches in the following locations:

• If the given CRS is an instance of Single­CRS and its datum is a Geodetic­Datum, then this method returns the datum ellipsoid.
• Otherwise, if the given CRS is an instance of Single­CRS, is associated to a Datum­Ensemble, and all members of the ensemble have equal (ignoring metadata) ellipsoid, then returns that ellipsoid.
• Otherwise, if the given CRS is an instance of Compound­CRS, then this method searches recursively in each component until a geodetic reference frame is found.
• Otherwise, this method returns an empty value.

This method may return an empty value if the ellipsoid is not equal (ignoring metadata) for all members of the ensemble.

Parameters:

crs - the coordinate reference system for which to get the ellipsoid.

Returns:

the ellipsoid, or an empty value if none or not equivalent for all members of the ensemble.

getPrimeMeridian

public static Optional<PrimeMeridian> getPrimeMeridian(CoordinateReferenceSystem crs)

Returns the prime meridian used by the given coordinate reference system. This method applies the same rules as get­Ellipsoid(Coordinate­Reference­System).

Parameters:

crs - the coordinate reference system for which to get the prime meridian.

Returns:

the prime meridian, or an empty value if none or not equivalent for all members of the ensemble.

See Also:

• CRS.get­Greenwich­Longitude(Geodetic­CRS)

getAccuracy

public static Optional<PositionalAccuracy> getAccuracy(IdentifiedObject object)

If the given object is a datum ensemble or a CRS associated to a datum ensemble, returns its accuracy.

Parameters:

object - the object from which to get the ensemble accuracy, or null.

Returns:

the datum ensemble accuracy if the given object is a datum ensemble.

Throws:

Null­Pointer­Exception - if the given object should provide an accuracy but didn't.

See Also:

• CRS.get­Linear­Accuracy(Coordinate­Operation)