qgscoordinatereferencesystem.sip.in

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










class QgsCoordinateReferenceSystem
{
%Docstring
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:

1. **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).
2. **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:

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

     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:

1. **Authority and Code.** Also referred to as OGC WMS format within QGIS as they have been widely
used in OGC standards. These are encoded as `<auth>:<code>`, for example `EPSG:4326` refers
to WGS84 system. EPSG is the most commonly used authority that covers a wide range
of coordinate systems around the world.

An extended variant of this format is OGC URN. Syntax of URN for CRS definition is
`urn:ogc:def:crs:<auth>:[<version>]:<code>`. This class can also parse URNs (versions
are currently ignored). For example, WGS84 may be encoded as `urn:ogc:def:crs:OGC:1.3:CRS84`.

QGIS adds support for "USER" authority that refers to IDs used internally in QGIS. This variant
is best avoided or used with caution as the IDs are not permanent and they refer to different CRS
on different machines or user profiles.

See authid() and createFromOgcWmsCrs() methods.

2. **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 toProj() and createFromProj() methods.

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

GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],
AUTHORITY["EPSG","6326"]],
PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],
UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],
AUTHORITY["EPSG","4326"]]

See toWkt() and createFromWkt() methods.

CRS Database and Custom CRS
===========================

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

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

There are therefore two databases: one for shipped CRS definitions and one for custom CRS definitions.
Custom CRS have internal IDs (accessible with srsid()) greater or equal to \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  {#crs_construct_and_copy}
===============================

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.


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

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

  public:

    enum CrsType
    {
      InternalCrsId,
      PostgisCrsId,
      EpsgCrsId
    };

    enum Format
    {
      FormatWkt,
      FormatProj,
    };

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

    ~QgsCoordinateReferenceSystem();


    explicit QgsCoordinateReferenceSystem( const QString &definition );
%Docstring
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()
- "PROJ4:<proj4>" - 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.

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


    explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId );
%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
%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 fromSrsId() to create a new, valid
QgsCoordinateReferenceSystem object.

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

.. versionadded:: 3.0
%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`

.. versionadded:: 3.0
%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

.. versionadded:: 3.0
%End

 static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) /Deprecated/;
%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`

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

.. versionadded:: 3.0
%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`

.. versionadded:: 3.0
%End



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

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

.. 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.
%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 invalidateCache() to clear the cache.

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


    bool createFromSrid( long srid );
%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``
%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 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 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 invalidateCache() to clear the cache.

.. seealso:: :py:func:`fromSrsId`
%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 invalidateCache() to clear the cache.

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

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

: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 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 createFromOgcWms()
- "POSTGIS:<srid>" - handled with createFromSrid()
- "INTERNAL:<srsid>" - handled with createFromSrsId()
- "PROJ4:<proj4>" - 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.

: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()
( http://www.gdal.org/ogr/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 createFromWkt() function.
   /    // TODO QGIS3: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
%End

    static void setupESRIWktFix();
%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 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() .
%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::
   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". In most
cases this is the best method to use when showing a friendly identifier for the CRS to a
user.

:return: descriptive name of the CRS

.. note::

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

.. seealso:: :py:func:`authid`
%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 ellipoid, 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

    enum WktVariant
    {
      WKT1_GDAL,
      WKT1_ESRI,
      WKT2_2015,
      WKT2_2015_SIMPLIFIED,
      WKT2_2018,
      WKT2_2018_SIMPLIFIED,
    };

    QString toWkt( WktVariant variant = WKT1_GDAL, 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::
   use 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

    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 hasAxisInverted() const;
%Docstring
Returns whether axis is inverted (e.g., for WMS 1.3) for the CRS.

:return: ``True`` if CRS axis is inverted
%End

    QgsUnitTypes::DistanceUnit mapUnits() const;
%Docstring
Returns the units for the projection used by the CRS.
%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.

.. versionadded:: 3.0
%End


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

    QString validationHint();
%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, Format nativeFormat = FormatWkt );
%Docstring
Saves the CRS as a 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.
%End

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

    SIP_PYOBJECT __repr__();
%MethodCode
    QString str = QStringLiteral( "<QgsCoordinateReferenceSystem: %1>" ).arg( sipCpp->authid() );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
%End


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

:return: list of srsid for recently used projections

.. versionadded:: 2.7
%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.

.. versionadded:: 3.0
%End

};



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