LBS maths functions

This document describes LBS maths functions, which allow application developers to calculate distances, bearings, speeds and to perform coordinate translations.

An application uses the LBS maths functions to:

• Calculate the distance between two points

• Calculate the bearing from one point to another

• Calculate the average speed of the mobile device between two points

• Translate a coordinate by a given distance along a bearing

Familiarity with the position classes described in Position info and data classes is required.

There are two ways to use LBS maths functions:

• The class TPositionCalc contains static functions that can be called directly by client applications.

• The classes TCoordinate, TLocality and TPosition have methods to allow calculations appropriate to their class type. These methods simply wrap calls on TPositionCalc.

TPositionCalc

TPositionCalc is defined in LbsPositionCalc.h. TPositionCalc provides a set of static functions to calculate distances, bearings, speeds and to perform coordinate translations. The functions are synchronous and are designed to return quickly.

// From TPositionCalc

// Functions to calculate the distance between two points
IMPORT_C static TInt GetDistance(const TCoordinate& aStartCoor, const TCoordinate& aStopCoor, TReal32& aDistance);
IMPORT_C static TInt GetDistance(const TLocality& aStartLoc, const TLocality& aStopLoc, TReal32& aDistance, TReal32& aDelta);

// Functions to calculate the bearing from one point to another
IMPORT_C static TInt GetBearing(const TCoordinate& aStartCoor, const TCoordinate& aStopCoor, TReal32& aBearing);
IMPORT_C static TInt GetBearing(const TLocality& aStartLoc, const TLocality& aStopLoc, TReal32& aBearing, TReal32& aDelta);

// Functions to calculate device speed
IMPORT_C static TInt GetSpeed(const TPosition& aStartPos, const TPosition& aStopPos, TReal32& aSpeed);
IMPORT_C static TInt GetSpeed(const TPosition& aStartPos, const TPosition& aStopPos, TReal32& aSpeed, TReal32& aDelta);

// Function to translate coordinate
IMPORT_C static TInt Translate(const TCoordinate& aStartCoor, const TReal32& aDistance, const TReal32& aBearing, TCoordinate& aStopCoor);

TPositionCalc::GetDistance() calculates the distance between two TCoordinate or TLocality objects. For TLocality objects, an accuracy value aDelta is calculated, based on the accuracy of position of the TLocality objects as given by TLocality::HorizontalAccuracy() and TLocality::VerticalAccuracy().

TPositionCalc::GetBearing() calculates the bearing between two TCoordinate or TLocality objects. For TLocality objects, an accuracy value is calculated.

TPositionCalc::GetSpeed() calculates the average speed between two TPosition objects. TPosition contains a time value for the position fix which is used to calculate the average speed.

TPositionCalc::Translate() performs a coordinate translation of aStartCoor a distance of aDistance in the direction of aBearing. aStopCoor is the translated coordinate.

The methods return KErrNone if their calculations are successful and KErrArgument if either TCoordinate::Latitude() or TCoordinate::Longitude() return Math::NaN. (Note that Math::NaN is the default value of latitude and longitude in a new TCoordinate object unless the appropriate initialising constructor is called).

TCoordinate

TCoordinate has three functions that calculate distances, bearings and perform coordinate translations.

// From TCoordinate

IMPORT_C TInt Distance(const TCoordinate& aCoordinate, TReal32& aDistance) const;
IMPORT_C TInt BearingTo(const TCoordinate& aTargetCoordinate, TReal32& aBearing) const;
IMPORT_C TInt Move(TReal32 aBearing, TReal32 aDistance);

TCoordinate::Distance() calculates the distance between the position represented by this TCoordinate object and aCoordinate. The calculated distance (in metres) is accessed through aDistance.

TCoordinate::BearingTo() calculates the bearing between the position represented by this TCoordinate object and aCoordinate. The calculated bearing (in degrees) is accessed through aBearing.

TCoordinate::Move() performs a coordinate translation of aDistance along aBearing.

The maths functions call the appropriate static functions on TPositionCalc. The return values from these functions are as described previously for TPositionCalc.

TLocality

TLocality derives from TCoordinate and adds position accuracy information. TLocality overrides the Distance() and BearingTo() methods defined in TCoordinate and adds methods to calculate a distance and bearing that include error estimates.

// From TLocality

IMPORT_C TInt Distance(const TCoordinate& aCoordinate, TReal32& aDistance) const;
IMPORT_C TInt Distance(const TLocality& aLocality, TReal32& aDistance, TReal32& aDelta) const;

IMPORT_C TInt BearingTo(const TCoordinate& aTargetCoordinate, TReal32& aBearing) const;
IMPORT_C TInt BearingTo(const TLocality& aTargetLocality, TReal32& aBearing, TReal32& aDelta) const;

For TLocality objects, an accuracy value aDelta is calculated, based on the accuracy of position of the TLocality objects as given by TLocality::HorizontalAccuracy() and TLocality::VerticalDistance().

The maths functions call the appropriate static functions on TPositionCalc. The return values from these functions are as described previously for TPositionCalc.

TPosition

TPosition derives from TLocality and represents a position fix, including the time at which the fix was obtained. TPosition has methods to calculate the average speed between two points.

// From TPosition
// Functions to calculate the average speed between two points

IMPORT_C TInt Speed(const TPosition& aPosition, TReal32& aSpeed) const;
IMPORT_C TInt Speed(const TPosition& aPosition, TReal32& aSpeed, TReal32& aDelta) const;

The two functions calculate the average speed based on the time value held by the TPosition object on which the method is called and aPosition. The second method shown above calculates a position accuracy aDelta. The functions call TPositionCalc::GetSpeed() and their return values are as described previously for TPositionCalc.

Calculation formulae

Symbian provides a maths library lbsmaths.dll that performs the calculations. Calculations are performed using the haversine formula and the spherical law of cosines. These formulae assume a spherical Earth of radius 6371km with the poles at 90 degrees.

Note that all TCoordinate derived objects that use the Symbian maths library must use the WGS-84 datum (the default for position data classes in LBS). Setting some other datum by calling TCoordinate::SetDatum() and attempting to use the maths functions with the Symbian provided lbsmaths.dll causes the maths functions to return KErrNotSupported.

Symbian OS partners and licensees can replace lbsmaths.dll with their own implementation in order to use different formulae in calculations (for example to obtain greater accuracy) or to use a different datum.

How to use LBS maths functions

Position info and data classes

Haversine formula

R.W. Sinnott, "Virtues of the Haversine", Sky and Telescope, vol. 68, no. 2, 1984, p. 159