QGIS API Documentation 3.31.0-Master (9938c594d0)
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
288 static QList< long > validSrsIds();
289
290 // static creators
291
299 static QgsCoordinateReferenceSystem fromOgcWmsCrs( const QString &ogcCrs );
300
307 Q_INVOKABLE static QgsCoordinateReferenceSystem fromEpsgId( long epsg );
308
315 Q_DECL_DEPRECATED static QgsCoordinateReferenceSystem fromProj4( const QString &proj4 ) SIP_DEPRECATED;
316
324 static QgsCoordinateReferenceSystem fromProj( const QString &proj );
325
333 static QgsCoordinateReferenceSystem fromWkt( const QString &wkt );
334
343 static QgsCoordinateReferenceSystem fromSrsId( long srsId );
344
345 // Misc helper functions -----------------------
346
347 // TODO QGIS 4: remove type and always use EPSG code, rename to createFromEpsg
348
354 Q_DECL_DEPRECATED bool createFromId( long id, CrsType type = PostgisCrsId ) SIP_DEPRECATED;
355
356 // TODO QGIS 4: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
357
368 bool createFromOgcWmsCrs( const QString &crs );
369
370 // TODO QGIS 4: remove unless really necessary - let's use EPSG codes instead
371
379 Q_DECL_DEPRECATED bool createFromSrid( long srid ) SIP_DEPRECATED;
380
393 bool createFromWkt( const QString &wkt );
394
407 bool createFromSrsId( long srsId );
408
432 Q_DECL_DEPRECATED bool createFromProj4( const QString &projString ) SIP_DEPRECATED;
433
461#ifndef SIP_RUN
462 bool createFromProj( const QString &projString, bool identify = true );
463#else
464 bool createFromProj( const QString &projString );
465#endif
466
482 bool createFromString( const QString &definition );
483
484 // TODO QGIS 4: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
485
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
740 bool isDynamic() const;
741
754 QgsDatumEnsemble datumEnsemble() const SIP_THROW( QgsNotSupportedException );
755
765 QString celestialBodyName() const SIP_THROW( QgsNotSupportedException );
766
790 void setCoordinateEpoch( double epoch );
791
815 double coordinateEpoch() const;
816
828 QgsProjectionFactors factors( const QgsPoint &point ) const;
829
836 QgsProjOperation operation() const;
837
842 bool hasAxisInverted() const;
843
849#ifndef SIP_RUN
850 QList< Qgis::CrsAxisDirection > axisOrdering() const;
851#else
852 SIP_PYOBJECT axisOrdering() const SIP_TYPEHINT( List[Qgis.CrsAxisDirection] );
853 % MethodCode
854 // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
855
856 const QList< Qgis::CrsAxisDirection > cppRes = sipCpp->axisOrdering();
857
858 PyObject *l = PyList_New( cppRes.size() );
859
860 if ( !l )
861 sipIsErr = 1;
862 else
863 {
864 for ( int i = 0; i < cppRes.size(); ++i )
865 {
866 PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
867 sipType_Qgis_CrsAxisDirection );
868
869 if ( !eobj )
870 {
871 sipIsErr = 1;
872 }
873
874 PyList_SetItem( l, i, eobj );
875 }
876
877 if ( !sipIsErr )
878 {
879 sipRes = l;
880 }
881 else
882 {
883 Py_DECREF( l );
884 }
885 }
886 % End
887#endif
888
892 Qgis::DistanceUnit mapUnits() const;
893
902 QgsRectangle bounds() const;
903
910 QString toOgcUri() const;
911
912 // Mutators -----------------------------------
913
930 void updateDefinition();
931
935 void setValidationHint( const QString &html );
936
940 QString validationHint() const;
941
948 static int syncDatabase();
949
963 long saveAsUserCrs( const QString &name, Qgis::CrsDefinitionFormat nativeFormat = Qgis::CrsDefinitionFormat::Wkt );
964
974 void setNativeFormat( Qgis::CrsDefinitionFormat format );
975
985 Qgis::CrsDefinitionFormat nativeFormat() const;
986
996 QgsCoordinateReferenceSystem toGeographicCrs() const;
997
999 QString geographicCrsAuthId() const;
1000
1001#ifdef SIP_RUN
1002 SIP_PYOBJECT __repr__();
1003 % MethodCode
1004 const QString str = sipCpp->isValid() ? QStringLiteral( "<QgsCoordinateReferenceSystem: %1%2>" ).arg( !sipCpp->authid().isEmpty() ? sipCpp->authid() : sipCpp->toWkt( QgsCoordinateReferenceSystem::WKT_PREFERRED ),
1005 std::isfinite( sipCpp->coordinateEpoch() ) ? QStringLiteral( " @ %1" ).arg( sipCpp->coordinateEpoch() ) : QString() )
1006 : QStringLiteral( "<QgsCoordinateReferenceSystem: invalid>" );
1007 sipRes = PyUnicode_FromString( str.toUtf8().constData() );
1008 % End
1009#endif
1010
1011#ifndef SIP_RUN
1012
1022 PJ *projObject() const;
1023
1034 static QgsCoordinateReferenceSystem fromProjObject( PJ *object );
1035
1044 bool createFromProjObject( PJ *object );
1045#endif
1046
1052 Q_DECL_DEPRECATED static QStringList recentProjections() SIP_DEPRECATED;
1053
1058 static QList< QgsCoordinateReferenceSystem > recentCoordinateReferenceSystems();
1059
1064 static void pushRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
1065
1070 static void removeRecentCoordinateReferenceSystem( const QgsCoordinateReferenceSystem &crs );
1071
1076 static void clearRecentCoordinateReferenceSystems();
1077
1078#ifndef SIP_RUN
1079
1090 static void invalidateCache( bool disableCache = false );
1091#else
1092
1100 static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
1101#endif
1102
1103 // Mutators -----------------------------------
1104 // We don't want to expose these to the public api since they won't create
1105 // a fully valid crs. Programmers should use the createFrom* methods rather
1106 private:
1107
1113 static QString projFromSrsId( int srsId );
1114
1120 void setProjString( const QString &projString );
1121
1125 bool setWktString( const QString &wkt );
1126
1130 void debugPrint();
1131
1133 typedef QMap<QString, QString> RecordMap;
1134
1142 RecordMap getRecord( const QString &sql );
1143
1148 static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
1149
1151 void setMapUnits();
1152
1154 static long getRecordCount();
1155
1156 bool loadFromAuthCode( const QString &auth, const QString &code );
1157
1161 static QList< long > userSrsIds();
1162
1170 long matchToUserCrs() const;
1171
1176 bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
1177
1178 bool createFromWktInternal( const QString &wkt, const QString &description );
1179
1180 QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
1181
1182 QString mValidationHint;
1183
1184 Qgis::CrsDefinitionFormat mNativeFormat = Qgis::CrsDefinitionFormat::Wkt;
1185
1186 friend class QgsProjContext;
1187
1188 // Only meant to be called by QgsProjContext::~QgsProjContext()
1189 static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
1190
1192 static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
1193
1194 // cache
1195
1196 static bool sDisableSrIdCache;
1197 static bool sDisableOgcCache;
1198 static bool sDisableProjCache;
1199 static bool sDisableWktCache;
1200 static bool sDisableSrsIdCache;
1201 static bool sDisableStringCache;
1202
1203 // for tests
1204 static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
1205 static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
1206 static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
1207 static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
1208 static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
1209 static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
1210
1211 friend class TestQgsCoordinateReferenceSystem;
1213 friend bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1214 friend bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1215 friend bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1216 friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1217
1218 bool createFromPostgisSrid( const long id );
1219};
1220
1222
1223
1224#ifndef SIP_RUN
1225inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
1226{
1227 QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1228 mySummary += QLatin1String( "\n\t\tDescription : " );
1229 if ( !r.description().isNull() )
1230 {
1231 mySummary += r.description();
1232 }
1233 else
1234 {
1235 mySummary += QLatin1String( "Undefined" );
1236 }
1237 mySummary += QLatin1String( "\n\t\tProjection : " );
1238 if ( !r.projectionAcronym().isNull() )
1239 {
1240 mySummary += r.projectionAcronym();
1241 }
1242 else
1243 {
1244 mySummary += QLatin1String( "Undefined" );
1245 }
1246
1247 mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1248 if ( !r.ellipsoidAcronym().isNull() )
1249 {
1250 mySummary += r.ellipsoidAcronym();
1251 }
1252 else
1253 {
1254 mySummary += QLatin1String( "Undefined" );
1255 }
1256
1257 mySummary += QLatin1String( "\n\t\tProjString : " );
1258 if ( !r.toProj().isNull() )
1259 {
1260 mySummary += r.toProj();
1261 }
1262 else
1263 {
1264 mySummary += QLatin1String( "Undefined" );
1265 }
1266 // Using streams we need to use local 8 Bit
1267 return os << mySummary.toLocal8Bit().data() << std::endl;
1268}
1269
1270bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1271bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1272bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1273bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1274#endif
1275
1276#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:3278
CrsDefinitionFormat
CRS definition formats.
Definition: qgis.h:2399
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.
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.
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:119
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
Unique pointer for sqlite3 databases, which automatically closes the database when the pointer goes o...
#define str(x)
Definition: qgis.cpp:37
#define SIP_TYPEHINT(type)
Definition: qgis_sip.h:227
#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:198
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