QgsCoordinateReferenceSystem class

This class represents a coordinate reference system (CRS).

Object Construction and Copying
Reference

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:

Geographic coordinate systems - based on a geodetic datum, normally with coordinates being latitude/longitude in degrees. The most common one is World Geodetic System 84 (WGS84).
Projected coordinate systems - based on a geodetic datum with coordinates projected to a plane, typically using meters or feet as units. Common projected coordinate systems are Universal Transverse Mercator or Albers Equal Area.

Internally QGIS uses proj4 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(), toProj4(), 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.toProj4()))
else:
    print("Invalid 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:

Authority and Code. Also referred to as OGC WMS format within QGIS as they have been widely used in OGC standards. These are encoded as <auth>:<code>, for example EPSG:4326 refers to WGS84 system. EPSG is the most commonly used authority that covers a wide range of coordinate systems around the world.
An extended variant of this format is OGC URN. Syntax of URN for CRS definition is urn:ogc:def:crs:<auth>:[<version>]:<code>. This class can also parse URNs (versions are currently ignored). For example, WGS84 may be encoded as urn:ogc:def:crs:OGC:1.3:CRS84.
QGIS adds support for "USER" authority that refers to IDs used internally in QGIS. This variant is best avoided or used with caution as the IDs are not permanent and they refer to different CRS on different machines or user profiles.
See authid() and createFromOgcWmsCrs() methods.
PROJ string. This is a string consisting of a series of key/value pairs in the following format: +param1=value1 +param2=value2 [...]. This is the format natively used by the underlying proj4 library. For example, the definition of WGS84 looks like this:
```
+proj=longlat +datum=WGS84 +no_defs
```
See toProj4() and createFromProj4() methods.

Well-known text (WKT). Defined by Open Geospatial Consortium (OGC), this is another common format to define CRS. For WGS84 the OGC WKT definition is the following:

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 toWkt() and createFromWkt() methods.

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.

Public types

enum CrsType { InternalCrsId, PostgisCrsId, EpsgCrsId }: Enumeration of types of IDs accepted in createFromId() method.

Public static functions

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

Constructors, destructors, conversion operators

QgsCoordinateReferenceSystem(): Constructs an invalid CRS object.
QgsCoordinateReferenceSystem(const QString& definition) explicit: Constructs a CRS object from a string definition using createFromString()
QgsCoordinateReferenceSystem(long id, CrsType type = PostgisCrsId) explicit: Constructor a CRS object using a PostGIS SRID, an EPSG code or an internal QGIS CRS ID.
QgsCoordinateReferenceSystem(const QgsCoordinateReferenceSystem& srs): Copy constructor.
operator QVariant() const: Allows direct construction of QVariants from QgsCoordinateReferenceSystem.

Public functions

auto authid() const -> QString: Returns the authority identifier for the CRS.
auto bounds() const -> QgsRectangle: Returns the approximate bounds for the region the CRS is usable within.
auto createFromId(long id, CrsType type = PostgisCrsId) -> bool: Sets this CRS by lookup of the given ID in the CRS database.
auto createFromOgcWmsCrs(const QString& crs) -> bool: Sets this CRS to the given OGC WMS-format Coordinate Reference Systems.
auto createFromProj4(const QString& projString) -> bool: Sets this CRS by passing it a PROJ style formatted string.
auto createFromSrid(long srid) -> bool: Sets this CRS by lookup of the given PostGIS SRID in the CRS database.
auto createFromSrsId(long srsId) -> bool: Sets this CRS by lookup of internal QGIS CRS ID in the CRS database.
auto createFromString(const QString& definition) -> bool: Set up this CRS from a string definition.
auto createFromUserInput(const QString& definition) -> bool: Set up this CRS from various text formats.
auto createFromWkt(const QString& wkt) -> bool: Sets this CRS using a WKT definition.
auto description() const -> QString: Returns the descriptive name of the CRS, e.g., "WGS 84" or "GDA 94 / Vicgrid94".
auto ellipsoidAcronym() const -> QString: Returns the ellipsoid acronym for the ellipsoid used by the CRS.
auto findMatchingProj() -> long: 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.
auto geographicCrsAuthId() const -> QString: Returns auth id of related geographic CRS.
auto hasAxisInverted() const -> bool: Returns whether axis is inverted (e.g., for WMS 1.3) for the CRS.
auto isGeographic() const -> bool: Returns whether the CRS is a geographic CRS (using lat/lon coordinates)
auto isValid() const -> bool: Returns whether this CRS is correctly initialized and usable.
auto mapUnits() const -> QgsUnitTypes::DistanceUnit: Returns the units for the projection used by the CRS.
auto operator!=(const QgsCoordinateReferenceSystem& srs) const -> bool: Overloaded != operator used to compare to CRS's.
auto operator=(const QgsCoordinateReferenceSystem& srs) -> QgsCoordinateReferenceSystem&: Assignment operator.
auto operator==(const QgsCoordinateReferenceSystem& srs) const -> bool: Overloaded == operator used to compare to CRS's.
auto postgisSrid() const -> long: Returns PostGIS SRID for the CRS.
auto projectionAcronym() const -> QString: Returns the projection acronym for the projection used by the CRS.
auto readXml(const QDomNode& node) -> bool: Restores state from the given DOM node.
auto saveAsUserCrs(const QString& name) -> long: Save the proj4-string as a custom CRS.
void setValidationHint(const QString& html): Set user hint for validation.
auto srsid() const -> long: Returns the internal CRS ID, if available.
auto toProj4() const -> QString: Returns a Proj4 string representation of this CRS.
auto toWkt() const -> QString: Returns a WKT representation of this CRS.
void validate(): Perform some validation on this CRS.
auto validationHint() -> QString: Gets user hint for validation.
auto writeXml(QDomNode& node, QDomDocument& doc) const -> bool: Stores state to the given Dom node in the given document.

Enum documentation

enum QgsCoordinateReferenceSystem::CrsType

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

Enumerators
InternalCrsId	Internal ID used by QGIS in the local SQLite database.
PostgisCrsId	SRID used in PostGIS.
EpsgCrsId	EPSG code.

Function documentation

static CUSTOM_CRS_VALIDATION QgsCoordinateReferenceSystem::customCrsValidation()

Gets custom function.

static Q_INVOKABLE QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromEpsgId(long epsg)

Creates a CRS from a given EPSG ID.

Parameters
epsg	epsg CRS ID
Returns	matching CRS, or an invalid CRS if string could not be matched

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

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

Parameters
ogcCrs	OGR compliant CRS definition, e.g., "EPSG:4326"
Returns	matching CRS, or an invalid CRS if string could not be matched

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

Creates a CRS from a proj4 style formatted string.

Parameters
proj4	proj4 format string
Returns	matching CRS, or an invalid CRS if string could not be matched

static QgsCoordinateReferenceSystem QgsCoordinateReferenceSystem::fromSrsId(long srsId)

Creates a CRS from a specified QGIS SRS ID.

Parameters
srsId	internal QGIS SRS ID
Returns	matching CRS, or an invalid CRS if ID could not be found

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

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

Parameters
wkt	WKT for the desired spatial reference system.
Returns	matching CRS, or an invalid CRS if string could not be matched

static void QgsCoordinateReferenceSystem::invalidateCache()

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.

static QStringList QgsCoordinateReferenceSystem::recentProjections()

Returns a list of recently used projections.

Returns	list of srsid for recently used projections

static void QgsCoordinateReferenceSystem::setCustomCrsValidation(CUSTOM_CRS_VALIDATION f)

Sets custom function to force valid CRS.

static void QgsCoordinateReferenceSystem::setupESRIWktFix()

Make sure that ESRI WKT import is done properly.

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

static int QgsCoordinateReferenceSystem::syncDatabase()

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.

static QList<long> QgsCoordinateReferenceSystem::validSrsIds()

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.

QgsCoordinateReferenceSystem::QgsCoordinateReferenceSystem(const QString& definition) explicit

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

Parameters
definition	A String containing a coordinate reference system definition.

It supports the following formats:

"EPSG:<code>" - handled with createFromOgcWms()
"POSTGIS:<srid>" - handled with createFromSrid()
"INTERNAL:<srsid>" - handled with createFromSrsId()
"PROJ4:<proj4>" - handled with createFromProj4()
"WKT:<wkt>" - handled with createFromWkt()

If no prefix is specified, WKT definition is assumed.

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.

Parameters
id	The ID valid for the chosen CRS ID type
type	One of the types described in CrsType

QString QgsCoordinateReferenceSystem::authid() const

Returns the authority identifier for the CRS.

Returns	the authority identifier for this 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"

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.

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

bool QgsCoordinateReferenceSystem::createFromOgcWmsCrs(const QString& crs)

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

Returns	True on success else false

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.

bool QgsCoordinateReferenceSystem::createFromProj4(const QString& projString)

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

Parameters
projString	A proj4 format string
Returns	True on success else false

The string will be parsed and the projection and ellipsoid members set and the remainder of the proj4 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 proj4 string to internal QGIS CRS ID using the following logic:

perform a whole text search on proj4 string (if not null)
if not match is found, split proj4 into individual parameters and try to find a match where the parameters are in a different order
if none of the above match, use findMatchingProj()

bool QgsCoordinateReferenceSystem::createFromSrid(long srid)

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

Parameters
srid	The PostGIS SRID for the desired spatial reference system.
Returns	True on success else false

bool QgsCoordinateReferenceSystem::createFromSrsId(long srsId)

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

Parameters
srsId	The internal QGIS CRS ID for the desired spatial reference system.
Returns	True on success else false

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

bool QgsCoordinateReferenceSystem::createFromString(const QString& definition)

Set up this CRS from a string definition.

Parameters
definition	A String containing a coordinate reference system definition.
Returns	True on success else false

It supports the following formats:

"EPSG:<code>" - handled with createFromOgcWms()
"POSTGIS:<srid>" - handled with createFromSrid()
"INTERNAL:<srsid>" - handled with createFromSrsId()
"PROJ4:<proj4>" - handled with createFromProj4()
"WKT:<wkt>" - handled with createFromWkt()

If no prefix is specified, WKT definition is assumed.

bool QgsCoordinateReferenceSystem::createFromUserInput(const QString& definition)

Set up this CRS from various text formats.

Parameters
definition	A String containing a coordinate reference system definition.
Returns	True on success else false

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() ( http://www.gdal.org/ogr/classOGRSpatialReference.html#aec3c6a49533fe457ddc763d699ff8796 )

bool QgsCoordinateReferenceSystem::createFromWkt(const QString& wkt)

Sets this CRS using a WKT definition.

Parameters
wkt	The WKT for the desired spatial reference system.
Returns	True on success else false

If EPSG code of the WKT definition can be determined, it is extracted and createFromOgcWmsCrs() is used to initialize the object. Otherwise the WKT will be converted to a proj4 string and createFromProj4() set up the object.

QString QgsCoordinateReferenceSystem::description() const

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

Returns	descriptive name of the CRS

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

QString QgsCoordinateReferenceSystem::ellipsoidAcronym() const

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

Returns	the official proj4 acronym for the ellipoid

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.

Returns	long the SrsId of the matched CRS, zero if no match was found

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

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

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

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

Returns opposite bool value to operator ==

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

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

Internally it will use authid() for comparison.

long QgsCoordinateReferenceSystem::postgisSrid() const

Returns PostGIS SRID for the CRS.

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

QString QgsCoordinateReferenceSystem::projectionAcronym() const

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

Returns	the official proj4 acronym for the projection family

bool QgsCoordinateReferenceSystem::readXml(const QDomNode& node)

Restores state from the given DOM node.

Parameters
node	The node from which state will be restored
Returns	bool True on success, False on failure

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

long QgsCoordinateReferenceSystem::saveAsUserCrs(const QString& name)

Save the proj4-string as a custom CRS.

Copied from QgsCustomProjectionDialog /// Please refactor into SQL handler !!! ///.

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

long QgsCoordinateReferenceSystem::srsid() const

Returns the internal CRS ID, if available.

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

QString QgsCoordinateReferenceSystem::toProj4() const

Returns a Proj4 string representation of this CRS.

Returns	Proj4 format string that defines 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.

QString QgsCoordinateReferenceSystem::toWkt() const

Returns a WKT representation of this CRS.

Returns	string containing WKT of the CRS

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.

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

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

Parameters
node	The node in which state will be restored
doc	The document in which state will be stored
Returns	bool True on success, False on failure