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 WKTNodePtr = std::unique_ptr<WKTNode>

Unique pointer of WKTNode.

using WKTNodeNNPtr = util::nn<WKTNodePtr>

Non-null unique pointer of WKTNode.

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 JSONFormatterPtr = std::unique_ptr<JSONFormatter>

JSONFormatter unique pointer.

using JSONFormatterNNPtr = util::nn<JSONFormatterPtr>

Non-null JSONFormatter unique pointer.

using IPROJStringExportablePtr = std::shared_ptr<IPROJStringExportable>

Shared pointer of IPROJStringExportable.

using IPROJStringExportableNNPtr = util::nn<IPROJStringExportablePtr>

Non-null shared pointer of IPROJStringExportable.

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)
BaseObjectNNPtr createFromUserInput(const std::string &text, const DatabaseContextPtr &dbContext, bool usePROJ4InitRules)

Instantiate a sub-class of BaseObject from a user specified text.

The text can be a:

  • WKT string

  • PROJ string

  • database code, prefixed by its authority. e.g. "EPSG:4326"

  • OGC URN. e.g. "urn:ogc:def:crs:EPSG::4326", "urn:ogc:def:coordinateOperation:EPSG::1671", "urn:ogc:def:ellipsoid:EPSG::7001" or "urn:ogc:def:datum:EPSG::6326"

  • OGC URN combining references for compound coordinate reference systems e.g. "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" We also accept a custom abbreviated syntax EPSG:2393+5717 or ESRI:103668+EPSG:5703

  • OGC URN combining references for references for projected or derived CRSs e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)" "urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031"

  • OGC URN combining references for concatenated operations e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618"

  • OGC URL for a single CRS. e.g. "http://www.opengis.net/def/crs/EPSG/0/4326"

  • OGC URL for a compound CRS. e.g "http://www.opengis.net/def/crs-compound?1=http://www.opengis.net/def/crs/EPSG/0/4326&2=http://www.opengis.net/def/crs/EPSG/0/3855"

  • an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as uniqueness is not guaranteed, the function may apply heuristics to determine the appropriate best match.

  • a CRS name and a coordinate epoch, separated with '@'. For example "ITRF2014@2025.0". (added in PROJ 9.2)

  • a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height"

  • PROJJSON string

Parameters:

  • text -- One of the above mentioned text format

  • dbContext -- Database context, or nullptr (in which case database lookups will not work)

  • usePROJ4InitRules -- When set to true, init=epsg:XXXX syntax will be allowed and will be interpreted according to PROJ.4 and PROJ.5 rules, that is geodeticCRS will have longitude, latitude order and will expect/output coordinates in radians. ProjectedCRS will have easting, northing axis order (except the ones with Transverse Mercator South Orientated projection). In that mode, the epsg:XXXX syntax will be also interpreted the same way.

Throws:

ParsingException --

BaseObjectNNPtr createFromUserInput(const std::string &text, PJ_CONTEXT *ctx)

Instantiate a sub-class of BaseObject from a user specified text.

The text can be a:

  • WKT string

  • PROJ string

  • database code, prefixed by its authority. e.g. "EPSG:4326"

  • OGC URN. e.g. "urn:ogc:def:crs:EPSG::4326", "urn:ogc:def:coordinateOperation:EPSG::1671", "urn:ogc:def:ellipsoid:EPSG::7001" or "urn:ogc:def:datum:EPSG::6326"

  • OGC URN combining references for compound coordinate reference systems e.g. "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" We also accept a custom abbreviated syntax EPSG:2393+5717

  • OGC URN combining references for references for projected or derived CRSs e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)" "urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031"

  • OGC URN combining references for concatenated operations e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618"

  • an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as uniqueness is not guaranteed, the function may apply heuristics to determine the appropriate best match.

  • a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height"

  • PROJJSON string

Parameters:

  • text -- One of the above mentioned text format

  • ctx -- PROJ context

Throws:

ParsingException --

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] (http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/AuthorityFactory.html) from GeoAPI

Public Types

enum class ObjectType

Object type.

Values:

enumerator PRIME_MERIDIAN

Object of type datum::PrimeMeridian

enumerator ELLIPSOID

Object of type datum::Ellipsoid

enumerator DATUM

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

enumerator GEODETIC_REFERENCE_FRAME

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

enumerator VERTICAL_REFERENCE_FRAME

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

enumerator CRS

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

enumerator GEODETIC_CRS

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

enumerator GEOCENTRIC_CRS

GEODETIC_CRS of type geocentric

enumerator GEOGRAPHIC_CRS

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

enumerator GEOGRAPHIC_2D_CRS

GEOGRAPHIC_CRS of type Geographic 2D

enumerator GEOGRAPHIC_3D_CRS

GEOGRAPHIC_CRS of type Geographic 3D

enumerator PROJECTED_CRS

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

enumerator VERTICAL_CRS

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

enumerator COMPOUND_CRS

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

enumerator COORDINATE_OPERATION

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

enumerator CONVERSION

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

enumerator TRANSFORMATION

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

enumerator CONCATENATED_OPERATION

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

enumerator DYNAMIC_GEODETIC_REFERENCE_FRAME

Object of type datum::DynamicGeodeticReferenceFrame

enumerator DYNAMIC_VERTICAL_REFERENCE_FRAME

Object of type datum::DynamicVerticalReferenceFrame

enumerator DATUM_ENSEMBLE

Object of type datum::DatumEnsemble

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.

Parameters:

code -- Object code allocated by authority. (e.g. "4326")

Throws:
Returns:

object.

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

Returns a common::UnitOfMeasure from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a metadata::Extent from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a datum::PrimeMeridian from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Identify a celestial body from an approximate radius.

Parameters:

  • semi_major_axis -- Approximate semi-major axis.

  • tolerance -- Relative error allowed.

Throws:

FactoryException --

Returns:

celestial body name if one single match found.

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

Returns a datum::Ellipsoid from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a datum::Datum from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

datum::DatumEnsembleNNPtr createDatumEnsemble(const std::string &code, const std::string &type = std::string()) const

Returns a datum::DatumEnsemble from the specified code.

Parameters:

  • code -- Object code allocated by authority.

  • type -- "geodetic_datum", "vertical_datum" or empty string if unknown

Throws:
Returns:

object.

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

Returns a datum::GeodeticReferenceFrame from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a datum::VerticalReferenceFrame from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a cs::CoordinateSystem from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a crs::GeodeticCRS from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a crs::GeographicCRS from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a crs::VerticalCRS from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a operation::Conversion from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a crs::ProjectedCRS from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a crs::CompoundCRS from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a crs::CRS from the specified code.

Parameters:

code -- Object code allocated by authority.

Throws:
Returns:

object.

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

Returns a operation::CoordinateOperation from the specified code.

Parameters:

  • code -- Object code allocated by authority.

  • usePROJAlternativeGridNames -- Whether PROJ alternative grid names should be substituted to the official grid names.

Throws:
Returns:

object.

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 inferring operations that are not explicitly in the database.

Deprecated operations are rejected.

Parameters:

  • sourceCRSCode -- Source CRS code allocated by authority.

  • targetCRSCode -- Source CRS code allocated by authority.

Throws:
Returns:

list of coordinate operations

std::list<std::string> getGeoidModels(const std::string &code) const

Returns a list of geoid models available for that crs.

The list includes the geoid models connected directly with the crs, or via "Height Depth Reversal" or "Change of Vertical Unit" transformations

Parameters:

code -- crs code allocated by authority.

Throws:

FactoryException --

Returns:

list of geoid model names

const std::string &getAuthority()

Returns the authority name associated to this factory.

Returns:

name.

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

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

Parameters:

  • type -- Object type.

  • allowDeprecated -- whether we should return deprecated objects as well.

Throws:

FactoryException --

Returns:

the set of authority codes for spatial reference objects of the given type

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. But if a CRS object is found, it will be selected.

Parameters:

code -- Object code allocated by authority. (e.g. "4326")

Throws:
Returns:

description.

std::list<CRSInfo> getCRSInfoList() const

Return a list of information on CRS objects.

This is functionally equivalent of listing the codes from an authority, instantiating a CRS object for each of them and getting the information from this CRS object, but this implementation has much less overhead.

Throws:

FactoryException --

std::list<UnitInfo> getUnitList() const

Return the list of units.

Since

7.1

Throws:

FactoryException --

std::list<CelestialBodyInfo> getCelestialBodyList() const

Return the list of celestial bodies.

Since

8.1

Throws:

FactoryException --

const 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, bool considerKnownGridsAsAvailable, bool discardSuperseded, bool tryReverseOrder = false, bool reportOnlyIntersectingTransformations = false, const metadata::ExtentPtr &intersectingExtent1 = nullptr, const metadata::ExtentPtr &intersectingExtent2 = nullptr) const

Returns a list operation::CoordinateOperation between two CRS.

The list is ordered with preferred operations first. No attempt is made at inferring operations that are not explicitly in the database (see createFromCRSCodesWithIntermediates() for that), and only source -> target operations are searched (i.e. 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.

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.

  • considerKnownGridsAsAvailable -- Whether known grids should be considered as available (typically when network is enabled).

  • discardSuperseded -- Whether coordinate operations that are superseded (but not deprecated) should be removed from the result set.

  • tryReverseOrder -- whether to search in the reverse order too (and thus inverse results found that way)

  • reportOnlyIntersectingTransformations -- if intersectingExtent1 and intersectingExtent2 should be honored in a strict way.

  • intersectingExtent1 -- Optional extent that the resulting operations must intersect.

  • intersectingExtent2 -- Optional extent that the resulting operations must intersect.

Throws:
Returns:

list of coordinate operations

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, bool considerKnownGridsAsAvailable, bool discardSuperseded, const std::vector<std::pair<std::string, std::string>> &intermediateCRSAuthCodes, ObjectType allowedIntermediateObjectType = ObjectType::CRS, const std::vector<std::string> &allowedAuthorities = std::vector<std::string>(), const metadata::ExtentPtr &intersectingExtent1 = nullptr, const metadata::ExtentPtr &intersectingExtent2 = nullptr) 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 (i.e. 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.

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.

  • considerKnownGridsAsAvailable -- Whether known grids should be considered as available (typically when network is enabled).

  • discardSuperseded -- Whether coordinate operations that are superseded (but not deprecated) 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.

  • allowedIntermediateObjectType -- Restrict the type of the intermediate object considered. Only ObjectType::CRS and ObjectType::GEOGRAPHIC_CRS supported currently

  • allowedAuthorities -- One or several authority name allowed for the two coordinate operations that are going to be searched. When this vector is no empty, it overrides the authority of this object. This is useful for example when the coordinate operations to chain belong to two different allowed authorities.

  • intersectingExtent1 -- Optional extent that the resulting operations must intersect.

  • intersectingExtent2 -- Optional extent that the resulting operations must intersect.

Throws:
Returns:

list of coordinate operations

std::string getOfficialNameFromAlias(const std::string &aliasedName, const std::string &tableName, const std::string &source, bool tryEquivalentNameSpelling, std::string &outTableName, std::string &outAuthName, std::string &outCode) const

Gets the official name from a possibly alias name.

Parameters:

  • aliasedName -- Alias name.

  • tableName -- Table name/category. Can help in case of ambiguities. Or empty otherwise.

  • source -- Source of the alias. Can help in case of ambiguities. Or empty otherwise.

  • tryEquivalentNameSpelling -- whether the comparison of aliasedName with the alt_name column of the alias_name table should be done with using metadata::Identifier::isEquivalentName() rather than strict string comparison;

  • outTableName -- Table name in which the official name has been found.

  • outAuthName -- Authority name of the official name that has been found.

  • outCode -- Code of the official name that has been found.

Throws:

FactoryException --

Returns:

official name (or empty if not found).

std::list<common::IdentifiedObjectNNPtr> createObjectsFromName(const std::string &name, const std::vector<ObjectType> &allowedObjectTypes = std::vector<ObjectType>(), bool approximateMatch = true, size_t limitResultCount = 0) const

Return a list of objects, identified by their name.

Parameters:

  • searchedName -- Searched name. Must be at least 2 character long.

  • allowedObjectTypes -- List of object types into which to search. If empty, all object types will be searched.

  • approximateMatch -- Whether approximate name identification is allowed.

  • limitResultCount -- Maximum number of results to return. Or 0 for unlimited.

Throws:

FactoryException --

Returns:

list of matched objects.

std::list<std::pair<std::string, std::string>> listAreaOfUseFromName(const std::string &name, bool approximateMatch) const

Return a list of area of use from their name.

Parameters:

  • name -- Searched name.

  • approximateMatch -- Whether approximate name identification is allowed.

Throws:

FactoryException --

Returns:

list of (auth_name, code) of matched objects.

Public Static Functions

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

Instantiate 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.

Parameters:

  • context -- Context.

  • authorityName -- Authority name.

Returns:

new AuthorityFactory.

struct CelestialBodyInfo
#include <io.hpp>

Celestial Body information

Public Members

std::string authName

Authority name

std::string name

Name

struct CRSInfo
#include <io.hpp>

CRS information

Public Members

std::string authName

Authority name

std::string code

Code

std::string name

Name

ObjectType type

Type

bool deprecated

Whether the object is deprecated

bool bbox_valid

Whereas the west_lon_degree, south_lat_degree, east_lon_degree and north_lat_degree fields are valid.

double west_lon_degree

Western-most longitude of the area of use, in degrees.

double south_lat_degree

Southern-most latitude of the area of use, in degrees.

double east_lon_degree

Eastern-most longitude of the area of use, in degrees.

double north_lat_degree

Northern-most latitude of the area of use, in degrees.

std::string areaName

Name of the area of use.

std::string projectionMethodName

Name of the projection method for a projected CRS. Might be empty even for projected CRS in some cases.

std::string celestialBodyName

Name of the celestial body of the CRS (e.g. "Earth")

struct UnitInfo
#include <io.hpp>

Unit information

Public Members

std::string authName

Authority name

std::string code

Code

std::string name

Name

std::string category

Category: one of "linear", "linear_per_time", "angular", "angular_per_time", "scale", "scale_per_time" or "time"

double convFactor

Conversion factor to the SI unit. It might be 0 in some cases to indicate no known conversion factor.

std::string projShortName

PROJ short name (may be empty)

bool deprecated

Whether the object is deprecated

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.

const char *getMetadata(const char *key) const

Return a metadata item.

Value remains valid while this is alive and to the next call to getMetadata

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.

void startInsertStatementsSession()

Starts a session for getInsertStatementsFor()

Starts a new session for one or several calls to getInsertStatementsFor(). An insertion session guarantees that the inserted objects will not create conflicting intermediate objects.

The session must be stopped with stopInsertStatementsSession().

Only one session may be active at a time for a given database context.

Since

8.1

Throws:

FactoryException --

std::string suggestsCodeFor(const common::IdentifiedObjectNNPtr &object, const std::string &authName, bool numericCode)

Suggests a database code for the passed object.

Supported type of objects are PrimeMeridian, Ellipsoid, Datum, DatumEnsemble, GeodeticCRS, ProjectedCRS, VerticalCRS, CompoundCRS, BoundCRS, Conversion.

Since

8.1

Parameters:

  • object -- Object for which to suggest a code.

  • authName -- Authority name into which the object will be inserted.

  • numericCode -- Whether the code should be numeric, or derived from the object name.

Throws:

FactoryException --

Returns:

the suggested code, that is guaranteed to not conflict with an existing one.

std::vector<std::string> getInsertStatementsFor(const common::IdentifiedObjectNNPtr &object, const std::string &authName, const std::string &code, bool numericCode, const std::vector<std::string> &allowedAuthorities = {"EPSG", "PROJ"})

Returns SQL statements needed to insert the passed object into the database.

startInsertStatementsSession() must have been called previously.

Since

8.1

Parameters:

  • object -- The object to insert into the database. Currently only PrimeMeridian, Ellipsoid, Datum, GeodeticCRS, ProjectedCRS, VerticalCRS, CompoundCRS or BoundCRS are supported.

  • authName -- Authority name into which the object will be inserted.

  • code -- Code with which the object will be inserted.

  • numericCode -- Whether intermediate objects that can be created should use numeric codes (true), or may be alphanumeric (false)

  • allowedAuthorities -- Authorities to which intermediate objects are allowed to refer to. authName will be implicitly added to it. Note that unit, coordinate systems, projection methods and parameters will in any case be allowed to refer to EPSG.

Throws:

FactoryException --

void stopInsertStatementsSession()

Stops an insertion session started with startInsertStatementsSession()

Since

8.1

Public Static Functions

static DatabaseContextNNPtr create(const std::string &databasePath = std::string(), const std::vector<std::string> &auxiliaryDatabasePaths = std::vector<std::string>(), PJ_CONTEXT *ctx = nullptr)

Instantiate a database context.

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. Might be empty. Starting with PROJ 8.1, if this parameter is an empty array, the PROJ_AUX_DB environment variable will be used, if set. It must contain one or several paths. If several paths are provided, they must be separated by the colon (:) character on Unix, and on Windows, by the semi-colon (;) character.

  • ctx -- Context used for file search.

Throws:

FactoryException --

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 IJSONExportable
#include <io.hpp>

Interface for an object that can be exported to JSON.

Subclassed by osgeo::proj::coordinates::CoordinateMetadata, osgeo::proj::crs::CRS, osgeo::proj::cs::CoordinateSystem, osgeo::proj::cs::CoordinateSystemAxis, osgeo::proj::cs::Meridian, osgeo::proj::datum::Datum, osgeo::proj::datum::DatumEnsemble, osgeo::proj::datum::Ellipsoid, osgeo::proj::datum::PrimeMeridian, osgeo::proj::metadata::Identifier, osgeo::proj::operation::CoordinateOperation, osgeo::proj::operation::GeneralParameterValue, osgeo::proj::operation::OperationMethod

Public Functions

std::string exportToJSON(JSONFormatter *formatter) const

Builds a JSON representation. May throw a FormattingException

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::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),

    • For a crs::CRS, returns the same as PROJStringFormatter::Convention::PROJ_4. It should be noted that the export of a CRS as a PROJ string may cause loss of many important aspects of a CRS definition. Consequently it is discouraged to use it for interoperability in newer projects. The choice of a WKT representation will be a better option.

    • For operation::CoordinateOperation, returns a PROJ pipeline.

  • For PROJStringFormatter::Convention::PROJ_4, format a string compatible with the OGRSpatialReference::exportToProj4() of GDAL <=2.3. It is only compatible of a few CRS objects. The PROJ string will also contain a +type=crs parameter to disambiguate the nature of the string from a CoordinateOperation.

    • 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.

Parameters:

formatter -- PROJ string formatter.

Throws:

FormattingException --

Returns:

a PROJ string.

class IWKTExportable
#include <io.hpp>

Interface for an object that can be exported to WKT.

Subclassed by osgeo::proj::common::IdentifiedObject, osgeo::proj::coordinates::CoordinateMetadata, osgeo::proj::metadata::Identifier, osgeo::proj::operation::GeneralParameterValue, osgeo::proj::operation::ParameterValue

Public Functions

std::string exportToWKT(WKTFormatter *formatter) const

Builds a WKT representation. May throw a FormattingException

class JSONFormatter
#include <io.hpp>

Formatter to JSON strings.

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

Public Functions

JSONFormatter &setMultiLine(bool multiLine) noexcept

Whether to use multi line output or not.

JSONFormatter &setIndentationWidth(int width) noexcept

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

JSONFormatter &setSchema(const std::string &schema) noexcept

Set the value of the "$schema" key in the top level object.

If set to empty string, it will not be written.

const std::string &toString() const

Return the serialized JSON.

Public Static Functions

static JSONFormatterNNPtr create(DatabaseContextPtr dbContext = nullptr)

Constructs a new formatter.

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

Returns:

new formatter.

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 class Convention

PROJ variant.

Values:

enumerator PROJ_5

PROJ v5 (or later versions) string.

enumerator PROJ_4

PROJ v4 string as output by GDAL exportToProj4()

Public Functions

PROJStringFormatter &setMultiLine(bool multiLine) noexcept

Whether to use multi line output or not.

PROJStringFormatter &setIndentationWidth(int width) noexcept

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

PROJStringFormatter &setMaxLineLength(int maxLineLength) noexcept

Set the maximum size of a line (when multiline output is enable). Can be set to 0 for unlimited length.

void setUseApproxTMerc(bool flag)

Set whether approximate Transverse Mercator or UTM should be used.

const std::string &toString() const

Returns the PROJ string.

Public Static Functions

static 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 behavior can be adjusted with the different setters.

Parameters:

  • conventionIn -- PROJ string flavor. Defaults to Convention::PROJ_5

  • dbContext -- Database context (can help to find alternative grid names). May be nullptr

Returns:

new formatter.

class PROJStringParser
#include <io.hpp>

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

Public Functions

PROJStringParser &attachDatabaseContext(const DatabaseContextPtr &dbContext)

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

PROJStringParser &setUsePROJ4InitRules(bool enable)

Set how init=epsg:XXXX syntax should be interpreted.

Parameters:

enable -- When set to true, init=epsg:XXXX syntax will be allowed and will be interpreted according to PROJ.4 and PROJ.5 rules, that is geodeticCRS will have longitude, latitude order and will expect/output coordinates in radians. ProjectedCRS will have easting, northing axis order (except the ones with Transverse Mercator South Orientated projection).

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

Return the list of warnings found during parsing.

util::BaseObjectNNPtr createFromPROJString(const std::string &projString)

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

The projString must contain +type=crs for the object to be detected as a CRS instead of a CoordinateOperation.

Throws:

ParsingException --

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 class Convention

WKT variant.

Values:

enumerator WKT2

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

enumerator WKT2_2015
enumerator 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.

enumerator WKT2_2015_SIMPLIFIED
enumerator WKT2_2019

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

  • WKT2_2019 uses GEOGCRS / BASEGEOGCRS keywords for GeographicCRS.

enumerator WKT2_2018

Deprecated alias for WKT2_2019

enumerator WKT2_2019_SIMPLIFIED

WKT2_2019 with the simplification rule of WKT2_SIMPLIFIED

enumerator WKT2_2018_SIMPLIFIED

Deprecated alias for WKT2_2019_SIMPLIFIED

enumerator WKT1_GDAL

WKT1 as traditionally output by GDAL, deriving from OGC 01-009. A notable departure from WKT1_GDAL with respect to OGC 01-009 is that in WKT1_GDAL, the unit of the PRIMEM value is always degrees.

enumerator WKT1_ESRI

WKT1 as traditionally output by ESRI software, deriving from OGC 99-049.

enum class OutputAxisRule

Rule for output AXIS nodes

Values:

enumerator YES

Always include AXIS nodes

enumerator NO

Never include AXIS nodes

enumerator WKT1_GDAL_EPSG_STYLE

Includes them only on PROJCS node if it uses Easting/Northing ordering. Typically used for WKT1_GDAL

Public Functions

WKTFormatter &setMultiLine(bool multiLine) noexcept

Whether to use multi line output or not.

WKTFormatter &setIndentationWidth(int width) noexcept

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

WKTFormatter &setOutputAxis(OutputAxisRule outputAxis) noexcept

Set whether AXIS nodes should be output.

WKTFormatter &setStrict(bool strict) noexcept

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

The default is strict mode, in which case a FormattingException can be thrown. In non-strict mode, a Geographic 3D CRS can be for example exported as WKT1_GDAL with 3 axes, whereas this is normally not allowed.

bool isStrict() const noexcept

Returns whether the formatter is in strict mode.

WKTFormatter &setAllowEllipsoidalHeightAsVerticalCRS(bool allow) noexcept

Set whether the formatter should export, in WKT1, a Geographic or Projected 3D CRS as a compound CRS whose vertical part represents an ellipsoidal height.

bool isAllowedEllipsoidalHeightAsVerticalCRS() const noexcept

Return whether the formatter should export, in WKT1, a Geographic or Projected 3D CRS as a compound CRS whose vertical part represents an ellipsoidal height.

WKTFormatter &setAllowLINUNITNode(bool allow) noexcept

Set whether the formatter should export, in WKT1_ESRI, a Geographic 3D CRS with the relatively new (ArcGIS Pro >= 2.7) LINUNIT node. Defaults to true.

Since

PROJ 9.1

bool isAllowedLINUNITNode() const noexcept

Return whether the formatter should export, in WKT1_ESRI, a Geographic 3D CRS with the relatively new (ArcGIS Pro >= 2.7) LINUNIT node. Defaults to true.

Since

PROJ 9.1

const std::string &toString() const

Returns the WKT string from the formatter.

Public Static Functions

static WKTFormatterNNPtr create(Convention convention = Convention::WKT2, DatabaseContextPtr dbContext = nullptr)

Constructs a new formatter.

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

Its default behavior can be adjusted with the different setters.

Parameters:

  • convention -- WKT flavor. Defaults to Convention::WKT2

  • dbContext -- Database context, to allow queries in it if needed. This is used for example for WKT1_ESRI output to do name substitutions.

Returns:

new formatter.

static 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 behavior can be adjusted with the different setters.

Parameters:

other -- source formatter.

Returns:

new formatter.

class WKTNode
#include <io.hpp>

Node in the tree-splitted WKT representation.

Public Functions

explicit WKTNode(const std::string &valueIn)

Instantiate 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 noexcept

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

Parameters:

  • childName -- name of the child.

  • occurrence -- occurrence index (starting at 0)

Returns:

the child, or nullptr.

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

Return the count of children of given name.

Parameters:

childName -- name of the children to look for.

Returns:

count

std::string toString() const

Return a WKT representation of the tree structure.

Public Static Functions

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

Instantiate a WKTNode hierarchy from a WKT string.

Parameters:

  • wkt -- the WKT string to parse.

  • indexStart -- the start index in the wkt string.

Throws:

ParsingException --

class WKTParser
#include <io.hpp>

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

Public Types

enum class WKTGuessedDialect

Guessed WKT "dialect"

Values:

enumerator WKT2_2019

WKT2:2019

enumerator WKT2_2018

Deprecated alias for WKT2_2019

enumerator WKT2_2015

WKT2:2015

enumerator WKT1_GDAL

WKT1 specification

enumerator WKT1_ESRI

ESRI variant of WKT1

enumerator NOT_WKT

Not WKT / unrecognized

Public Functions

WKTParser &attachDatabaseContext(const DatabaseContextPtr &dbContext)

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

WKTParser &setStrict(bool strict)

Set whether parsing should be done in strict mode.

std::list<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.

WKTParser &setUnsetIdentifiersIfIncompatibleDef(bool unset)

Set whether object identifiers should be unset when there is a contradiction between the definition from WKT and the one from the database.

At time of writing, this only applies to the base geographic CRS of a projected CRS, when comparing its coordinate system.

util::BaseObjectNNPtr createFromWKT(const std::string &wkt)

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

By default, validation is strict (to the extent of the checks that are actually implemented. Currently only WKT1 strict grammar is checked), and any issue detected will cause an exception to be thrown, unless setStrict(false) is called priorly.

In non-strict mode, non-fatal issues will be recovered and simply listed in warningList(). This does not prevent more severe errors to cause an exception to be thrown.

Throws:

ParsingException --

WKTGuessedDialect guessDialect(const std::string &wkt) noexcept

Guess the "dialect" of the WKT string.