1 /*************************************************************************** 2 qgsellipsoidutils.h 3 -------------------- 4 Date : April 2017 5 Copyright : (C) 2017 by Nyall Dawson 6 email : nyall dot dawson at gmail dot com 7 *************************************************************************** 8 * * 9 * This program is free software; you can redistribute it and/or modify * 10 * it under the terms of the GNU General Public License as published by * 11 * the Free Software Foundation; either version 2 of the License, or * 12 * (at your option) any later version. * 13 * * 14 ***************************************************************************/ 15 16 #ifndef QGSELLIPSOIDUTILS_H 17 #define QGSELLIPSOIDUTILS_H 18 19 #include "qgis_core.h" 20 #include "qgis_sip.h" 21 #include "qgscoordinatereferencesystem.h" 22 #include <QStringList> 23 24 class QgsCelestialBody; 25 26 /** 27 * \class QgsEllipsoidUtils 28 * \ingroup core 29 * \brief Contains utility functions for working with ellipsoids and querying the ellipsoid database. 30 * 31 * \since QGIS 3.0 32 */ 33 class CORE_EXPORT QgsEllipsoidUtils 34 { 35 public: 36 37 /** 38 * Contains parameters for an ellipsoid. 39 * \since QGIS 3.0 40 */ 41 struct EllipsoidParameters 42 { 43 //! Whether ellipsoid parameters are valid 44 bool valid{ true }; 45 46 //! Semi-major axis 47 double semiMajor{ -1.0 }; 48 //! Semi-minor axis 49 double semiMinor{ -1.0 }; 50 51 //! Whether custom parameters alone should be used (semiMajor/semiMinor only) 52 bool useCustomParameters{ false }; 53 54 //! Inverse flattening 55 double inverseFlattening{ -1.0 }; 56 57 //! Associated coordinate reference system 58 QgsCoordinateReferenceSystem crs; 59 60 }; 61 62 /** 63 * Contains definition of an ellipsoid. 64 * \since QGIS 3.0 65 */ 66 struct EllipsoidDefinition 67 { 68 //! authority:code for QGIS builds with proj version 6 or greater, or custom acronym for ellipsoid for earlier proj builds 69 QString acronym; 70 //! Description of ellipsoid 71 QString description; 72 //! Ellipsoid parameters 73 QgsEllipsoidUtils::EllipsoidParameters parameters; 74 75 /** 76 * Name of the associated celestial body (e.g. "Earth"). 77 * 78 * \warning This method requires PROJ 8.1 or later. On earlier PROJ builds the string will always be empty. 79 * 80 * \since QGIS 3.20 81 */ 82 QString celestialBodyName; 83 }; 84 85 /** 86 * Returns the parameters for the specified \a ellipsoid. 87 * Results are cached to allow for fast retrieval of parameters. 88 */ 89 static EllipsoidParameters ellipsoidParameters( const QString &ellipsoid ); 90 91 /** 92 * Returns a list of the definitions for all known ellipsoids from the 93 * internal ellipsoid database. 94 * \see acronyms() 95 */ 96 static QList< QgsEllipsoidUtils::EllipsoidDefinition > definitions(); 97 98 /** 99 * Returns a list of all known ellipsoid acronyms from the internal 100 * ellipsoid database. 101 * \see definitions() 102 */ 103 static QStringList acronyms(); 104 105 /** 106 * Returns a list of all known celestial bodies. 107 * 108 * \note This method is an alias for QgsCoordinateReferenceSystemRegistry::celestialBodies(). 109 * 110 * \warning This method requires PROJ 8.1 or later 111 * 112 * \throws QgsNotSupportedException on QGIS builds based on PROJ 8.0 or earlier. 113 * 114 * \since QGIS 3.20 115 */ 116 static QList< QgsCelestialBody > celestialBodies(); 117 118 #ifndef SIP_RUN 119 120 /** 121 * Clears the internal cache used. 122 * 123 * If \a disableCache is TRUE then the inbuilt cache will be completely disabled. This 124 * argument is for internal use only. 125 * 126 * \since QGIS 3.10 127 */ 128 static void invalidateCache( bool disableCache = false ); 129 #endif 130 }; 131 132 #endif // QGSELLIPSOIDUTILS_H 133 134