QGIS API Documentation  3.17.0-Master (7a14973234)
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 #if PROJ_VERSION_MAJOR>=6
44 #ifndef SIP_RUN
45 struct PJconsts;
46 typedef struct PJconsts PJ;
47 
48 struct projCtx_t;
49 typedef struct projCtx_t PJ_CONTEXT;
50 
51 #endif
52 #endif
53 
54 // forward declaration for sqlite3
55 typedef struct sqlite3 sqlite3 SIP_SKIP;
56 
57 #ifdef DEBUG
58 typedef struct OGRSpatialReferenceHS *OGRSpatialReferenceH SIP_SKIP;
59 #else
61 #endif
62 
65 
206 {
207  Q_GADGET
208 
209  Q_PROPERTY( QgsUnitTypes::DistanceUnit mapUnits READ mapUnits )
210  Q_PROPERTY( bool isGeographic READ isGeographic )
211 
212  public:
213 
215  enum CrsType
216  {
219  EpsgCrsId
220  };
221 
223  enum Format
224  {
225  FormatWkt = 0,
227  };
228 
231 
233 
234  // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
235 
251  explicit QgsCoordinateReferenceSystem( const QString &definition );
252 
253  // TODO QGIS 4: remove type and always use EPSG code
254 
266  Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
267 
270 
273 
275  operator QVariant() const
276  {
277  return QVariant::fromValue( *this );
278  }
279 
287  static QList< long > validSrsIds();
288 
289  // static creators
290 
298  static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
299 
306  Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
307 
314  Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
315 
323  static QgsCoordinateReferenceSystem fromProj( const QString &proj );
324 
332  static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
333 
342  static QgsCoordinateReferenceSystem fromSrsId( long srsId );
343 
344  // Misc helper functions -----------------------
345 
346  // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
347 
353  Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
354 
355  // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
356 
367  bool createFromOgcWmsCrs( const QString &crs );
368 
369  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
370 
378  Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
379 
392  bool createFromWkt( const QString &wkt );
393 
406  bool createFromSrsId( long srsId );
407 
431  Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
432 
460 #ifndef SIP_RUN
461  bool createFromProj( const QString &projString, bool identify = true );
462 #else
463  bool createFromProj( const QString &projString );
464 #endif
465 
481  bool createFromString( const QString &definition );
482 
483  // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
484 
500  bool createFromUserInput( const QString &definition );
501 
512  Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
513 
515  bool isValid() const;
516 
528  void validate();
529 
530  // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
531 
540  Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
541 
547  bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
548 
554  bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
555 
562  bool readXml( const QDomNode &node );
563 
570  bool writeXml( QDomNode &node, QDomDocument &doc ) const;
571 
572 
577  static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
578 
583  static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
584 
585  // Accessors -----------------------------------
586 
591  long srsid() const;
592 
593  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
594 
599  long postgisSrid() const;
600 
613  QString authid() const;
614 
622  QString description() const;
623 
630  {
634  };
635 
649  QString userFriendlyIdentifier( IdentifierType type = MediumString ) const;
650 
657  QString projectionAcronym() const;
658 
665  QString ellipsoidAcronym() const;
666 
669  {
676  WKT2_2019 = WKT2_2018,
677  WKT2_2019_SIMPLIFIED = WKT2_2018_SIMPLIFIED,
678 
679  WKT_PREFERRED = WKT2_2019,
680  WKT_PREFERRED_SIMPLIFIED = WKT2_2019_SIMPLIFIED,
681  WKT_PREFERRED_GDAL = WKT2_2019,
682  };
683 
695  QString toWkt( WktVariant variant = WKT1_GDAL, bool multiline = false, int indentationWidth = 4 ) const;
696 
709  Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
710 
723  QString toProj() const;
724 
729  bool isGeographic() const;
730 
735  bool hasAxisInverted() const;
736 
740  QgsUnitTypes::DistanceUnit mapUnits() const;
741 
750  QgsRectangle bounds() const;
751 
752  // Mutators -----------------------------------
753 
757  void setValidationHint( const QString &html );
758 
762  QString validationHint();
763 
770  static int syncDatabase();
771 
783  long saveAsUserCrs( const QString &name, Format nativeFormat = FormatWkt );
784 
786  QString geographicCrsAuthId() const;
787 
788 #ifdef SIP_RUN
789  SIP_PYOBJECT __repr__();
790  % MethodCode
791  QString str = QStringLiteral( "<QgsCoordinateReferenceSystem: %1>" ).arg( sipCpp->authid() );
792  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
793  % End
794 #endif
795 
796 #ifndef SIP_RUN
797 #if PROJ_VERSION_MAJOR>=6
798 
808  PJ *projObject() const;
809 #endif
810 #endif
811 
817  Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
818 
823  static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems();
824 
829  static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
830 
831 #ifndef SIP_RUN
832 
843  static void invalidateCache( bool disableCache = false );
844 #else
845 
853  static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
854 #endif
855 
856  // Mutators -----------------------------------
857  // We don't want to expose these to the public api since they won't create
858  // a fully valid crs. Programmers should use the createFrom* methods rather
859  private:
860 
866  static QString projFromSrsId( int srsId );
867 
873  void setProjString( const QString &projString );
874 
878  bool setWktString( const QString &wkt, bool allowProjFallback = true );
879 
883  void debugPrint();
884 
886  typedef QMap<QString, QString> RecordMap;
887 
895  RecordMap getRecord( const QString &sql );
896 
901  static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
902 
904  void setMapUnits();
905 
907  long getRecordCount();
908 
909 #if PROJ_VERSION_MAJOR>=6
910  bool loadFromAuthCode( const QString &auth, const QString &code );
911 
915  static QList< long > userSrsIds();
916 
924  long matchToUserCrs() const;
925 #endif
926 
931  bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
932 
933  bool createFromWktInternal( const QString &wkt, const QString &description );
934 
935 #if PROJ_VERSION_MAJOR<6 // not used for proj >= 6.0
936  static bool loadIds( QHash<int, QString> &wkts );
937  static bool loadWkts( QHash<int, QString> &wkts, const char *filename );
938 
940  static bool syncDatumTransform( const QString &dbPath );
941 #endif
942 
943  QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
944 
945  QString mValidationHint;
946 
947 #if PROJ_VERSION_MAJOR>=6
948  friend class QgsProjContext;
949 
950  // Only meant to be called by QgsProjContext::~QgsProjContext()
951  static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
952 #endif
953 
955  static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
956 
957  // cache
958 
959  static bool sDisableSrIdCache;
960  static bool sDisableOgcCache;
961  static bool sDisableProjCache;
962  static bool sDisableWktCache;
963  static bool sDisableSrsIdCache;
964  static bool sDisableStringCache;
965 
966  // for tests
967  static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
968  static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
969  static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
970  static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
971  static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
972  static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
973 
974  friend class TestQgsCoordinateReferenceSystem;
975  friend class QgsPostgresProvider;
976 
977  bool createFromPostgisSrid( const long id );
978 };
979 
981 
982 #ifndef SIP_RUN
984 inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
985 {
986  QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
987  mySummary += QLatin1String( "\n\t\tDescription : " );
988  if ( !r.description().isNull() )
989  {
990  mySummary += r.description();
991  }
992  else
993  {
994  mySummary += QLatin1String( "Undefined" );
995  }
996  mySummary += QLatin1String( "\n\t\tProjection : " );
997  if ( !r.projectionAcronym().isNull() )
998  {
999  mySummary += r.projectionAcronym();
1000  }
1001  else
1002  {
1003  mySummary += QLatin1String( "Undefined" );
1004  }
1005 
1006  mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1007  if ( !r.ellipsoidAcronym().isNull() )
1008  {
1009  mySummary += r.ellipsoidAcronym();
1010  }
1011  else
1012  {
1013  mySummary += QLatin1String( "Undefined" );
1014  }
1015 
1016  mySummary += QLatin1String( "\n\t\tProjString : " );
1017  if ( !r.toProj().isNull() )
1018  {
1019  mySummary += r.toProj();
1020  }
1021  else
1022  {
1023  mySummary += QLatin1String( "Undefined" );
1024  }
1025  // Using streams we need to use local 8 Bit
1026  return os << mySummary.toLocal8Bit().data() << std::endl;
1027 }
1028 #endif
1029 
1030 #endif // QGSCOORDINATEREFERENCESYSTEM_H
A rectangle specified with double values.
Definition: qgsrectangle.h:41
QString toProj() const
Returns a Proj string representation of this CRS.
bool operator==(const QgsFeatureIterator &fi1, const QgsFeatureIterator &fi2)
bool operator!=(const QgsFeatureIterator &fi1, const QgsFeatureIterator &fi2)
Helper functions for various unit types.
Definition: qgsunittypes.h:38
Full WKT2 string, conforming to ISO 19162:2015(E) / OGC 12-063r5 with all possible nodes and new keyw...
SRID used in PostGIS. DEPRECATED – DO NOT USE.
const QgsCoordinateReferenceSystem & crs
Full definition – possibly a very lengthy string, e.g. with no truncation of custom WKT definitions...
Internal ID used by QGIS in the local SQLite database.
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:161
QString ellipsoidAcronym() const
Returns the ellipsoid acronym for the ellipsoid used by the CRS.
Format
Projection definition formats.
WKT1 as traditionally output by GDAL, deriving from OGC 01-009. A notable departure from WKT1_GDAL wi...
#define SIP_SKIP
Definition: qgis_sip.h:126
QString description() const
Returns the descriptive name of the CRS, e.g., "WGS 84" or "GDA 94 / Vicgrid94".
Q_DECLARE_METATYPE(QgsMeshTimeSettings)
IdentifierType
Type of identifier string to create.
std::ostream & operator<<(std::ostream &os, const QgsCoordinateReferenceSystem &r)
Output stream operator.
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
CrsType
Enumeration of types of IDs accepted in createFromId() method.
struct sqlite3 sqlite3
A medium-length string, recommended for general purpose use.
QString projectionAcronym() const
Returns the projection acronym for the projection used by the CRS.
DistanceUnit
Units of distance.
Definition: qgsunittypes.h:67
Unique pointer for sqlite3 databases, which automatically closes the database when the pointer goes o...
#define SIP_PYARGREMOVE
Definition: qgis_sip.h:146
void PJ_CONTEXT
Definition: qgsprojutils.h:151
This class represents a coordinate reference system (CRS).
A heavily abbreviated string, for use when a compact representation is required.
WktVariant
WKT formatting variants, only used for builds based on Proj >= 6.
void(* CUSTOM_CRS_VALIDATION)(QgsCoordinateReferenceSystem &)
void * OGRSpatialReferenceH
WKT1 as traditionally output by ESRI software, deriving from OGC 99-049.