Marble

GeoDataLineString.h
1// SPDX-License-Identifier: LGPL-2.1-or-later
2//
3// SPDX-FileCopyrightText: 2008-2009 Torsten Rahn <tackat@kde.org>
4// SPDX-FileCopyrightText: 2009 Patrick Spendrin <ps_ml@gmx.de>
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
20namespace Marble
21{
22class GeoDataCoordinates;
23class 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
67class GEODATA_EXPORT GeoDataLineString : public GeoDataGeometry
68{
69
70 public:
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
410Q_DECLARE_METATYPE( Marble::GeoDataLineString )
411
412#endif
A 3d point representation.
A base class for all geodata features.
A class that defines a 3D bounding box for geographic data.
A LineString that allows to store a contiguous set of line segments.
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 May 17 2024 11:49:23 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.