QGeoCoordinate Class

The QGeoCoordinate class defines a geographical position on the surface of the Earth. More...

Header: #include <QGeoCoordinate>
qmake: QT += positioning
Since: Qt 5.2

Public Types

enum CoordinateFormat { Degrees, DegreesWithHemisphere, DegreesMinutes, DegreesMinutesWithHemisphere, DegreesMinutesSeconds, DegreesMinutesSecondsWithHemisphere }
enum CoordinateType { InvalidCoordinate, Coordinate2D, Coordinate3D }

Public Functions

QGeoCoordinate()
QGeoCoordinate(double latitude, double longitude)
QGeoCoordinate(double latitude, double longitude, double altitude)
QGeoCoordinate(const QGeoCoordinate & other)
~QGeoCoordinate()
double altitude() const
QGeoCoordinate atDistanceAndAzimuth(qreal distance, qreal azimuth, qreal distanceUp = 0.0) const
qreal azimuthTo(const QGeoCoordinate & other) const
qreal distanceTo(const QGeoCoordinate & other) const
bool isValid() const
double latitude() const
double longitude() const
void setAltitude(double altitude)
void setLatitude(double latitude)
void setLongitude(double longitude)
QString toString(CoordinateFormat format = DegreesMinutesSecondsWithHemisphere) const
CoordinateType type() const
bool operator!=(const QGeoCoordinate & other) const
QGeoCoordinate & operator=(const QGeoCoordinate & other)
bool operator==(const QGeoCoordinate & other) const
QDataStream & operator<<(QDataStream & stream, const QGeoCoordinate & coordinate)
QDataStream & operator>>(QDataStream & stream, QGeoCoordinate & coordinate)

Detailed Description

The QGeoCoordinate class defines a geographical position on the surface of the Earth.

A QGeoCoordinate is defined by latitude, longitude, and optionally, altitude.

Use type() to determine whether a coordinate is a 2D coordinate (has latitude and longitude only) or 3D coordinate (has latitude, longitude and altitude). Use distanceTo() and azimuthTo() to calculate the distance and bearing between coordinates.

The coordinate values should be specified using the WGS84 datum. For more information on geographical terms see this article on coordinates and another on geodetic systems including WGS84.

Azimuth in this context is equivalent to a compass bearing based on true north.

Member Type Documentation

enum QGeoCoordinate::​CoordinateFormat

Defines the possible formatting options for toString().

ConstantValueDescription
QGeoCoordinate::Degrees0Returns a string representation of the coordinates in decimal degrees format.
QGeoCoordinate::DegreesWithHemisphere1Returns a string representation of the coordinates in decimal degrees format, using 'N', 'S', 'E' or 'W' to indicate the hemispheres of the coordinates.
QGeoCoordinate::DegreesMinutes2Returns a string representation of the coordinates in degrees-minutes format.
QGeoCoordinate::DegreesMinutesWithHemisphere3Returns a string representation of the coordinates in degrees-minutes format, using 'N', 'S', 'E' or 'W' to indicate the hemispheres of the coordinates.
QGeoCoordinate::DegreesMinutesSeconds4Returns a string representation of the coordinates in degrees-minutes-seconds format.
QGeoCoordinate::DegreesMinutesSecondsWithHemisphere5Returns a string representation of the coordinates in degrees-minutes-seconds format, using 'N', 'S', 'E' or 'W' to indicate the hemispheres of the coordinates.

See also toString().

enum QGeoCoordinate::​CoordinateType

Defines the types of a coordinate.

ConstantValueDescription
QGeoCoordinate::InvalidCoordinate0An invalid coordinate. A coordinate is invalid if its latitude or longitude values are invalid.
QGeoCoordinate::Coordinate2D1A coordinate with valid latitude and longitude values.
QGeoCoordinate::Coordinate3D2A coordinate with valid latitude and longitude values, and also an altitude value.

Member Function Documentation

QGeoCoordinate::​QGeoCoordinate()

Constructs a coordinate. The coordinate will be invalid until setLatitude() and setLongitude() have been called.

QGeoCoordinate::​QGeoCoordinate(double latitude, double longitude)

Constructs a coordinate with the given latitude and longitude.

If the latitude is not between -90 to 90 inclusive, or the longitude is not between -180 to 180 inclusive, none of the values are set and the type() will be QGeoCoordinate::InvalidCoordinate.

See also isValid().

QGeoCoordinate::​QGeoCoordinate(double latitude, double longitude, double altitude)

Constructs a coordinate with the given latitude, longitude and altitude.

If the latitude is not between -90 to 90 inclusive, or the longitude is not between -180 to 180 inclusive, none of the values are set and the type() will be QGeoCoordinate::InvalidCoordinate.

Note that altitude specifies the meters above sea level.

See also isValid().

QGeoCoordinate::​QGeoCoordinate(const QGeoCoordinate & other)

Constructs a coordinate from the contents of other.

QGeoCoordinate::​~QGeoCoordinate()

Destroys the coordinate object.

double QGeoCoordinate::​altitude() const

Returns the altitude (meters above sea level).

The return value is undefined if the altitude has not been set.

See also setAltitude() and type().

QGeoCoordinate QGeoCoordinate::​atDistanceAndAzimuth(qreal distance, qreal azimuth, qreal distanceUp = 0.0) const

Returns the coordinate that is reached by traveling distance meters from the current coordinate at azimuth (or bearing) along a great-circle. There is an assumption that the Earth is spherical for the purpose of this calculation.

The altitude will have distanceUp added to it.

Returns an invalid coordinate if this coordinate is invalid.

qreal QGeoCoordinate::​azimuthTo(const QGeoCoordinate & other) const

Returns the azimuth (or bearing) in degrees from this coordinate to the coordinate specified by other. Altitude is not used in the calculation.

The bearing returned is the bearing from the origin to other along the great-circle between the two coordinates. There is an assumption that the Earth is spherical for the purpose of this calculation.

Returns 0 if the type of this coordinate or the type of other is QGeoCoordinate::InvalidCoordinate.

qreal QGeoCoordinate::​distanceTo(const QGeoCoordinate & other) const

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.

Returns 0 if the type of this coordinate or the type of other is QGeoCoordinate::InvalidCoordinate.

bool QGeoCoordinate::​isValid() const

Returns true if the type() is Coordinate2D or Coordinate3D.

double QGeoCoordinate::​latitude() const

Returns the latitude, in decimal degrees. The return value is undefined if the latitude has not been set.

A positive latitude indicates the Northern Hemisphere, and a negative latitude indicates the Southern Hemisphere.

See also setLatitude() and type().

double QGeoCoordinate::​longitude() const

Returns the longitude, in decimal degrees. The return value is undefined if the longitude has not been set.

A positive longitude indicates the Eastern Hemisphere, and a negative longitude indicates the Western Hemisphere.

See also setLongitude() and type().

void QGeoCoordinate::​setAltitude(double altitude)

Sets the altitude (meters above sea level) to altitude.

See also altitude().

void QGeoCoordinate::​setLatitude(double latitude)

Sets the latitude (in decimal degrees) to latitude. The value should be in the WGS84 datum.

To be valid, the latitude must be between -90 to 90 inclusive.

See also latitude().

void QGeoCoordinate::​setLongitude(double longitude)

Sets the longitude (in decimal degrees) to longitude. The value should be in the WGS84 datum.

To be valid, the longitude must be between -180 to 180 inclusive.

See also longitude().

QString QGeoCoordinate::​toString(CoordinateFormat format = DegreesMinutesSecondsWithHemisphere) const

Returns this coordinate as a string in the specified format.

For example, if this coordinate has a latitude of -27.46758, a longitude of 153.027892 and an altitude of 28.1, these are the strings returned depending on format:

format valueReturned string
Degrees-27.46758°, 153.02789°, 28.1m
DegreesWithHemisphere27.46758° S, 153.02789° E, 28.1m
DegreesMinutes-27° 28.054', 153° 1.673', 28.1m
DegreesMinutesWithHemisphere27° 28.054 S', 153° 1.673' E, 28.1m
DegreesMinutesSeconds-27° 28' 3.2", 153° 1' 40.4", 28.1m
DegreesMinutesSecondsWithHemisphere27° 28' 3.2" S, 153° 1' 40.4" E, 28.1m

The altitude field is omitted if no altitude is set.

If the coordinate is invalid, an empty string is returned.

CoordinateType QGeoCoordinate::​type() const

Returns the type of this coordinate.

bool QGeoCoordinate::​operator!=(const QGeoCoordinate & other) const

Returns true if the latitude, longitude or altitude of this coordinate are not the same as those of other.

QGeoCoordinate & QGeoCoordinate::​operator=(const QGeoCoordinate & other)

Assigns other to this coordinate and returns a reference to this coordinate.

bool QGeoCoordinate::​operator==(const QGeoCoordinate & other) const

Returns true if the latitude, longitude and altitude of this coordinate are the same as those of other.

The longitude will be ignored if the latitude is +/- 90 degrees.

Related Non-Members

QDataStream & operator<<(QDataStream & stream, const QGeoCoordinate & coordinate)

Writes the given coordinate to the specified stream.

See also Serializing Qt Data Types.

QDataStream & operator>>(QDataStream & stream, QGeoCoordinate & coordinate)

Reads a coordinate from the specified stream into the given coordinate.

See also Serializing Qt Data Types.

© 2015 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.