/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/proj/qgscoordinatereferencesystem.h                         *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py 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:: text

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

       +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:: text

           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 /BaseType=IntEnum/
    {
      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.

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

.. 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:: 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 );

    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.

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

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

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

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

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

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

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

.. deprecated:: 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.

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

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

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

: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

    static QgsCoordinateReferenceSystem createCompoundCrs( const QgsCoordinateReferenceSystem &horizontalCrs, const QgsCoordinateReferenceSystem &verticalCrs, QString &error /Out/ );
%Docstring
Given a horizontal and vertical CRS, attempts to create a compound CRS
from them.

Returns an invalid CRS if the inputs are not suitable for a compound
CRS, or the compound CRS could not be created for the combination.

:param horizontalCrs: horizontal component for CRS
:param verticalCrs: vertical component for CRS

:return: - compound CRS if it was possible to create one, or an invalid
           CRS if not
         - error: a descriptive error if the compound CRS could not be
           created

.. versionadded:: 3.38
%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:: 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 to speed up creation of multiple CRS with the same definition.
   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:: 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 to speed up creation of multiple CRS with the same definition.
   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 to speed up creation of multiple CRS with the same definition.
   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 to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

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

.. deprecated:: 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 to speed up creation of multiple CRS with the same definition.
   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.

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.

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

.. note::

   This method uses an internal cache to speed up creation of multiple CRS with the same definition.
   Call :py:func:`~QgsCoordinateReferenceSystem.invalidateCache` to clear the cache.
%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:: 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`

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

    QgsCoordinateReferenceSystem horizontalCrs() const;
%Docstring
Returns the horizontal CRS associated with this CRS object.

In the case of a compound CRS, this method will return just the
horizontal CRS component.

An invalid CRS will be returned if the object does not contain a
horizontal component.

.. seealso:: :py:func:`verticalCrs`

.. versionadded:: 3.38
%End

    QgsCoordinateReferenceSystem verticalCrs() const;
%Docstring
Returns the vertical CRS associated with this CRS object.

In the case of a compound CRS, this method will return just the vertical
CRS component.

An invalid CRS will be returned if the object does not contain a
vertical component.

.. seealso:: :py:func:`horizontalCrs`

.. seealso:: :py:func:`hasVerticalAxis`

.. versionadded:: 3.38
%End

    bool hasVerticalAxis() const;
%Docstring
Returns ``True`` if the CRS has a vertical axis.

.. seealso:: :py:func:`verticalCrs`

.. versionadded:: 3.38
%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:: 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:: 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:: 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:: 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:: 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.py again   *
 ************************************************************************/