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