Marble

GeoDataTrack.h
1 // SPDX-License-Identifier: LGPL-2.1-or-later
2 //
3 // SPDX-FileCopyrightText: 2011 Guillaume Martres <[email protected]>
4 //
5 
6 #ifndef MARBLE_GEODATATRACK_H
7 #define MARBLE_GEODATATRACK_H
8 
9 #include "GeoDataGeometry.h"
10 
11 #include <QList>
12 
13 class QDateTime;
14 
15 namespace Marble {
16 
17 class GeoDataTrackPrivate;
18 class GeoDataExtendedData;
19 class GeoDataLineString;
20 class GeoDataCoordinates;
21 
22 /**
23  * @class GeoDataTrack
24  * @brief A geometry for tracking objects made of (time, coordinates) pairs
25  *
26  * GeoDataTrack implements the Track tag defined in Google's extension of the
27  * Open Geospatial Consortium standard KML 2.2 at
28  * https://developers.google.com/kml/documentation/kmlreference#gxtrack .
29  *
30  * A track is made of points, each point has a coordinates and a time value
31  * associated with the coordinates. New points can be added using the addPoint()
32  * method. The coordinates of the tracked object at a particular time can be
33  * found using coordinatesAt(), you can specify if interpolation should be used
34  * using the setInterpolate() function.
35  *
36  * By default, a LineString that passes through every coordinates in the track
37  * is drawn. You can customize it by changing the GeoDataLineStyle, for example
38  * if the GeoDataTrack is the geometry of feature, you can disable the line drawing with:
39  * @code
40  * feature->style()->lineStyle().setPenStyle( Qt::NoPen );
41  * @endcode
42  *
43  * For convenience, the methods appendCoordinates() and appendWhen() are provided.
44  * They let you add points by specifying their coordinates and time value separately.
45  * When N calls to one of these methods are followed by N calls to the other,
46  * the first coordinates will be matched with the first time value, the second
47  * coordinates with the second time value, etc. This follows the way "coord"
48  * and "when" tags inside the Track tag should be parsed.
49  */
50 class GEODATA_EXPORT GeoDataTrack : public GeoDataGeometry
51 {
52 
53 public:
54  GeoDataTrack();
55  explicit GeoDataTrack( const GeoDataTrack &other );
56 
57  GeoDataTrack &operator=( const GeoDataTrack &other );
58 
59  const char *nodeType() const override;
60 
61  EnumGeometryId geometryId() const override;
62 
63  GeoDataGeometry *copy() const override;
64 
65  /**
66  * Returns the number of points in the track
67  */
68  int size() const;
69 
70  /**
71  * @brief: Equality operators.
72  */
73  bool operator==( const GeoDataTrack& other ) const;
74  bool operator!=( const GeoDataTrack& other ) const;
75 
76  /**
77  * Returns true if coordinatesAt() should use interpolation, false otherwise.
78  * The default is false.
79  *
80  * @see setInterpolate, coordinatesAt
81  */
82  bool interpolate() const;
83 
84  /**
85  * Set whether coordinatesAt() should use interpolation.
86  *
87  * @see interpolate, coordinatesAt
88  */
89  void setInterpolate(bool on);
90 
91  /**
92  * Return the time value of the first point in the track, or
93  * an invalid QDateTime if the track is empty.
94  */
95  QDateTime firstWhen() const;
96 
97  /**
98  * Return the time value of the last point in the track, or
99  * an invalid QDateTime if the track is empty.
100  */
101  QDateTime lastWhen() const;
102 
103  /**
104  * Returns the coordinates of all the points in the map, sorted by their
105  * time value
106  */
107  QVector<GeoDataCoordinates> coordinatesList() const;
108 
109  /**
110  * Returns the time value of all the points in the map, in chronological
111  * order.
112  * @since 0.26.0
113  */
114  QVector<QDateTime> whenList() const;
115 
116  /**
117  * If interpolate() is true, return the coordinates interpolated from the
118  * time values before and after @p when, otherwise return the coordinates
119  * of the point with the closest time value less than or equal to @p when.
120  *
121  * @see interpolate
122  */
123  GeoDataCoordinates coordinatesAt( const QDateTime &when ) const;
124 
125  /**
126  * Return coordinates at specified index. This is useful when the track contains
127  * coordinates without time information.
128  */
129  GeoDataCoordinates coordinatesAt( int index ) const;
130 
131  /**
132  * Add a new point with coordinates @p coord associated with the
133  * time value @p when
134  */
135  void addPoint( const QDateTime &when, const GeoDataCoordinates &coord );
136 
137  /**
138  * Add the coordinates part for a new point. See this class description
139  * for more information.
140  * @see appendWhen
141  */
142  void appendCoordinates( const GeoDataCoordinates &coord );
143 
144  /**
145  * Add altitude information to the last appended coordinates
146  */
147  void appendAltitude( qreal altitude );
148 
149  /**
150  * Add the time value part for a new point. See this class description
151  * for more information.
152  * @see appendCoordinates
153  */
154  void appendWhen( const QDateTime &when );
155 
156  /**
157  * Remove all the points contained in the track.
158  */
159  void clear();
160 
161  /**
162  * Remove all points from the track whose time value is less than @p when.
163  */
164  void removeBefore( const QDateTime &when );
165 
166  /**
167  * Remove all points from the track whose time value is greater than @p when.
168  */
169  void removeAfter( const QDateTime &when );
170 
171  /**
172  * Return the GeoDataLineString representing the current track
173  */
174  const GeoDataLineString *lineString() const;
175 
176  /**
177  * Return the ExtendedData assigned to the feature.
178  */
179  const GeoDataExtendedData& extendedData() const;
180  GeoDataExtendedData& extendedData();
181 
182  /**
183  * Sets the ExtendedData of the feature.
184  * @param extendedData the new ExtendedData to be used.
185  */
186  void setExtendedData( const GeoDataExtendedData& extendedData );
187 
188  const GeoDataLatLonAltBox& latLonAltBox() const override;
189  void pack( QDataStream& stream ) const override;
190  void unpack( QDataStream& stream ) override;
191 
192 private:
193  Q_DECLARE_PRIVATE(GeoDataTrack)
194 };
195 
196 }
197 
198 Q_DECLARE_METATYPE( Marble::GeoDataTrack* )
199 
200 #endif // MARBLE_GEODATATRACK_H
A 3d point representation.
A geometry for tracking objects made of (time, coordinates) pairs.
Definition: GeoDataTrack.h:50
Binds a QML item to a specific geodetic location in screen coordinates.
A base class for all geodata features.
a class which allows to add custom data to KML Feature.
A LineString that allows to store a contiguous set of line segments.
A class that defines a 3D bounding box for geographic data.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Nov 26 2021 23:23:28 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.