QGIS API Documentation  3.23.0-Master (eb871beae0)
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 
229  enum Format
230  {
231  FormatWkt = 0,
233  };
234 
237 
239 
240  // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
241 
257  explicit QgsCoordinateReferenceSystem( const QString &definition );
258 
259  // TODO QGIS 4: remove type and always use EPSG code
260 
272  Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
273 
276 
279 
281  operator QVariant() const
282  {
283  return QVariant::fromValue( *this );
284  }
285 
293  static QList< long > validSrsIds();
294 
295  // static creators
296 
304  static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
305 
312  Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
313 
320  Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
321 
329  static QgsCoordinateReferenceSystem fromProj( const QString &proj );
330 
338  static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
339 
348  static QgsCoordinateReferenceSystem fromSrsId( long srsId );
349 
350  // Misc helper functions -----------------------
351 
352  // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
353 
359  Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
360 
361  // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
362 
373  bool createFromOgcWmsCrs( const QString &crs );
374 
375  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
376 
384  Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
385 
398  bool createFromWkt( const QString &wkt );
399 
412  bool createFromSrsId( long srsId );
413 
437  Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
438 
466 #ifndef SIP_RUN
467  bool createFromProj( const QString &projString, bool identify = true );
468 #else
469  bool createFromProj( const QString &projString );
470 #endif
471 
487  bool createFromString( const QString &definition );
488 
489  // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
490 
506  bool createFromUserInput( const QString &definition );
507 
518  Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
519 
521  bool isValid() const;
522 
534  void validate();
535 
536  // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
537 
546  Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
547 
553  bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
554 
560  bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
561 
568  bool readXml( const QDomNode &node );
569 
576  bool writeXml( QDomNode &node, QDomDocument &doc ) const;
577 
578 
583  static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
584 
589  static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
590 
591  // Accessors -----------------------------------
592 
597  long srsid() const;
598 
599  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
600 
605  long postgisSrid() const;
606 
619  QString authid() const;
620 
628  QString description() const;
629 
636  {
640  };
641 
655  QString userFriendlyIdentifier( IdentifierType type = MediumString ) const;
656 
663  QString projectionAcronym() const;
664 
671  QString ellipsoidAcronym() const;
672 
675  {
682  WKT2_2019 = WKT2_2018,
683  WKT2_2019_SIMPLIFIED = WKT2_2018_SIMPLIFIED,
684 
685  WKT_PREFERRED = WKT2_2019,
686  WKT_PREFERRED_SIMPLIFIED = WKT2_2019_SIMPLIFIED,
687  WKT_PREFERRED_GDAL = WKT2_2019,
688  };
689 
701  QString toWkt( WktVariant variant = WKT1_GDAL, bool multiline = false, int indentationWidth = 4 ) const;
702 
715  Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
716 
729  QString toProj() const;
730 
735  bool isGeographic() const;
736 
745  bool isDynamic() const;
746 
759  QgsDatumEnsemble datumEnsemble() const SIP_THROW( QgsNotSupportedException );
760 
770  QString celestialBodyName() const SIP_THROW( QgsNotSupportedException );
771 
795  void setCoordinateEpoch( double epoch );
796 
820  double coordinateEpoch() const;
821 
833  QgsProjectionFactors factors( const QgsPoint &point ) const;
834 
841  QgsProjOperation operation() const;
842 
847  bool hasAxisInverted() const;
848 
852  QgsUnitTypes::DistanceUnit mapUnits() const;
853 
862  QgsRectangle bounds() const;
863 
864  // Mutators -----------------------------------
865 
882  void updateDefinition();
883 
887  void setValidationHint( const QString &html );
888 
892  QString validationHint();
893 
900  static int syncDatabase();
901 
915  long saveAsUserCrs( const QString &name, Format nativeFormat = FormatWkt );
916 
918  QString geographicCrsAuthId() const;
919 
920 #ifdef SIP_RUN
921  SIP_PYOBJECT __repr__();
922  % MethodCode
923  const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1%2>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( QgsCoordinateReferenceSystem::WKT_PREFERRED ),
924  std::isfinite( sipCpp->coordinateEpoch() ) ? QStringLiteral( " @ %1" ).arg( sipCpp->coordinateEpoch() ) : QString() )
925  : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
926  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
927  % End
928 #endif
929 
930 #ifndef SIP_RUN
931 
941  PJ *projObject() const;
942 #endif
943 
949  Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
950 
955  static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems();
956 
961  static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
962 
963 #ifndef SIP_RUN
964 
975  static void invalidateCache( bool disableCache = false );
976 #else
977 
985  static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
986 #endif
987 
988  // Mutators -----------------------------------
989  // We don't want to expose these to the public api since they won't create
990  // a fully valid crs. Programmers should use the createFrom* methods rather
991  private:
992 
998  static QString projFromSrsId( int srsId );
999 
1005  void setProjString( const QString &projString );
1006 
1010  bool setWktString( const QString &wkt );
1011 
1015  void debugPrint();
1016 
1018  typedef QMap<QString, QString> RecordMap;
1019 
1027  RecordMap getRecord( const QString &sql );
1028 
1033  static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
1034 
1036  void setMapUnits();
1037 
1039  static long getRecordCount();
1040 
1041  bool loadFromAuthCode( const QString &auth, const QString &code );
1042 
1046  static QList< long > userSrsIds();
1047 
1055  long matchToUserCrs() const;
1056 
1061  bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
1062 
1063  bool createFromWktInternal( const QString &wkt, const QString &description );
1064 
1065  QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
1066 
1067  QString mValidationHint;
1068 
1069  friend class QgsProjContext;
1070 
1071  // Only meant to be called by QgsProjContext::~QgsProjContext()
1072  static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
1073 
1075  static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
1076 
1077  // cache
1078 
1079  static bool sDisableSrIdCache;
1080  static bool sDisableOgcCache;
1081  static bool sDisableProjCache;
1082  static bool sDisableWktCache;
1083  static bool sDisableSrsIdCache;
1084  static bool sDisableStringCache;
1085 
1086  // for tests
1087  static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
1088  static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
1089  static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
1090  static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
1091  static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
1092  static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
1093 
1094  friend class TestQgsCoordinateReferenceSystem;
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  friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1100 
1101  bool createFromPostgisSrid( const long id );
1102 };
1103 
1105 
1106 #ifndef SIP_RUN
1108 inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
1109 {
1110  QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1111  mySummary += QLatin1String( "\n\t\tDescription : " );
1112  if ( !r.description().isNull() )
1113  {
1114  mySummary += r.description();
1115  }
1116  else
1117  {
1118  mySummary += QLatin1String( "Undefined" );
1119  }
1120  mySummary += QLatin1String( "\n\t\tProjection : " );
1121  if ( !r.projectionAcronym().isNull() )
1122  {
1123  mySummary += r.projectionAcronym();
1124  }
1125  else
1126  {
1127  mySummary += QLatin1String( "Undefined" );
1128  }
1129 
1130  mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1131  if ( !r.ellipsoidAcronym().isNull() )
1132  {
1133  mySummary += r.ellipsoidAcronym();
1134  }
1135  else
1136  {
1137  mySummary += QLatin1String( "Undefined" );
1138  }
1139 
1140  mySummary += QLatin1String( "\n\t\tProjString : " );
1141  if ( !r.toProj().isNull() )
1142  {
1143  mySummary += r.toProj();
1144  }
1145  else
1146  {
1147  mySummary += QLatin1String( "Undefined" );
1148  }
1149  // Using streams we need to use local 8 Bit
1150  return os << mySummary.toLocal8Bit().data() << std::endl;
1151 }
1152 
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 bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1157 #endif
1158 
1159 #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
bool hasAxisInverted