QGIS API Documentation  3.19.0-Master (100d2d1764)
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 
43 #ifndef SIP_RUN
44 struct PJconsts;
45 typedef struct PJconsts PJ;
46 
47 #if PROJ_VERSION_MAJOR>=8
48 struct pj_ctx;
49 typedef struct pj_ctx PJ_CONTEXT;
50 #else
51 struct projCtx_t;
52 typedef struct projCtx_t PJ_CONTEXT;
53 #endif
54 #endif
55 
56 // forward declaration for sqlite3
57 typedef struct sqlite3 sqlite3 SIP_SKIP;
58 
59 #ifdef DEBUG
60 typedef struct OGRSpatialReferenceHS *OGRSpatialReferenceH SIP_SKIP;
61 #else
63 #endif
64 
67 
208 {
209  Q_GADGET
210 
211  Q_PROPERTY( QgsUnitTypes::DistanceUnit mapUnits READ mapUnits )
212  Q_PROPERTY( bool isGeographic READ isGeographic )
213 
214  public:
215 
217  enum CrsType
218  {
221  EpsgCrsId
222  };
223 
225  enum Format
226  {
227  FormatWkt = 0,
229  };
230 
233 
235 
236  // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
237 
253  explicit QgsCoordinateReferenceSystem( const QString &definition );
254 
255  // TODO QGIS 4: remove type and always use EPSG code
256 
268  Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
269 
272 
275 
277  operator QVariant() const
278  {
279  return QVariant::fromValue( *this );
280  }
281 
289  static QList< long > validSrsIds();
290 
291  // static creators
292 
300  static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
301 
308  Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
309 
316  Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
317 
325  static QgsCoordinateReferenceSystem fromProj( const QString &proj );
326 
334  static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
335 
344  static QgsCoordinateReferenceSystem fromSrsId( long srsId );
345 
346  // Misc helper functions -----------------------
347 
348  // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
349 
355  Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
356 
357  // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
358 
369  bool createFromOgcWmsCrs( const QString &crs );
370 
371  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
372 
380  Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
381 
394  bool createFromWkt( const QString &wkt );
395 
408  bool createFromSrsId( long srsId );
409 
433  Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
434 
462 #ifndef SIP_RUN
463  bool createFromProj( const QString &projString, bool identify = true );
464 #else
465  bool createFromProj( const QString &projString );
466 #endif
467 
483  bool createFromString( const QString &definition );
484 
485  // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
486 
502  bool createFromUserInput( const QString &definition );
503 
514  Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
515 
517  bool isValid() const;
518 
530  void validate();
531 
532  // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
533 
542  Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
543 
549  bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
550 
556  bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
557 
564  bool readXml( const QDomNode &node );
565 
572  bool writeXml( QDomNode &node, QDomDocument &doc ) const;
573 
574 
579  static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
580 
585  static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
586 
587  // Accessors -----------------------------------
588 
593  long srsid() const;
594 
595  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
596 
601  long postgisSrid() const;
602 
615  QString authid() const;
616 
624  QString description() const;
625 
632  {
636  };
637 
651  QString userFriendlyIdentifier( IdentifierType type = MediumString ) const;
652 
659  QString projectionAcronym() const;
660 
667  QString ellipsoidAcronym() const;
668 
671  {
678  WKT2_2019 = WKT2_2018,
679  WKT2_2019_SIMPLIFIED = WKT2_2018_SIMPLIFIED,
680 
681  WKT_PREFERRED = WKT2_2019,
682  WKT_PREFERRED_SIMPLIFIED = WKT2_2019_SIMPLIFIED,
683  WKT_PREFERRED_GDAL = WKT2_2019,
684  };
685 
697  QString toWkt( WktVariant variant = WKT1_GDAL, bool multiline = false, int indentationWidth = 4 ) const;
698 
711  Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
712 
725  QString toProj() const;
726 
731  bool isGeographic() const;
732 
737  bool hasAxisInverted() const;
738 
742  QgsUnitTypes::DistanceUnit mapUnits() const;
743 
752  QgsRectangle bounds() const;
753 
754  // Mutators -----------------------------------
755 
772  void updateDefinition();
773 
777  void setValidationHint( const QString &html );
778 
782  QString validationHint();
783 
790  static int syncDatabase();
791 
805  long saveAsUserCrs( const QString &name, Format nativeFormat = FormatWkt );
806 
808  QString geographicCrsAuthId() const;
809 
810 #ifdef SIP_RUN
811  SIP_PYOBJECT __repr__();
812  % MethodCode
813  const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( QgsCoordinateReferenceSystem::WKT_PREFERRED ) )
814  : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
815  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
816  % End
817 #endif
818 
819 #ifndef SIP_RUN
820 
830  PJ *projObject() const;
831 #endif
832 
838  Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
839 
844  static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems();
845 
850  static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
851 
852 #ifndef SIP_RUN
853 
864  static void invalidateCache( bool disableCache = false );
865 #else
866 
874  static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
875 #endif
876 
877  // Mutators -----------------------------------
878  // We don't want to expose these to the public api since they won't create
879  // a fully valid crs. Programmers should use the createFrom* methods rather
880  private:
881 
887  static QString projFromSrsId( int srsId );
888 
894  void setProjString( const QString &projString );
895 
899  bool setWktString( const QString &wkt );
900 
904  void debugPrint();
905 
907  typedef QMap<QString, QString> RecordMap;
908 
916  RecordMap getRecord( const QString &sql );
917 
922  static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
923 
925  void setMapUnits();
926 
928  static long getRecordCount();
929 
930  bool loadFromAuthCode( const QString &auth, const QString &code );
931 
935  static QList< long > userSrsIds();
936 
944  long matchToUserCrs() const;
945 
950  bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
951 
952  bool createFromWktInternal( const QString &wkt, const QString &description );
953 
954  QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
955 
956  QString mValidationHint;
957 
958  friend class QgsProjContext;
959 
960  // Only meant to be called by QgsProjContext::~QgsProjContext()
961  static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
962 
964  static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
965 
966  // cache
967 
968  static bool sDisableSrIdCache;
969  static bool sDisableOgcCache;
970  static bool sDisableProjCache;
971  static bool sDisableWktCache;
972  static bool sDisableSrsIdCache;
973  static bool sDisableStringCache;
974 
975  // for tests
976  static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
977  static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
978  static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
979  static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
980  static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
981  static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
982 
983  friend class TestQgsCoordinateReferenceSystem;
984  friend class QgsPostgresProvider;
986  friend bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
987  friend bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
988  friend bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
989  friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
990 
991  bool createFromPostgisSrid( const long id );
992 };
993 
995 
996 #ifndef SIP_RUN
998 inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
999 {
1000  QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1001  mySummary += QLatin1String( "\n\t\tDescription : " );
1002  if ( !r.description().isNull() )
1003  {
1004  mySummary += r.description();
1005  }
1006  else
1007  {
1008  mySummary += QLatin1String( "Undefined" );
1009  }
1010  mySummary += QLatin1String( "\n\t\tProjection : " );
1011  if ( !r.projectionAcronym().isNull() )
1012  {
1013  mySummary += r.projectionAcronym();
1014  }
1015  else
1016  {
1017  mySummary += QLatin1String( "Undefined" );
1018  }
1019 
1020  mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1021  if ( !r.ellipsoidAcronym().isNull() )
1022  {
1023  mySummary += r.ellipsoidAcronym();
1024  }
1025  else
1026  {
1027  mySummary += QLatin1String( "Undefined" );
1028  }
1029 
1030  mySummary += QLatin1String( "\n\t\tProjString : " );
1031  if ( !r.toProj().isNull() )
1032  {
1033  mySummary += r.toProj();
1034  }
1035  else
1036  {
1037  mySummary += QLatin1String( "Undefined" );
1038  }
1039  // Using streams we need to use local 8 Bit
1040  return os << mySummary.toLocal8Bit().data() << std::endl;
1041 }
1042 
1043 bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1044 bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1045 bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1046 bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1047 #endif
1048 
1049 #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....
Used to create and store a proj context object, correctly freeing the context upon destruction.
Definition: qgsprojutils.h:155
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_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