1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the QtLocation module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** GNU Lesser General Public License Usage
** This file may be used under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation and
** appearing in the file LICENSE.LGPL included in the packaging of this
** file. Please review the following information to ensure the GNU Lesser
** General Public License version 2.1 requirements will be met:
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU General
** Public License version 3.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of this
** file. Please review the following information to ensure the GNU General
** Public License version 3.0 requirements will be met:
** http://www.gnu.org/copyleft/gpl.html.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms and
** conditions contained in a signed written agreement between you and Nokia.
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
#include "qdeclarativecoordinate_p.h"
QT_BEGIN_NAMESPACE
/*!
\qmlbasictype coordinate
\inqmlmodule QtLocation 5.0
\ingroup qml-QtLocation5-basictypes
\since Qt Location 5.0
\brief The coordinate type represents and stores a geographic position.
The \c coordinate type represents a geographic position in the form of \c {latitude},
\c longitude and \c altitude attributes. The \c latitude attribute specifies the number of
decimal degrees above and below the equator. A positive latitude indicates the Northern
Hemisphere and a negative latitude indicates the Southern Hemisphere. The \c longitude
attribute specifies the number of decimal degrees east and west. A positive longitude
indicates the Eastern Hemisphere and a negative longitude indicates the Western Hemisphere.
The \c altitude attribute specifies the number of meters above sea level. Together, these
attributes specify a 3-dimensional position anywhere on or near the Earth's surface.
The \c isValid attribute can be used to test if a coordinate is valid. A coordinate is
considered valid if it has a valid latitude and longitude. A valid altitude is not required.
The latitude must be between -90 and 90 inclusive and the longitude must be between -180 and
180 inclusive.
The coordinate type is used by many other types in the Qt Location module, for specifying
the position of an object on a Map, the current position of a device and many other tasks.
They also feature a number of important utility methods that make otherwise complex
calculations simple to use, such as \l atDistanceAndAzimuth().
\section2 Accuracy
The latitude, longitude and altitude attributes stored in the coordinate type are represented
as doubles, giving them approximately 16 decimal digits of precision -- enough to specify
micrometers. The calculations performed in coordinate's methods such as \l azimuthTo() and
\l distanceTo() also use doubles for all intermediate values, but the inherent inaccuracies in
their spherical Earth model dominate the amount of error in their output.
\section2 Example Usage
Use properties of type \l variant to store a \c {coordinate}. To create a \c coordinate use
one of the methods described below. In all cases, specifying the \c altitude attribute is
optional.
To create a \c coordinate value, use the \l{QtLocation5::QtLocation}{QtLocation.coordinate()}
function:
\qml
import QtLocation 5.0
Location { coordinate: QtLocation.coordinate(-27.5, 153.1) }
\endqml
or as separate \c {latitude}, \c longitude and \c altitude components:
\qml
Location {
coordinate {
latitude: -27.5
longitude: 153.1
}
}
\endqml
When integrating with C++, note that any QGeoCoordinate value passed into QML from C++ is
automatically converted into a \c coordinate value, and vice-versa.
\section2 Methods
\section3 distanceTo()
\code
real distanceTo(coordinate other)
\endcode
Returns the distance (in meters) from this coordinate to the coordinate specified by \a other.
Altitude is not used in the calculation.
This calculation returns the great-circle distance between the two coordinates, with an
assumption that the Earth is spherical for the purpose of this calculation.
\section3 azimuthTo()
\code
real azimuth(coordinate other)
\endcode
Returns the azimuth (or bearing) in degrees from this coordinate to the coordinate specified by
\a other. Altitude is not used in the calculation.
There is an assumption that the Earth is spherical for the purpose of this calculation.
\section3 atDistanceAndAzimuth()
\code
coordinate atDistanceAndAzimuth(real distance, real azimuth)
\endcode
Returns the coordinate that is reached by traveling \a distance metres from this coordinate at
\a azimuth degrees along a great-circle.
There is an assumption that the Earth is spherical for the purpose of this calculation.
*/
CoordinateValueType::CoordinateValueType(QObject *parent)
: QQmlValueTypeBase<QGeoCoordinate>(qMetaTypeId<QGeoCoordinate>(), parent)
{
}
CoordinateValueType::~CoordinateValueType()
{
}
/*
This property holds the value of altitude (meters above sea level).
If the property has not been set, its default value is NaN.
*/
void CoordinateValueType::setAltitude(double altitude)
{
v.setAltitude(altitude);
}
double CoordinateValueType::altitude() const
{
return v.altitude();
}
/*
This property holds the longitude value of the geographical position
(decimal degrees). A positive longitude indicates the Eastern Hemisphere,
and a negative longitude indicates the Western Hemisphere
If the property has not been set, its default value is NaN.
*/
void CoordinateValueType::setLongitude(double longitude)
{
v.setLongitude(longitude);
}
double CoordinateValueType::longitude() const
{
return v.longitude();
}
/*
This property holds latitude value of the geographical position
(decimal degrees). A positive latitude indicates the Northern Hemisphere,
and a negative latitude indicates the Southern Hemisphere.
If the property has not been set, its default value is NaN.
*/
void CoordinateValueType::setLatitude(double latitude)
{
v.setLatitude(latitude);
}
double CoordinateValueType::latitude() const
{
return v.latitude();
}
/*
This property holds the current validity of the coordinate. Coordinates
are considered valid if they have been set with a valid latitude and
longitude (altitude is not required).
The latitude must be between -90 to 90 inclusive to be considered valid,
and the longitude must be between -180 to 180 inclusive to be considered
valid.
*/
bool CoordinateValueType::isValid() const
{
return v.isValid();
}
QString CoordinateValueType::toString() const
{
return QStringLiteral("QGeoCoordinate(%1,%2,%3)")
.arg(v.latitude()).arg(v.longitude()).arg(v.altitude());
}
bool CoordinateValueType::isEqual(const QVariant &other) const
{
if (other.userType() != qMetaTypeId<QGeoCoordinate>())
return false;
return v == other.value<QGeoCoordinate>();
}
/*
Returns the distance (in meters) from this coordinate to the
coordinate specified by other. Altitude is not used in the calculation.
This calculation returns the great-circle distance between the two
coordinates, with an assumption that the Earth is spherical for the
purpose of this calculation.
*/
qreal CoordinateValueType::distanceTo(const QGeoCoordinate &coordinate) const
{
return v.distanceTo(coordinate);
}
/*
Returns the azimuth (or bearing) in degrees from this coordinate to the
coordinate specified by other. Altitude is not used in the calculation.
There is an assumption that the Earth is spherical for the purpose of
this calculation.
*/
qreal CoordinateValueType::azimuthTo(const QGeoCoordinate &coordinate) const
{
return v.azimuthTo(coordinate);
}
/*
Returns the coordinate that is reached by traveling distance metres
from the current coordinate at azimuth degrees along a great-circle.
There is an assumption that the Earth is spherical for the purpose
of this calculation.
*/
QGeoCoordinate CoordinateValueType::atDistanceAndAzimuth(qreal distance, qreal azimuth) const
{
return v.atDistanceAndAzimuth(distance, azimuth);
}
#include "moc_qdeclarativecoordinate_p.cpp"
QT_END_NAMESPACE
|