QGIS API Documentation  3.13.0-Master (9729a43df7)
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 
210 {
211  Q_GADGET
212 
213  Q_PROPERTY( QgsUnitTypes::DistanceUnit mapUnits READ mapUnits )
214  Q_PROPERTY( bool isGeographic READ isGeographic )
215 
216  public:
217 
219  enum CrsType
220  {
223  EpsgCrsId
224  };
225 
227  enum Format
228  {
229  FormatWkt = 0,
231  };
232 
235 
237 
238  // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
239 
255  explicit QgsCoordinateReferenceSystem( const QString &definition );
256 
257  // TODO QGIS 4: remove type and always use EPSG code
258 
270  Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
271 
274 
277 
279  operator QVariant() const
280  {
281  return QVariant::fromValue( *this );
282  }
283 
291  static QList< long > validSrsIds();
292 
293  // static creators
294 
302  static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
303 
310  Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
311 
318  Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
319 
327  static QgsCoordinateReferenceSystem fromProj( const QString &proj );
328 
336  static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
337 
346  static QgsCoordinateReferenceSystem fromSrsId( long srsId );
347 
348  // Misc helper functions -----------------------
349 
350  // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
351 
357  Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
358 
359  // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
360 
371  bool createFromOgcWmsCrs( const QString &crs );
372 
373  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
374 
382  Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
383 
396  bool createFromWkt( const QString &wkt );
397 
410  bool createFromSrsId( long srsId );
411 
435  Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
436 
464 #ifndef SIP_RUN
465  bool createFromProj( const QString &projString, bool identify = true );
466 #else
467  bool createFromProj( const QString &projString );
468 #endif
469 
484  bool createFromString( const QString &definition );
485  // TODO QGIS3: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
501  bool createFromUserInput( const QString &definition );
502 
513  Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
514 
516  bool isValid() const;
517 
529  void validate();
530 
531  // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
532 
541  Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
542 
548  bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
549 
555  bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
556 
563  bool readXml( const QDomNode &node );
564 
571  bool writeXml( QDomNode &node, QDomDocument &doc ) const;
572 
573 
578  static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
579 
584  static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
585 
586  // Accessors -----------------------------------
587 
592  long srsid() const;
593 
594  // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
595 
600  long postgisSrid() const;
601 
614  QString authid() const;
615 
623  QString description() const;
624 
631  {
635  };
636 
650  QString userFriendlyIdentifier( IdentifierType type = MediumString ) const;
651 
658  QString projectionAcronym() const;
659 
666  QString ellipsoidAcronym() const;
667 
670  {
677  WKT2_2019 = WKT2_2018,
678  WKT2_2019_SIMPLIFIED = WKT2_2018_SIMPLIFIED,
679 
680  WKT_PREFERRED = WKT2_2019,
681  WKT_PREFERRED_SIMPLIFIED = WKT2_2019_SIMPLIFIED,
682  WKT_PREFERRED_GDAL = WKT2_2019,
683  };
684 
696  QString toWkt( WktVariant variant = WKT1_GDAL, bool multiline = false, int indentationWidth = 4 ) const;
697 
710  Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
711 
724  QString toProj() const;
725 
730  bool isGeographic() const;
731 
736  bool hasAxisInverted() const;
737 
741  QgsUnitTypes::DistanceUnit mapUnits() const;
742 
751  QgsRectangle bounds() const;
752 
753  // Mutators -----------------------------------
754 
758  void setValidationHint( const QString &html );
759 
763  QString validationHint();
764 
771  static int syncDatabase();
772 
784  long saveAsUserCrs( const QString &name, Format nativeFormat = FormatWkt );
785 
787  QString geographicCrsAuthId() const;
788 
789 #ifdef SIP_RUN
790  SIP_PYOBJECT __repr__();
791  % MethodCode
792  QString str = QStringLiteral( "<QgsCoordinateReferenceSystem: %1>" ).arg( sipCpp->authid() );
793  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
794  % End
795 #endif
796 
797 #ifndef SIP_RUN
798 #if PROJ_VERSION_MAJOR>=6
799 
809  PJ *projObject() const;
810 #endif
811 #endif
812 
818  Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
819 
824  static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems();
825 
830  static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
831 
832 #ifndef SIP_RUN
833 
844  static void invalidateCache( bool disableCache = false );
845 #else
846 
854  static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
855 #endif
856 
857  // Mutators -----------------------------------
858  // We don't want to expose these to the public api since they won't create
859  // a fully valid crs. Programmers should use the createFrom* methods rather
860  private:
861 
867  static QString projFromSrsId( int srsId );
868 
874  void setProjString( const QString &projString );
875 
879  bool setWktString( const QString &wkt, bool allowProjFallback = true );
880 
884  void debugPrint();
885 
887  typedef QMap<QString, QString> RecordMap;
888 
896  RecordMap getRecord( const QString &sql );
897 
902  static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
903 
905  void setMapUnits();
906 
908  long getRecordCount();
909 
910 #if PROJ_VERSION_MAJOR>=6
911  bool loadFromAuthCode( const QString &auth, const QString &code );
912 
916  static QList< long > userSrsIds();
917 
925  long matchToUserCrs() const;
926 #endif
927 
932  bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
933 
934 #if PROJ_VERSION_MAJOR<6 // not used for proj >= 6.0
935  static bool loadIds( QHash<int, QString> &wkts );
936  static bool loadWkts( QHash<int, QString> &wkts, const char *filename );
937 
939  static bool syncDatumTransform( const QString &dbPath );
940 #endif
941 
942  QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
943 
944  QString mValidationHint;
945 
946 #if PROJ_VERSION_MAJOR>=6
947  friend class QgsProjContext;
948 
949  // Only meant to be called by QgsProjContext::~QgsProjContext()
950  static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
951 #endif
952 
954  static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
955 
956  // cache
957 
958  static bool sDisableSrIdCache;
959  static bool sDisableOgcCache;
960  static bool sDisableProjCache;
961  static bool sDisableWktCache;
962  static bool sDisableSrsIdCache;
963  static bool sDisableStringCache;
964 
965  // for tests
966  static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
967  static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
968  static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
969  static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
970  static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
971  static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
972 
973  friend class TestQgsCoordinateReferenceSystem;
974  friend class QgsPostgresProvider;
975 
976  bool createFromPostgisSrid( const long id );
977 };
978 
980 
981 #ifndef SIP_RUN
983 inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
984 {
985  QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
986  mySummary += QLatin1String( "\n\t\tDescription : " );
987  if ( !r.description().isNull() )
988  {
989  mySummary += r.description();
990  }
991  else
992  {
993  mySummary += QLatin1String( "Undefined" );
994  }
995  mySummary += QLatin1String( "\n\t\tProjection : " );
996  if ( !r.projectionAcronym().isNull() )
997  {
998  mySummary += r.projectionAcronym();
999  }
1000  else
1001  {
1002  mySummary += QLatin1String( "Undefined" );
1003  }
1004 
1005  mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1006  if ( !r.ellipsoidAcronym().isNull() )
1007  {
1008  mySummary += r.ellipsoidAcronym();
1009  }
1010  else
1011  {
1012  mySummary += QLatin1String( "Undefined" );
1013  }
1014 
1015  mySummary += QLatin1String( "\n\t\tProjString : " );
1016  if ( !r.toProj().isNull() )
1017  {
1018  mySummary += r.toProj();
1019  }
1020  else
1021  {
1022  mySummary += QLatin1String( "Undefined" );
1023  }
1024  // Using streams we need to use local 8 Bit
1025  return os << mySummary.toLocal8Bit().data() << std::endl;
1026 }
1027 #endif
1028 
1029 #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.