Class: QgsCoordinateReferenceSystem¶

class qgis.core.QgsCoordinateReferenceSystem¶

Bases: sip.wrapper

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:

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 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 ref crs_construct_and_copy 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 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 also

authid()

See also

createFromOgcWmsCrs()

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 proj library. For example, the definition of WGS84 looks like this:

+proj=longlat +datum=WGS84 +no_defs

See also

toProj()

See also

createFromProj()

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 also

toWkt()

See also

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

QgsCoordinateReferenceSystem() Constructs an invalid CRS object

QgsCoordinateReferenceSystem(definition: str) Constructs a CRS object from a string definition using createFromString()

It supports the following formats:

“EPSG:<code>” - handled with createFromOgcWms()
“POSTGIS:<srid>” - handled with createFromSrid()
“INTERNAL:<srsid>” - handled with createFromSrsId()
“PROJ:<proj>” - handled with createFromProj()
“WKT:<wkt>” - handled with createFromWkt()

If no prefix is specified, WKT definition is assumed.

param definition:: A String containing a coordinate reference system definition.

See also

createFromString()

QgsCoordinateReferenceSystem(id: int, type: QgsCoordinateReferenceSystem.CrsType = QgsCoordinateReferenceSystem.PostgisCrsId) 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.

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

Deprecated since version 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.

QgsCoordinateReferenceSystem(srs: QgsCoordinateReferenceSystem) Copy constructor

Enums

Format

alias of CrsDefinitionFormat

Methods

authid

Returns the authority identifier for the CRS.

axisOrdering

Returns an ordered list of the axis directions reflecting the native axis order for the CRS.

bounds

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

celestialBodyName

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

clearRecentCoordinateReferenceSystems

Cleans the list of recently used CRS.

coordinateEpoch

Returns the coordinate epoch, as a decimal year.

createFromId

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

createFromOgcWmsCrs

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

createFromProj

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

createFromProj4

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

createFromSrid

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

createFromSrsId

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

createFromString

Set up this CRS from a string definition.

createFromUserInput

Set up this CRS from various text formats.

createFromWkt

Sets this CRS using a WKT definition.

datumEnsemble

Attempts to retrieve datum ensemble details from the CRS.

description

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

ellipsoidAcronym

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

factors

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

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.

fromEpsgId

Creates a CRS from a given EPSG ID.

fromOgcWmsCrs

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

fromProj

Creates a CRS from a proj style formatted string.

fromProj4

Creates a CRS from a proj style formatted string.

fromSrsId

Creates a CRS from a specified QGIS SRS ID.

fromWkt

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

geographicCrsAuthId

Returns auth id of related geographic CRS

hasAxisInverted

Returns whether the axis order is inverted for the CRS compared to the order east/north (longitude/latitude).

invalidateCache

Clears the internal cache used to initialize QgsCoordinateReferenceSystem objects.

isDynamic

Returns True if the CRS is a dynamic CRS.

isGeographic

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

isValid

Returns whether this CRS is correctly initialized and usable

mapUnits

Returns the units for the projection used by the CRS.

nativeFormat

Returns the native format for the CRS definition.

operation

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

postgisSrid

Returns PostGIS SRID for the CRS.

projectionAcronym

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

pushRecentCoordinateReferenceSystem

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

readXml

Restores state from the given DOM node.

recentCoordinateReferenceSystems

Returns a list of recently used CRS.

recentProjections

Returns a list of recently used projections

removeRecentCoordinateReferenceSystem

Removes a CRS from the list of recently used CRS.

saveAsUserCrs

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

setCoordinateEpoch

Sets the coordinate epoch, as a decimal year.

setNativeFormat

Sets the native format for the CRS definition.

setValidationHint

Set user hint for validation

setupESRIWktFix

Make sure that ESRI WKT import is done properly.

srsid

Returns the internal CRS ID, if available.

syncDatabase

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

toGeographicCrs

Returns the geographic CRS associated with this CRS object.

toOgcUri

Returns the crs as OGC URI (format: http://www.opengis.net/def/crs/OGC/1.3/CRS84) Returns an empty string on failure.

toProj

Returns a Proj string representation of this CRS.

toProj4

Returns a Proj string representation of this CRS.

toWkt

Returns a WKT representation of this CRS.

type

Returns the type of the CRS.

updateDefinition

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

userFriendlyIdentifier

Returns a user friendly identifier for the CRS.

validSrsIds

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

validate

Perform some validation on this CRS.

validationHint

Gets user hint for validation

writeXml

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

Attributes

EpsgCrsId

FullString

InternalCrsId

MediumString

PostgisCrsId

ShortString

WKT1_ESRI

WKT1_GDAL

WKT2_2015

WKT2_2015_SIMPLIFIED

WKT2_2018

WKT2_2018_SIMPLIFIED

WKT2_2019

WKT2_2019_SIMPLIFIED

WKT_PREFERRED

WKT_PREFERRED_GDAL

WKT_PREFERRED_SIMPLIFIED

staticMetaObject

class CrsType¶: Bases: int

EpsgCrsId = 2¶

Format¶: alias of CrsDefinitionFormat

FullString = 2¶

class IdentifierType¶: Bases: int

InternalCrsId = 0¶

MediumString = 1¶

PostgisCrsId = 1¶

ShortString = 0¶

WKT1_ESRI = 1¶

WKT1_GDAL = 0¶

WKT2_2015 = 2¶

WKT2_2015_SIMPLIFIED = 3¶

WKT2_2018 = 4¶

WKT2_2018_SIMPLIFIED = 5¶

WKT2_2019 = 4¶

WKT2_2019_SIMPLIFIED = 5¶

WKT_PREFERRED = 4¶

WKT_PREFERRED_GDAL = 4¶

WKT_PREFERRED_SIMPLIFIED = 5¶

class WktVariant¶: Bases: int

authid(self) → str¶

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”

Return type:: str
Returns:: the authority identifier for this CRS

See also

description()

axisOrdering(self) → List[Qgis.CrsAxisDirection]¶

Returns an ordered list of the axis directions reflecting the native axis order for the CRS.

New in version 3.26.

Return type:: List[Qgis.CrsAxisDirection]

bounds(self) → QgsRectangle¶

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.

New in version 3.0.

Return type:: QgsRectangle

celestialBodyName(self) → str¶

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

Raises:: QgsNotSupportedException – on QGIS builds based on PROJ 8.0 or earlier.

New in version 3.20.

Return type:: str

clearRecentCoordinateReferenceSystems()¶: Cleans the list of recently used CRS.

New in version 3.32.

coordinateEpoch(self) → float¶

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.

Return type:: float
Returns:: Coordinate epoch as decimal year (e.g. 2021.3), or NaN if not set, or relevant.

See also

setCoordinateEpoch()

New in version 3.20.

createFromId(self, id: int, type: QgsCoordinateReferenceSystem.CrsType = QgsCoordinateReferenceSystem.PostgisCrsId) → bool¶

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

Return type:: bool
Returns:: True on success else False

Deprecated since version 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.

Parameters:

id (int) –
type (QgsCoordinateReferenceSystem.CrsType = QgsCoordinateReferenceSystem.PostgisCrsId) –

createFromOgcWmsCrs(self, crs: str) → bool¶

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.

Return type:: bool
Returns:: True on success else False

Note

this method uses an internal cache. Call invalidateCache() to clear the cache.

See also

fromOgcWmsCrs()

Parameters:: crs (str) –

createFromProj(self, projString: str) → bool¶

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:

projString (str) – A Proj format string
identify – if 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.

Return type:

bool

Returns:

True on success else False

Note

Some members may be left blank if no match can be found in CRS database.

Note

This method uses an internal cache. Call invalidateCache() to clear the cache.

See also

fromProj()

New in version 3.10.3.

createFromProj4(self, projString: str) → bool¶

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:: projString (str) – A Proj format string
Return type:: bool
Returns:: True on success else False

Note

Some members may be left blank if no match can be found in CRS database.

Note

This method uses an internal cache. Call invalidateCache() to clear the cache.

See also

fromProj()

Deprecated since version QGIS: 3.10 Use createFromProj() instead

createFromSrid(self, srid: int) → bool¶

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

Parameters:: srid (int) – The PostGIS SRID for the desired spatial reference system.
Return type:: bool
Returns:: True on success else False

Deprecated since version 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.

createFromSrsId(self, srsId: int) → bool¶

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:: srsId (int) – The internal QGIS CRS ID for the desired spatial reference system.
Return type:: bool
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

createFromString(self, definition: str) → bool¶

Set up this CRS from a string definition.

It supports the following formats:

“EPSG:<code>” - handled with createFromOgcWms()
“POSTGIS:<srid>” - handled with createFromSrid()
“INTERNAL:<srsid>” - handled with createFromSrsId()
“PROJ:<proj>” - handled with createFromProj()
“WKT:<wkt>” - handled with createFromWkt()

If no prefix is specified, WKT definition is assumed.

Parameters:: definition (str) – A String containing a coordinate reference system definition.
Return type:: bool
Returns:: True on success else False

createFromUserInput(self, definition: str) → bool¶

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:: definition (str) – A String containing a coordinate reference system definition.
Return type:: bool
Returns:: True on success else False

Note

this function generates a WKT string using OSRSetFromUserInput() and passes it to createFromWkt() function.

createFromWkt(self, wkt: str) → bool¶

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:: wkt (str) – The WKT for the desired spatial reference system.
Return type:: bool
Returns:: True on success else False

Note

Some members may be left blank if no match can be found in CRS database.

Note

this method uses an internal cache. Call invalidateCache() to clear the cache.

See also

fromWkt()

datumEnsemble(self) → QgsDatumEnsemble¶

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.

Note

In the case of a compound crs, this method will always return the datum ensemble for the horizontal component.

Warning

This method requires PROJ 8.0 or later

Raises:: QgsNotSupportedException – on QGIS builds based on PROJ 7 or earlier.

New in version 3.20.

Return type:: QgsDatumEnsemble

description(self) → str¶

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

See also

userFriendlyIdentifier()

Return type:: str

ellipsoidAcronym(self) → str¶

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

Return type:: str
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()

factors(self, point: QgsPoint) → QgsProjectionFactors¶

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.

New in version 3.20.

Parameters:: point (QgsPoint) –
Return type:: QgsProjectionFactors

findMatchingProj(self) → int¶

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!

Return type:: int
Returns:: long the SrsId of the matched CRS, zero if no match was found

Deprecated since version QGIS: 3.10 Not used in Proj >= 6 based builds

fromEpsgId(epsg: int) → QgsCoordinateReferenceSystem¶

Creates a CRS from a given EPSG ID.

Parameters:: epsg (int) – epsg CRS ID
Return type:: QgsCoordinateReferenceSystem
Returns:: matching CRS, or an invalid CRS if string could not be matched

New in version 3.0.

fromOgcWmsCrs(ogcCrs: str) → QgsCoordinateReferenceSystem¶

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

Parameters:: ogcCrs (str) – OGR compliant CRS definition, e.g., “EPSG:4326”
Return type:: QgsCoordinateReferenceSystem
Returns:: matching CRS, or an invalid CRS if string could not be matched

See also

createFromOgcWmsCrs()

New in version 3.0.

fromProj(proj: str) → QgsCoordinateReferenceSystem¶

Creates a CRS from a proj style formatted string.

Parameters:: proj (str) – proj format string
Return type:: QgsCoordinateReferenceSystem
Returns:: matching CRS, or an invalid CRS if string could not be matched

See also

createFromProj()

New in version 3.10.3.

fromProj4(proj4: str) → QgsCoordinateReferenceSystem¶

Creates a CRS from a proj style formatted string.

Return type:: QgsCoordinateReferenceSystem
Returns:: matching CRS, or an invalid CRS if string could not be matched

See also

createFromProj()

Deprecated since version QGIS: 3.10 Use fromProj() instead.

Parameters:: proj4 (str) –

fromSrsId(srsId: int) → QgsCoordinateReferenceSystem¶

Creates a CRS from a specified QGIS SRS ID.

Parameters:: srsId (int) – internal QGIS SRS ID
Return type:: QgsCoordinateReferenceSystem
Returns:: matching CRS, or an invalid CRS if ID could not be found

See also

createFromSrsId()

See also

validSrsIds()

New in version 3.0.

fromWkt(wkt: str) → QgsCoordinateReferenceSystem¶

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

Parameters:: wkt (str) – WKT for the desired spatial reference system.
Return type:: QgsCoordinateReferenceSystem
Returns:: matching CRS, or an invalid CRS if string could not be matched

See also

createFromWkt()

New in version 3.0.

geographicCrsAuthId(self) → str¶

Returns auth id of related geographic CRS

Return type:: str

hasAxisInverted(self) → bool¶

Returns whether the axis order is inverted for the CRS compared to the order east/north (longitude/latitude). E.g. with WMS 1.3 the axis order for EPSG:4326 is north/east (latitude/longitude), i.e. inverted.

Return type:: bool
Returns:: True if CRS axis is inverted

See also

axisOrdering()

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.

New in version 3.0.

isDynamic(self) → bool¶

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.

New in version 3.20.

Return type:: bool

isGeographic(self) → bool¶

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

Return type:: bool
Returns:: True if CRS is geographic, or False if it is a projected CRS

isValid(self) → bool¶

Returns whether this CRS is correctly initialized and usable

Return type:: bool

mapUnits(self) → Qgis.DistanceUnit¶

Returns the units for the projection used by the CRS.

Note

In the case of a compound CRS, this method will always return the units for the horizontal component.

Return type:: Qgis.DistanceUnit

nativeFormat(self) → Qgis.CrsDefinitionFormat¶

Returns the native format for the CRS definition.

Note

This has no effect on the underlying definition of the CRS, rather it controls what format to use when displaying the CRS’s definition to users.

See also

setNativeFormat()

New in version 3.24.

Return type:: Qgis.CrsDefinitionFormat

operation(self) → QgsProjOperation¶

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

New in version 3.20.

Return type:: QgsProjOperation

postgisSrid(self) → int¶

Returns PostGIS SRID for the CRS.

Return type:: int
Returns:: the PostGIS spatial_ref_sys identifier for this CRS (defaults to 0)

projectionAcronym(self) → str¶

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

Return type:: str
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()

pushRecentCoordinateReferenceSystem(crs: QgsCoordinateReferenceSystem)¶

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

New in version 3.10.3.

Parameters:: crs (QgsCoordinateReferenceSystem) –

readXml(self, node: QDomNode) → bool¶

Restores state from the given DOM node. If it fails or if the node is empty, a default empty CRS will be returned.

Parameters:: node (QDomNode) – The node from which state will be restored
Return type:: bool
Returns:: bool True on success, False on failure

recentCoordinateReferenceSystems() → List[QgsCoordinateReferenceSystem]¶

Returns a list of recently used CRS.

New in version 3.10.3.

Return type:: List[QgsCoordinateReferenceSystem]

recentProjections() → List[str]¶

Returns a list of recently used projections

Return type:: List[str]
Returns:: list of srsid for recently used projections

Deprecated since version QGIS: 3.10 Use recentCoordinateReferenceSystems() instead.

removeRecentCoordinateReferenceSystem(crs: QgsCoordinateReferenceSystem)¶

Removes a CRS from the list of recently used CRS.

New in version 3.32.

Parameters:: crs (QgsCoordinateReferenceSystem) –

saveAsUserCrs(self, name: str, nativeFormat: Qgis.CrsDefinitionFormat = Qgis.CrsDefinitionFormat.Wkt) → int¶

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

Parameters:

name (str) –
nativeFormat (Qgis.CrsDefinitionFormat = Qgis.CrsDefinitionFormat.Wkt) –

Return type:

int

setCoordinateEpoch(self, epoch: float)¶

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:: epoch (float) – Coordinate 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()

New in version 3.20.

setNativeFormat(self, format: Qgis.CrsDefinitionFormat)¶

Sets the native format for the CRS definition.

Note

This has no effect on the underlying definition of the CRS, rather it controls what format to use when displaying the CRS’s definition to users.

See also

nativeFormat()

New in version 3.24.

Parameters:: format (Qgis.CrsDefinitionFormat) –

setValidationHint(self, html: str)¶

Set user hint for validation

Parameters:: html (str) –

setupESRIWktFix()¶: 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.

Note

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 since version QGIS: 3.10 Not used on builds based on Proj version 6 or later

srsid(self) → int¶

Returns the internal CRS ID, if available.

Return type:: int
Returns:: the internal sqlite3 srs.db primary key for this CRS

staticMetaObject = <PyQt5.QtCore.QMetaObject object>¶

syncDatabase() → int¶

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

Return type:: int
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

toGeographicCrs(self) → QgsCoordinateReferenceSystem¶

Returns the geographic CRS associated with this CRS object.

May return an invalid CRS if the geographic CRS could not be determined.

Note

This method will always return a longitude, latitude ordered CRS.

New in version 3.24.

Return type:: QgsCoordinateReferenceSystem

toOgcUri(self) → str¶

Returns the crs as OGC URI (format: http://www.opengis.net/def/crs/OGC/1.3/CRS84) Returns an empty string on failure.

New in version 3.30.

Return type:: str

toProj(self) → str¶

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.

Return type:: str
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()

New in version 3.10.3.

toProj4(self) → str¶

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.

Return type:: str
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 since version QGIS: 3.10 Use toProj() instead.

toWkt(self, variant: QgsCoordinateReferenceSystem.WktVariant = QgsCoordinateReferenceSystem.WKT1_GDAL, multiline: bool = False, indentationWidth: int = 4) → str¶

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

Parameters:

variant (QgsCoordinateReferenceSystem.WktVariant = QgsCoordinateReferenceSystem.WKT1_GDAL) –
multiline (bool = False) –
indentationWidth (int = 4) –

Return type:

str

type(self) → Qgis.CrsType¶

Returns the type of the CRS.

New in version 3.34.

Return type:: Qgis.CrsType

updateDefinition(self)¶

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.

New in version 3.18.

userFriendlyIdentifier(self, type: QgsCoordinateReferenceSystem.IdentifierType = QgsCoordinateReferenceSystem.MediumString) → str¶

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

New in version 3.10.3.

Parameters:: type (QgsCoordinateReferenceSystem.IdentifierType = QgsCoordinateReferenceSystem.MediumString) –
Return type:: str

validSrsIds() → object¶

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

New in version 3.0.

Return type:: object

validate(self)¶: 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()

validationHint(self) → str¶

Gets user hint for validation

Return type:: str

writeXml(self, node: QDomNode, doc: QDomDocument) → bool¶

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

Parameters:

node (QDomNode) – The node in which state will be restored
doc (QDomDocument) – The document in which state will be stored

Return type:

bool

Returns:

bool True on success, False on failure