Marble

GeoDataLineString.h
1 // SPDX-License-Identifier: LGPL-2.1-or-later
2 //
3 // SPDX-FileCopyrightText: 2008-2009 Torsten Rahn <[email protected]>
4 // SPDX-FileCopyrightText: 2009 Patrick Spendrin <[email protected]>
5 //
6 
7 
8 #ifndef MARBLE_GEODATALINESTRING_H
9 #define MARBLE_GEODATALINESTRING_H
10 
11 #include <QVector>
12 #include <QMetaType>
13 
14 #include "MarbleGlobal.h"
15 
16 #include "geodata_export.h"
17 #include "GeoDataGeometry.h"
18 
19 
20 namespace Marble
21 {
22 class GeoDataCoordinates;
23 class GeoDataLineStringPrivate;
24 
25 /*!
26  \class GeoDataLineString
27  \brief A LineString that allows to store a contiguous set of line segments.
28 
29  GeoDataLineString is a tool class that implements the LineString tag/class
30  of the Open Geospatial Consortium standard KML 2.2.
31 
32  GeoDataLineString extends GeoDataGeometry to store and edit
33  LineStrings.
34 
35  In the QPainter API "pure" LineStrings are also referred to as "polylines".
36  As such they are similar to the outline of a non-closed QPolygon.
37 
38  Whenever a LineString is painted GeoDataLineStyle should be used to assign a
39  color and line width.
40 
41  A GeoDataLineString consists of several (geodetic) nodes which are each
42  connected through line segments. The nodes are stored as GeoDataCoordinates
43  objects.
44 
45  The API which provides access to the nodes is similar to the API of
46  QVector.
47 
48  GeoDataLineString allows LineStrings to be tessellated in order to make them
49  follow the terrain and the curvature of the earth. The tessellation options
50  allow for different ways of visualization:
51 
52  \li Not tessellated: A LineString that connects each two nodes directly and
53  straight in screen coordinate space.
54  \li A tessellated line: Each line segment is bent so that the LineString
55  follows the curvature of the earth and its terrain. A tessellated
56  line segment connects two nodes at the shortest possible distance
57  ("along great circles").
58  \li A tessellated line that follows latitude circles whenever possible:
59  In this case Latitude circles are followed as soon as two subsequent
60  nodes have exactly the same amount of latitude. In all other places the
61  line segments follow great circles.
62 
63  Some convenience methods have been added that allow to calculate the
64  geodesic bounding box or the length of a LineString.
65 */
66 
67 class GEODATA_EXPORT GeoDataLineString : public GeoDataGeometry
68 {
69 
70  public:
72  using ConstIterator = QVector<GeoDataCoordinates>::ConstIterator;
73  using const_iterator = QVector<GeoDataCoordinates>::const_iterator;
74 
75 
76 /*!
77  \brief Creates a new LineString.
78 */
79  explicit GeoDataLineString( TessellationFlags f = NoTessellation );
80 
81 
82 /*!
83  \brief Creates a LineString from an existing geometry object.
84 */
85  explicit GeoDataLineString( const GeoDataGeometry &other );
86 
87 
88 /*!
89  \brief Destroys a LineString.
90 */
91  ~GeoDataLineString() override;
92 
93  const char *nodeType() const override;
94 
95  EnumGeometryId geometryId() const override;
96 
97  GeoDataGeometry *copy() const override;
98 
99 /*!
100  \brief Returns whether a LineString is a closed polygon.
101 
102  \return <code>false</code> if the LineString is not a LinearRing.
103 */
104  virtual bool isClosed() const;
105 
106 
107 /*!
108  \brief Returns whether the LineString follows the earth's surface.
109 
110  \return <code>true</code> if the LineString's line segments follow the
111  earth's surface and terrain along great circles.
112 */
113  bool tessellate() const;
114 
115 
116 /*!
117  \brief Sets the tessellation property for the LineString.
118 
119  If \a tessellate is <code>true</code> then the LineString's line segments
120  are bent and follow the earth's surface and terrain along great circles.
121  If \a tessellate is <code>false</code> then the LineString's line segments
122  are rendered as straight lines in screen coordinate space.
123 */
124  void setTessellate( bool tessellate );
125 
126 
127 /*!
128  \brief Returns the tessellation flags for a LineString.
129 */
130  TessellationFlags tessellationFlags() const;
131 
132 
133 /*!
134  \brief Sets the given tessellation flags for a LineString.
135 */
136  void setTessellationFlags( TessellationFlags f );
137 
138 /*!
139  \brief Reverses the LineString.
140  @since 0.26.0
141 */
142  void reverse();
143 
144 /*!
145  \brief Returns the smallest latLonAltBox that contains the LineString.
146 
147  \see GeoDataLatLonAltBox
148 */
149 
150  const GeoDataLatLonAltBox& latLonAltBox() const override;
151 
152 /**
153  * @brief Returns the length of LineString across a sphere starting from a coordinate in LineString
154  * This method can be used as an approximation for distances along LineStrings.
155  * The unit used for the resulting length matches the unit of the planet
156  * radius.
157  * @param planetRadius radius of the sphere
158  * @param offset position of coordinate within LineString
159  */
160  virtual qreal length( qreal planetRadius, int offset = 0 ) const;
161 
162 /*!
163  \brief Provides a more generic representation of the LineString.
164 
165  The LineString is normalized, and pole corrected.
166 
167  Deprecation Warning: This method will likely be removed from the public API.
168 */
169  virtual GeoDataLineString toRangeCorrected() const;
170 
171 
172 /*!
173  \brief The line string with nodes that have proper longitude/latitude ranges.
174 
175  \return A LineString that resembles the original linestring with nodes that
176  have longitude values between -180 and +180 deg and that
177  feature latitude values between -90 and +90 deg.
178 
179  Deprecation Warning: This method will likely be removed from the public API.
180 */
181  virtual GeoDataLineString toNormalized() const;
182 
183 
184 /*!
185  \brief The line string with more generic pole values.
186 
187  \return A LineString that resembles the original linestring. Nodes that
188  represent one of the poles are duplicated to allow for a better
189  visualization of flat projections.
190 
191  Deprecation Warning: This method will likely be removed from the public API.
192 */
193  virtual GeoDataLineString toPoleCorrected() const;
194 
195 
196 /*!
197  \brief The line string corrected for date line crossing.
198 
199  \return A set of LineStrings that don't cross the dateline and which
200  resemble the original linestring.
201 
202  Deprecation Warning: This method will likely be removed from the public API.
203 */
204  virtual QVector<GeoDataLineString*> toDateLineCorrected() const;
205 
206 
207 
208  // "Reimplementation" of QVector API
209 /*!
210  \brief Returns whether the LineString has no nodes at all.
211 
212  \return <code>true</code> if there are no nodes inside the line string.
213 */
214  bool isEmpty() const;
215 
216 
217 /*!
218  \brief Returns the number of nodes in a LineString.
219 */
220  int size() const;
221 
222 
223 /*!
224  \brief Returns a reference to the coordinates of a node at a given position.
225  This method detaches the returned coordinate object from the line string.
226 */
227  GeoDataCoordinates& at( int pos );
228 
229 
230 /*!
231  \brief Returns a reference to the coordinates of a node at a given position.
232  This method does not detach the returned coordinate object from the line string.
233 */
234  const GeoDataCoordinates& at( int pos ) const;
235 
236 
237 /*!
238  \brief Returns a reference to the coordinates of a node at a given position.
239  This method detaches the returned coordinate object from the line string.
240 */
241  GeoDataCoordinates& operator[]( int pos );
242 
243 
244  /**
245  Returns a sub-string which contains elements from this vector, starting at position pos. If length is -1
246  (the default), all elements after pos are included; otherwise length elements (or all remaining elements if
247  there are less than length elements) are included.
248  */
249  GeoDataLineString mid(int pos, int length = -1) const;
250 
251 /*!
252  \brief Returns a reference to the coordinates of a node at a given position.
253  This method does not detach the returned coordinate object from the line string.
254 */
255  const GeoDataCoordinates& operator[]( int pos ) const;
256 
257 
258 /*!
259  \brief Returns a reference to the first node in the LineString.
260  This method detaches the returned coordinate object from the line string.
261 */
262  GeoDataCoordinates& first();
263 
264 
265 /*!
266  \brief Returns a reference to the first node in the LineString.
267  This method does not detach the returned coordinate object from the line string.
268 */
269  const GeoDataCoordinates& first() const;
270 
271 
272 /*!
273  \brief Returns a reference to the last node in the LineString.
274  This method detaches the returned coordinate object from the line string.
275 */
276  GeoDataCoordinates& last();
277 
278 
279 /*!
280  \brief Returns a reference to the last node in the LineString.
281  This method does not detach the returned coordinate object from the line string.
282 */
283  const GeoDataCoordinates& last() const;
284 
285 
286 /*!
287  \brief Inserts a new node at the given index.
288 */
289  void insert( int index, const GeoDataCoordinates& value );
290 
291 /*!
292  \brief Attempts to allocate memory for at least \a size coordinates.
293 */
294  void reserve(int size);
295 
296 /*!
297  \brief Appends a given geodesic position as a new node to the LineString.
298 */
299  void append ( const GeoDataCoordinates& value );
300 
301 
302 /*!
303  \brief Appends a given geodesic position as new nodes to the LineString.
304 */
305  void append(const QVector<GeoDataCoordinates>& values);
306 
307 
308 /*!
309  \brief Appends a given geodesic position as a new node to the LineString.
310 */
311  GeoDataLineString& operator << ( const GeoDataCoordinates& value );
312 
313 
314 /*!
315  \brief Appends a given LineString to the end of the LineString.
316 */
317  GeoDataLineString& operator << ( const GeoDataLineString& lineString );
318 
319 
320 /*!
321  \brief Returns true/false depending on whether this and other are/are not equal.
322 */
323  bool operator==( const GeoDataLineString &other ) const;
324  bool operator!=( const GeoDataLineString &other ) const;
325 
326 
327 /*!
328  \brief Returns an iterator that points to the begin of the LineString.
329 */
332 
333 
334 /*!
335  \brief Returns an iterator that points to the end of the LineString.
336 */
339 
340 
341 /*!
342  \brief Returns a const iterator that points to the begin of the LineString.
343 */
345 
346 
347 /*!
348  \brief Returns a const iterator that points to the end of the LineString.
349 */
351 
352 
353 /*!
354  \brief Destroys all nodes in a LineString.
355 */
356  void clear();
357 
358 
359 /*!
360  \brief Removes the node at the given position and returns it.
361 */
363 
364 
365 /*!
366  \brief Removes the nodes within the given range and returns them.
367 */
370 
371 
372 /*!
373  \brief Removes the node at the given position and destroys it.
374 */
375  void remove ( int i );
376 
377  /*!
378  \brief Returns a linestring with detail values assigned to each node.
379  */
380  GeoDataLineString optimized() const;
381 
382  /*!
383  \brief Returns a javascript-style list (that can be used e.g. with the QML GeoPolyline element).
384  */
385  QVariantList toVariantList() const;
386 
387  // Serialization
388 /*!
389  \brief Serialize the LineString to a stream.
390  \param stream the stream.
391 */
392  void pack( QDataStream& stream ) const override;
393 
394 
395 /*!
396  \brief Unserialize the LineString from a stream.
397  \param stream the stream.
398 */
399  void unpack( QDataStream& stream ) override;
400 
401  protected:
402  explicit GeoDataLineString(GeoDataLineStringPrivate* priv);
403 
404  private:
405  Q_DECLARE_PRIVATE(GeoDataLineString)
406 };
407 
408 }
409 
410 Q_DECLARE_METATYPE( Marble::GeoDataLineString )
411 
412 #endif
A 3d point representation.
A class that defines a 3D bounding box for geographic data.
A base class for all geodata features.
A LineString that allows to store a contiguous set of line segments.
Binds a QML item to a specific geodetic location in screen coordinates.
QVector< V > values(const QMultiHash< K, V > &c)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:09:06 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.