io namespace

namespace io

I/O classes.

osgeo.proj.io namespace.

Typedefs

using DatabaseContextPtr = std::shared_ptr<DatabaseContext>

Shared pointer of DatabaseContext.

using DatabaseContextNNPtr = util::nn<DatabaseContextPtr>

Non-null shared pointer of DatabaseContext.

using WKTFormatterPtr = std::unique_ptr<WKTFormatter>

WKTFormatter unique pointer.

using WKTFormatterNNPtr = util::nn<WKTFormatterPtr>

Non-null WKTFormatter unique pointer.

using PROJStringFormatterPtr = std::unique_ptr<PROJStringFormatter>

PROJStringFormatter unique pointer.

using PROJStringFormatterNNPtr = util::nn<PROJStringFormatterPtr>

Non-null PROJStringFormatter unique pointer.

using IPROJStringExportablePtr = std::shared_ptr<IPROJStringExportable>

Shared pointer of IPROJStringExportable.

using IPROJStringExportableNNPtr = util::nn<IPROJStringExportablePtr>

Non-null shared pointer of IPROJStringExportable.

using WKTNodePtr = std::unique_ptr<WKTNode>

Unique pointer of WKTNode.

using WKTNodeNNPtr = util::nn<WKTNodePtr>

Non-null unique pointer of WKTNode.

using AuthorityFactoryPtr = std::shared_ptr<AuthorityFactory>

Shared pointer of AuthorityFactory.

using AuthorityFactoryNNPtr = util::nn<AuthorityFactoryPtr>

Non-null shared pointer of AuthorityFactory.

Functions

static crs::GeodeticCRSNNPtr cloneWithProps(const crs::GeodeticCRSNNPtr &geodCRS, const util::PropertyMap &props)
util::BaseObjectNNPtr createFromUserInput(const std::string &text, const DatabaseContextPtr &dbContext)

Instanciate a sub-class of BaseObject from a WKT string, PROJ string or database code (like “EPSG:4326”, “urn:ogc:def:crs:EPSG::4326”, “urn:ogc:def:coordinateOperation:EPSG::1671”).

Exceptions

class AuthorityFactory
#include <io.hpp>

Builds object from an authority database.

A AuthorityFactory should be used only by one thread at a time.

Remark
Implements AuthorityFactory from GeoAPI

Public Types

enum ObjectType

Object type.

Values:

PRIME_MERIDIAN

Object of type datum::PrimeMeridian

ELLIPSOID

Object of type datum::Ellipsoid

DATUM

Object of type datum::Datum (and derived classes)

GEODETIC_REFERENCE_FRAME

Object of type datum::GeodeticReferenceFrame (and derived classes)

VERTICAL_REFERENCE_FRAME

Object of type datum::VerticalReferenceFrame (and derived classes)

CRS

Object of type crs::CRS (and derived classes)

GEODETIC_CRS

Object of type crs::GeodeticCRS (and derived classes)

GEOGRAPHIC_CRS

Object of type crs::GeographicCRS (and derived classes)

PROJECTED_CRS

Object of type crs::ProjectedCRS (and derived classes)

VERTICAL_CRS

Object of type crs::VerticalCRS (and derived classes)

COMPOUND_CRS

Object of type crs::CompoundCRS (and derived classes)

COORDINATE_OPERATION

Object of type operation::CoordinateOperation (and derived classes)

CONVERSION

Object of type operation::Conversion (and derived classes)

TRANSFORMATION

Object of type operation::Transformation (and derived classes)

CONCATENATED_OPERATION

Object of type operation::ConcatenatedOperation (and derived classes)

Public Functions

util::BaseObjectNNPtr createObject(const std::string &code) const

Returns an arbitrary object from a code.

The returned object will typically be an instance of Datum, CoordinateSystem, ReferenceSystem or CoordinateOperation. If the type of the object is know at compile time, it is recommended to invoke the most precise method instead of this one (for example createCoordinateReferenceSystem(code) instead of createObject(code) if the caller know he is asking for a coordinate reference system).

If there are several objects with the same code, a FactoryException is thrown.

Return
object.
Parameters
  • code: Object code allocated by authority. (e.g. “4326”)
Exceptions

UnitOfMeasureNNPtr createUnitOfMeasure(const std::string &code) const

Returns a common::UnitOfMeasure from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

metadata::ExtentNNPtr createExtent(const std::string &code) const

Returns a metadata::Extent from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

datum::PrimeMeridianNNPtr createPrimeMeridian(const std::string &code) const

Returns a datum::PrimeMeridian from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

std::string identifyBodyFromSemiMajorAxis(double a, double tolerance) const

Identify a celestial body from an approximate radius.

Return
celestial body name if one single match found.
Parameters
  • semi_major_axis: Approximate semi-major axis.
  • tolerance: Relative error allowed.
Exceptions

datum::EllipsoidNNPtr createEllipsoid(const std::string &code) const

Returns a datum::Ellipsoid from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

datum::DatumNNPtr createDatum(const std::string &code) const

Returns a datum::Datum from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

datum::GeodeticReferenceFrameNNPtr createGeodeticDatum(const std::string &code) const

Returns a datum::GeodeticReferenceFrame from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

datum::VerticalReferenceFrameNNPtr createVerticalDatum(const std::string &code) const

Returns a datum::VerticalReferenceFrame from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

cs::CoordinateSystemNNPtr createCoordinateSystem(const std::string &code) const

Returns a cs::CoordinateSystem from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

crs::GeodeticCRSNNPtr createGeodeticCRS(const std::string &code) const

Returns a crs::GeodeticCRS from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

crs::GeographicCRSNNPtr createGeographicCRS(const std::string &code) const

Returns a crs::GeographicCRS from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

crs::VerticalCRSNNPtr createVerticalCRS(const std::string &code) const

Returns a crs::VerticalCRS from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

operation::ConversionNNPtr createConversion(const std::string &code) const

Returns a operation::Conversion from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

crs::ProjectedCRSNNPtr createProjectedCRS(const std::string &code) const

Returns a crs::ProjectedCRS from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

crs::CompoundCRSNNPtr createCompoundCRS(const std::string &code) const

Returns a crs::CompoundCRS from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

crs::CRSNNPtr createCoordinateReferenceSystem(const std::string &code) const

Returns a crs::CRS from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
Exceptions

operation::CoordinateOperationNNPtr createCoordinateOperation(const std::string &code, bool usePROJAlternativeGridNames) const

Returns a operation::CoordinateOperation from the specified code.

Return
object.
Parameters
  • code: Object code allocated by authority.
  • usePROJAlternativeGridNames: Whether PROJ alternative grid names should be substituted to the official grid names.
Exceptions

std::vector<operation::CoordinateOperationNNPtr> createFromCoordinateReferenceSystemCodes(const std::string &sourceCRSCode, const std::string &targetCRSCode) const

Returns a list operation::CoordinateOperation between two CRS.

The list is ordered with preferred operations first. No attempt is made at infering operations that are not explicitly in the database.

Deprecated operations are rejected.

Return
list of coordinate operations
Parameters
  • sourceCRSCode: Source CRS code allocated by authority.
  • targetCRSCode: Source CRS code allocated by authority.
Exceptions

const std::string &getAuthority()

Returns the authority name associated to this factory.

Return
name.

std::set<std::string> getAuthorityCodes(const ObjectType &type, bool allowDeprecated = true) const

Returns the set of authority codes of the given object type.

Return
the set of authority codes for spatial reference objects of the given type
Parameters
  • type: Object type.
  • allowDeprecated: whether we should return deprecated objects as well.
Exceptions

std::string getDescriptionText(const std::string &code) const

Gets a description of the object corresponding to a code.

Note
In case of several objects of different types with the same code, one of them will be arbitrarily selected.
Return
description.
Parameters
  • code: Object code allocated by authority. (e.g. “4326”)
Exceptions

DatabaseContextNNPtr databaseContext() const

Returns the database context.

std::vector<operation::CoordinateOperationNNPtr> createFromCoordinateReferenceSystemCodes(const std::string &sourceCRSAuthName, const std::string &sourceCRSCode, const std::string &targetCRSAuthName, const std::string &targetCRSCode, bool usePROJAlternativeGridNames, bool discardIfMissingGrid) const

Returns a list operation::CoordinateOperation between two CRS.

The list is ordered with preferred operations first. No attempt is made at infering operations that are not explicitly in the database (see createFromCRSCodesWithIntermediates() for that), and only source -> target operations are searched (ie if target -> source is present, you need to call this method with the arguments reversed, and apply the reverse transformations).

Deprecated operations are rejected.

If getAuthority() returns empty, then coordinate operations from all authorities are considered.

Return
list of coordinate operations
Parameters
  • sourceCRSAuthName: Authority name of sourceCRSCode
  • sourceCRSCode: Source CRS code allocated by authority sourceCRSAuthName.
  • targetCRSAuthName: Authority name of targetCRSCode
  • targetCRSCode: Source CRS code allocated by authority targetCRSAuthName.
  • usePROJAlternativeGridNames: Whether PROJ alternative grid names should be substituted to the official grid names.
  • discardIfMissingGrid: Whether coordinate operations that reference missing grids should be removed from the result set.
Exceptions

std::vector<operation::CoordinateOperationNNPtr> createFromCRSCodesWithIntermediates(const std::string &sourceCRSAuthName, const std::string &sourceCRSCode, const std::string &targetCRSAuthName, const std::string &targetCRSCode, bool usePROJAlternativeGridNames, bool discardIfMissingGrid, const std::vector<std::pair<std::string, std::string>> &intermediateCRSAuthCodes) const

Returns a list operation::CoordinateOperation between two CRS, using intermediate codes.

The list is ordered with preferred operations first.

Deprecated operations are rejected.

The method will take care of considering all potential combinations (ie contrary to createFromCoordinateReferenceSystemCodes(), you do not need to call it with sourceCRS and targetCRS switched)

If getAuthority() returns empty, then coordinate operations from all authorities are considered.

Return
list of coordinate operations
Parameters
  • sourceCRSAuthName: Authority name of sourceCRSCode
  • sourceCRSCode: Source CRS code allocated by authority sourceCRSAuthName.
  • targetCRSAuthName: Authority name of targetCRSCode
  • targetCRSCode: Source CRS code allocated by authority targetCRSAuthName.
  • usePROJAlternativeGridNames: Whether PROJ alternative grid names should be substituted to the official grid names.
  • discardIfMissingGrid: Whether coordinate operations that reference missing grids should be removed from the result set.
  • intermediateCRSAuthCodes: List of (auth_name, code) of CRS that can be used as potential intermediate CRS. If the list is empty, the database will be used to find common CRS in operations involving both the source and target CRS.
Exceptions

Public Static Functions

AuthorityFactoryNNPtr create(DatabaseContextNNPtr context, const std::string &authorityName)

Instanciate a AuthorityFactory.

The authority name might be set to the empty string in the particular case where createFromCoordinateReferenceSystemCodes(const std::string&,const std::string&,const std::string&,const std::string&) const is called.

Return
new AuthorityFactory.
Parameters
  • context: Contexte.
  • authorityName: Authority name.

class DatabaseContext
#include <io.hpp>

Database context.

A database context should be used only by one thread at a time.

Public Functions

const std::string &getPath() const

Return the path to the database.

std::set<std::string> getAuthorities() const

Return the list of authorities used in the database.

std::vector<std::string> getDatabaseStructure() const

Return the list of SQL commands (CREATE TABLE, CREATE TRIGGER, CREATE VIEW) needed to initialize a new database.

Public Static Functions

DatabaseContextNNPtr create()

Instanciate a database context, using the default proj.db file.

It will be searched in the directory pointed by the PROJ_LIB environment variable. If not found, on Unix builds, it will be then searched first in the pkgdatadir directory of the installation prefix.

This database context should be used only by one thread at a time.

Exceptions

DatabaseContextNNPtr create(const std::string &databasePath)

Instanciate a database context from a full filename.

This database context should be used only by one thread at a time.

Parameters
  • databasePath: Path and filename of the database. Might be empty string for the default rules to locate the default proj.db
Exceptions

DatabaseContextNNPtr create(const std::string &databasePath, const std::vector<std::string> &auxiliaryDatabasePaths)

Instanciate a database context from a full filename, and attach auxiliary databases to it.

This database context should be used only by one thread at a time.

Parameters
  • databasePath: Path and filename of the database. Might be empty string for the default rules to locate the default proj.db
  • auxiliaryDatabasePaths: Path and filename of auxiliary databases;
Exceptions

class FactoryException : public osgeo::proj::util::Exception
#include <io.hpp>

Exception thrown when a factory can’t create an instance of the requested object.

Subclassed by osgeo::proj::io::NoSuchAuthorityCodeException

class FormattingException : public osgeo::proj::util::Exception
#include <io.hpp>

Exception possibly thrown by IWKTExportable::exportToWKT() or IPROJStringExportable::exportToPROJString().

class IPROJStringExportable
#include <io.hpp>

Interface for an object that can be exported to a PROJ string.

Subclassed by osgeo::proj::crs::BoundCRS, osgeo::proj::crs::CompoundCRS, osgeo::proj::crs::DerivedProjectedCRS, osgeo::proj::crs::GeodeticCRS, osgeo::proj::crs::ProjectedCRS, osgeo::proj::crs::VerticalCRS, osgeo::proj::datum::Ellipsoid, osgeo::proj::datum::PrimeMeridian, osgeo::proj::operation::CoordinateOperation

Public Functions

std::string exportToPROJString(PROJStringFormatter *formatter) const

Builds a PROJ string representation.

  • For PROJStringFormatter::Convention::PROJ_5 (the default), return strings that generally express PROJ.5 pipelines.

    • For a crs::GeographicCRS, returns a string expressing the transformation from geographic coordinates expressed in radian with longitude, latitude order, and with respect to the international reference meridian, into geographic coordinates expressed in the units and axis order of the CRS, taking into account its prime meridian.
    • For a geocentric crs::GeodeticCRS, returns a string expressing the transformation from geographic coordinates expressed in radian with longitude, latitude order, and with respect to the international reference meridian, into geocentric coordinates.
    • For a crs::ProjectedCRS / crs::DerivedGeographicCRS / crs::DerivedProjectedCRS, returns a string expressing the transformation from the base CRS to the CRS
    • For a crs::BoundCRS, throws a FormattingException.
    • For operation::CoordinateTransformations, returns a PROJ pipeline.

  • For PROJStringFormatter::Convention::PROJ_4, format a string compatible with the OGRSpatialReference::exportToProj4() of GDAL <=2.3.

    • For a crs::GeographicCRS, returns a proj=longlat string, with ellipsoid / datum / prime meridian information, ignoring axis order and unit information.
    • For a geocentric crs::GeodeticCRS, returns the transformation from geographic coordinates into geocentric coordinates.
    • For a crs::ProjectedCRS, returns the projection method, ignoring axis order.
    • For a crs::BoundCRS, returns the PROJ string of its source/base CRS, amended with towgs84 / nadgrids parameter when the deriving conversion can be expressed in that way.

Return
a PROJ string.
Parameters
  • formatter: PROJ string formatter.
Exceptions

class IWKTExportable
#include <io.hpp>

Interface for an object that can be exported to WKT.

Subclassed by osgeo::proj::crs::CRS, osgeo::proj::cs::CoordinateSystem, osgeo::proj::cs::CoordinateSystemAxis, osgeo::proj::cs::Meridian, osgeo::proj::datum::DatumEnsemble, osgeo::proj::datum::Ellipsoid, osgeo::proj::datum::EngineeringDatum, osgeo::proj::datum::GeodeticReferenceFrame, osgeo::proj::datum::ParametricDatum, osgeo::proj::datum::PrimeMeridian, osgeo::proj::datum::TemporalDatum, osgeo::proj::datum::VerticalReferenceFrame, osgeo::proj::metadata::Identifier, osgeo::proj::operation::CoordinateOperation, osgeo::proj::operation::GeneralParameterValue, osgeo::proj::operation::OperationMethod, osgeo::proj::operation::ParameterValue

Public Functions

std::string exportToWKT(WKTFormatter *formatter) const

Builds a WKT representation. May throw a FormattingException

class NoSuchAuthorityCodeException : public osgeo::proj::io::FactoryException
#include <io.hpp>

Exception thrown when an authority factory can’t find the requested authority code.

Public Functions

const std::string &getAuthority() const

Returns authority name.

const std::string &getAuthorityCode() const

Returns authority code.

class ParsingException : public osgeo::proj::util::Exception
#include <io.hpp>

Exception possibly thrown by WKTNode::createFrom() or WKTParser::createFromWKT().

class PROJStringFormatter
#include <io.hpp>

Formatter to PROJ strings.

An instance of this class can only be used by a single thread at a time.

Public Types

enum Convention

PROJ variant.

Values:

PROJ_5

PROJ v5 (or later versions) string.

PROJ_4

PROJ v4 string as output by GDAL exportToProj4()

Public Functions

void setUseETMercForTMerc(bool flag)

Set whether Extented Transverse Mercator (etmerc) should be used instead of tmerc.

const std::string &toString() const

Returns the PROJ string.

Public Static Functions

PROJStringFormatterNNPtr create(Convention conventionIn = Convention::PROJ_5, DatabaseContextPtr dbContext = nullptr)

Constructs a new formatter.

A formatter can be used only once (its internal state is mutated)

Its default behaviour can be adjusted with the different setters.

Return
new formatter.
Parameters
  • conventionIn: PROJ string flavor. Defaults to Convention::PROJ_5
  • dbContext: Database context (can help to find alternative grid names). May be nullptr

class PROJStringParser
#include <io.hpp>

Parse a PROJ string into the appropriate suclass of util::BaseObject.

Public Functions

PROJStringParser &attachDatabaseContext(const DatabaseContextPtr &dbContext)

Attach a database context, to allow queries in it if needed.

std::vector<std::string> warningList() const

Return the list of warnings found during parsing.

BaseObjectNNPtr createFromPROJString(const std::string &projString)

Instanciate a sub-class of BaseObject from a PROJ string.

Exceptions

class WKTFormatter
#include <io.hpp>

Formatter to WKT strings.

An instance of this class can only be used by a single thread at a time.

Public Types

enum Convention

WKT variant.

Values:

WKT2

Full WKT2 string, conforming to ISO 19162:2015(E) / OGC 12-063r5, with all possible nodes and new keyword names.

WKT2_2015 = WKT2
WKT2_SIMPLIFIED

Same as WKT2 with the following exceptions:

  • UNIT keyword used.
  • ID node only on top element.
  • No ORDER element in AXIS element.
  • PRIMEM node omitted if it is Greenwich.
  • ELLIPSOID.UNIT node omitted if it is UnitOfMeasure::METRE.
  • PARAMETER.UNIT / PRIMEM.UNIT omitted if same as AXIS.
  • AXIS.UNIT omitted and replaced by a common GEODCRS.UNIT if they are all the same on all axis.

WKT2_2015_SIMPLIFIED = WKT2_SIMPLIFIED
WKT2_2018

Full WKT2 string, conforming to ISO 19162:2018 / OGC 18-010, with all possible nodes and new keyword names. Non-normative list of differences:

  • WKT2_2018 uses GEOGCRS / BASEGEOGCRS keywords for GeographicCRS.

WKT2_2018_SIMPLIFIED

WKT2_2018 with the simplification rule of WKT2_SIMPLIFIED

WKT1_GDAL

WKT1 as traditionally output by GDAL

Public Functions

WKTFormatter &setMultiLine(bool multiLine)

Whether to use multi line output or not.

WKTFormatter &setIndendationWidth(int width)

Set number of spaces for each indentation level (defaults to 4).

WKTFormatter &setStrict(bool strict)

Set whether the formatter should operate on strict more or not.

The default is strit mode, in which case a FormattingException can be thrown.

bool isStrict() const

Returns whether the formatter is in strict mode.

const std::string &toString() const

Returns the WKT string from the formatter.

Public Static Functions

WKTFormatterNNPtr create(Convention convention = Convention::WKT2)

Constructs a new formatter.

A formatter can be used only once (its internal state is mutated)

Its default behaviour can be adjusted with the different setters.

Return
new formatter.
Parameters

WKTFormatterNNPtr create(const WKTFormatterNNPtr &other)

Constructs a new formatter from another one.

A formatter can be used only once (its internal state is mutated)

Its default behaviour can be adjusted with the different setters.

Return
new formatter.
Parameters
  • other: source formatter.

class WKTNode
#include <io.hpp>

Node in the tree-splitted WKT representation.

Public Functions

WKTNode(const std::string &valueIn)

Instanciate a WKTNode.

Parameters
  • valueIn: the name of the node.

const std::string &value() const

Return the value of a node.

const std::vector<WKTNodeNNPtr> &children() const

Return the children of a node.

void addChild(WKTNodeNNPtr &&child)

Adds a child to the current node.

Parameters
  • child: child to add. This should not be a parent of this node.

const WKTNodePtr &lookForChild(const std::string &childName, int occurrence = 0) const

Return the (occurrence-1)th sub-node of name childName.

Return
the child, or nullptr.
Parameters
  • childName: name of the child.
  • occurrence: occurrence index (starting at 0)

int countChildrenOfName(const std::string &childName) const

Return the count of children of given name.

Return
count
Parameters
  • childName: name of the children to look for.

std::string toString() const

Return a WKT representation of the tree structure.

Public Static Functions

WKTNodeNNPtr createFrom(const std::string &wkt, size_t indexStart = 0)

Instanciate a WKTNode hierarchy from a WKT string.

Parameters
  • wkt: the WKT string to parse.
  • indexStart: the start index in the wkt string.
Exceptions

class WKTParser
#include <io.hpp>

Parse a WKT string into the appropriate suclass of util::BaseObject.

Public Functions

WKTParser &setStrict(bool strict)

Set whether parsing should be done in strict mode.

std::vector<std::string> warningList() const

Return the list of warnings found during parsing.

Note
The list might be non-empty only is setStrict(false) has been called.

BaseObjectNNPtr createFromWKT(const std::string &wkt)

Instanciate a sub-class of BaseObject from a WKT string.

Exceptions