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 <ingwa@kde.org>
4// SPDX-FileCopyrightText: 2007-2012 Torsten Rahn <rahn@kde.org>
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 <inge@lysator.liu.se>
16 * @author Torsten Rahn <rahn@kde.org>
17 */
18
19#include <QVector>
20
21#include "GeoDataCoordinates.h"
22#include "marble_export.h"
23
24class QIcon;
25class QPainterPath;
26class QPolygonF;
27class QRect;
28class QString;
29
30namespace Marble
31{
32
33// The manhattan distance in pixels at which extra nodes get created for tessellation.
34static const int tessellationPrecision = 10;
35static const int latLonAltBoxSamplingRate = 4;
36
37class GeoDataLineString;
38class GeoDataLatLonAltBox;
39class ViewportParams;
40class AbstractProjectionPrivate;
41
42
43/**
44 * @short A base class for all projections in Marble.
45 */
46
47class MARBLE_EXPORT AbstractProjection
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 base class for all projections in Marble.
virtual bool mapCoversViewport(const ViewportParams *viewport) const =0
Returns whether the projected data fully obstructs the current viewport.
virtual bool screenCoordinates(const GeoDataCoordinates &coordinates, const ViewportParams *viewport, qreal *x, qreal &y, int &pointRepeatNum, const QSizeF &size, bool &globeHidesPoint) const =0
Get the coordinates of screen points for geographical coordinates in the map.
virtual bool geoCoordinates(const int x, const int y, const ViewportParams *viewport, qreal &lon, qreal &lat, GeoDataCoordinates::Unit unit=GeoDataCoordinates::Degree) const =0
Get the earth coordinates corresponding to a pixel in the map.
virtual QPainterPath mapShape(const ViewportParams *viewport) const =0
Returns the shape/outline of a map projection.
virtual bool screenCoordinates(const GeoDataCoordinates &geopoint, const ViewportParams *viewport, qreal &x, qreal &y, bool &globeHidesPoint) const =0
Get the screen coordinates corresponding to geographical coordinates in the map.
virtual QIcon icon() const =0
Returns an icon for the projection.
virtual QString name() const =0
Returns the user-visible name of the projection.
virtual QString description() const =0
Returns a short user description of the projection that can be used in tooltips or dialogs.
A 3d point representation.
Unit
enum used constructor to specify the units used
A class that defines a 3D bounding box for geographic data.
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.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 21 2024 12:00:07 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.