QGIS API Documentation 3.37.0-Master (fdefdf9c27f)
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
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 "qgis.h"
36#include "qgsconfig.h"
37#include "qgsrectangle.h"
38#include "qgssqliteutils.h"
39
40class QDomNode;
41class QDomDocument;
42class QgsCoordinateReferenceSystemPrivate;
46
47#ifndef SIP_RUN
48struct PJconsts;
49typedef struct PJconsts PJ;
50
51#if PROJ_VERSION_MAJOR>=8
52struct pj_ctx;
53typedef struct pj_ctx PJ_CONTEXT;
54#else
55struct projCtx_t;
56typedef struct projCtx_t PJ_CONTEXT;
57#endif
58#endif
59
60// forward declaration for sqlite3
61typedef struct sqlite3 sqlite3 SIP_SKIP;
62
63#ifdef DEBUG
64typedef struct OGRSpatialReferenceHS *OGRSpatialReferenceH SIP_SKIP;
65#else
67#endif
68
71
212{
213 Q_GADGET
214
215 Q_PROPERTY( Qgis::DistanceUnit mapUnits READ mapUnits )
216 Q_PROPERTY( bool isGeographic READ isGeographic )
217 Q_PROPERTY( QString authid READ authid )
218 Q_PROPERTY( QString description READ description )
219
220 public:
221
224 {
227 EpsgCrsId
228 };
229
232
234
235 // TODO QGIS 4: remove "POSTGIS" and "INTERNAL"
236
252 explicit QgsCoordinateReferenceSystem( const QString &definition );
253
254 // TODO QGIS 4: remove type and always use EPSG code
255
267 Q_DECL_DEPRECATED explicit QgsCoordinateReferenceSystem( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
268
271
274
276 operator QVariant() const
277 {
278 return QVariant::fromValue( *this );
279 }
280
287 static QList< long > validSrsIds();
288
289 // static creators
290
297 static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
298
304 Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
305
312 Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
313
321 static QgsCoordinateReferenceSystem fromProj( const QString &proj );
322
329 static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
330
338 static QgsCoordinateReferenceSystem fromSrsId( long srsId );
339
349 static QgsCoordinateReferenceSystem createCompoundCrs( const QgsCoordinateReferenceSystem &horizontalCrs, const QgsCoordinateReferenceSystem &verticalCrs );
350
351 // Misc helper functions -----------------------
352
353 // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
354
360 Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
361
362 // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
363
374 bool createFromOgcWmsCrs( const QString &crs );
375
376 // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
377
385 Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
386
399 bool createFromWkt( const QString &wkt );
400
413 bool createFromSrsId( long srsId );
414
438 Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
439
467#ifndef SIP_RUN
468 bool createFromProj( const QString &projString, bool identify = true );
469#else
470 bool createFromProj( const QString &projString );
471#endif
472
488 bool createFromString( const QString &definition );
489
490 // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
491
507 bool createFromUserInput( const QString &definition );
508
519 Q_DECL_DEPRECATED static void setupESRIWktFix() SIP_DEPRECATED;
520
522 bool isValid() const;
523
535 void validate();
536
537 // TODO QGIS 4: seems completely obsolete now (only compares proj4 - already done in createFromProj4)
538
547 Q_DECL_DEPRECATED long findMatchingProj() SIP_DEPRECATED;
548
554 bool operator==( const QgsCoordinateReferenceSystem &srs ) const;
555
561 bool operator!=( const QgsCoordinateReferenceSystem &srs ) const;
562
569 bool readXml( const QDomNode &node );
570
577 bool writeXml( QDomNode &node, QDomDocument &doc ) const;
578
579
584 static void setCustomCrsValidation( CUSTOM_CRS_VALIDATION f ) SIP_SKIP;
585
590 static CUSTOM_CRS_VALIDATION customCrsValidation() SIP_SKIP;
591
592 // Accessors -----------------------------------
593
598 long srsid() const;
599
600 // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
601
606 long postgisSrid() const;
607
620 QString authid() const;
621
629 QString description() const;
630
644 QString userFriendlyIdentifier( Qgis::CrsIdentifierType type = Qgis::CrsIdentifierType::MediumString ) const;
645
652 QString projectionAcronym() const;
653
660 QString ellipsoidAcronym() const;
661
673 QString toWkt( Qgis::CrsWktVariant variant = Qgis::CrsWktVariant::Wkt1Gdal, bool multiline = false, int indentationWidth = 4 ) const;
674
687 Q_DECL_DEPRECATED QString toProj4() const SIP_DEPRECATED;
688
701 QString toProj() const;
702
708 Qgis::CrsType type() const;
709
715 bool isDeprecated() const;
716
721 bool isGeographic() const;
722
731 bool isDynamic() const;
732
747 QgsDatumEnsemble datumEnsemble() const SIP_THROW( QgsNotSupportedException );
748
758 QString celestialBodyName() const SIP_THROW( QgsNotSupportedException );
759
783 void setCoordinateEpoch( double epoch );
784
808 double coordinateEpoch() const;
809
821 QgsProjectionFactors factors( const QgsPoint &point ) const;
822
829 QgsProjOperation operation() const;
830
838 bool hasAxisInverted() const;
839
845#ifndef SIP_RUN
846 QList< Qgis::CrsAxisDirection > axisOrdering() const;
847#else
848 SIP_PYOBJECT axisOrdering() const SIP_TYPEHINT( List[Qgis.CrsAxisDirection] );
849 % MethodCode
850 // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
851
852 const QList< Qgis::CrsAxisDirection > cppRes = sipCpp->axisOrdering();
853
854 PyObject *l = PyList_New( cppRes.size() );
855
856 if ( !l )
857 sipIsErr = 1;
858 else
859 {
860 for ( int i = 0; i < cppRes.size(); ++i )
861 {
862 PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
863 sipType_Qgis_CrsAxisDirection );
864
865 if ( !eobj )
866 {
867 sipIsErr = 1;
868 }
869
870 PyList_SetItem( l, i, eobj );
871 }
872
873 if ( !sipIsErr )
874 {
875 sipRes = l;
876 }
877 else
878 {
879 Py_DECREF( l );
880 }
881 }
882 % End
883#endif
884
890 Qgis::DistanceUnit mapUnits() const;
891
899 QgsRectangle bounds() const;
900
907 QString toOgcUri() const;
908
909 // Mutators -----------------------------------
910
927 void updateDefinition();
928
932 void setValidationHint( const QString &html );
933
937 QString validationHint() const;
938
945 static int syncDatabase();
946
960 long saveAsUserCrs( const QString &name, Qgis::CrsDefinitionFormat nativeFormat = Qgis::CrsDefinitionFormat::Wkt );
961
971 void setNativeFormat( Qgis::CrsDefinitionFormat format );
972
982 Qgis::CrsDefinitionFormat nativeFormat() const;
983
993 QgsCoordinateReferenceSystem toGeographicCrs() const;
994
1005 QgsCoordinateReferenceSystem horizontalCrs() const;
1006
1017 QgsCoordinateReferenceSystem verticalCrs() const;
1018
1020 QString geographicCrsAuthId() const;
1021
1022#ifdef SIP_RUN
1023 SIP_PYOBJECT __repr__();
1024 % MethodCode
1025 const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1%2>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( Qgis::CrsWktVariant::Preferred ),
1026 std::isfinite( sipCpp->coordinateEpoch() ) ? QStringLiteral( " @ %1" ).arg( sipCpp->coordinateEpoch() ) : QString() )
1027 : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
1028 sipRes = PyUnicode_FromString( str.toUtf8().constData() );
1029 % End
1030#endif
1031
1032#ifndef SIP_RUN
1033
1043 PJ *projObject() const;
1044
1055 static QgsCoordinateReferenceSystem fromProjObject( PJ *object );
1056
1065 bool createFromProjObject( PJ *object );
1066#endif
1067
1074 Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
1075
1081 Q_DECL_DEPRECATED static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems() SIP_DEPRECATED;
1082
1088 Q_DECL_DEPRECATED static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs ) SIP_DEPRECATED;
1089
1095 Q_DECL_DEPRECATED static void removeRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs ) SIP_DEPRECATED;
1096
1102 Q_DECL_DEPRECATED static void clearRecentCoordinateReferenceSystems() SIP_DEPRECATED;
1103
1104#ifndef SIP_RUN
1105
1115 static void invalidateCache( bool disableCache = false );
1116#else
1117
1124 static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
1125#endif
1126
1127 // Mutators -----------------------------------
1128 // We don't want to expose these to the public api since they won't create
1129 // a fully valid crs. Programmers should use the createFrom* methods rather
1130 private:
1131
1137 static QString projFromSrsId( int srsId );
1138
1144 void setProjString( const QString &projString );
1145
1149 bool setWktString( const QString &wkt );
1150
1154 void debugPrint();
1155
1157 typedef QMap<QString, QString> RecordMap;
1158
1166 RecordMap getRecord( const QString &sql );
1167
1172 static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
1173
1175 void setMapUnits();
1176
1178 static long getRecordCount();
1179
1180 bool loadFromAuthCode( const QString &auth, const QString &code );
1181
1185 static QList< long > userSrsIds();
1186
1194 long matchToUserCrs() const;
1195
1200 bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
1201
1202 bool createFromWktInternal( const QString &wkt, const QString &description );
1203
1204 QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
1205
1206 QString mValidationHint;
1207
1209
1210 friend class QgsProjContext;
1211
1212 // Only meant to be called by QgsProjContext::~QgsProjContext()
1213 static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
1214
1216 static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
1217
1218 // cache
1219
1220 static bool sDisableSrIdCache;
1221 static bool sDisableOgcCache;
1222 static bool sDisableProjCache;
1223 static bool sDisableWktCache;
1224 static bool sDisableSrsIdCache;
1225 static bool sDisableStringCache;
1226
1227 // for tests
1228 static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
1229 static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
1230 static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
1231 static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
1232 static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
1233 static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
1234
1235 friend class TestQgsCoordinateReferenceSystem;
1237 friend bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1238 friend bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1239 friend bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1240 friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1241
1242 bool createFromPostgisSrid( const long id );
1243};
1244
1246
1247
1248#ifndef SIP_RUN
1249inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
1250{
1251 QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1252 mySummary += QLatin1String( "\n\t\tDescription : " );
1253 if ( !r.description().isNull() )
1254 {
1255 mySummary += r.description();
1256 }
1257 else
1258 {
1259 mySummary += QLatin1String( "Undefined" );
1260 }
1261 mySummary += QLatin1String( "\n\t\tProjection : " );
1262 if ( !r.projectionAcronym().isNull() )
1263 {
1264 mySummary += r.projectionAcronym();
1265 }
1266 else
1267 {
1268 mySummary += QLatin1String( "Undefined" );
1269 }
1270
1271 mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1272 if ( !r.ellipsoidAcronym().isNull() )
1273 {
1274 mySummary += r.ellipsoidAcronym();
1275 }
1276 else
1277 {
1278 mySummary += QLatin1String( "Undefined" );
1279 }
1280
1281 mySummary += QLatin1String( "\n\t\tProjString : " );
1282 if ( !r.toProj().isNull() )
1283 {
1284 mySummary += r.toProj();
1285 }
1286 else
1287 {
1288 mySummary += QLatin1String( "Undefined" );
1289 }
1290 // Using streams we need to use local 8 Bit
1291 return os << mySummary.toLocal8Bit().data() << std::endl;
1292}
1293
1294bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1295bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1296bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1297bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1298#endif
1299
1300#endif // QGSCOORDINATEREFERENCESYSTEM_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:54
DistanceUnit
Units of distance.
Definition: qgis.h:4124
CrsDefinitionFormat
CRS definition formats.
Definition: qgis.h:3167
@ Wkt
WKT format (always recommended over proj string format)
@ Preferred
Preferred format, matching the most recent WKT ISO standard. Currently an alias to WKT2_2019,...
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 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.
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:264
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
Unique pointer for sqlite3 databases, which automatically closes the database when the pointer goes o...
#define str(x)
Definition: qgis.cpp:38
#define SIP_TYPEHINT(type)
Definition: qgis_sip.h:232
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_PYARGREMOVE
Definition: qgis_sip.h:151
#define SIP_THROW(name,...)
Definition: qgis_sip.h:203
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
struct projCtx_t PJ_CONTEXT
bool CORE_EXPORT operator>=(const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2)
void(* CUSTOM_CRS_VALIDATION)(QgsCoordinateReferenceSystem &)
std::ostream & operator<<(std::ostream &os, const QgsCoordinateReferenceSystem &r)
Output stream operator.
Q_DECLARE_METATYPE(QgsDatabaseQueryLogEntry)
const QgsCoordinateReferenceSystem & crs
bool hasAxisInverted