qgscoordinatereferencesystem.sip.in

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/proj/qgscoordinatereferencesystem.h                         *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/











class QgsCoordinateReferenceSystem
{
%Docstring(signature="appended")
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 :py:func:`~isValid`, :py:func:`~authid`, :py:func:`~description`,
:py:func:`~toWkt`, :py:func:`~toProj`, :py:func:`~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 :py:class:`QgsCoordinateTransform` class.

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

.. code-block:: python

     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:


.. code-block:: raw

     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.


.. seealso:: :py:func:`authid`

.. seealso:: :py:func:`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:


.. code-block:: raw

       +proj=longlat +datum=WGS84 +no_defs



.. seealso:: :py:func:`toProj`

.. seealso:: :py:func:`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:


.. code-block:: raw

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



.. seealso:: :py:func:`toWkt`

.. seealso:: :py:func:`createFromWkt`

CRS Database and Custom CRS
---------------------------

The database of CRS shipped with QGIS is stored in a SQLite database (see :py:func:`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 :py:func:`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 :py:func:`~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 :py:class:`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 :py:func:`~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 :py:func:`~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
:py:func:`~invalidateCache` to ensure that outdated records are not being returned from the cache.

Since QGIS 2.16 :py:class:`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.


.. seealso:: :py:class:`QgsCoordinateTransform`
%End

%TypeHeaderCode
#include "qgscoordinatereferencesystem.h"
%End
  public:
    static const QMetaObject staticMetaObject;

  public:

    enum CrsType
    {
      InternalCrsId,
      PostgisCrsId,
      EpsgCrsId
    };

    QgsCoordinateReferenceSystem();
%Docstring
Constructs an invalid CRS object
%End

    ~QgsCoordinateReferenceSystem();


    explicit QgsCoordinateReferenceSystem( const QString &definition );
%Docstring
Constructs a CRS object from a string definition using :py:func:`~QgsCoordinateReferenceSystem.createFromString`

It supports the following formats:

- "EPSG:<code>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromOgcWms`
- "POSTGIS:<srid>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromSrid`
- "INTERNAL:<srsid>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromSrsId`
- "PROJ:<proj>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromProj`
- "WKT:<wkt>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromWkt`

If no prefix is specified, WKT definition is assumed.

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

.. seealso:: :py:func:`createFromString`
%End


 explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) /Deprecated/;
%Docstring
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::
   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.
%End

    QgsCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &srs );
%Docstring
Copy constructor
%End


    operator QVariant() const;

    static QList< long > validSrsIds();
%Docstring
Returns a list of all valid SRS IDs present in the CRS database. Any of the
returned values can be safely passed to :py:func:`~QgsCoordinateReferenceSystem.fromSrsId` to create a new, valid
QgsCoordinateReferenceSystem object.

.. seealso:: :py:func:`fromSrsId`
%End


    static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
%Docstring
Creates a CRS from a given OGC WMS-format Coordinate Reference System string.

:param ogcCrs: OGR compliant CRS definition, e.g., "EPSG:4326"

:return: matching CRS, or an invalid CRS if string could not be matched

.. seealso:: :py:func:`createFromOgcWmsCrs`
%End

    static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
%Docstring
Creates a CRS from a given EPSG ID.

:param epsg: epsg CRS ID

:return: matching CRS, or an invalid CRS if string could not be matched
%End

 static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) /Deprecated/;
%Docstring
Creates a CRS from a proj style formatted string.

:return: matching CRS, or an invalid CRS if string could not be matched

.. seealso:: :py:func:`createFromProj`

.. deprecated::
   QGIS 3.10 Use :py:func:`~QgsCoordinateReferenceSystem.fromProj` instead.
%End

    static QgsCoordinateReferenceSystem fromProj( const QString &proj );
%Docstring
Creates a CRS from a proj style formatted string.

:param proj: proj format string

:return: matching CRS, or an invalid CRS if string could not be matched

.. seealso:: :py:func:`createFromProj`

.. versionadded:: 3.10.3
%End

    static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
%Docstring
Creates a CRS from a WKT spatial ref sys definition string.

:param wkt: WKT for the desired spatial reference system.

:return: matching CRS, or an invalid CRS if string could not be matched

.. seealso:: :py:func:`createFromWkt`
%End

    static QgsCoordinateReferenceSystem fromSrsId( long srsId );
%Docstring
Creates a CRS from a specified QGIS SRS ID.

:param srsId: internal QGIS SRS ID

:return: matching CRS, or an invalid CRS if ID could not be found

.. seealso:: :py:func:`createFromSrsId`

.. seealso:: :py:func:`validSrsIds`
%End



 bool createFromId( long id, CrsType type = PostgisCrsId ) /Deprecated/;
%Docstring
Sets this CRS by lookup of the given ID in the CRS database.

:return: ``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.
%End


    bool createFromOgcWmsCrs( const QString &crs );
%Docstring
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: ``True`` on success else ``False``

.. note::

   this method uses an internal cache. Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

.. seealso:: :py:func:`fromOgcWmsCrs`
%End


 bool createFromSrid( long srid ) /Deprecated/;
%Docstring
Sets this CRS by lookup of the given PostGIS SRID in the CRS database.

:param srid: The PostGIS SRID for the desired spatial reference system.

:return: ``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.
%End

    bool createFromWkt( const QString &wkt );
%Docstring
Sets this CRS using a WKT definition.

If EPSG code of the WKT definition can be determined, it is extracted
and :py:func:`~QgsCoordinateReferenceSystem.createFromOgcWmsCrs` is used to initialize the object.

:param wkt: The WKT for the desired spatial reference system.

:return: ``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 :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

.. seealso:: :py:func:`fromWkt`
%End

    bool createFromSrsId( long srsId );
%Docstring
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.

:param srsId: The internal QGIS CRS ID for the desired spatial reference system.

:return: ``True`` on success else ``False``

.. note::

   this method uses an internal cache. Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

.. seealso:: :py:func:`fromSrsId`

.. warning::

   This method is highly discouraged, and CRS objects should instead be constructed
   using auth:id codes or WKT strings
%End

 bool createFromProj4( const QString &projString ) /Deprecated/;
%Docstring
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.

:param projString: A Proj format string

:return: ``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 :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

.. seealso:: :py:func:`fromProj`

.. deprecated::
   QGIS 3.10 Use :py:func:`~QgsCoordinateReferenceSystem.createFromProj` instead
%End

    bool createFromProj( const QString &projString );
%Docstring
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.

:param projString: A Proj format string
:param 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: ``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 :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

.. seealso:: :py:func:`fromProj`

.. versionadded:: 3.10.3
%End

    bool createFromString( const QString &definition );
%Docstring
Set up this CRS from a string definition.

It supports the following formats:

- "EPSG:<code>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromOgcWms`
- "POSTGIS:<srid>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromSrid`
- "INTERNAL:<srsid>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromSrsId`
- "PROJ:<proj>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromProj`
- "WKT:<wkt>" - handled with :py:func:`~QgsCoordinateReferenceSystem.createFromWkt`

If no prefix is specified, WKT definition is assumed.

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

:return: ``True`` on success else ``False``
%End


    bool createFromUserInput( const QString &definition );
%Docstring
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 )

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

:return: ``True`` on success else ``False``

.. note::

   this function generates a WKT string using OSRSetFromUserInput() and
   passes it to :py:func:`~QgsCoordinateReferenceSystem.createFromWkt` function.
%End

 static void setupESRIWktFix() /Deprecated/;
%Docstring
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 :py:func:`~QgsCoordinateReferenceSystem.createFromUserInput` and :py:func:`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::
   QGIS 3.10 Not used on builds based on Proj version 6 or later
%End

    bool isValid() const;
%Docstring
Returns whether this CRS is correctly initialized and usable
%End

    void validate();
%Docstring
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.

.. seealso:: :py:func:`setCustomCrsValidation`
%End


 long findMatchingProj() /Deprecated/;
%Docstring
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: long the SrsId of the matched CRS, zero if no match was found

.. deprecated::
   QGIS 3.10 Not used in Proj >= 6 based builds
%End

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

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

    bool readXml( const QDomNode &node );
%Docstring
Restores state from the given DOM node.
If it fails or if the node is empty, a default empty CRS will be returned.

:param node: The node from which state will be restored

:return: bool ``True`` on success, ``False`` on failure
%End

    bool writeXml( QDomNode &node, QDomDocument &doc ) const;
%Docstring
Stores state to the given Dom node in the given document.

:param node: The node in which state will be restored
:param doc: The document in which state will be stored

:return: bool ``True`` on success, ``False`` on failure
%End





    long srsid() const;
%Docstring
Returns the internal CRS ID, if available.

:return: the internal sqlite3 srs.db primary key for this CRS
%End


    long postgisSrid() const;
%Docstring
Returns PostGIS SRID for the CRS.

:return: the PostGIS spatial_ref_sys identifier for this CRS (defaults to 0)
%End

    QString authid() const;
%Docstring
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: the authority identifier for this CRS

.. seealso:: :py:func:`description`
%End

    QString description() const;
%Docstring
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

.. seealso:: :py:func:`authid`

.. seealso:: :py:func:`userFriendlyIdentifier`
%End

    QString userFriendlyIdentifier( Qgis::CrsIdentifierType type = Qgis::CrsIdentifierType::MediumString ) const;
%Docstring
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.

.. seealso:: :py:func:`description`

.. versionadded:: 3.10.3
%End

    QString projectionAcronym() const;
%Docstring
Returns the projection acronym for the projection used by the CRS.

:return: the official Proj acronym for the projection family

.. note::

   an empty string will be returned if the projectionAcronym is not available for the CRS

.. seealso:: :py:func:`ellipsoidAcronym`
%End

    QString ellipsoidAcronym() const;
%Docstring
Returns the ellipsoid acronym for the ellipsoid used by the CRS.

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

.. seealso:: :py:func:`projectionAcronym`
%End

    QString toWkt( Qgis::CrsWktVariant variant = Qgis::CrsWktVariant::Wkt1Gdal, bool multiline = false, int indentationWidth = 4 ) const;
%Docstring
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.

.. seealso:: :py:func:`toProj`
%End

 QString toProj4() const /Deprecated/;
%Docstring
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: 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.

.. seealso:: :py:func:`toWkt`

.. deprecated::
   QGIS 3.10 Use :py:func:`~QgsCoordinateReferenceSystem.toProj` instead.
%End

    QString toProj() const;
%Docstring
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: 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.

.. seealso:: :py:func:`toWkt`

.. versionadded:: 3.10.3
%End

    Qgis::CrsType type() const;
%Docstring
Returns the type of the CRS.

.. versionadded:: 3.34
%End

    bool isDeprecated() const;
%Docstring
Returns ``True`` if the CRS is considered deprecated.

.. versionadded:: 3.36
%End

    bool isGeographic() const;
%Docstring
Returns whether the CRS is a geographic CRS (using lat/lon coordinates)

:return: ``True`` if CRS is geographic, or ``False`` if it is a projected CRS
%End

    bool isDynamic() const;
%Docstring
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.

.. versionadded:: 3.20
%End

    QgsDatumEnsemble datumEnsemble() const throw( QgsNotSupportedException );
%Docstring
Attempts to retrieve datum ensemble details from the CRS.

If the CRS does not use a datum ensemble then an invalid :py:class:`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.


.. versionadded:: 3.20
%End

    QString celestialBodyName() const throw( QgsNotSupportedException );
%Docstring
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.


.. versionadded:: 3.20
%End

    void setCoordinateEpoch( double epoch );
%Docstring
Sets the coordinate ``epoch``, as a decimal year.

In a dynamic CRS (see :py:func:`~QgsCoordinateReferenceSystem.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 :py:func:`~QgsCoordinateReferenceSystem.isDynamic`).

:param epoch: Coordinate epoch as decimal year (e.g. 2021.3)

.. warning::

   The :py:class:`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.


.. seealso:: :py:func:`coordinateEpoch`


.. versionadded:: 3.20
%End

    double coordinateEpoch() const;
%Docstring
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 :py:func:`~QgsCoordinateReferenceSystem.isDynamic`).

.. warning::

   The :py:class:`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: Coordinate epoch as decimal year (e.g. 2021.3), or NaN if not set, or relevant.


.. seealso:: :py:func:`setCoordinateEpoch`


.. versionadded:: 3.20
%End

    QgsProjectionFactors factors( const QgsPoint &point ) const;
%Docstring
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.

.. versionadded:: 3.20
%End

    QgsProjOperation operation() const;
%Docstring
Returns information about the PROJ operation associated with the coordinate reference system, for example
the projection method used by the CRS.

.. versionadded:: 3.20
%End

    bool hasAxisInverted() const;
%Docstring
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: ``True`` if CRS axis is inverted

.. seealso:: :py:func:`axisOrdering`
%End

    SIP_PYOBJECT axisOrdering() const /TypeHint="List[Qgis.CrsAxisDirection]"/;
%Docstring
Returns an ordered list of the axis directions reflecting the native axis order for the CRS.

.. versionadded:: 3.26
%End
%MethodCode
    // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources

    const QList< Qgis::CrsAxisDirection > cppRes = sipCpp->axisOrdering();

    PyObject *l = PyList_New( cppRes.size() );

    if ( !l )
      sipIsErr = 1;
    else
    {
      for ( int i = 0; i < cppRes.size(); ++i )
      {
        PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
                                             sipType_Qgis_CrsAxisDirection );

        if ( !eobj )
        {
          sipIsErr = 1;
        }

        PyList_SetItem( l, i, eobj );
      }

      if ( !sipIsErr )
      {
        sipRes = l;
      }
      else
      {
        Py_DECREF( l );
      }
    }
%End

    Qgis::DistanceUnit mapUnits() const;
%Docstring
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.
%End

    QgsRectangle bounds() const;
%Docstring
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.
%End

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

.. versionadded:: 3.30
%End

    QString toOgcUrn() const;
%Docstring
Returns the crs as OGC URN (format: urn:ogc:def:crs:OGC:1.3:CRS84)
Returns an empty string on failure.

.. versionadded:: 3.38
%End


    void updateDefinition();
%Docstring
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 :py:func:`QgsApplication.coordinateReferenceSystemRegistry()`'s
:py:func:`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.

.. versionadded:: 3.18
%End

    void setValidationHint( const QString &html );
%Docstring
Set user hint for validation
%End

    QString validationHint() const;
%Docstring
Gets user hint for validation
%End

    static int syncDatabase();
%Docstring
Update proj.4 parameters in our database from proj.4

:return: 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
%End

    long saveAsUserCrs( const QString &name, Qgis::CrsDefinitionFormat nativeFormat = Qgis::CrsDefinitionFormat::Wkt );
%Docstring
Saves the CRS as a new custom ("USER") CRS.

Returns the new CRS :py:func:`~QgsCoordinateReferenceSystem.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 :py:func:`QgsCoordinateReferenceSystemRegistry.addUserCrs()`.
%End

    void setNativeFormat( Qgis::CrsDefinitionFormat format );
%Docstring
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.

.. seealso:: :py:func:`nativeFormat`

.. versionadded:: 3.24
%End

    Qgis::CrsDefinitionFormat nativeFormat() const;
%Docstring
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.

.. seealso:: :py:func:`setNativeFormat`

.. versionadded:: 3.24
%End

    QgsCoordinateReferenceSystem toGeographicCrs() const;
%Docstring
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.

.. versionadded:: 3.24
%End

    QString geographicCrsAuthId() const;
%Docstring
Returns auth id of related geographic CRS
%End

    SIP_PYOBJECT __repr__();
%MethodCode
    const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1%2>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( Qgis::CrsWktVariant::Preferred ),
                        std::isfinite( sipCpp->coordinateEpoch() ) ? QStringLiteral( " @ %1" ).arg( sipCpp->coordinateEpoch() ) : QString() )
                        : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
%End


 static QStringList recentProjections() /Deprecated/;
%Docstring
Returns a list of recently used projections

:return: list of srsid for recently used projections

.. deprecated::
   QGIS 3.10 Use :py:func:`QgsApplication.coordinateReferenceSystemRegistry()`->:py:func:`~QgsCoordinateReferenceSystem.recentCrs` instead.
%End

 static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems() /Deprecated/;
%Docstring
Returns a list of recently used CRS.

.. deprecated::
   QGIS 3.36 Use :py:func:`QgsApplication.coordinateReferenceSystemRegistry()`->:py:func:`~QgsCoordinateReferenceSystem.recentCrs` instead.
%End

 static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs ) /Deprecated/;
%Docstring
Pushes a recently used CRS to the top of the recent CRS list.

.. deprecated::
   QGIS 3.36 Use :py:func:`QgsApplication.coordinateReferenceSystemRegistry()`->:py:func:`~QgsCoordinateReferenceSystem.pushRecent` instead.
%End

 static void removeRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs ) /Deprecated/;
%Docstring
Removes a CRS from the list of recently used CRS.

.. deprecated::
   QGIS 3.36 Use :py:func:`QgsApplication.coordinateReferenceSystemRegistry()`->:py:func:`~QgsCoordinateReferenceSystem.removeRecent` instead.
%End

 static void clearRecentCoordinateReferenceSystems() /Deprecated/;
%Docstring
Cleans the list of recently used CRS.

.. deprecated::
   QGIS 3.36 Use :py:func:`QgsApplication.coordinateReferenceSystemRegistry()`->:py:func:`~QgsCoordinateReferenceSystem.clearRecent` instead.
%End


    static void invalidateCache();
%Docstring
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.
%End

};



/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/proj/qgscoordinatereferencesystem.h                         *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/