QGIS API Documentation 3.29.0-Master (19d7edcfed)
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 "qgsconfig.h"
36#include "qgsunittypes.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( QgsUnitTypes::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 QgsUnitTypes::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
1066#ifndef SIP_RUN
1067
1078 static void invalidateCache( bool disableCache = false );
1079#else
1080
1088 static void invalidateCache( bool disableCache SIP_PYARGREMOVE = false );
1089#endif
1090
1091 // Mutators -----------------------------------
1092 // We don't want to expose these to the public api since they won't create
1093 // a fully valid crs. Programmers should use the createFrom* methods rather
1094 private:
1095
1101 static QString projFromSrsId( int srsId );
1102
1108 void setProjString( const QString &projString );
1109
1113 bool setWktString( const QString &wkt );
1114
1118 void debugPrint();
1119
1121 typedef QMap<QString, QString> RecordMap;
1122
1130 RecordMap getRecord( const QString &sql );
1131
1136 static int openDatabase( const QString &path, sqlite3_database_unique_ptr &database, bool readonly = true );
1137
1139 void setMapUnits();
1140
1142 static long getRecordCount();
1143
1144 bool loadFromAuthCode( const QString &auth, const QString &code );
1145
1149 static QList< long > userSrsIds();
1150
1158 long matchToUserCrs() const;
1159
1164 bool loadFromDatabase( const QString &db, const QString &expression, const QString &value );
1165
1166 bool createFromWktInternal( const QString &wkt, const QString &description );
1167
1168 QExplicitlySharedDataPointer<QgsCoordinateReferenceSystemPrivate> d;
1169
1170 QString mValidationHint;
1171
1172 Qgis::CrsDefinitionFormat mNativeFormat = Qgis::CrsDefinitionFormat::Wkt;
1173
1174 friend class QgsProjContext;
1175
1176 // Only meant to be called by QgsProjContext::~QgsProjContext()
1177 static void removeFromCacheObjectsBelongingToCurrentThread( PJ_CONTEXT *pj_context );
1178
1180 static CUSTOM_CRS_VALIDATION sCustomSrsValidation;
1181
1182 // cache
1183
1184 static bool sDisableSrIdCache;
1185 static bool sDisableOgcCache;
1186 static bool sDisableProjCache;
1187 static bool sDisableWktCache;
1188 static bool sDisableSrsIdCache;
1189 static bool sDisableStringCache;
1190
1191 // for tests
1192 static const QHash< QString, QgsCoordinateReferenceSystem > &stringCache();
1193 static const QHash< QString, QgsCoordinateReferenceSystem > &projCache();
1194 static const QHash< QString, QgsCoordinateReferenceSystem > &ogcCache();
1195 static const QHash< QString, QgsCoordinateReferenceSystem > &wktCache();
1196 static const QHash< long, QgsCoordinateReferenceSystem > &srsIdCache();
1197 static const QHash< long, QgsCoordinateReferenceSystem > &srIdCache();
1198
1199 friend class TestQgsCoordinateReferenceSystem;
1201 friend bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1202 friend bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1203 friend bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1204 friend bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1205
1206 bool createFromPostgisSrid( const long id );
1207};
1208
1210
1211
1212#ifndef SIP_RUN
1213inline std::ostream &operator << ( std::ostream &os, const QgsCoordinateReferenceSystem &r )
1214{
1215 QString mySummary( QStringLiteral( "\n\tSpatial Reference System:" ) );
1216 mySummary += QLatin1String( "\n\t\tDescription : " );
1217 if ( !r.description().isNull() )
1218 {
1219 mySummary += r.description();
1220 }
1221 else
1222 {
1223 mySummary += QLatin1String( "Undefined" );
1224 }
1225 mySummary += QLatin1String( "\n\t\tProjection : " );
1226 if ( !r.projectionAcronym().isNull() )
1227 {
1228 mySummary += r.projectionAcronym();
1229 }
1230 else
1231 {
1232 mySummary += QLatin1String( "Undefined" );
1233 }
1234
1235 mySummary += QLatin1String( "\n\t\tEllipsoid : " );
1236 if ( !r.ellipsoidAcronym().isNull() )
1237 {
1238 mySummary += r.ellipsoidAcronym();
1239 }
1240 else
1241 {
1242 mySummary += QLatin1String( "Undefined" );
1243 }
1244
1245 mySummary += QLatin1String( "\n\t\tProjString : " );
1246 if ( !r.toProj().isNull() )
1247 {
1248 mySummary += r.toProj();
1249 }
1250 else
1251 {
1252 mySummary += QLatin1String( "Undefined" );
1253 }
1254 // Using streams we need to use local 8 Bit
1255 return os << mySummary.toLocal8Bit().data() << std::endl;
1256}
1257
1258bool CORE_EXPORT operator> ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1259bool CORE_EXPORT operator< ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1260bool CORE_EXPORT operator>= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1261bool CORE_EXPORT operator<= ( const QgsCoordinateReferenceSystem &c1, const QgsCoordinateReferenceSystem &c2 );
1262#endif
1263
1264#endif // QGSCOORDINATEREFERENCESYSTEM_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:72
CrsDefinitionFormat
CRS definition formats.
Definition: qgis.h:2119
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: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: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
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_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