datum namespace

namespace datum

Datum (the relationship of a coordinate system to the body).

osgeo.proj.datum namespace

Typedefs

typedef std::shared_ptr<Datum> DatumPtr

Shared pointer of Datum

typedef util::nn<DatumPtr> DatumNNPtr

Non-null shared pointer of Datum

typedef std::shared_ptr<DatumEnsemble> DatumEnsemblePtr

Shared pointer of DatumEnsemble

typedef util::nn<DatumEnsemblePtr> DatumEnsembleNNPtr

Non-null shared pointer of DatumEnsemble

typedef std::shared_ptr<PrimeMeridian> PrimeMeridianPtr

Shared pointer of PrimeMeridian

typedef util::nn<PrimeMeridianPtr> PrimeMeridianNNPtr

Non-null shared pointer of PrimeMeridian

typedef std::shared_ptr<Ellipsoid> EllipsoidPtr

Shared pointer of Ellipsoid

typedef util::nn<EllipsoidPtr> EllipsoidNNPtr

Non-null shared pointer of Ellipsoid

typedef std::shared_ptr<GeodeticReferenceFrame> GeodeticReferenceFramePtr

Shared pointer of GeodeticReferenceFrame

typedef util::nn<GeodeticReferenceFramePtr> GeodeticReferenceFrameNNPtr

Non-null shared pointer of GeodeticReferenceFrame

using DynamicGeodeticReferenceFramePtr = std::shared_ptr<DynamicGeodeticReferenceFrame>

Shared pointer of DynamicGeodeticReferenceFrame

using DynamicGeodeticReferenceFrameNNPtr = util::nn<DynamicGeodeticReferenceFramePtr>

Non-null shared pointer of DynamicGeodeticReferenceFrame

typedef std::shared_ptr<VerticalReferenceFrame> VerticalReferenceFramePtr

Shared pointer of VerticalReferenceFrame

typedef util::nn<VerticalReferenceFramePtr> VerticalReferenceFrameNNPtr

Non-null shared pointer of VerticalReferenceFrame

using DynamicVerticalReferenceFramePtr = std::shared_ptr<DynamicVerticalReferenceFrame>

Shared pointer of DynamicVerticalReferenceFrame

using DynamicVerticalReferenceFrameNNPtr = util::nn<DynamicVerticalReferenceFramePtr>

Non-null shared pointer of DynamicVerticalReferenceFrame

using TemporalDatumPtr = std::shared_ptr<TemporalDatum>

Shared pointer of TemporalDatum

using TemporalDatumNNPtr = util::nn<TemporalDatumPtr>

Non-null shared pointer of TemporalDatum

using EngineeringDatumPtr = std::shared_ptr<EngineeringDatum>

Shared pointer of EngineeringDatum

using EngineeringDatumNNPtr = util::nn<EngineeringDatumPtr>

Non-null shared pointer of EngineeringDatum

using ParametricDatumPtr = std::shared_ptr<ParametricDatum>

Shared pointer of ParametricDatum

using ParametricDatumNNPtr = util::nn<ParametricDatumPtr>

Non-null shared pointer of ParametricDatum

class Datum : public osgeo::proj::common::ObjectUsage, public osgeo::proj::io::IJSONExportable
#include <datum.hpp>

Abstract class of the relationship of a coordinate system to an object, thus creating a coordinate reference system.

For geodetic and vertical coordinate reference systems, it relates a coordinate system to the Earth (or the celestial body considered). With other types of coordinate reference systems, the datum may relate the coordinate system to another physical or virtual object. A datum uses a parameter or set of parameters that determine the location of the origin of the coordinate reference system. Each datum subtype can be associated with only specific types of coordinate reference systems.

Remark

Implements Datum from ISO 19111:2019

Subclassed by osgeo::proj::datum::EngineeringDatum, osgeo::proj::datum::GeodeticReferenceFrame, osgeo::proj::datum::ParametricDatum, osgeo::proj::datum::TemporalDatum, osgeo::proj::datum::VerticalReferenceFrame

Public Functions

const util::optional<std::string> &anchorDefinition() const

Return the anchor definition.

A description - possibly including coordinates of an identified point or points - of the relationship used to anchor a coordinate system to the Earth or alternate object.

  • For modern geodetic reference frames the anchor may be a set of station coordinates; if the reference frame is dynamic it will also include coordinate velocities. For a traditional geodetic datum, this anchor may be a point known as the fundamental point, which is traditionally the point where the relationship between geoid and ellipsoid is defined, together with a direction from that point.

  • For a vertical reference frame the anchor may be the zero level at one or more defined locations or a conventionally defined surface.

  • For an engineering datum, the anchor may be an identified physical point with the orientation defined relative to the object.

Returns:

the anchor definition, or empty.

const util::optional<common::Measure> &anchorEpoch() const

Return the anchor epoch.

Epoch at which a static reference frame matches a dynamic reference frame from which it has been derived.

Note: Not to be confused with the frame reference epoch of dynamic geodetic and dynamic vertical reference frames. Nor with the epoch at which a reference frame is defined to be aligned with another reference frame; this information should be included in the datum anchor definition.

Since

9.2

Returns:

the anchor epoch, or empty.

const util::optional<common::DateTime> &publicationDate() const

Return the date on which the datum definition was published.

Note

Departure from ISO 19111:2019 : we return a DateTime instead of a Citation::Date.

Returns:

the publication date, or empty.

const common::IdentifiedObjectPtr &conventionalRS() const

Return the conventional reference system.

This is the name, identifier, alias and remarks for the terrestrial reference system or vertical reference system realized by this reference frame, for example "ITRS" for ITRF88 through ITRF2008 and ITRF2014, or "EVRS" for EVRF2000 and EVRF2007.

Returns:

the conventional reference system, or nullptr.

class DatumEnsemble : public osgeo::proj::common::ObjectUsage, public osgeo::proj::io::IJSONExportable
#include <datum.hpp>

A collection of two or more geodetic or vertical reference frames (or if not geodetic or vertical reference frame, a collection of two or more datums) which for all but the highest accuracy requirements may be considered to be insignificantly different from each other.

Every frame within the datum ensemble must be a realizations of the same Terrestrial Reference System or Vertical Reference System.

Remark

Implements DatumEnsemble from ISO 19111:2019

Public Functions

const std::vector<DatumNNPtr> &datums() const

Return the set of datums which may be considered to be insignificantly different from each other.

Returns:

the set of datums of the DatumEnsemble.

const metadata::PositionalAccuracyNNPtr &positionalAccuracy() const

Return the inaccuracy introduced through use of this collection of datums.

It is an indication of the differences in coordinate values at all points between the various realizations that have been grouped into this datum ensemble.

Returns:

the accuracy.

Public Static Functions

static DatumEnsembleNNPtr create(const util::PropertyMap &properties, const std::vector<DatumNNPtr> &datumsIn, const metadata::PositionalAccuracyNNPtr &accuracy)

Instantiate a DatumEnsemble.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • datumsIn -- Array of at least 2 datums.

  • accuracy -- Accuracy of the datum ensemble

Throws:

util::Exception --

Returns:

new DatumEnsemble.

class PrimeMeridian : public osgeo::proj::common::IdentifiedObject, public osgeo::proj::io::IPROJStringExportable, public osgeo::proj::io::IJSONExportable
#include <datum.hpp>

The origin meridian from which longitude values are determined.

Remark

Implements PrimeMeridian from ISO 19111:2019

Note

The default value for prime meridian name is "Greenwich". When the default applies, the value for the longitude shall be 0 (degrees).

Public Functions

const common::Angle &longitude()

Return the longitude of the prime meridian.

It is measured from the internationally-recognised reference meridian ('Greenwich meridian'), positive eastward. The default value is 0 degrees.

Returns:

the longitude of the prime meridian.

Public Static Functions

static PrimeMeridianNNPtr create(const util::PropertyMap &properties, const common::Angle &longitudeIn)

Instantiate a PrimeMeridian.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • longitudeIn -- the longitude of the prime meridian.

Returns:

new PrimeMeridian.

Public Static Attributes

static const PrimeMeridianNNPtr GREENWICH

The Greenwich PrimeMeridian.

static const PrimeMeridianNNPtr REFERENCE_MERIDIAN

The "Reference Meridian" PrimeMeridian.

This is a meridian of longitude 0 to be used with non-Earth bodies.

static const PrimeMeridianNNPtr PARIS

The Paris PrimeMeridian.

class Ellipsoid : public osgeo::proj::common::IdentifiedObject, public osgeo::proj::io::IPROJStringExportable, public osgeo::proj::io::IJSONExportable
#include <datum.hpp>

A geometric figure that can be used to describe the approximate shape of an object.

For the Earth an oblate biaxial ellipsoid is used: in mathematical terms, it is a surface formed by the rotation of an ellipse about its minor axis.

Remark

Implements Ellipsoid from ISO 19111:2019

Public Functions

const common::Length &semiMajorAxis()

Return the length of the semi-major axis of the ellipsoid.

Returns:

the semi-major axis.

const util::optional<common::Scale> &inverseFlattening()

Return the inverse flattening value of the ellipsoid, if the ellipsoid has been defined with this value.

See also

computeInverseFlattening() that will always return a valid value of the inverse flattening, whether the ellipsoid has been defined through inverse flattening or semi-minor axis.

Returns:

the inverse flattening value of the ellipsoid, or empty.

const util::optional<common::Length> &semiMinorAxis()

Return the length of the semi-minor axis of the ellipsoid, if the ellipsoid has been defined with this value.

See also

computeSemiMinorAxis() that will always return a valid value of the semi-minor axis, whether the ellipsoid has been defined through inverse flattening or semi-minor axis.

Returns:

the semi-minor axis of the ellipsoid, or empty.

bool isSphere()

Return whether the ellipsoid is spherical.

That is to say is semiMajorAxis() == computeSemiMinorAxis().

A sphere is completely defined by the semi-major axis, which is the radius of the sphere.

Returns:

true if the ellipsoid is spherical.

const util::optional<common::Length> &semiMedianAxis()

Return the length of the semi-median axis of a triaxial ellipsoid.

This parameter is not required for a biaxial ellipsoid.

Returns:

the semi-median axis of the ellipsoid, or empty.

double computedInverseFlattening()

Return or compute the inverse flattening value of the ellipsoid.

If computed, the inverse flattening is the result of a / (a - b), where a is the semi-major axis and b the semi-minor axis.

Returns:

the inverse flattening value of the ellipsoid, or 0 for a sphere.

double squaredEccentricity()

Return the squared eccentricity of the ellipsoid.

Returns:

the squared eccentricity, or a negative value if invalid.

common::Length computeSemiMinorAxis() const

Return or compute the length of the semi-minor axis of the ellipsoid.

If computed, the semi-minor axis is the result of a * (1 - 1 / rf) where a is the semi-major axis and rf the reverse/inverse flattening.

Returns:

the semi-minor axis of the ellipsoid.

const std::string &celestialBody()

Return the name of the celestial body on which the ellipsoid refers to.

EllipsoidNNPtr identify() const

Return a Ellipsoid object where some parameters are better identified.

Returns:

a new Ellipsoid.

Public Static Functions

static EllipsoidNNPtr createSphere(const util::PropertyMap &properties, const common::Length &radius, const std::string &celestialBody = EARTH)

Instantiate a Ellipsoid as a sphere.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • radius -- the sphere radius (semi-major axis).

  • celestialBody -- Name of the celestial body on which the ellipsoid refers to.

Returns:

new Ellipsoid.

static EllipsoidNNPtr createFlattenedSphere(const util::PropertyMap &properties, const common::Length &semiMajorAxisIn, const common::Scale &invFlattening, const std::string &celestialBody = EARTH)

Instantiate a Ellipsoid from its inverse/reverse flattening.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • semiMajorAxisIn -- the semi-major axis.

  • invFlattening -- the inverse/reverse flattening. If set to 0, this will be considered as a sphere.

  • celestialBody -- Name of the celestial body on which the ellipsoid refers to.

Returns:

new Ellipsoid.

static EllipsoidNNPtr createTwoAxis(const util::PropertyMap &properties, const common::Length &semiMajorAxisIn, const common::Length &semiMinorAxisIn, const std::string &celestialBody = EARTH)

Instantiate a Ellipsoid from the value of its two semi axis.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • semiMajorAxisIn -- the semi-major axis.

  • semiMinorAxisIn -- the semi-minor axis.

  • celestialBody -- Name of the celestial body on which the ellipsoid refers to.

Returns:

new Ellipsoid.

Public Static Attributes

static const std::string EARTH

Earth celestial body.

static const EllipsoidNNPtr CLARKE_1866

The EPSG:7008 / "Clarke 1866" Ellipsoid.

static const EllipsoidNNPtr WGS84

The EPSG:7030 / "WGS 84" Ellipsoid.

static const EllipsoidNNPtr GRS1980

The EPSG:7019 / "GRS 1980" Ellipsoid.

class GeodeticReferenceFrame : public osgeo::proj::datum::Datum
#include <datum.hpp>

The definition of the position, scale and orientation of a geocentric Cartesian 3D coordinate system relative to the Earth.

It may also identify a defined ellipsoid (or sphere) that approximates the shape of the Earth and which is centred on and aligned to this geocentric coordinate system. Older geodetic datums define the location and orientation of a defined ellipsoid (or sphere) that approximates the shape of the earth.

Remark

Implements GeodeticReferenceFrame from ISO 19111:2019

Note

The terminology "Datum" is often used to mean a GeodeticReferenceFrame.

Note

In ISO 19111:2007, this class was called GeodeticDatum.

Subclassed by osgeo::proj::datum::DynamicGeodeticReferenceFrame

Public Functions

const PrimeMeridianNNPtr &primeMeridian()

Return the PrimeMeridian associated with a GeodeticReferenceFrame.

Returns:

the PrimeMeridian.

const EllipsoidNNPtr &ellipsoid()

Return the Ellipsoid associated with a GeodeticReferenceFrame.

Note

The ISO 19111:2019 modelling allows (but discourages) a GeodeticReferenceFrame to not be associated with a Ellipsoid in the case where it is used by a geocentric crs::GeodeticCRS. We have made the choice of making the ellipsoid specification compulsory.

Returns:

the Ellipsoid.

Public Static Functions

static GeodeticReferenceFrameNNPtr create(const util::PropertyMap &properties, const EllipsoidNNPtr &ellipsoid, const util::optional<std::string> &anchor, const PrimeMeridianNNPtr &primeMeridian)

Instantiate a GeodeticReferenceFrame.

Parameters:
Returns:

new GeodeticReferenceFrame.

static GeodeticReferenceFrameNNPtr create(const util::PropertyMap &properties, const EllipsoidNNPtr &ellipsoid, const util::optional<std::string> &anchor, const util::optional<common::Measure> &anchorEpoch, const PrimeMeridianNNPtr &primeMeridian)

Instantiate a GeodeticReferenceFrame.

Since

9.2

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • ellipsoid -- the Ellipsoid.

  • anchor -- the anchor definition, or empty.

  • anchorEpoch -- the anchor epoch, or empty.

  • primeMeridian -- the PrimeMeridian.

Returns:

new GeodeticReferenceFrame.

Public Static Attributes

static const GeodeticReferenceFrameNNPtr EPSG_6267

The EPSG:6267 / "North_American_Datum_1927" GeodeticReferenceFrame.

static const GeodeticReferenceFrameNNPtr EPSG_6269

The EPSG:6269 / "North_American_Datum_1983" GeodeticReferenceFrame.

static const GeodeticReferenceFrameNNPtr EPSG_6326

The EPSG:6326 / "WGS_1984" GeodeticReferenceFrame.

class DynamicGeodeticReferenceFrame : public osgeo::proj::datum::GeodeticReferenceFrame
#include <datum.hpp>

A geodetic reference frame in which some of the parameters describe time evolution of defining station coordinates.

For example defining station coordinates having linear velocities to account for crustal motion.

Public Functions

const common::Measure &frameReferenceEpoch() const

Return the epoch to which the coordinates of stations defining the dynamic geodetic reference frame are referenced.

Usually given as a decimal year e.g. 2016.47.

Returns:

the frame reference epoch.

const util::optional<std::string> &deformationModelName() const

Return the name of the deformation model.

Note

This is an extension to the ISO 19111:2019 modeling, to hold the content of the DYNAMIC.MODEL WKT2 node.

Returns:

the name of the deformation model.

Public Static Functions

static DynamicGeodeticReferenceFrameNNPtr create(const util::PropertyMap &properties, const EllipsoidNNPtr &ellipsoid, const util::optional<std::string> &anchor, const PrimeMeridianNNPtr &primeMeridian, const common::Measure &frameReferenceEpochIn, const util::optional<std::string> &deformationModelNameIn)

Instantiate a DynamicGeodeticReferenceFrame.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • ellipsoid -- the Ellipsoid.

  • anchor -- the anchor definition, or empty.

  • primeMeridian -- the PrimeMeridian.

  • frameReferenceEpochIn -- the frame reference epoch.

  • deformationModelNameIn -- deformation model name, or empty

Returns:

new DynamicGeodeticReferenceFrame.

class RealizationMethod : public osgeo::proj::util::CodeList
#include <datum.hpp>

The specification of the method by which the vertical reference frame is realized.

Remark

Implements RealizationMethod from ISO 19111:2019

Public Static Attributes

static const RealizationMethod LEVELLING

The realization is by adjustment of a levelling network fixed to one or more tide gauges.

static const RealizationMethod GEOID

The realization is through a geoid height model or a height correction model. This is applied to a specified geodetic CRS.

static const RealizationMethod TIDAL

The realization is through a tidal model or by tidal predictions.

class VerticalReferenceFrame : public osgeo::proj::datum::Datum
#include <datum.hpp>

A textual description and/or a set of parameters identifying a particular reference level surface used as a zero-height or zero-depth surface, including its position with respect to the Earth.

Remark

Implements VerticalReferenceFrame from ISO 19111:2019

Note

In ISO 19111:2007, this class was called VerticalDatum.

Subclassed by osgeo::proj::datum::DynamicVerticalReferenceFrame

Public Functions

const util::optional<RealizationMethod> &realizationMethod() const

Return the method through which this vertical reference frame is realized.

Returns:

the realization method.

Public Static Functions

static VerticalReferenceFrameNNPtr create(const util::PropertyMap &properties, const util::optional<std::string> &anchor = util::optional<std::string>(), const util::optional<RealizationMethod> &realizationMethodIn = util::optional<RealizationMethod>())

Instantiate a VerticalReferenceFrame.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • anchor -- the anchor definition, or empty.

  • realizationMethodIn -- the realization method, or empty.

Returns:

new VerticalReferenceFrame.

static VerticalReferenceFrameNNPtr create(const util::PropertyMap &properties, const util::optional<std::string> &anchor, const util::optional<common::Measure> &anchorEpoch, const util::optional<RealizationMethod> &realizationMethodIn = util::optional<RealizationMethod>())

Instantiate a VerticalReferenceFrame.

Since

9.2

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • anchor -- the anchor definition, or empty.

  • anchorEpoch -- the anchor epoch, or empty.

  • realizationMethodIn -- the realization method, or empty.

Returns:

new VerticalReferenceFrame.

class DynamicVerticalReferenceFrame : public osgeo::proj::datum::VerticalReferenceFrame
#include <datum.hpp>

A vertical reference frame in which some of the defining parameters have time dependency.

For example defining station heights have velocity to account for post-glacial isostatic rebound motion.

Public Functions

const common::Measure &frameReferenceEpoch() const

Return the epoch to which the coordinates of stations defining the dynamic geodetic reference frame are referenced.

Usually given as a decimal year e.g. 2016.47.

Returns:

the frame reference epoch.

const util::optional<std::string> &deformationModelName() const

Return the name of the deformation model.

Note

This is an extension to the ISO 19111:2019 modeling, to hold the content of the DYNAMIC.MODEL WKT2 node.

Returns:

the name of the deformation model.

Public Static Functions

static DynamicVerticalReferenceFrameNNPtr create(const util::PropertyMap &properties, const util::optional<std::string> &anchor, const util::optional<RealizationMethod> &realizationMethodIn, const common::Measure &frameReferenceEpochIn, const util::optional<std::string> &deformationModelNameIn)

Instantiate a DynamicVerticalReferenceFrame.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • anchor -- the anchor definition, or empty.

  • realizationMethodIn -- the realization method, or empty.

  • frameReferenceEpochIn -- the frame reference epoch.

  • deformationModelNameIn -- deformation model name, or empty

Returns:

new DynamicVerticalReferenceFrame.

class TemporalDatum : public osgeo::proj::datum::Datum
#include <datum.hpp>

The definition of the relationship of a temporal coordinate system to an object. The object is normally time on the Earth.

Remark

Implements TemporalDatum from ISO 19111:2019

Public Functions

const common::DateTime &temporalOrigin() const

Return the date and time to which temporal coordinates are referenced, expressed in conformance with ISO 8601.

Returns:

the temporal origin.

const std::string &calendar() const

Return the calendar to which the temporal origin is referenced.

Default value: TemporalDatum::CALENDAR_PROLEPTIC_GREGORIAN.

Returns:

the calendar.

Public Static Functions

static TemporalDatumNNPtr create(const util::PropertyMap &properties, const common::DateTime &temporalOriginIn, const std::string &calendarIn)

Instantiate a TemporalDatum.

Parameters:
Returns:

new TemporalDatum.

Public Static Attributes

static const std::string CALENDAR_PROLEPTIC_GREGORIAN

The proleptic Gregorian calendar.

class EngineeringDatum : public osgeo::proj::datum::Datum
#include <datum.hpp>

The definition of the origin and orientation of an engineering coordinate reference system.

Remark

Implements EngineeringDatum from ISO 19111:2019

Note

The origin can be fixed with respect to the Earth (such as a defined point at a construction site), or be a defined point on a moving vehicle (such as on a ship or satellite), or a defined point of an image.

Public Static Functions

static EngineeringDatumNNPtr create(const util::PropertyMap &properties, const util::optional<std::string> &anchor = util::optional<std::string>())

Instantiate a EngineeringDatum.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • anchor -- the anchor definition, or empty.

Returns:

new EngineeringDatum.

class ParametricDatum : public osgeo::proj::datum::Datum
#include <datum.hpp>

Textual description and/or a set of parameters identifying a particular reference surface used as the origin of a parametric coordinate system, including its position with respect to the Earth.

Remark

Implements ParametricDatum from ISO 19111:2019

Public Static Functions

static ParametricDatumNNPtr create(const util::PropertyMap &properties, const util::optional<std::string> &anchor = util::optional<std::string>())

Instantiate a ParametricDatum.

Parameters:
  • properties -- See General properties. At minimum the name should be defined.

  • anchor -- the anchor definition, or empty.

Returns:

new ParametricDatum.