Defines the location and orientation of an ellipsoid that approximates the shape of the earth. Geodetic datum are used together with ellipsoidal coordinate system, and also with Cartesian coordinate system centered in the ellipsoid (or sphere). {@section Bursa-Wolf parameters}One or many {@link BursaWolfParameters} can optionally be associated to each {@code DefaultGeodeticDatum} instance.This association is not part of the ISO 19111 model, but still a common practice (especially in older standards). Associating Bursa-Wolf parameters to geodetic datum is known as the
early-binding approach. A recommended alternative, discussed below, is the
late-binding approach.
There is different methods for transforming coordinates from one geodetic datum to an other datum, and Bursa-Wolf parameters are used with some of them. However different set of parameters may exist for the same pair of (source, target) datum, so it is often not sufficient to know those datum. The (source, target) pair of CRS are often necessary, sometime together with the geographic extent of the coordinates to transform.
Apache SIS searches for datum shift methods (including Bursa-Wolf parameters) in the EPSG database when a {@link org.opengis.referencing.operation.CoordinateOperation} or a{@link org.opengis.referencing.operation.MathTransform} is requested for a pair of CRS.This is known as the late-binding approach. If a datum shift method is found in the database, it will have precedence over any {@code BursaWolfParameters}instance associated to this {@code DefaultGeodeticDatum}. Only if no datum shift method is found in the database, then the {@code BursaWolfParameters} associated to the datum may be used as a fallback.
The Bursa-Wolf parameters association serves an other purpose: when a CRS is formatted in the older Well Known Text (WKT 1) format, the formatted string may contain a {@code TOWGS84[…]} elementwith the parameter values of the transformation to the WGS 84 datum. This element is provided as a help for other Geographic Information Systems that support only the early-binding approach. Apache SIS usually does not need the {@code TOWGS84} element, except as a fallback for datum thatdo not exist in the EPSG database.
{@section Creating new geodetic datum instances}New instances can be created either directly by specifying all information to a factory method (choices 3 and 4 below), or indirectly by specifying the identifier of an entry in a database (choices 1 and 2 below). Choice 1 in the following list is the easiest but most restrictive way to get a geodetic datum. The other choices provide more freedom.
- Create a {@code GeodeticDatum} from one of the static convenience shortcuts listed in{@link org.apache.sis.referencing.CommonCRS#datum()}.
- Create a {@code GeodeticDatum} from an identifier in a database by invoking{@link org.opengis.referencing.datum.DatumAuthorityFactory#createGeodeticDatum(String)}.
- Create a {@code GeodeticDatum} by invoking the {@code createGeodeticDatum(…)}method defined in the {@link org.opengis.referencing.datum.DatumFactory} interface.
- Create a {@code DefaultGeodeticDatum} by invoking the{@link #DefaultGeodeticDatum(Map,Ellipsoid,PrimeMeridian) constructor}.
Example: the following code gets a
World Geodetic System 1984 datum: {@preformat javaGeodeticDatum datum = CommonCRS.WGS84.datum();}{@section Immutability and thread safety}This class is immutable and thus thread-safe if the property
values (not necessarily the map itself), the {@link Ellipsoid} and the {@link PrimeMeridian} given to the constructor are also immutable. Unless otherwisenoted in the javadoc, this condition holds if all components were created using only SIS factories and static constants.
@author Martin Desruisseaux (IRD, Geomatys)
@since 0.4 (derived from geotk-1.2)
@version 0.4
@module
@see DefaultEllipsoid
@see DefaultPrimeMeridian
@see org.apache.sis.referencing.CommonCRS#datum()