QGIS API Documentation  3.21.0-Master (909859188c)
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 "qgsunittypes.h"
36 #include "qgsrectangle.h"
37 #include "qgssqliteutils.h"
38 
39 class QDomNode;
40 class QDomDocument;
41 class QgsCoordinateReferenceSystemPrivate;
42 class QgsDatumEnsemble;
44 class QgsProjOperation;
45 
46 #ifndef SIP_RUN
47 struct PJconsts;
48 typedef struct PJconsts PJ;
49 
50 #if PROJ_VERSION_MAJOR>=8
51 struct pj_ctx;
52 typedef struct pj_ctx PJ_CONTEXT;
53 #else
54 struct projCtx_t;
55 typedef struct projCtx_t PJ_CONTEXT;
56 #endif
57 #endif
58 
59 // forward declaration for sqlite3
60 typedef struct sqlite3 sqlite3 SIP_SKIP;
61 
62 #ifdef DEBUG
63 typedef struct OGRSpatialReferenceHS *OGRSpatialReferenceH SIP_SKIP;
64 #else
66 #endif
67 
70 
211 {
212  Q_GADGET
213 
214  Q_PROPERTY( QgsUnitTypes::DistanceUnit mapUnits READ mapUnits )
215  Q_PROPERTY( bool isGeographic READ isGeographic )
216 
217  public:
218 
220  enum CrsType
221  {
224  EpsgCrsId
225  };
226 
228  enum Format
229  {
230  FormatWkt = 0,
232  };
233 
236 
238 
239  // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
240 
256  explicit QgsCoordinateReferenceSystem( const QString &definition );
257 
258  // TODO QGIS 4: remove type and always use EPSG code
259 
271  Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
272 
275 
278 
280  operator QVariant() const
281  {
282  return QVariant::fromValue( *this );
283  }
284 
292  static QList< long > validSrsIds();
293 
294  // static creators
295 
303  static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
304 
311  Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
312 
319  Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
320 
328  static QgsCoordinateReferenceSystem fromProj( const QString &proj );
329 
337  static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
338 
347  static QgsCoordinateReferenceSystem fromSrsId( long srsId );
348 
349  // Misc helper functions -----------------------
350 
351  // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
352 
358  Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
359 
360  // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
361 
372  bool createFromOgcWmsCrs( const QString &crs );
373 
374  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
375 
383  Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
384 
397  bool createFromWkt( const QString &wkt );
398 
411  bool createFromSrsId( long srsId );
412 
436  Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
437 
465 #ifndef SIP_RUN
466  bool createFromProj( const QString &projString, bool identify = true );
467 #else
468  bool createFromProj( const QString &projString );
469 #endif
470 
486  bool createFromString( const QString &definition );
487 
488  // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
489 
505  bool createFromUserInput( const QString &definition );
506 
517  Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
518 
520  bool isValid() const;
521 
533  void validate();
534 
535  // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
536 
545  Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
546 
552  bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
553 
559  bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
560 
567  bool readXml( const QDomNode &node );
568 
575  bool writeXml( QDomNode &node, QDomDocument &doc ) const;
576 
577 
582  static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
583 
588  static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
589 
590  // Accessors -----------------------------------
591 
596  long srsid() const;
597 
598  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
599 
604  long postgisSrid() const;
605 
618  QString authid() const;
619 
627  QString description() const;
628 
635  {
639  };
640 
654  QString userFriendlyIdentifier( IdentifierType type = MediumString ) const;
655 
662  QString projectionAcronym() const;
663 
670  QString ellipsoidAcronym() const;
671 
674  {
681  WKT2_2019 = WKT2_2018,
682  WKT2_2019_SIMPLIFIED = WKT2_2018_SIMPLIFIED,
683 
684  WKT_PREFERRED = WKT2_2019,
685  WKT_PREFERRED_SIMPLIFIED = WKT2_2019_SIMPLIFIED,
686  WKT_PREFERRED_GDAL = WKT2_2019,
687  };
688 
700  QString toWkt( WktVariant variant = WKT1_GDAL, bool multiline = false, int indentationWidth = 4 ) const;
701 
714  Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
715 
728  QString toProj() const;
729 
734  bool isGeographic() const;
735 
744  bool isDynamic() const;
745 
758  QgsDatumEnsemble datumEnsemble() const SIP_THROW( QgsNotSupportedException );
759 
769  QString celestialBodyName() const SIP_THROW( QgsNotSupportedException );
770 
794  void setCoordinateEpoch( double epoch );
795 
819  double coordinateEpoch() const;
820 
832  QgsProjectionFactors factors( const QgsPoint &point ) const;
833 
840  QgsProjOperation operation() const;
841 
846  bool hasAxisInverted() const;
847 
851  QgsUnitTypes::DistanceUnit mapUnits() const;
852 
861  QgsRectangle bounds() const;
862 
863  // Mutators -----------------------------------
864 
881  void updateDefinition();
882 
886  void setValidationHint( const QString &html );
887 
891  QString validationHint();
892 
899  static int syncDatabase();
900 
914  long saveAsUserCrs( const QString &name, Format nativeFormat = FormatWkt );
915 
917  QString geographicCrsAuthId() const;
918 
919 #ifdef SIP_RUN
920  SIP_PYOBJECT __repr__();
921  % MethodCode
922  const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1%2>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( QgsCoordinateReferenceSystem::WKT_PREFERRED ),
923  std::isfinite( sipCpp->coordinateEpoch() ) ? QStringLiteral( " @ %1" ).arg( sipCpp->coordinateEpoch() ) : QString() )
924  : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
925  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
926  % End
927 #endif
928 
929 #ifndef SIP_RUN
930 
940  PJ *projObject() const;
941 #endif
942 
948  Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
949 
954  static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems();
955 
960  static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
961 
962 #ifndef SIP_RUN
963 
974  static void invalidateCache( bool disableCache = false );
975 #else
976 
984  static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
985 #endif
986 
987  // Mutators -----------------------------------
988  // We don't want to expose these to the public api since they won't create
989  // a fully valid crs. Programmers should use the createFrom* methods rather
990  private:
991 
997  static QString projFromSrsId( int srsId );
998 
1004  void setProjString( const QString &projString );
1005 
1009  bool setWktString( const QString &wkt );
1010 
1014  void debugPrint();
1015 
1017  typedef QMap<QString, QString> RecordMap;
1018 
1026  RecordMap getRecord( const QString &sql );
1027 
1032  static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
1033 
1035  void setMapUnits();
1036 
1038  static long getRecordCount();
1039 
1040  bool loadFromAuthCode( const QString &auth, const QString &code );
1041 
1045  static QList< long > userSrsIds();
1046 
1054  long matchToUserCrs() const;
1055 
1060  bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
1061 
1062  bool createFromWktInternal( const QString &wkt, const QString &description );
1063 
1064  QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
1065 
1066  QString mValidationHint;
1067 
1068  friend class QgsProjContext;
1069 
1070  // Only meant to be called by QgsProjContext::~QgsProjContext()
1071  static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
1072 
1074  static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
1075 
1076  // cache
1077 
1078  static bool sDisableSrIdCache;
1079  static bool sDisableOgcCache;
1080  static bool sDisableProjCache;
1081  static bool sDisableWktCache;
1082  static bool sDisableSrsIdCache;
1083  static bool sDisableStringCache;
1084 
1085  // for tests
1086  static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
1087  static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
1088  static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
1089  static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
1090  static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
1091  static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
1092 
1093  friend class TestQgsCoordinateReferenceSystem;
1095  friend bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1096  friend bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1097  friend bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1098  friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1099 
1100  bool createFromPostgisSrid( const long id );
1101 };
1102 
1104 
1105 #ifndef SIP_RUN
1107 inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
1108 {
1109  QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1110  mySummary += QLatin1String( "\n\t\tDescription : " );
1111  if ( !r.description().isNull() )
1112  {
1113  mySummary += r.description();
1114  }
1115  else
1116  {
1117  mySummary += QLatin1String( "Undefined" );
1118  }
1119  mySummary += QLatin1String( "\n\t\tProjection : " );
1120  if ( !r.projectionAcronym().isNull() )
1121  {
1122  mySummary += r.projectionAcronym();
1123  }
1124  else
1125  {
1126  mySummary += QLatin1String( "Undefined" );
1127  }
1128 
1129  mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1130  if ( !r.ellipsoidAcronym().isNull() )
1131  {
1132  mySummary += r.ellipsoidAcronym();
1133  }
1134  else
1135  {
1136  mySummary += QLatin1String( "Undefined" );
1137  }
1138 
1139  mySummary += QLatin1String( "\n\t\tProjString : " );
1140  if ( !r.toProj().isNull() )
1141  {
1142  mySummary += r.toProj();
1143  }
1144  else
1145  {
1146  mySummary += QLatin1String( "Undefined" );
1147  }
1148  // Using streams we need to use local 8 Bit
1149  return os << mySummary.toLocal8Bit().data() << std::endl;
1150 }
1151 
1152 bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1153 bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1154 bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1155 bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1156 #endif
1157 
1158 #endif // QGSCOORDINATEREFERENCESYSTEM_H
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.
Format
Projection definition formats.
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