QGIS API Documentation  3.22.4-Białowieża (ce8e65e95e)
Public Types | Public Member Functions | Static Public Member Functions | Properties | Friends | List of all members
QgsCoordinateReferenceSystem Class Reference

This class represents a coordinate reference system (CRS). More...

#include <qgscoordinatereferencesystem.h>

Public Types

enum  CrsType { InternalCrsId , PostgisCrsId , EpsgCrsId }
 Enumeration of types of IDs accepted in createFromId() method. More...
 
enum  Format { FormatWkt = 0 , FormatProj }
 Projection definition formats. More...
 
enum  IdentifierType { ShortString , MediumString , FullString }
 Type of identifier string to create. More...
 
enum  WktVariant {
  WKT1_GDAL , WKT1_ESRI , WKT2_2015 , WKT2_2015_SIMPLIFIED ,
  WKT2_2018 , WKT2_2018_SIMPLIFIED , WKT2_2019 = WKT2_2018 , WKT2_2019_SIMPLIFIED = WKT2_2018_SIMPLIFIED ,
  WKT_PREFERRED = WKT2_2019 , WKT_PREFERRED_SIMPLIFIED = WKT2_2019_SIMPLIFIED , WKT_PREFERRED_GDAL = WKT2_2019
}
 WKT formatting variants, only used for builds based on Proj >= 6. More...
 

Public Member Functions

 QgsCoordinateReferenceSystem ()
 Constructs an invalid CRS object. More...
 
 QgsCoordinateReferenceSystem (const QgsCoordinateReferenceSystem &srs)
 Copy constructor. More...
 
 QgsCoordinateReferenceSystem (const QString &definition)
 Constructs a CRS object from a string definition using createFromString() More...
 
Q_DECL_DEPRECATED QgsCoordinateReferenceSystem (long id, CrsType type=PostgisCrsId)
 Constructor. More...
 
 ~QgsCoordinateReferenceSystem ()
 
QString authid () const
 Returns the authority identifier for the CRS. More...
 
QgsRectangle bounds () const
 Returns the approximate bounds for the region the CRS is usable within. More...
 
QString celestialBodyName () const SIP_THROW(QgsNotSupportedException)
 Attempts to retrieve the name of the celestial body associated with the CRS (e.g. More...
 
double coordinateEpoch () const
 Returns the coordinate epoch, as a decimal year. More...
 
Q_DECL_DEPRECATED bool createFromId (long id, CrsType type=PostgisCrsId)
 Sets this CRS by lookup of the given ID in the CRS database. More...
 
bool createFromOgcWmsCrs (const QString &crs)
 Sets this CRS to the given OGC WMS-format Coordinate Reference Systems. More...
 
bool createFromProj (const QString &projString, bool identify=true)
 Sets this CRS by passing it a PROJ style formatted string. More...
 
Q_DECL_DEPRECATED bool createFromProj4 (const QString &projString)
 Sets this CRS by passing it a PROJ style formatted string. More...
 
Q_DECL_DEPRECATED bool createFromSrid (long srid)
 Sets this CRS by lookup of the given PostGIS SRID in the CRS database. More...
 
bool createFromSrsId (long srsId)
 Sets this CRS by lookup of internal QGIS CRS ID in the CRS database. More...
 
bool createFromString (const QString &definition)
 Set up this CRS from a string definition. More...
 
bool createFromUserInput (const QString &definition)
 Set up this CRS from various text formats. More...
 
bool createFromWkt (const QString &wkt)
 Sets this CRS using a WKT definition. More...
 
QgsDatumEnsemble datumEnsemble () const SIP_THROW(QgsNotSupportedException)
 Attempts to retrieve datum ensemble details from the CRS. More...
 
QString description () const
 Returns the descriptive name of the CRS, e.g., "WGS 84" or "GDA 94 / Vicgrid94". More...
 
QString ellipsoidAcronym () const
 Returns the ellipsoid acronym for the ellipsoid used by the CRS. More...
 
QgsProjectionFactors factors (const QgsPoint &point) const
 Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence for the CRS at the given geodetic point (in geographic coordinates). More...
 
Q_DECL_DEPRECATED long findMatchingProj ()
 Walks the CRS databases (both system and user database) trying to match stored PROJ string to a database entry in order to fill in further pieces of information about CRS. More...
 
QString geographicCrsAuthId () const
 Returns auth id of related geographic CRS. More...
 
bool hasAxisInverted () const
 Returns whether axis is inverted (e.g., for WMS 1.3) for the CRS. More...
 
bool isDynamic () const
 Returns true if the CRS is a dynamic CRS. More...
 
bool isGeographic () const
 Returns whether the CRS is a geographic CRS (using lat/lon coordinates) More...
 
bool isValid () const
 Returns whether this CRS is correctly initialized and usable. More...
 
QgsUnitTypes::DistanceUnit mapUnits () const
 Returns the units for the projection used by the CRS. More...
 
QgsProjOperation operation () const
 Returns information about the PROJ operation associated with the coordinate reference system, for example the projection method used by the CRS. More...
 
 operator QVariant () const
 Allows direct construction of QVariants from QgsCoordinateReferenceSystem. More...
 
bool operator!= (const QgsCoordinateReferenceSystem &srs) const
 Overloaded != operator used to compare to CRS's. More...
 
QgsCoordinateReferenceSystemoperator= (const QgsCoordinateReferenceSystem &srs)
 Assignment operator. More...
 
bool operator== (const QgsCoordinateReferenceSystem &srs) const
 Overloaded == operator used to compare to CRS's. More...
 
long postgisSrid () const
 Returns PostGIS SRID for the CRS. More...
 
QString projectionAcronym () const
 Returns the projection acronym for the projection used by the CRS. More...
 
PJprojObject () const
 Returns the underlying PROJ PJ object corresponding to the CRS, or nullptr if the CRS is invalid. More...
 
bool readXml (const QDomNode &node)
 Restores state from the given DOM node. More...
 
long saveAsUserCrs (const QString &name, Format nativeFormat=FormatWkt)
 Saves the CRS as a new custom ("USER") CRS. More...
 
void setCoordinateEpoch (double epoch)
 Sets the coordinate epoch, as a decimal year. More...
 
void setValidationHint (const QString &html)
 Set user hint for validation. More...
 
long srsid () const
 Returns the internal CRS ID, if available. More...
 
QString toProj () const
 Returns a Proj string representation of this CRS. More...
 
Q_DECL_DEPRECATED QString toProj4 () const
 Returns a Proj string representation of this CRS. More...
 
QString toWkt (WktVariant variant=WKT1_GDAL, bool multiline=false, int indentationWidth=4) const
 Returns a WKT representation of this CRS. More...
 
void updateDefinition ()
 Updates the definition and parameters of the coordinate reference system to their latest values. More...
 
QString userFriendlyIdentifier (IdentifierType type=MediumString) const
 Returns a user friendly identifier for the CRS. More...
 
void validate ()
 Perform some validation on this CRS. More...
 
QString validationHint ()
 Gets user hint for validation. More...
 
bool writeXml (QDomNode &node, QDomDocument &doc) const
 Stores state to the given Dom node in the given document. More...
 

Static Public Member Functions

static CUSTOM_CRS_VALIDATION customCrsValidation ()
 Gets custom function. More...
 
static Q_INVOKABLE QgsCoordinateReferenceSystem fromEpsgId (long epsg)
 Creates a CRS from a given EPSG ID. More...
 
static QgsCoordinateReferenceSystem fromOgcWmsCrs (const QString &ogcCrs)
 Creates a CRS from a given OGC WMS-format Coordinate Reference System string. More...
 
static QgsCoordinateReferenceSystem fromProj (const QString &proj)
 Creates a CRS from a proj style formatted string. More...
 
static Q_DECL_DEPRECATED QgsCoordinateReferenceSystem fromProj4 (const QString &proj4)
 Creates a CRS from a proj style formatted string. More...
 
static QgsCoordinateReferenceSystem fromSrsId (long srsId)
 Creates a CRS from a specified QGIS SRS ID. More...
 
static QgsCoordinateReferenceSystem fromWkt (const QString &wkt)
 Creates a CRS from a WKT spatial ref sys definition string. More...
 
static void invalidateCache (bool disableCache=false)
 Clears the internal cache used to initialize QgsCoordinateReferenceSystem objects. More...
 
static void pushRecentCoordinateReferenceSystem (const QgsCoordinateReferenceSystem &crs)
 Pushes a recently used CRS to the top of the recent CRS list. More...
 
static QList< QgsCoordinateReferenceSystemrecentCoordinateReferenceSystems ()
 Returns a list of recently used CRS. More...
 
static Q_DECL_DEPRECATED QStringList recentProjections ()
 Returns a list of recently used projections. More...
 
static void setCustomCrsValidation (CUSTOM_CRS_VALIDATION f)
 Sets custom function to force valid CRS. More...
 
static Q_DECL_DEPRECATED void setupESRIWktFix ()
 Make sure that ESRI WKT import is done properly. More...
 
static int syncDatabase ()
 Update proj.4 parameters in our database from proj.4. More...
 
static QList< long > validSrsIds ()
 Returns a list of all valid SRS IDs present in the CRS database. More...
 

Properties

bool isGeographic
 
Q_GADGET QgsUnitTypes::DistanceUnit mapUnits
 

Friends

bool CORE_EXPORT operator< (const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
 
bool CORE_EXPORT operator<= (const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
 
bool CORE_EXPORT operator> (const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
 
bool CORE_EXPORT operator>= (const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
 
class QgsCoordinateReferenceSystemRegistry
 
class QgsProjContext
 
class TestQgsCoordinateReferenceSystem
 

Detailed Description

This class represents a coordinate reference system (CRS).

Coordinate reference system object defines a specific map projection, as well as transformations between different coordinate reference systems. There are various ways how a CRS can be defined: using well-known text (WKT), PROJ string or combination of authority and code (e.g. EPSG:4326). QGIS comes with its internal database of coordinate reference systems (stored in SQLite) that allows lookups of CRS and seamless conversions between the various definitions.

Most commonly one comes across two types of coordinate systems:

Internally QGIS uses proj library for all the math behind coordinate transformations, so in case of any troubles with projections it is best to examine the PROJ representation within the object, as that is the representation that will be ultimately used.

Methods that allow inspection of CRS instances include isValid(), authid(), description(), toWkt(), toProj(), mapUnits() and others. Creation of CRS instances is further described in Object Construction and Copying section below. Transformations between coordinate reference systems are done using QgsCoordinateTransform class.

For example, the following code will create and inspect "British national grid" CRS:

crs = QgsCoordinateReferenceSystem("EPSG:27700")
if crs.isValid():
print("CRS Description: {}".format(crs.description()))
print("CRS PROJ text: {}".format(crs.toProj()))
else:
print("Invalid CRS!")
This class represents a coordinate reference system (CRS).

This will produce the following output:

CRS Description: OSGB 1936 / British National Grid
CRS PROJ text: +proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 [output trimmed]

CRS Definition Formats

This section gives an overview of various supported CRS definition formats:

+proj=longlat +datum=WGS84 +no_defs
See also
toProj()
createFromProj()
GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],
AUTHORITY["EPSG","6326"]],
PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],
UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],
AUTHORITY["EPSG","4326"]]
See also
toWkt()
createFromWkt()

CRS Database and Custom CRS

The database of CRS shipped with QGIS is stored in a SQLite database (see QgsApplication::srsDatabaseFilePath()) and it is based on the data files maintained by GDAL project (a variety of .csv and .wkt files).

Sometimes it happens that users need to use a CRS definition that is not well known or that has been only created with a specific purpose (and thus its definition is not available in our database of CRS). Whenever a new CRS definition is seen, it will be added to the local database (in user's home directory, see QgsApplication::qgisUserDatabaseFilePath()). QGIS also features a GUI for management of local custom CRS definitions.

There are therefore two databases: one for shipped CRS definitions and one for custom CRS definitions. Custom CRS have internal IDs (accessible with srsid()) greater or equal to USER_CRS_START_ID. The local CRS databases should never be accessed directly with SQLite functions, instead you should use QgsCoordinateReferenceSystem API for CRS lookups and for managements of custom CRS.

Validation

In some cases (most prominently when loading a map layer), QGIS will try to ensure that the given map layer CRS is valid using validate() call. If not, a custom validation function will be called - such function may for example show a GUI for manual CRS selection. The validation function is configured using setCustomCrsValidation(). If validation fails or no validation function is set, the default CRS is assigned (WGS84). QGIS application registers its validation function that will act according to user's settings (either show CRS selector dialog or use project/custom CRS).

Object Construction and Copying

The easiest way of creating CRS instances is to use QgsCoordinateReferenceSystem(const QString&) constructor that automatically recognizes definition format from the given string.

Creation of CRS object involves some queries in a local SQLite database, which may be potentially expensive. Consequently, CRS creation methods use an internal cache to avoid unnecessary database lookups. If the CRS database is modified, then it is necessary to call invalidateCache() to ensure that outdated records are not being returned from the cache.

Since QGIS 2.16 QgsCoordinateReferenceSystem objects are implicitly shared.

Caveats

There are two different flavors of WKT: one is defined by OGC, the other is the standard used by ESRI. They look very similar, but they are not the same. QGIS is able to consume both flavors.

See also
QgsCoordinateTransform

Definition at line 211 of file qgscoordinatereferencesystem.h.

Member Enumeration Documentation

◆ CrsType

Enumeration of types of IDs accepted in createFromId() method.

Enumerator
InternalCrsId 

Internal ID used by QGIS in the local SQLite database.

PostgisCrsId 

SRID used in PostGIS. DEPRECATED – DO NOT USE.

EpsgCrsId 

EPSG code.

Definition at line 221 of file qgscoordinatereferencesystem.h.

◆ Format

Projection definition formats.

Enumerator
FormatWkt 

WKT format (always recommended over proj string format)

FormatProj 

Proj string format.

Definition at line 229 of file qgscoordinatereferencesystem.h.

◆ IdentifierType

Type of identifier string to create.

Since
QGIS 3.10.3
Enumerator
ShortString 

A heavily abbreviated string, for use when a compact representation is required.

MediumString 

A medium-length string, recommended for general purpose use.

FullString 

Full definition – possibly a very lengthy string, e.g. with no truncation of custom WKT definitions.

Definition at line 635 of file qgscoordinatereferencesystem.h.

◆ WktVariant

WKT formatting variants, only used for builds based on Proj >= 6.

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.

WKT1_ESRI 

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

WKT2_2015 

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

WKT2_2015_SIMPLIFIED 

Same as WKT2_2015 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_2018 

Alias for WKT2_2019.

WKT2_2018_SIMPLIFIED 

Alias for WKT2_2019_SIMPLIFIED.

WKT2_2019 

Full WKT2 string, conforming to ISO 19162:2019 / OGC 18-010, with all possible nodes and new keyword names. Non-normative list of differences: WKT2_2019 uses GEOGCRS / BASEGEOGCRS keywords for GeographicCRS.

WKT2_2019_SIMPLIFIED 

WKT2_2019 with the simplification rule of WKT2_SIMPLIFIED.

WKT_PREFERRED 

Preferred format, matching the most recent WKT ISO standard. Currently an alias to WKT2_2019, but may change in future versions.

WKT_PREFERRED_SIMPLIFIED 

Preferred simplified format, matching the most recent WKT ISO standard. Currently an alias to WKT2_2019_SIMPLIFIED, but may change in future versions.

WKT_PREFERRED_GDAL 

Preferred format for conversion of CRS to WKT for use with the GDAL library.

Definition at line 674 of file qgscoordinatereferencesystem.h.

Constructor & Destructor Documentation

◆ QgsCoordinateReferenceSystem() [1/4]

QgsCoordinateReferenceSystem::QgsCoordinateReferenceSystem ( )

Constructs an invalid CRS object.

Definition at line 103 of file qgscoordinatereferencesystem.cpp.

◆ ~QgsCoordinateReferenceSystem()

QgsCoordinateReferenceSystem::~QgsCoordinateReferenceSystem ( )

Definition at line 240 of file qgscoordinatereferencesystem.cpp.

◆ QgsCoordinateReferenceSystem() [2/4]

QgsCoordinateReferenceSystem::QgsCoordinateReferenceSystem ( const QString &  definition)
explicit

Constructs a CRS object from a string definition using createFromString()

It supports the following formats:

If no prefix is specified, WKT definition is assumed.

Parameters
definitionA String containing a coordinate reference system definition.
See also
createFromString()

Definition at line 110 of file qgscoordinatereferencesystem.cpp.

◆ QgsCoordinateReferenceSystem() [3/4]

QgsCoordinateReferenceSystem::QgsCoordinateReferenceSystem ( long  id,
CrsType  type = PostgisCrsId 
)
explicit

Constructor.

A CRS object using a PostGIS SRID, an EPSG code or an internal QGIS CRS ID.

Note
We encourage you to use EPSG code or WKT to describe CRSes in your code wherever possible. Internal QGIS CRS IDs are not guaranteed to be permanent / involatile, and proj strings are a lossy format.
Parameters
idThe ID valid for the chosen CRS ID type
typeOne of the types described in CrsType
Deprecated:
QGIS 3.10 We encourage you to use EPSG codes or WKT to describe CRSes in your code wherever possible. Internal QGIS CRS IDs are not guaranteed to be permanent / involatile, and Proj strings are a lossy format.

Definition at line 116 of file qgscoordinatereferencesystem.cpp.

◆ QgsCoordinateReferenceSystem() [4/4]

QgsCoordinateReferenceSystem::QgsCoordinateReferenceSystem ( const QgsCoordinateReferenceSystem srs)

Copy constructor.

Definition at line 124 of file qgscoordinatereferencesystem.cpp.

Member Function Documentation

◆ authid()

QString QgsCoordinateReferenceSystem::authid ( ) const

Returns the authority identifier for the CRS.

The identifier includes both the authority (e.g., EPSG) and the CRS number (e.g., 4326). This is the best method to use when showing a very short CRS identifier to a user, e.g., "EPSG:4326".

If CRS object is a custom CRS (not found in database), the method will return internal QGIS CRS ID with "QGIS" authority, for example "QGIS:100005"

Returns
the authority identifier for this CRS
See also
description()

Definition at line 1090 of file qgscoordinatereferencesystem.cpp.

◆ bounds()

QgsRectangle QgsCoordinateReferenceSystem::bounds ( ) const

Returns the approximate bounds for the region the CRS is usable within.

The returned bounds represent the latitude and longitude extent for the projection in the WGS 84 CRS.

Since
QGIS 3.0

Definition at line 1365 of file qgscoordinatereferencesystem.cpp.

◆ celestialBodyName()

QString QgsCoordinateReferenceSystem::celestialBodyName ( ) const

Attempts to retrieve the name of the celestial body associated with the CRS (e.g.

"Earth").

Warning
This method requires PROJ 8.1 or later
Exceptions
QgsNotSupportedExceptionon QGIS builds based on PROJ 8.0 or earlier.
Since
QGIS 3.20

Definition at line 1218 of file qgscoordinatereferencesystem.cpp.

◆ coordinateEpoch()

double QgsCoordinateReferenceSystem::coordinateEpoch ( ) const

Returns the coordinate epoch, as a decimal year.

In a dynamic CRS, coordinates of a point on the surface of the Earth may change with time. To be unambiguous the coordinates must always be qualified with the epoch at which they are valid. The coordinate epoch is not necessarily the epoch at which the observation was collected.

Pedantically the coordinate epoch of an observation belongs to the observation, and not to the CRS, however it is often more practical to bind it to the CRS. The coordinate epoch should be specified for dynamic CRS (see isDynamic()).

Warning
The QgsCoordinateTransform class can perform time-dependent transformations between a static and dynamic CRS based on either the source or destination CRS coordinate epoch, however dynamic CRS to dynamic CRS transformations are not currently supported.
Returns
Coordinate epoch as decimal year (e.g. 2021.3), or NaN if not set, or relevant.
See also
setCoordinateEpoch()
Since
QGIS 3.20

Definition at line 1245 of file qgscoordinatereferencesystem.cpp.

◆ createFromId()

bool QgsCoordinateReferenceSystem::createFromId ( long  id,
CrsType  type = PostgisCrsId 
)

Sets this CRS by lookup of the given ID in the CRS database.

Returns
true on success else false
Deprecated:
QGIS 3.10 We encourage you to use EPSG code or WKT to describe CRSes in your code wherever possible. Internal QGIS CRS IDs are not guaranteed to be permanent / involatile, and Proj strings are a lossy format.

Definition at line 244 of file qgscoordinatereferencesystem.cpp.

◆ createFromOgcWmsCrs()

bool QgsCoordinateReferenceSystem::createFromOgcWmsCrs ( const QString &  crs)

Sets this CRS to the given OGC WMS-format Coordinate Reference Systems.

Accepts both "<auth>:<code>" format and OGC URN "urn:ogc:def:crs:<auth>:[<version>]:<code>". It also recognizes "QGIS", "USER", "CUSTOM" authorities, which all have the same meaning and refer to QGIS internal CRS IDs.

Returns
true on success else false
Note
this method uses an internal cache. Call invalidateCache() to clear the cache.
See also
fromOgcWmsCrs()

Definition at line 375 of file qgscoordinatereferencesystem.cpp.

◆ createFromProj()

bool QgsCoordinateReferenceSystem::createFromProj ( const QString &  projString,
bool  identify = true 
)

Sets this CRS by passing it a PROJ style formatted string.

The string will be parsed and the projection and ellipsoid members set and the remainder of the Proj string will be stored in the parameters member. The reason for this is so that we can easily present the user with 'natural language' representation of the projection and ellipsoid by looking them up in the srs.db sqlite database.

We try to match the Proj string to internal QGIS CRS ID using the following logic:

  • ask the Proj library to identify the CRS to a standard registered CRS (e.g. EPSG codes)
  • if no match is found, compare the CRS to all user CRSes, using the Proj library to determine CRS equivalence (hence making the match parameter order insensitive)
  • if none of the above match, use the Proj string to create the CRS and do not associated an internal CRS ID to it.
Parameters
projStringA Proj format string
identifyif false, no attempts will be made to match the proj string against known CRS authorities. This is much faster, but should only ever be used when it is known in advance that the definition does not correspond to a known or user CRS. This argument is not available in Python.
Returns
true on success else false
Note
Some members may be left blank if no match can be found in CRS database.
This method uses an internal cache. Call invalidateCache() to clear the cache.
See also
fromProj()
Since
QGIS 3.10.3

Definition at line 882 of file qgscoordinatereferencesystem.cpp.

◆ createFromProj4()

bool QgsCoordinateReferenceSystem::createFromProj4 ( const QString &  projString)

Sets this CRS by passing it a PROJ style formatted string.

The string will be parsed and the projection and ellipsoid members set and the remainder of the Proj string will be stored in the parameters member. The reason for this is so that we can easily present the user with 'natural language' representation of the projection and ellipsoid by looking them up in the srs.db sqlite database.

We try to match the Proj string to internal QGIS CRS ID using the following logic:

  • ask the Proj library to identify the CRS to a standard registered CRS (e.g. EPSG codes)
  • if no match is found, compare the CRS to all user CRSes, using the Proj library to determine CRS equivalence (hence making the match parameter order insensitive)
  • if none of the above match, use the Proj string to create the CRS and do not associated an internal CRS ID to it.
Parameters
projStringA Proj format string
Returns
true on success else false
Note
Some members may be left blank if no match can be found in CRS database.
This method uses an internal cache. Call invalidateCache() to clear the cache.
See also
fromProj()
Deprecated:
QGIS 3.10 Use createFromProj() instead

Definition at line 877 of file qgscoordinatereferencesystem.cpp.

◆ createFromSrid()

bool QgsCoordinateReferenceSystem::createFromSrid ( long  srid)

Sets this CRS by lookup of the given PostGIS SRID in the CRS database.

Parameters
sridThe PostGIS SRID for the desired spatial reference system.
Returns
true on success else false
Deprecated:
QGIS 3.10 Use alternative methods for SRS construction instead – this method was specifically created for use by the postgres provider alone, and using it elsewhere will lead to subtle bugs.

Definition at line 502 of file qgscoordinatereferencesystem.cpp.

◆ createFromSrsId()

bool QgsCoordinateReferenceSystem::createFromSrsId ( long  srsId)

Sets this CRS by lookup of internal QGIS CRS ID in the CRS database.

If the srsid is < USER_CRS_START_ID, system CRS database is used, otherwise user's local CRS database from home directory is used.

Parameters
srsIdThe internal QGIS CRS ID for the desired spatial reference system.
Returns
true on success else false
Note
this method uses an internal cache. Call invalidateCache() to clear the cache.
See also
fromSrsId()
Warning
This method is highly discouraged, and CRS objects should instead be constructed using auth:id codes or WKT strings

Definition at line 545 of file qgscoordinatereferencesystem.cpp.

◆ createFromString()

bool QgsCoordinateReferenceSystem::createFromString ( const QString &  definition)

Set up this CRS from a string definition.

It supports the following formats:

If no prefix is specified, WKT definition is assumed.

Parameters
definitionA String containing a coordinate reference system definition.
Returns
true on success else false

Definition at line 267 of file qgscoordinatereferencesystem.cpp.

◆ createFromUserInput()

bool QgsCoordinateReferenceSystem::createFromUserInput ( const QString &  definition)

Set up this CRS from various text formats.

Valid formats: WKT string, "EPSG:n", "EPSGA:n", "AUTO:proj_id,unit_id,lon0,lat0", "urn:ogc:def:crs:EPSG::n", PROJ string, filename (with WKT, XML or PROJ string), well known name (such as NAD27, NAD83, WGS84 or WGS72), ESRI::[WKT string] (directly or in a file), "IGNF:xxx"

For more details on supported formats see OGRSpatialReference::SetFromUserInput() ( https://gdal.org/doxygen/classOGRSpatialReference.html#aec3c6a49533fe457ddc763d699ff8796 )

Parameters
definitionA String containing a coordinate reference system definition.
Returns
true on success else false
Note
this function generates a WKT string using OSRSetFromUserInput() and passes it to createFromWkt() function.

Definition at line 337 of file qgscoordinatereferencesystem.cpp.

◆ createFromWkt()

bool QgsCoordinateReferenceSystem::createFromWkt ( const QString &  wkt)

Sets this CRS using a WKT definition.

If EPSG code of the WKT definition can be determined, it is extracted and createFromOgcWmsCrs() is used to initialize the object.

Parameters
wktThe WKT for the desired spatial reference system.
Returns
true on success else false
Note
Some members may be left blank if no match can be found in CRS database.
this method uses an internal cache. Call invalidateCache() to clear the cache.
See also
fromWkt()

Definition at line 794 of file qgscoordinatereferencesystem.cpp.

◆ customCrsValidation()

CUSTOM_CRS_VALIDATION QgsCoordinateReferenceSystem::customCrsValidation ( )
static

Gets custom function.

Note
not available in Python bindings

Definition at line 2013 of file qgscoordinatereferencesystem.cpp.

◆ datumEnsemble()

QgsDatumEnsemble QgsCoordinateReferenceSystem::datumEnsemble ( ) const

Attempts to retrieve datum ensemble details from the CRS.

If the CRS does not use a datum ensemble then an invalid QgsDatumEnsemble will be returned.

Warning
This method requires PROJ 8.0 or later
Exceptions
QgsNotSupportedExceptionon QGIS builds based on PROJ 7 or earlier.
Since
QGIS 3.20

Definition at line 1250 of file qgscoordinatereferencesystem.cpp.

◆ description()

QString QgsCoordinateReferenceSystem::description ( ) const

Returns the descriptive name of the CRS, e.g., "WGS 84" or "GDA 94 / Vicgrid94".

Note
an empty string will be returned if the description is not available for the CRS
See also
authid()
userFriendlyIdentifier()

Definition at line 1095 of file qgscoordinatereferencesystem.cpp.

◆ ellipsoidAcronym()

QString QgsCoordinateReferenceSystem::ellipsoidAcronym ( ) const

Returns the ellipsoid acronym for the ellipsoid used by the CRS.

Returns
the official authority:code identifier for the ellipsoid, or PARAMETER:MAJOR:MINOR for custom ellipsoids
Note
an empty string will be returned if the ellipsoidAcronym is not available for the CRS
See also
projectionAcronym()

Definition at line 1146 of file qgscoordinatereferencesystem.cpp.

◆ factors()

QgsProjectionFactors QgsCoordinateReferenceSystem::factors ( const QgsPoint point) const

Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence for the CRS at the given geodetic point (in geographic coordinates).

Depending on the underlying projection values will be calculated either numerically (default) or analytically. The function also calculates the partial derivatives of the given coordinate.

Note
Internally uses the proj library proj_factors API to calculate the factors.
Since
QGIS 3.20

Definition at line 1296 of file qgscoordinatereferencesystem.cpp.

◆ findMatchingProj()

long QgsCoordinateReferenceSystem::findMatchingProj ( )

Walks the CRS databases (both system and user database) trying to match stored PROJ string to a database entry in order to fill in further pieces of information about CRS.

Note
The ellipsoid and projection acronyms must be set as well as the proj string!
Returns
long the SrsId of the matched CRS, zero if no match was found
Deprecated:
QGIS 3.10 Not used in Proj >= 6 based builds

Definition at line 1597 of file qgscoordinatereferencesystem.cpp.

◆ fromEpsgId()

QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromEpsgId ( long  epsg)
static

Creates a CRS from a given EPSG ID.

Parameters
epsgepsg CRS ID
Returns
matching CRS, or an invalid CRS if string could not be matched
Since
QGIS 3.0

Definition at line 200 of file qgscoordinatereferencesystem.cpp.

◆ fromOgcWmsCrs()

QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromOgcWmsCrs ( const QString &  ogcCrs)
static

Creates a CRS from a given OGC WMS-format Coordinate Reference System string.

Parameters
ogcCrsOGR compliant CRS definition, e.g., "EPSG:4326"
Returns
matching CRS, or an invalid CRS if string could not be matched
See also
createFromOgcWmsCrs()
Since
QGIS 3.0

Definition at line 193 of file qgscoordinatereferencesystem.cpp.

◆ fromProj()

QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromProj ( const QString &  proj)
static

Creates a CRS from a proj style formatted string.

Parameters
projproj format string
Returns
matching CRS, or an invalid CRS if string could not be matched
See also
createFromProj()
Since
QGIS 3.10.3

Definition at line 219 of file qgscoordinatereferencesystem.cpp.

◆ fromProj4()

QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromProj4 ( const QString &  proj4)
static

Creates a CRS from a proj style formatted string.

Returns
matching CRS, or an invalid CRS if string could not be matched
See also
createFromProj()
Deprecated:
QGIS 3.10 Use fromProj() instead.

Definition at line 214 of file qgscoordinatereferencesystem.cpp.

◆ fromSrsId()

QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromSrsId ( long  srsId)
static

Creates a CRS from a specified QGIS SRS ID.

Parameters
srsIdinternal QGIS SRS ID
Returns
matching CRS, or an invalid CRS if ID could not be found
See also
createFromSrsId()
validSrsIds()
Since
QGIS 3.0

Definition at line 233 of file qgscoordinatereferencesystem.cpp.

◆ fromWkt()

QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromWkt ( const QString &  wkt)
static

Creates a CRS from a WKT spatial ref sys definition string.

Parameters
wktWKT for the desired spatial reference system.
Returns
matching CRS, or an invalid CRS if string could not be matched
See also
createFromWkt()
Since
QGIS 3.0

Definition at line 226 of file qgscoordinatereferencesystem.cpp.

◆ geographicCrsAuthId()

QString QgsCoordinateReferenceSystem::geographicCrsAuthId ( ) const

Returns auth id of related geographic CRS.

Definition at line 2614 of file qgscoordinatereferencesystem.cpp.

◆ hasAxisInverted()

bool QgsCoordinateReferenceSystem::hasAxisInverted ( ) const

Returns whether axis is inverted (e.g., for WMS 1.3) for the CRS.

Returns
true if CRS axis is inverted

Definition at line 783 of file qgscoordinatereferencesystem.cpp.

◆ invalidateCache()

void QgsCoordinateReferenceSystem::invalidateCache ( bool  disableCache = false)
static

Clears the internal cache used to initialize QgsCoordinateReferenceSystem objects.

This should be called whenever the srs database has been modified in order to ensure that outdated CRS objects are not created.

If disableCache is true then the inbuilt cache will be completely disabled. This argument is for internal use only.

Since
QGIS 3.0

Definition at line 2710 of file qgscoordinatereferencesystem.cpp.

◆ isDynamic()

bool QgsCoordinateReferenceSystem::isDynamic ( ) const

Returns true if the CRS is a dynamic CRS.

A dynamic CRS relies on a dynamic datum, that is a datum that is not plate-fixed.

Since
QGIS 3.20

Definition at line 1209 of file qgscoordinatereferencesystem.cpp.

◆ isGeographic()

bool QgsCoordinateReferenceSystem::isGeographic ( ) const

Returns whether the CRS is a geographic CRS (using lat/lon coordinates)

Returns
true if CRS is geographic, or false if it is a projected CRS

Definition at line 1204 of file qgscoordinatereferencesystem.cpp.

◆ isValid()

bool QgsCoordinateReferenceSystem::isValid ( ) const

Returns whether this CRS is correctly initialized and usable.

Definition at line 872 of file qgscoordinatereferencesystem.cpp.

◆ mapUnits()

QgsUnitTypes::DistanceUnit QgsCoordinateReferenceSystem::mapUnits ( ) const

Returns the units for the projection used by the CRS.

Definition at line 1357 of file qgscoordinatereferencesystem.cpp.

◆ operation()

QgsProjOperation QgsCoordinateReferenceSystem::operation ( ) const

Returns information about the PROJ operation associated with the coordinate reference system, for example the projection method used by the CRS.

Since
QGIS 3.20

Definition at line 1335 of file qgscoordinatereferencesystem.cpp.

◆ operator QVariant()

QgsCoordinateReferenceSystem::operator QVariant ( ) const
inline

Allows direct construction of QVariants from QgsCoordinateReferenceSystem.

Definition at line 281 of file qgscoordinatereferencesystem.h.

◆ operator!=()

bool QgsCoordinateReferenceSystem::operator!= ( const QgsCoordinateReferenceSystem srs) const

Overloaded != operator used to compare to CRS's.

Returns opposite bool value to operator ==

Definition at line 1700 of file qgscoordinatereferencesystem.cpp.

◆ operator=()

QgsCoordinateReferenceSystem & QgsCoordinateReferenceSystem::operator= ( const QgsCoordinateReferenceSystem srs)

Assignment operator.

Definition at line 130 of file qgscoordinatereferencesystem.cpp.

◆ operator==()

bool QgsCoordinateReferenceSystem::operator== ( const QgsCoordinateReferenceSystem srs) const

Overloaded == operator used to compare to CRS's.

Internally it will use authid() for comparison.

Definition at line 1673 of file qgscoordinatereferencesystem.cpp.

◆ postgisSrid()

long QgsCoordinateReferenceSystem::postgisSrid ( ) const

Returns PostGIS SRID for the CRS.

Returns
the PostGIS spatial_ref_sys identifier for this CRS (defaults to 0)

Definition at line 1085 of file qgscoordinatereferencesystem.cpp.

◆ projectionAcronym()

QString QgsCoordinateReferenceSystem::projectionAcronym ( ) const

Returns the projection acronym for the projection used by the CRS.

Returns
the official Proj acronym for the projection family
Note
an empty string will be returned if the projectionAcronym is not available for the CRS
See also
ellipsoidAcronym()

Definition at line 1134 of file qgscoordinatereferencesystem.cpp.

◆ projObject()

PJ * QgsCoordinateReferenceSystem::projObject ( ) const

Returns the underlying PROJ PJ object corresponding to the CRS, or nullptr if the CRS is invalid.

This object is only valid for the lifetime of the QgsCoordinateReferenceSystem.

Note
Not available in Python bindings.
Since
QGIS 3.8

Definition at line 2631 of file qgscoordinatereferencesystem.cpp.

◆ pushRecentCoordinateReferenceSystem()

void QgsCoordinateReferenceSystem::pushRecentCoordinateReferenceSystem ( const QgsCoordinateReferenceSystem crs)
static

Pushes a recently used CRS to the top of the recent CRS list.

Since
QGIS 3.10.3

Definition at line 2679 of file qgscoordinatereferencesystem.cpp.

◆ readXml()

bool QgsCoordinateReferenceSystem::readXml ( const QDomNode &  node)

Restores state from the given DOM node.

If it fails or if the node is empty, a default empty CRS will be returned.

Parameters
nodeThe node from which state will be restored
Returns
bool true on success, false on failure

Definition at line 1755 of file qgscoordinatereferencesystem.cpp.

◆ recentCoordinateReferenceSystems()

QList< QgsCoordinateReferenceSystem > QgsCoordinateReferenceSystem::recentCoordinateReferenceSystems ( )
static

Returns a list of recently used CRS.

Since
QGIS 3.10.3

Definition at line 2648 of file qgscoordinatereferencesystem.cpp.

◆ recentProjections()

QStringList QgsCoordinateReferenceSystem::recentProjections ( )
static

Returns a list of recently used projections.

Returns
list of srsid for recently used projections
Deprecated:
QGIS 3.10 Use recentCoordinateReferenceSystems() instead.

Definition at line 2636 of file qgscoordinatereferencesystem.cpp.

◆ saveAsUserCrs()

long QgsCoordinateReferenceSystem::saveAsUserCrs ( const QString &  name,
Format  nativeFormat = FormatWkt 
)

Saves the CRS as a new custom ("USER") CRS.

Returns the new CRS srsid(), or -1 if the CRS could not be saved.

The nativeFormat argument specifies the format to use when saving the CRS definition. FormatWkt is recommended as it is a lossless format.

Warning
Not all CRS definitions can be represented as a Proj string, so take care when using the FormatProj option.
Note
Since QGIS 3.18, internally this calls QgsCoordinateReferenceSystemRegistry::addUserCrs().

Definition at line 2050 of file qgscoordinatereferencesystem.cpp.

◆ setCoordinateEpoch()

void QgsCoordinateReferenceSystem::setCoordinateEpoch ( double  epoch)

Sets the coordinate epoch, as a decimal year.

In a dynamic CRS (see isDynamic()), coordinates of a point on the surface of the Earth may change with time. To be unambiguous the coordinates must always be qualified with the epoch at which they are valid. The coordinate epoch is not necessarily the epoch at which the observation was collected.

Pedantically the coordinate epoch of an observation belongs to the observation, and not to the CRS, however it is often more practical to bind it to the CRS. The coordinate epoch should be specified for dynamic CRS (see isDynamic()).

Parameters
epochCoordinate epoch as decimal year (e.g. 2021.3)
Warning
The QgsCoordinateTransform class can perform time-dependent transformations between a static and dynamic CRS based on either the source or destination CRS coordinate epoch, however dynamic CRS to dynamic CRS transformations are not currently supported.
See also
coordinateEpoch()
Since
QGIS 3.20

Definition at line 1233 of file qgscoordinatereferencesystem.cpp.

◆ setCustomCrsValidation()

void QgsCoordinateReferenceSystem::setCustomCrsValidation ( CUSTOM_CRS_VALIDATION  f)
static

Sets custom function to force valid CRS.

Note
not available in Python bindings

Definition at line 2008 of file qgscoordinatereferencesystem.cpp.

◆ setupESRIWktFix()

void QgsCoordinateReferenceSystem::setupESRIWktFix ( )
static

Make sure that ESRI WKT import is done properly.

This is required for proper shapefile CRS import when using gdal>= 1.9.

Note
This function is called by createFromUserInput() and QgsOgrProvider::crs(), there is usually no need to call it from elsewhere.
This function sets CPL config option GDAL_FIX_ESRI_WKT to a proper value, unless it has been set by the user through the commandline or an environment variable. For more details refer to OGRSpatialReference::morphFromESRI() .
Deprecated:
QGIS 3.10 Not used on builds based on Proj version 6 or later

Definition at line 354 of file qgscoordinatereferencesystem.cpp.

◆ setValidationHint()

void QgsCoordinateReferenceSystem::setValidationHint ( const QString &  html)

Set user hint for validation.

Definition at line 2040 of file qgscoordinatereferencesystem.cpp.

◆ srsid()

long QgsCoordinateReferenceSystem::srsid ( ) const

Returns the internal CRS ID, if available.

Returns
the internal sqlite3 srs.db primary key for this CRS

Definition at line 1080 of file qgscoordinatereferencesystem.cpp.

◆ syncDatabase()

int QgsCoordinateReferenceSystem::syncDatabase ( )
static

Update proj.4 parameters in our database from proj.4.

Returns
number of updated CRS on success and negative number of failed updates in case of errors.
Note
This is used internally and should not be necessary to call in client code

Definition at line 2287 of file qgscoordinatereferencesystem.cpp.

◆ toProj()

QString QgsCoordinateReferenceSystem::toProj ( ) const

Returns a Proj string representation of this CRS.

If proj and ellps keys are found in the parameters, they will be stripped out and the projection and ellipsoid acronyms will be overridden with these.

Returns
Proj format string that defines this CRS.
Warning
Not all CRS definitions can be represented by Proj strings. An empty string will be returned if the CRS could not be represented by a Proj string.
See also
toWkt()
Since
QGIS 3.10.3

Definition at line 1188 of file qgscoordinatereferencesystem.cpp.

◆ toProj4()

QString QgsCoordinateReferenceSystem::toProj4 ( ) const

Returns a Proj string representation of this CRS.

If proj and ellps keys are found in the parameters, they will be stripped out and the projection and ellipsoid acronyms will be overridden with these.

Returns
Proj format string that defines this CRS.
Warning
Not all CRS definitions can be represented by Proj strings. An empty string will be returned if the CRS could not be represented by a Proj string.
See also
toWkt()
Deprecated:
QGIS 3.10 Use toProj() instead.

Definition at line 1183 of file qgscoordinatereferencesystem.cpp.

◆ toWkt()

QString QgsCoordinateReferenceSystem::toWkt ( WktVariant  variant = WKT1_GDAL,
bool  multiline = false,
int  indentationWidth = 4 
) const

Returns a WKT representation of this CRS.

The variant argument specifies the formatting variant to use when creating the WKT string. This is only used on builds based on Proj >= 6, with earlier versions always using WKT1_GDAL.

If multiline is true then a formatted multiline string will be returned, using the specified indentationWidth. This is only used on builds based on Proj >= 6.

See also
toProj()

Definition at line 1705 of file qgscoordinatereferencesystem.cpp.

◆ updateDefinition()

void QgsCoordinateReferenceSystem::updateDefinition ( )

Updates the definition and parameters of the coordinate reference system to their latest values.

This only has an effect if the CRS is a user defined custom CRS, and the definition of that custom CRS has changed. In this case the parameters of the object (such as the proj and WKT string definitions, and other related properties) will be updated to reflect the current definition of the custom CRS.

Any objects which store CRS objects should connect to the QgsApplication::coordinateReferenceSystemRegistry()'s QgsCoordinateReferenceSystemRegistry::userCrsChanged() signal and call this method on their stored CRS objects whenever the signal is emitted in order to update these CRSes to their new definitions.

Since
QGIS 3.18

Definition at line 1393 of file qgscoordinatereferencesystem.cpp.

◆ userFriendlyIdentifier()

QString QgsCoordinateReferenceSystem::userFriendlyIdentifier ( IdentifierType  type = MediumString) const

Returns a user friendly identifier for the CRS.

Depending on the format of the CRS, this may reflect the CRSes registered name, or for CRSes not saved in the database it may reflect the underlying WKT or Proj string definition of the CRS.

In most cases this is the best method to use when showing a friendly identifier for the CRS to a user.

See also
description()
Since
QGIS 3.10.3

Definition at line 1107 of file qgscoordinatereferencesystem.cpp.

◆ validate()

void QgsCoordinateReferenceSystem::validate ( )

Perform some validation on this CRS.

If the CRS doesn't validate the default behavior settings for layers with unknown CRS will be consulted and acted on accordingly. By hell or high water this method will do its best to make sure that this CRS is valid - even if that involves resorting to a hard coded default of geocs:wgs84.

Note
It is not usually necessary to use this function, unless you are trying to force this CRS to be valid.
See also
setCustomCrsValidation(), customCrsValidation()

Definition at line 492 of file qgscoordinatereferencesystem.cpp.

◆ validationHint()

QString QgsCoordinateReferenceSystem::validationHint ( )

Gets user hint for validation.

Definition at line 2045 of file qgscoordinatereferencesystem.cpp.

◆ validSrsIds()

QList< long > QgsCoordinateReferenceSystem::validSrsIds ( )
static

Returns a list of all valid SRS IDs present in the CRS database.

Any of the returned values can be safely passed to fromSrsId() to create a new, valid QgsCoordinateReferenceSystem object.

See also
fromSrsId()
Since
QGIS 3.0

Definition at line 137 of file qgscoordinatereferencesystem.cpp.

◆ writeXml()

bool QgsCoordinateReferenceSystem::writeXml ( QDomNode &  node,
QDomDocument &  doc 
) const

Stores state to the given Dom node in the given document.

Parameters
nodeThe node in which state will be restored
docThe document in which state will be stored
Returns
bool true on success, false on failure

Definition at line 1873 of file qgscoordinatereferencesystem.cpp.

Friends And Related Function Documentation

◆ operator<

bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem c1,
const QgsCoordinateReferenceSystem c2 
)
friend

Definition at line 2819 of file qgscoordinatereferencesystem.cpp.

◆ operator<=

bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem c1,
const QgsCoordinateReferenceSystem c2 
)
friend

Definition at line 2874 of file qgscoordinatereferencesystem.cpp.

◆ operator>

bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem c1,
const QgsCoordinateReferenceSystem c2 
)
friend

Definition at line 2768 of file qgscoordinatereferencesystem.cpp.

◆ operator>=

bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem c1,
const QgsCoordinateReferenceSystem c2 
)
friend

Definition at line 2870 of file qgscoordinatereferencesystem.cpp.

◆ QgsCoordinateReferenceSystemRegistry

Definition at line 1095 of file qgscoordinatereferencesystem.h.

◆ QgsProjContext

friend class QgsProjContext
friend

Definition at line 1069 of file qgscoordinatereferencesystem.h.

◆ TestQgsCoordinateReferenceSystem

friend class TestQgsCoordinateReferenceSystem
friend

Definition at line 1094 of file qgscoordinatereferencesystem.h.

Property Documentation

◆ isGeographic

bool QgsCoordinateReferenceSystem::isGeographic
read

Definition at line 213 of file qgscoordinatereferencesystem.h.

◆ mapUnits

Q_GADGET QgsUnitTypes::DistanceUnit QgsCoordinateReferenceSystem::mapUnits
read

Definition at line 213 of file qgscoordinatereferencesystem.h.


The documentation for this class was generated from the following files: