QGIS API Documentation  3.23.0-Master (b5237dafc3)
qgscoordinatereferencesystem.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgscoordinatereferencesystem.h
3 
4  -------------------
5  begin : 2007
6  copyright : (C) 2007 by Gary E. Sherman
7  email : [email protected]
8 ***************************************************************************/
9 
10 /***************************************************************************
11  * *
12  * This program is free software; you can redistribute it and/or modify *
13  * it under the terms of the GNU General Public License as published by *
14  * the Free Software Foundation; either version 2 of the License, or *
15  * (at your option) any later version. *
16  * *
17  ***************************************************************************/
18 #ifndef QGSCOORDINATEREFERENCESYSTEM_H
19 #define QGSCOORDINATEREFERENCESYSTEM_H
20 
21 //Standard includes
22 #include "qgis_core.h"
23 #include <ostream>
24 
25 //qt includes
26 #include <QString>
27 #include <QMap>
28 #include <QHash>
29 #include <QReadWriteLock>
30 #include <QExplicitlySharedDataPointer>
31 #include <QObject>
32 
33 //qgis includes
34 #include "qgis_sip.h"
35 #include "qgsconfig.h"
36 #include "qgsunittypes.h"
37 #include "qgsrectangle.h"
38 #include "qgssqliteutils.h"
39 
40 class QDomNode;
41 class QDomDocument;
42 class QgsCoordinateReferenceSystemPrivate;
43 class QgsDatumEnsemble;
45 class QgsProjOperation;
46 
47 #ifndef SIP_RUN
48 struct PJconsts;
49 typedef struct PJconsts PJ;
50 
51 #if PROJ_VERSION_MAJOR>=8
52 struct pj_ctx;
53 typedef struct pj_ctx PJ_CONTEXT;
54 #else
55 struct projCtx_t;
56 typedef struct projCtx_t PJ_CONTEXT;
57 #endif
58 #endif
59 
60 // forward declaration for sqlite3
61 typedef struct sqlite3 sqlite3 SIP_SKIP;
62 
63 #ifdef DEBUG
64 typedef struct OGRSpatialReferenceHS *OGRSpatialReferenceH SIP_SKIP;
65 #else
67 #endif
68 
71 
212 {
213  Q_GADGET
214 
215  Q_PROPERTY( QgsUnitTypes::DistanceUnit mapUnits READ mapUnits )
216  Q_PROPERTY( bool isGeographic READ isGeographic )
217 
218  public:
219 
221  enum CrsType
222  {
225  EpsgCrsId
226  };
227 
230 
232 
233  // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
234 
250  explicit QgsCoordinateReferenceSystem( const QString &definition );
251 
252  // TODO QGIS 4: remove type and always use EPSG code
253 
265  Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
266 
269 
272 
274  operator QVariant() const
275  {
276  return QVariant::fromValue( *this );
277  }
278 
286  static QList< long > validSrsIds();
287 
288  // static creators
289 
297  static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
298 
305  Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
306 
313  Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
314 
322  static QgsCoordinateReferenceSystem fromProj( const QString &proj );
323 
331  static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
332 
341  static QgsCoordinateReferenceSystem fromSrsId( long srsId );
342 
343  // Misc helper functions -----------------------
344 
345  // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
346 
352  Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
353 
354  // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
355 
366  bool createFromOgcWmsCrs( const QString &crs );
367 
368  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
369 
377  Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
378 
391  bool createFromWkt( const QString &wkt );
392 
405  bool createFromSrsId( long srsId );
406 
430  Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
431 
459 #ifndef SIP_RUN
460  bool createFromProj( const QString &projString, bool identify = true );
461 #else
462  bool createFromProj( const QString &projString );
463 #endif
464 
480  bool createFromString( const QString &definition );
481 
482  // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
483 
499  bool createFromUserInput( const QString &definition );
500 
511  Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
512 
514  bool isValid() const;
515 
527  void validate();
528 
529  // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
530 
539  Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
540 
546  bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
547 
553  bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
554 
561  bool readXml( const QDomNode &node );
562 
569  bool writeXml( QDomNode &node, QDomDocument &doc ) const;
570 
571 
576  static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
577 
582  static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
583 
584  // Accessors -----------------------------------
585 
590  long srsid() const;
591 
592  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
593 
598  long postgisSrid() const;
599 
612  QString authid() const;
613 
621  QString description() const;
622 
629  {
633  };
634 
648  QString userFriendlyIdentifier( IdentifierType type = MediumString ) const;
649 
656  QString projectionAcronym() const;
657 
664  QString ellipsoidAcronym() const;
665 
668  {
675  WKT2_2019 = WKT2_2018,
676  WKT2_2019_SIMPLIFIED = WKT2_2018_SIMPLIFIED,
677 
678  WKT_PREFERRED = WKT2_2019,
679  WKT_PREFERRED_SIMPLIFIED = WKT2_2019_SIMPLIFIED,
680  WKT_PREFERRED_GDAL = WKT2_2019,
681  };
682 
694  QString toWkt( WktVariant variant = WKT1_GDAL, bool multiline = false, int indentationWidth = 4 ) const;
695 
708  Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
709 
722  QString toProj() const;
723 
728  bool isGeographic() const;
729 
738  bool isDynamic() const;
739 
752  QgsDatumEnsemble datumEnsemble() const SIP_THROW( QgsNotSupportedException );
753 
763  QString celestialBodyName() const SIP_THROW( QgsNotSupportedException );
764 
788  void setCoordinateEpoch( double epoch );
789 
813  double coordinateEpoch() const;
814 
826  QgsProjectionFactors factors( const QgsPoint &point ) const;
827 
834  QgsProjOperation operation() const;
835 
840  bool hasAxisInverted() const;
841 
845  QgsUnitTypes::DistanceUnit mapUnits() const;
846 
855  QgsRectangle bounds() const;
856 
857  // Mutators -----------------------------------
858 
875  void updateDefinition();
876 
880  void setValidationHint( const QString &html );
881 
885  QString validationHint();
886 
893  static int syncDatabase();
894 
908  long saveAsUserCrs( const QString &name, Qgis::CrsDefinitionFormat nativeFormat = Qgis::CrsDefinitionFormat::Wkt );
909 
919  void setNativeFormat( Qgis::CrsDefinitionFormat format );
920 
930  Qgis::CrsDefinitionFormat nativeFormat() const;
931 
941  QgsCoordinateReferenceSystem toGeographicCrs() const;
942 
944  QString geographicCrsAuthId() const;
945 
946 #ifdef SIP_RUN
947  SIP_PYOBJECT __repr__();
948  % MethodCode
949  const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1%2>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( QgsCoordinateReferenceSystem::WKT_PREFERRED ),
950  std::isfinite( sipCpp->coordinateEpoch() ) ? QStringLiteral( " @ %1" ).arg( sipCpp->coordinateEpoch() ) : QString() )
951  : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
952  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
953  % End
954 #endif
955 
956 #ifndef SIP_RUN
957 
967  PJ *projObject() const;
968 
979  static QgsCoordinateReferenceSystem fromProjObject( PJ *object );
980 
989  bool createFromProjObject( PJ *object );
990 #endif
991 
997  Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
998 
1003  static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems();
1004 
1009  static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
1010 
1011 #ifndef SIP_RUN
1012 
1023  static void invalidateCache( bool disableCache = false );
1024 #else
1025 
1033  static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
1034 #endif
1035 
1036  // Mutators -----------------------------------
1037  // We don't want to expose these to the public api since they won't create
1038  // a fully valid crs. Programmers should use the createFrom* methods rather
1039  private:
1040 
1046  static QString projFromSrsId( int srsId );
1047 
1053  void setProjString( const QString &projString );
1054 
1058  bool setWktString( const QString &wkt );
1059 
1063  void debugPrint();
1064 
1066  typedef QMap<QString, QString> RecordMap;
1067 
1075  RecordMap getRecord( const QString &sql );
1076 
1081  static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
1082 
1084  void setMapUnits();
1085 
1087  static long getRecordCount();
1088 
1089  bool loadFromAuthCode( const QString &auth, const QString &code );
1090 
1094  static QList< long > userSrsIds();
1095 
1103  long matchToUserCrs() const;
1104 
1109  bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
1110 
1111  bool createFromWktInternal( const QString &wkt, const QString &description );
1112 
1113  QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
1114 
1115  QString mValidationHint;
1116 
1117  Qgis::CrsDefinitionFormat mNativeFormat = Qgis::CrsDefinitionFormat::Wkt;
1118 
1119  friend class QgsProjContext;
1120 
1121  // Only meant to be called by QgsProjContext::~QgsProjContext()
1122  static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
1123 
1125  static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
1126 
1127  // cache
1128 
1129  static bool sDisableSrIdCache;
1130  static bool sDisableOgcCache;
1131  static bool sDisableProjCache;
1132  static bool sDisableWktCache;
1133  static bool sDisableSrsIdCache;
1134  static bool sDisableStringCache;
1135 
1136  // for tests
1137  static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
1138  static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
1139  static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
1140  static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
1141  static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
1142  static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
1143 
1144  friend class TestQgsCoordinateReferenceSystem;
1146  friend bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1147  friend bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1148  friend bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1149  friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1150 
1151  bool createFromPostgisSrid( const long id );
1152 };
1153 
1155 
1156 #ifndef SIP_RUN
1158 inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
1159 {
1160  QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1161  mySummary += QLatin1String( "\n\t\tDescription : " );
1162  if ( !r.description().isNull() )
1163  {
1164  mySummary += r.description();
1165  }
1166  else
1167  {
1168  mySummary += QLatin1String( "Undefined" );
1169  }
1170  mySummary += QLatin1String( "\n\t\tProjection : " );
1171  if ( !r.projectionAcronym().isNull() )
1172  {
1173  mySummary += r.projectionAcronym();
1174  }
1175  else
1176  {
1177  mySummary += QLatin1String( "Undefined" );
1178  }
1179 
1180  mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1181  if ( !r.ellipsoidAcronym().isNull() )
1182  {
1183  mySummary += r.ellipsoidAcronym();
1184  }
1185  else
1186  {
1187  mySummary += QLatin1String( "Undefined" );
1188  }
1189 
1190  mySummary += QLatin1String( "\n\t\tProjString : " );
1191  if ( !r.toProj().isNull() )
1192  {
1193  mySummary += r.toProj();
1194  }
1195  else
1196  {
1197  mySummary += QLatin1String( "Undefined" );
1198  }
1199  // Using streams we need to use local 8 Bit
1200  return os << mySummary.toLocal8Bit().data() << std::endl;
1201 }
1202 
1203 bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1204 bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1205 bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1206 bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1207 #endif
1208 
1209 #endif // QGSCOORDINATEREFERENCESYSTEM_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:64
CrsDefinitionFormat
CRS definition formats.
Definition: qgis.h:1273
A registry for known coordinate reference system (CRS) definitions, including any user-defined CRSes.
This class represents a coordinate reference system (CRS).
QString toProj() const
Returns a Proj string representation of this CRS.
QString ellipsoidAcronym() const
Returns the ellipsoid acronym for the ellipsoid used by the CRS.
QString description() const
Returns the descriptive name of the CRS, e.g., "WGS 84" or "GDA 94 / Vicgrid94".
QString projectionAcronym() const
Returns the projection acronym for the projection used by the CRS.
CrsType
Enumeration of types of IDs accepted in createFromId() method.
@ InternalCrsId
Internal ID used by QGIS in the local SQLite database.
@ PostgisCrsId
SRID used in PostGIS. DEPRECATED – DO NOT USE.
IdentifierType
Type of identifier string to create.
@ MediumString
A medium-length string, recommended for general purpose use.
@ FullString
Full definition – possibly a very lengthy string, e.g. with no truncation of custom WKT definitions.
@ ShortString
A heavily abbreviated string, for use when a compact representation is required.
WktVariant
WKT formatting variants, only used for builds based on Proj >= 6.
@ WKT1_GDAL
WKT1 as traditionally output by GDAL, deriving from OGC 01-009. A notable departure from WKT1_GDAL wi...
@ WKT2_2018_SIMPLIFIED
Alias for WKT2_2019_SIMPLIFIED.
@ WKT_PREFERRED
Preferred format, matching the most recent WKT ISO standard. Currently an alias to WKT2_2019,...
@ WKT2_2015
Full WKT2 string, conforming to ISO 19162:2015(E) / OGC 12-063r5 with all possible nodes and new keyw...
@ WKT1_ESRI
WKT1 as traditionally output by ESRI software, deriving from OGC 99-049.
@ WKT2_2015_SIMPLIFIED
Same as WKT2_2015 with the following exceptions: UNIT keyword used. ID node only on top element....
Contains information about a datum ensemble.
Definition: qgsdatums.h:95
Custom exception class which is raised when an operation is not supported.
Definition: qgsexception.h:118
Point geometry type, with support for z-dimension and m-values.
Definition: qgspoint.h:49
Used to create and store a proj context object, correctly freeing the context upon destruction.
Definition: qgsprojutils.h:231
Contains information about a PROJ operation.
contains various cartographic properties, such as scale factors, angular distortion and meridian conv...
A rectangle specified with double values.
Definition: qgsrectangle.h:42
Helper functions for various unit types.
Definition: qgsunittypes.h:39
DistanceUnit
Units of distance.
Definition: qgsunittypes.h:68
Unique pointer for sqlite3 databases, which automatically closes the database when the pointer goes o...
#define str(x)
Definition: qgis.cpp:37
#define SIP_THROW(name)
Definition: qgis_sip.h:189
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_PYARGREMOVE
Definition: qgis_sip.h:146
struct sqlite3 sqlite3
void * OGRSpatialReferenceH
bool CORE_EXPORT operator<(const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
bool CORE_EXPORT operator>(const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
bool CORE_EXPORT operator<=(const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
struct PJconsts PJ
std::ostream & operator<<(std::ostream &os, const QgsCoordinateReferenceSystem &r)
Output stream operator.
struct projCtx_t PJ_CONTEXT
bool CORE_EXPORT operator>=(const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
void(* CUSTOM_CRS_VALIDATION)(QgsCoordinateReferenceSystem &)
Q_DECLARE_METATYPE(QgsMeshTimeSettings)
const QgsCoordinateReferenceSystem & crs
bool hasAxisInverted