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
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)
-
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 sourceCRSCodesourceCRSCode
: Source CRS code allocated by authority sourceCRSAuthName.targetCRSAuthName
: Authority name of targetCRSCodetargetCRSCode
: 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 sourceCRSCodesourceCRSCode
: Source CRS code allocated by authority sourceCRSAuthName.targetCRSAuthName
: Authority name of targetCRSCodetargetCRSCode
: 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.dbauxiliaryDatabasePaths
: Path and filename of auxiliary databases;
- Exceptions
-
const std::string &
-
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
-
std::string
-
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
-
std::string
-
class
NoSuchAuthorityCodeException
: public osgeo::proj::io::FactoryException¶ - #include <io.hpp>
Exception thrown when an authority factory can’t find the requested 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
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_5dbContext
: Database context (can help to find alternative grid names). May be nullptr
-
void
-
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
-
PROJStringParser &
-
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¶
-
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
convention
: WKT flavor. Defaults to Convention::WKT2
-
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.
-
enum
-
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
-
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
-
std::vector<std::string>
-
using