Marble

GeoDataTrack.h
1// SPDX-License-Identifier: LGPL-2.1-or-later
2//
3// SPDX-FileCopyrightText: 2011 Guillaume Martres <smarter@ubuntu.com>
4//
5
6#ifndef MARBLE_GEODATATRACK_H
7#define MARBLE_GEODATATRACK_H
8
9#include "GeoDataGeometry.h"
10
11#include <QList>
12
13class QDateTime;
14
15namespace Marble {
16
17class GeoDataTrackPrivate;
18class GeoDataExtendedData;
19class GeoDataLineString;
20class 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 */
50class GEODATA_EXPORT GeoDataTrack : public GeoDataGeometry
51{
52
53public:
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
192private:
193 Q_DECLARE_PRIVATE(GeoDataTrack)
194};
195
196}
197
198Q_DECLARE_METATYPE( Marble::GeoDataTrack* )
199
200#endif // MARBLE_GEODATATRACK_H
A 3d point representation.
a class which allows to add custom data to KML Feature.
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.
A geometry for tracking objects made of (time, coordinates) pairs.
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 Tue Mar 26 2024 11:18:17 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.