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)
util::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 authoriy. 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.

  • 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 interprated the same way.

Exceptions

util::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 authoriy. 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.

  • PROJJSON string

Parameters

  • text: One of the above mentioned text format

  • ctx: PROJ context

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)

GEOCENTRIC_CRS

GEODETIC_CRS of type geocentric

GEOGRAPHIC_CRS

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

GEOGRAPHIC_2D_CRS

GEOGRAPHIC_CRS of type Geographic 2D

GEOGRAPHIC_3D_CRS

GEOGRAPHIC_CRS of type Geographic 3D

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

Return

description.

Parameters

  • code: Object code allocated by authority. (e.g. “4326”)

Exceptions

std::list<AuthorityFactory::CRSInfo> getCRSInfoList() const

Return a list of information on CRS objects.

This is functionnaly 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.

Exceptions

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

  • discardSuperseded: Whether cordinate 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.

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, 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 (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.

  • discardSuperseded: Whether cordinate 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.

Exceptions

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.

Return

official name (or empty if not found).

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

Exceptions

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 by their name.

Return

list of matched objects.

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.

Exceptions

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.

Return

list of (auth_name, code) of matched objects.

Parameters

  • name: Searched name.

  • approximateMatch: Whether approximate name identification is allowed.

Exceptions

Public Static Functions

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.

Return

new AuthorityFactory.

Parameters

  • context: Contexte.

  • authorityName: Authority 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.

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.

Public Static Functions

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.

  • ctx: Context used for file search.

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

Interface for an object that can be exported to JSON.

Subclassed by osgeo::proj::crs::CRS, osgeo::proj::cs::CoordinateSystem, osgeo::proj::cs::CoordinateSystemAxis, 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 disambiguish 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.

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

Whether to use multi line output or not.

JSONFormatter &setIndentationWidth(int width)

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

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

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

JSONFormatterNNPtr create(DatabaseContextPtr dbContext = nullptr)

Constructs a new formatter.

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

Return

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

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.

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.

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.

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 (_WKT2_2015) 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_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.

_WKT2_2018 = _WKT2_2019

Deprecated alias for _WKT2_2019

_WKT2_2019_SIMPLIFIED

_WKT2_2019 with the simplification rule of WKT2_SIMPLIFIED

_WKT2_2018_SIMPLIFIED = _WKT2_2019_SIMPLIFIED

Deprecated alias for _WKT2_2019_SIMPLIFIED

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

_WKT1_ESRI

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

enum OutputAxisRule

Rule for output AXIS nodes

Values:

YES

Always include AXIS nodes

NO

Never include AXIS nodes

_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)

Whether to use multi line output or not.

WKTFormatter &setIndentationWidth(int width)

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

WKTFormatter &setOutputAxis(OutputAxisRule outputAxis)

Set whether AXIS nodes should be output.

WKTFormatter &setStrict(bool strict)

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

The default is strict 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, 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

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

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)

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

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)

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

enum WKTGuessedDialect

Guessed WKT “dialect”

Values:

WKT2_2019

WKT2_2019

WKT2_2018 = WKT2_2019

Deprecated alias for WKT2_2019

WKT2_2015

WKT2_2015

WKT1_GDAL

WKT1

WKT1_ESRI

ESRI variant of WKT1

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.

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.

Exceptions

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

Guess the “dialect” of the WKT string.