QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
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 "qgis.h"
36 #include "qgsconfig.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( Qgis::DistanceUnit mapUnits READ mapUnits )
216  Q_PROPERTY( bool isGeographic READ isGeographic )
217  Q_PROPERTY( QString authid READ authid )
218  Q_PROPERTY( QString description READ description )
219 
220  public:
221 
223  enum CrsType
224  {
227  EpsgCrsId
228  };
229 
232 
234 
235  // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
236 
252  explicit QgsCoordinateReferenceSystem( const QString &definition );
253 
254  // TODO QGIS 4: remove type and always use EPSG code
255 
267  Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
268 
271 
274 
276  operator QVariant() const
277  {
278  return QVariant::fromValue( *this );
279  }
280 
287  static QList< long > validSrsIds();
288 
289  // static creators
290 
297  static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
298 
304  Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
305 
312  Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
313 
321  static QgsCoordinateReferenceSystem fromProj( const QString &proj );
322 
329  static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
330 
338  static QgsCoordinateReferenceSystem fromSrsId( long srsId );
339 
349  static QgsCoordinateReferenceSystem createCompoundCrs( const QgsCoordinateReferenceSystem &horizontalCrs, const QgsCoordinateReferenceSystem &verticalCrs );
350 
351  // Misc helper functions -----------------------
352 
353  // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
354 
360  Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
361 
362  // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
363 
374  bool createFromOgcWmsCrs( const QString &crs );
375 
376  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
377 
385  Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
386 
399  bool createFromWkt( const QString &wkt );
400 
413  bool createFromSrsId( long srsId );
414 
438  Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
439 
467 #ifndef SIP_RUN
468  bool createFromProj( const QString &projString, bool identify = true );
469 #else
470  bool createFromProj( const QString &projString );
471 #endif
472 
488  bool createFromString( const QString &definition );
489 
490  // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
491 
507  bool createFromUserInput( const QString &definition );
508 
519  Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
520 
522  bool isValid() const;
523 
535  void validate();
536 
537  // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
538 
547  Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
548 
554  bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
555 
561  bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
562 
569  bool readXml( const QDomNode &node );
570 
577  bool writeXml( QDomNode &node, QDomDocument &doc ) const;
578 
579 
584  static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
585 
590  static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
591 
592  // Accessors -----------------------------------
593 
598  long srsid() const;
599 
600  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
601 
606  long postgisSrid() const;
607 
620  QString authid() const;
621 
629  QString description() const;
630 
644  QString userFriendlyIdentifier( Qgis::CrsIdentifierType type = Qgis::CrsIdentifierType::MediumString ) const;
645 
652  QString projectionAcronym() const;
653 
660  QString ellipsoidAcronym() const;
661 
673  QString toWkt( Qgis::CrsWktVariant variant = Qgis::CrsWktVariant::Wkt1Gdal, bool multiline = false, int indentationWidth = 4 ) const;
674 
687  Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
688 
701  QString toProj() const;
702 
708  Qgis::CrsType type() const;
709 
715  bool isDeprecated() const;
716 
721  bool isGeographic() const;
722 
731  bool isDynamic() const;
732 
747  QgsDatumEnsemble datumEnsemble() const SIP_THROW( QgsNotSupportedException );
748 
758  QString celestialBodyName() const SIP_THROW( QgsNotSupportedException );
759 
783  void setCoordinateEpoch( double epoch );
784 
808  double coordinateEpoch() const;
809 
821  QgsProjectionFactors factors( const QgsPoint &point ) const;
822 
829  QgsProjOperation operation() const;
830 
838  bool hasAxisInverted() const;
839 
845 #ifndef SIP_RUN
846  QList< Qgis::CrsAxisDirection > axisOrdering() const;
847 #else
848  SIP_PYOBJECT axisOrdering() const SIP_TYPEHINT( List[Qgis.CrsAxisDirection] );
849  % MethodCode
850  // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
851 
852  const QList< Qgis::CrsAxisDirection > cppRes = sipCpp->axisOrdering();
853 
854  PyObject *l = PyList_New( cppRes.size() );
855 
856  if ( !l )
857  sipIsErr = 1;
858  else
859  {
860  for ( int i = 0; i < cppRes.size(); ++i )
861  {
862  PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
863  sipType_Qgis_CrsAxisDirection );
864 
865  if ( !eobj )
866  {
867  sipIsErr = 1;
868  }
869 
870  PyList_SetItem( l, i, eobj );
871  }
872 
873  if ( !sipIsErr )
874  {
875  sipRes = l;
876  }
877  else
878  {
879  Py_DECREF( l );
880  }
881  }
882  % End
883 #endif
884 
890  Qgis::DistanceUnit mapUnits() const;
891 
899  QgsRectangle bounds() const;
900 
907  QString toOgcUri() const;
908 
909  // Mutators -----------------------------------
910 
927  void updateDefinition();
928 
932  void setValidationHint( const QString &html );
933 
937  QString validationHint() const;
938 
945  static int syncDatabase();
946 
960  long saveAsUserCrs( const QString &name, Qgis::CrsDefinitionFormat nativeFormat = Qgis::CrsDefinitionFormat::Wkt );
961 
971  void setNativeFormat( Qgis::CrsDefinitionFormat format );
972 
982  Qgis::CrsDefinitionFormat nativeFormat() const;
983 
993  QgsCoordinateReferenceSystem toGeographicCrs() const;
994 
1005  QgsCoordinateReferenceSystem horizontalCrs() const;
1006 
1017  QgsCoordinateReferenceSystem verticalCrs() const;
1018 
1020  QString geographicCrsAuthId() const;
1021 
1022 #ifdef SIP_RUN
1023  SIP_PYOBJECT __repr__();
1024  % MethodCode
1025  const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1%2>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( Qgis::CrsWktVariant::Preferred ),
1026  std::isfinite( sipCpp->coordinateEpoch() ) ? QStringLiteral( " @ %1" ).arg( sipCpp->coordinateEpoch() ) : QString() )
1027  : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
1028  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
1029  % End
1030 #endif
1031 
1032 #ifndef SIP_RUN
1033 
1043  PJ *projObject() const;
1044 
1055  static QgsCoordinateReferenceSystem fromProjObject( PJ *object );
1056 
1065  bool createFromProjObject( PJ *object );
1066 #endif
1067 
1074  Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
1075 
1081  Q_DECL_DEPRECATED static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems() SIP_DEPRECATED;
1082 
1088  Q_DECL_DEPRECATED static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs ) SIP_DEPRECATED;
1089 
1095  Q_DECL_DEPRECATED static void removeRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs ) SIP_DEPRECATED;
1096 
1102  Q_DECL_DEPRECATED static void clearRecentCoordinateReferenceSystems() SIP_DEPRECATED;
1103 
1104 #ifndef SIP_RUN
1105 
1115  static void invalidateCache( bool disableCache = false );
1116 #else
1117 
1124  static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
1125 #endif
1126 
1127  // Mutators -----------------------------------
1128  // We don't want to expose these to the public api since they won't create
1129  // a fully valid crs. Programmers should use the createFrom* methods rather
1130  private:
1131 
1137  static QString projFromSrsId( int srsId );
1138 
1144  void setProjString( const QString &projString );
1145 
1149  bool setWktString( const QString &wkt );
1150 
1154  void debugPrint();
1155 
1157  typedef QMap<QString, QString> RecordMap;
1158 
1166  RecordMap getRecord( const QString &sql );
1167 
1172  static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
1173 
1175  void setMapUnits();
1176 
1178  static long getRecordCount();
1179 
1180  bool loadFromAuthCode( const QString &auth, const QString &code );
1181 
1185  static QList< long > userSrsIds();
1186 
1194  long matchToUserCrs() const;
1195 
1200  bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
1201 
1202  bool createFromWktInternal( const QString &wkt, const QString &description );
1203 
1204  QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
1205 
1206  QString mValidationHint;
1207 
1209 
1210  friend class QgsProjContext;
1211 
1212  // Only meant to be called by QgsProjContext::~QgsProjContext()
1213  static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
1214 
1216  static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
1217 
1218  // cache
1219 
1220  static bool sDisableSrIdCache;
1221  static bool sDisableOgcCache;
1222  static bool sDisableProjCache;
1223  static bool sDisableWktCache;
1224  static bool sDisableSrsIdCache;
1225  static bool sDisableStringCache;
1226 
1227  // for tests
1228  static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
1229  static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
1230  static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
1231  static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
1232  static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
1233  static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
1234 
1235  friend class TestQgsCoordinateReferenceSystem;
1237  friend bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1238  friend bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1239  friend bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1240  friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1241 
1242  bool createFromPostgisSrid( const long id );
1243 };
1244 
1246 
1247 #ifndef SIP_RUN
1249 inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
1250 {
1251  QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1252  mySummary += QLatin1String( "\n\t\tDescription : " );
1253  if ( !r.description().isNull() )
1254  {
1255  mySummary += r.description();
1256  }
1257  else
1258  {
1259  mySummary += QLatin1String( "Undefined" );
1260  }
1261  mySummary += QLatin1String( "\n\t\tProjection : " );
1262  if ( !r.projectionAcronym().isNull() )
1263  {
1264  mySummary += r.projectionAcronym();
1265  }
1266  else
1267  {
1268  mySummary += QLatin1String( "Undefined" );
1269  }
1270 
1271  mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1272  if ( !r.ellipsoidAcronym().isNull() )
1273  {
1274  mySummary += r.ellipsoidAcronym();
1275  }
1276  else
1277  {
1278  mySummary += QLatin1String( "Undefined" );
1279  }
1280 
1281  mySummary += QLatin1String( "\n\t\tProjString : " );
1282  if ( !r.toProj().isNull() )
1283  {
1284  mySummary += r.toProj();
1285  }
1286  else
1287  {
1288  mySummary += QLatin1String( "Undefined" );
1289  }
1290  // Using streams we need to use local 8 Bit
1291  return os << mySummary.toLocal8Bit().data() << std::endl;
1292 }
1293 
1294 bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1295 bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1296 bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1297 bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1298 #endif
1299 
1300 #endif // QGSCOORDINATEREFERENCESYSTEM_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:54
DistanceUnit
Units of distance.
Definition: qgis.h:4090
CrsDefinitionFormat
CRS definition formats.
Definition: qgis.h:3147
@ Wkt
WKT format (always recommended over proj string format)
@ Preferred
Preferred format, matching the most recent WKT ISO standard. Currently an alias to WKT2_2019,...
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 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.
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:264
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
Unique pointer for sqlite3 databases, which automatically closes the database when the pointer goes o...
#define str(x)
Definition: qgis.cpp:38
#define SIP_TYPEHINT(type)
Definition: qgis_sip.h:232
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_PYARGREMOVE
Definition: qgis_sip.h:151
#define SIP_THROW(name,...)
Definition: qgis_sip.h:203
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(QgsDatabaseQueryLogEntry)
const QgsCoordinateReferenceSystem & crs
bool hasAxisInverted