Marble

AbstractProjection.h
Go to the documentation of this file.
1 // SPDX-License-Identifier: LGPL-2.1-or-later
2 //
3 // SPDX-FileCopyrightText: 2007-2008 Inge Wallin <[email protected]>
4 // SPDX-FileCopyrightText: 2007-2012 Torsten Rahn <[email protected]>
5 //
6 
7 
8 #ifndef MARBLE_ABSTRACTPROJECTION_H
9 #define MARBLE_ABSTRACTPROJECTION_H
10 
11 
12 /** @file
13  * This file contains the headers for AbstractProjection.
14  *
15  * @author Inge Wallin <[email protected]>
16  * @author Torsten Rahn <[email protected]>
17  */
18 
19 #include <QVector>
20 
21 #include "GeoDataCoordinates.h"
22 #include "marble_export.h"
23 
24 class QIcon;
25 class QPainterPath;
26 class QPolygonF;
27 class QRect;
28 class QString;
29 
30 namespace Marble
31 {
32 
33 // The manhattan distance in pixels at which extra nodes get created for tessellation.
34 static const int tessellationPrecision = 10;
35 static const int latLonAltBoxSamplingRate = 4;
36 
37 class GeoDataLineString;
38 class GeoDataLatLonAltBox;
39 class ViewportParams;
40 class AbstractProjectionPrivate;
41 
42 
43 /**
44  * @short A base class for all projections in Marble.
45  */
46 
47 class MARBLE_EXPORT AbstractProjection
48 {
49  // Not a QObject so far because we don't need to send signals.
50  public:
51  enum SurfaceType {
52  Cylindrical,
53  Pseudocylindrical,
54  Hybrid,
55  Conical,
56  Pseudoconical,
57  Azimuthal
58  };
59 
60  enum PreservationType {
61  NoPreservation,
62  Conformal,
63  EqualArea
64  };
65 
66  /**
67  * @brief Construct a new AbstractProjection.
68  */
70 
71  virtual ~AbstractProjection();
72 
73  /**
74  * @brief Returns the user-visible name of the projection.
75  *
76  * Example: "Mercator"
77  */
78  virtual QString name() const = 0;
79 
80  /**
81  * @brief Returns a short user description of the projection
82  * that can be used in tooltips or dialogs.
83  */
84  virtual QString description() const = 0;
85 
86  /**
87  * @brief Returns an icon for the projection.
88  */
89  virtual QIcon icon() const = 0;
90 
91  /**
92  * @brief Returns the maximum (northern) latitude that is mathematically defined and reasonable.
93  *
94  * Example: For many projections the value will represent +90 degrees in Radian.
95  * In the case of Mercator this value will equal +85.05113 degrees in Radian.
96  */
97  virtual qreal maxValidLat() const;
98 
99  /**
100  * @brief Returns the arbitrarily chosen maximum (northern) latitude.
101  * By default this value is equal to the value defined inside maxValidLat().
102  * In general this value can only be smaller or equal to maxValidLat().
103  */
104  qreal maxLat() const;
105  void setMaxLat( qreal maxLat );
106 
107  /**
108  * @brief Returns the minimum (southern) latitude that is mathematically defined and reasonable.
109  *
110  * Example: For many projections the value will represent -90 degrees in Radian.
111  * In the case of Mercator this value will equal -85.05113 degrees in Radian.
112  */
113  virtual qreal minValidLat() const;
114 
115  /**
116  * @brief Returns the arbitrarily chosen minimum (southern) latitude.
117  * By default this value is equal to the value defined inside minValidLat().
118  * In general this value can only be larger or equal to minValidLat().
119  */
120  qreal minLat() const;
121  void setMinLat( qreal minLat );
122 
123  /**
124  * @brief Returns whether the projection allows for wrapping in x direction (along the longitude scale).
125  *
126  * Example: Cylindrical projections allow for repeating.
127  */
128  virtual bool repeatableX() const;
129 
130  /**
131  * @brief Returns whether the projection allows to navigate seamlessly "over" the pole.
132  *
133  * Example: Azimuthal projections.
134  */
135  virtual bool traversablePoles() const;
136  virtual bool traversableDateLine() const;
137 
138  virtual SurfaceType surfaceType() const = 0;
139 
140  virtual PreservationType preservationType() const;
141 
142  // The projection surface can have different orientations:
143  // - normal: the surface's axis of symmetry matches the Earth's axis
144  // - transverse: orthogonally oriented compared to the Earth's axis
145  // - oblique: somewhere in between
146 
147  virtual bool isOrientedNormal() const;
148 
149  /**
150  * @brief Defines whether a projection is supposed to be clipped to a certain radius.
151  *
152  * Example: The Gnomonic projection is clipped to a circle of a certain clipping radius
153  * (although it's mathematically defined beyond that radius).
154  */
155  virtual bool isClippedToSphere() const;
156 
157  virtual qreal clippingRadius() const;
158 
159  /**
160  * @brief Get the screen coordinates corresponding to geographical coordinates in the map.
161  * @param lon the lon coordinate of the requested pixel position in radians
162  * @param lat the lat coordinate of the requested pixel position in radians
163  * @param viewport the viewport parameters
164  * @param x the x coordinate of the pixel is returned through this parameter
165  * @param y the y coordinate of the pixel is returned through this parameter
166  * @return @c true if the geographical coordinates are visible on the screen
167  * @c false if the geographical coordinates are not visible on the screen
168  *
169  * @see ViewportParams
170  */
171  bool screenCoordinates( const qreal lon, const qreal lat,
172  const ViewportParams *viewport,
173  qreal& x, qreal& y ) const;
174 
175  /**
176  * @brief Get the screen coordinates corresponding to geographical coordinates in the map.
177  *
178  * @param geopoint the point on earth, including altitude, that we want the coordinates for.
179  * @param viewport the viewport parameters
180  * @param x the x coordinate of the pixel is returned through this parameter
181  * @param y the y coordinate of the pixel is returned through this parameter
182  * @param globeHidesPoint whether the point gets hidden on the far side of the earth
183  *
184  * @return @c true if the geographical coordinates are visible on the screen
185  * @c false if the geographical coordinates are not visible on the screen
186  *
187  * @see ViewportParams
188  */
189  virtual bool screenCoordinates( const GeoDataCoordinates &geopoint,
190  const ViewportParams *viewport,
191  qreal &x, qreal &y,
192  bool &globeHidesPoint ) const = 0;
193 
194  // Will just call the virtual version with a dummy globeHidesPoint.
195  bool screenCoordinates( const GeoDataCoordinates &geopoint,
196  const ViewportParams *viewport,
197  qreal &x, qreal &y ) const;
198 
199  /**
200  * @brief Get the coordinates of screen points for geographical coordinates in the map.
201  *
202  * @param coordinates the point on earth, including altitude, that we want the coordinates for.
203  * @param viewport the viewport parameters
204  * @param x the x coordinates of the pixels are returned through this parameter
205  * @param y the y coordinate of the pixel is returned through this parameter
206  * @param pointRepeatNum the amount of times that a single geographical
207  point gets represented on the map
208  * @param size the size
209  * @param globeHidesPoint whether the point gets hidden on the far side of the earth
210  *
211  * @return @c true if the geographical coordinates are visible on the screen
212  * @c false if the geographical coordinates are not visible on the screen
213  *
214  * @see ViewportParams
215  */
216  virtual bool screenCoordinates( const GeoDataCoordinates &coordinates,
217  const ViewportParams *viewport,
218  qreal *x, qreal &y, int &pointRepeatNum,
219  const QSizeF& size,
220  bool &globeHidesPoint ) const = 0;
221 
222  virtual bool screenCoordinates( const GeoDataLineString &lineString,
223  const ViewportParams *viewport,
224  QVector<QPolygonF*> &polygons ) const = 0;
225 
226  /**
227  * @brief Get the earth coordinates corresponding to a pixel in the map.
228  * @param x the x coordinate of the pixel
229  * @param y the y coordinate of the pixel
230  * @param viewport the viewport parameters
231  * @param lon the longitude angle is returned through this parameter
232  * @param lat the latitude angle is returned through this parameter
233  * @param unit the unit of the angles for lon and lat.
234  * @return @c true if the pixel (x, y) is within the globe
235  * @c false if the pixel (x, y) is outside the globe, i.e. in space.
236  */
237  virtual bool geoCoordinates( const int x, const int y,
238  const ViewportParams *viewport,
239  qreal& lon, qreal& lat,
240  GeoDataCoordinates::Unit unit = GeoDataCoordinates::Degree ) const = 0;
241 
242 
243  /**
244  * @brief Returns a GeoDataLatLonAltBox bounding box of the given screenrect inside the given viewport.
245  */
246  virtual GeoDataLatLonAltBox latLonAltBox( const QRect& screenRect,
247  const ViewportParams *viewport ) const;
248 
249  /**
250  * @brief Returns whether the projected data fully obstructs the current viewport.
251  * In this case there are no black areas visible around the actual map.
252  * This case allows for performance optimizations.
253  */
254  virtual bool mapCoversViewport( const ViewportParams *viewport ) const = 0;
255 
256  /**
257  * @brief Returns the shape/outline of a map projection.
258  * This call allows e.g. to draw the default background color of the map itself.
259  *
260  * Example: For an azimuthal projection a circle is returned at low zoom values.
261  */
262  virtual QPainterPath mapShape( const ViewportParams *viewport ) const = 0;
263 
264  QRegion mapRegion( const ViewportParams *viewport ) const;
265 
266  protected:
268  explicit AbstractProjection( AbstractProjectionPrivate* dd );
269 
270  private:
271  Q_DECLARE_PRIVATE(AbstractProjection)
272  Q_DISABLE_COPY( AbstractProjection )
273 };
274 
275 }
276 
277 #endif
A 3d point representation.
A class that defines a 3D bounding box for geographic data.
A base class for all projections in Marble.
A LineString that allows to store a contiguous set of line segments.
A public class that controls what is visible in the viewport of a Marble map.
Binds a QML item to a specific geodetic location in screen coordinates.
Unit
enum used constructor to specify the units used
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:09:05 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.