Detailed Description

This class contains only static methods which are used to convert between latitude/longitude, GARS, MGRS, UTM and UPS.

Additionally this class contains methods that do the following conversions:

Great Circle
Vincenty
Rhumbline
Geocentric
Geodetic
Topocentric

Many conversions either return a standard format string or take a string as an input parameter. The input parameter string parsing is fairly lax with regards to the presence of spaces, and the easting/northing component may be truncated as long as they contain equal numbers of digits. If there is no space between the easting and northing then the number of digits must be even.

All combinations of conversions would take 24 methods, some of these are not provided, but those provided allow all combinations in an efficient manner with only two method calls.

Two special methods have been added that take a UTM position which may be past the junction between zones and converts it to a valid UTM (or MGRS) position within the zone past the junction.

NOTE : In order for most of these methods to work you must have loaded the Coordinate Systems database using the TSLCoordinateSystems::loadCoordinateSystems method.

Classes
class	GreatCircle

class	Sphere

Static Public Member Functions
static double	azimuth (double lat1, double lon1, double lat2, double lon2)

static bool	garsToLatLong (const int longBand, const char *const latBand, const int quadrant, const int area, double &latitude, double &longitude)

static int	geodesicPath (double startLat, double startLon, double endLat, double endLon, double postDistance, double totalDistance, int numPoints, double latitudes, double longitudes, bool calcGeodesicPath=true)

static bool	geocentricToGeodetic (const TSLCoordinateSystem coordinateSystem, int numberOfPoints, const TSLPoint3D from, TSLGeographicCoord *to)

static bool	geodeticToGeocentric (const TSLCoordinateSystem coordinateSystem, int numberOfPoints, const TSLGeographicCoord from, TSLPoint3D *to)

static bool	geocentricToTopocentric (const TSLCoordinateSystem coordinateSystem, const TSLGeographicCoord &topocentricOrigin, int numberOfPoints, TSLPoint3D geocentricPoint, TSLPoint3D *topocentricPoint)

static bool	geographicToTopocentric (const TSLCoordinateSystem coordinateSystem, const TSLGeographicCoord &topocentricOrigin, int numberOfPoints, const TSLGeographicCoord geographicPoint, TSLPoint3D *topocentricPoint)

static double	greatCircleDistance (double lat1, double lon1, double lat2, double lon2)

static void	greatCircleDistancePoint (double startLat, double startLon, double bearing, double distance, double &endLat, double &endLon)

static void	greatCircleDistance (double lat1, double lon1, double lat2, double lon2, double &range, double &bearing)

static bool	latLongToGARS (const double latitude, const double longitude, int &longBand, TSLSimpleString &latBand, int &quadrant, int &area)

static bool	latLongToGARS (const double latitude, const double longitude, TSLSimpleString &positionString)

static bool	latLongToMGRS (const double latitude, const double longitude, int &zone, char &band, char &gridSquareCol, char &gridSquareRow, double &easting, double &northing, bool &polar, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	latLongToMGRS (const double latitude, const double longitude, TSLSimpleString &positionString, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	latLongToUPS (const double latitude, const double longitude, char &zone, double &easting, double &northing)

static bool	latLongToUPS (const double latitude, const double longitude, TSLSimpleString &positionString)

static bool	latLongToUTM (const double latitude, const double longitude, int &zone, char &band, double &easting, double &northing, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	latLongToUTM (const double latitude, const double longitude, TSLSimpleString &positionString, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	mgrsToUPS (const char *const mgrs, char &zone, double &easting, double &northing)

static bool	mgrsToUPS (const char *const mgrs, TSLSimpleString &positionString)

static bool	mgrsToUTM (const char *const mgrs, int &zone, char &band, double &easting, double &northing, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	mgrsToUTM (const char *const mgrs, TSLSimpleString &positionString, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static double	normaliseDegrees (double angle)

static double	rhumbLineDistance (const TSLLatLongCoord &startPoint, const TSLLatLongCoord &destinationPoint, double &trueCourse)

static bool	rhumbLineDestination (const TSLLatLongCoord &startPoint, double trueCourse, double distance, TSLLatLongCoord &destination)

static void	rhumbLineMidPoint (const TSLLatLongCoord &startPoint, const TSLLatLongCoord &destinationPoint, TSLLatLongCoord &midPoint)

static bool	topocentricToGeocentric (const TSLCoordinateSystem coordinateSystem, const TSLGeographicCoord &geographicOrigin, int numberOfPoints, const TSLPoint3D topocentricPoint, TSLPoint3D *geocentricPoint)

static bool	topocentricToGeographic (const TSLCoordinateSystem coordinateSystem, const TSLGeographicCoord &geographicOrigin, int numberOfPoints, const TSLPoint3D topocentricPoint, TSLGeographicCoord *geographicPoint)

static bool	upsToLatLong (const char zone, const double easting, const double northing, double &latitude, double &longitude)

static bool	upsToMGRS (const char band, const double easting, const double northing, TSLSimpleString &positionString)

static bool	upsToMGRS (const char *const ups, TSLSimpleString &positionString)

static bool	utmToLatLong (const int zone, const char band, const double easting, const double northing, double &latitude, double &longitude, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	utmToLatLong (const char *const utm, double &latitude, double &longitude, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	utmToMGRS (const int zone, const char band, const double easting, const double northing, TSLSimpleString &positionString, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	utmToMGRS (const char *const utm, TSLSimpleString &positionString, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	utmToTrueMGRS (const int zone, const char band, const double easting, const double northing, double &latitude, double &longitude, int &trueZone, char &trueBand, char &gridSquareCol, char &gridSquareRow, double &trueEasting, double &trueNorthing, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	utmToTrueUTM (const int zone, const char band, const double easting, const double northing, double &latitude, double &longitude, int &trueZone, char &trueBand, double &trueEasting, double &trueNorthing, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	validateMGRS (const char *const mgrs, int &zone, char &band, char &gridSquareCol, char &gridSquareRow, double &easting, double &northing, bool &polar, TSLCoordinateSystem::TSLTransverseMercatorFormula transverseMercatorFormula)

static bool	validateUPS (const char *const ups, char &zone, double &easting, double &northing)

static bool	validateUTM (const char *const utm, int &zone, char &band, double &easting, double &northing)

static double	vincentyDirect (const double startLatitude, const double startLongitude, const double azimuth, const double distance, double &endLatitude, double &endLongitude)

static double	vincentyInverse (const double startLatitude, const double startLongitude, const double endLatitude, const double endLongitude, double &azimuth)

Member Function Documentation

◆ azimuth()

static double TSLCoordinateConverter::azimuth	(	double	lat1,
		double	lon1,
		double	lat2,
		double	lon2 )

static

Returns the initial bearing (forward azimuth) for a great circle line.

Reference: Map Projections - A Working Manual, by John P Snyder, page 30.

Parameters

lat1	latitude of first point in degrees
lon1	longitude of first point in degrees
lat2	latitude of second point in degrees
lon2	longitude of second point in degrees

Returns: the azimuth in degrees.

◆ garsToLatLong()

static bool TSLCoordinateConverter::garsToLatLong	(	const int	longBand,
		const char *const	latBand,
		const int	quadrant,
		const int	area,
		double &	latitude,
		double &	longitude )

static

Convert from the GARS grid position given into latitude and longitude.

Parameters

longBand	The GARS longitude band, 001-720.
latBand	The GARS latitude band, AA to QZ omitting I & O.
quadrant	The GARS quadrant, 1 - 4.
area	The GARS area, 1 - 9.
latitude	On output, the latitude value.
longitude	On output, the longitude value.

A false value is returned if there is any problem with the conversion.

Function is threadsafe.

◆ geocentricToGeodetic()

static bool TSLCoordinateConverter::geocentricToGeodetic	(	const TSLCoordinateSystem *	coordinateSystem,
		int	numberOfPoints,
		const TSLPoint3D *	from,
		TSLGeographicCoord *	to )

static

Geocentric to Geodetic coordinate conversion.

The user is responsible for ensuring that sufficient space has been provided for the result.

See http://en.wikipedia.org/wiki/Geodetic_datum

Parameters

coordinateSystem	Valid coordinate system. Required for the Ellipsoid.
numberOfPoints	the number of Geocentric points to convert.
from	Pointer to an array of X, Y, Z position (meters).
to	Pointer to an array to return the Geographic positions (latitude, longitude and height in meters)

Returns: true if the calculation can be completed.

◆ geocentricToTopocentric()

static bool TSLCoordinateConverter::geocentricToTopocentric	(	const TSLCoordinateSystem *	coordinateSystem,
		const TSLGeographicCoord &	topocentricOrigin,
		int	numberOfPoints,
		TSLPoint3D *	geocentricPoint,
		TSLPoint3D *	topocentricPoint )

static

Geocentric to Topocentric coordinate calculation.

The user is responsible for ensuring that sufficient space has been provided for the result.

See http://www.epsg.org/guides/docs/g7-2.pdf

Parameters

coordinateSystem	Valid coordinate system. Required for the Ellipsoid.
topocentricOrigin	Topocentric origin.
numberOfPoints	Number of points in the arrays.
geocentricPoint	Pointer to an array of XYZ points to convert.
topocentricPoint	Pointer to an array of calculated Topocentric points (return)

Returns: true if calculation can be completed.

◆ geodesicPath()

static int TSLCoordinateConverter::geodesicPath	(	double	startLat,
		double	startLon,
		double	endLat,
		double	endLon,
		double	postDistance,
		double	totalDistance,
		int	numPoints,
		double *	latitudes,
		double *	longitudes,
		bool	calcGeodesicPath = true )

static

This method calculates the geodesic or great circle path between the start and end points specified.

The geodesic path is more accurate than great circle path..

The method should only be used to calculate paths that are less than 180 degrees. The shortest path between the start and end points will always be calculated.

If latitudes or longitudes is set to NULL the method returns the maximum possible number of points.

A sensible calculation for the number of points is as follows:

double totalDistance = TSLCoordinateConverter::greatCircleDistance(startLat, startLon, endLat, endLon) / 1000;
int numPoints = (int)((totalDistance / postDistance)  + 0.5) + 1;

Parameters

startLat	Start latitude (radians).
startLon	Start longitude (radians).
endLat	End latitude (radians).
endLon	End longitude (radians).
postDistance	Distance between generated points in km.
totalDistance	The total distance between the start and end points in km. You can get this by calling greatCircleDistance.
numPoints	The size of the two arrays passed in. Must be at least 2.
latitudes	A pointer to where to store the calculated points.
longitudes	A pointer to where to store the calculated points.
calcGeodesicPath	If true a geodesic path calculation is used.

Returns: the number of points generated. If 0 was returned then an error occurred.

◆ geodeticToGeocentric()

static bool TSLCoordinateConverter::geodeticToGeocentric	(	const TSLCoordinateSystem *	coordinateSystem,
		int	numberOfPoints,
		const TSLGeographicCoord *	from,
		TSLPoint3D *	to )

static

Geodetic to Geocentric coordinate conversion.

The user is responsible for ensuring that sufficient space has been provided for the result.

See http://en.wikipedia.org/wiki/Geodetic_datum

Parameters

coordinateSystem	Valid coordinate system. Required for the Ellipsoid.
numberOfPoints	the number of Geocentric points to convert.
from	Pointer to an array of Geographic positions (latitude, longitude and height in meters)
to	Pointer to an array to return X, Y, Z positions (meters).

Returns: true if the calculation can be completed.

◆ geographicToTopocentric()

static bool TSLCoordinateConverter::geographicToTopocentric	(	const TSLCoordinateSystem *	coordinateSystem,
		const TSLGeographicCoord &	topocentricOrigin,
		int	numberOfPoints,
		const TSLGeographicCoord *	geographicPoint,
		TSLPoint3D *	topocentricPoint )

static

Geographic to Topocentric coordinate calculation.

The user is responsible for ensuring that sufficient space has been provided for the result.

See http://www.epsg.org/guides/docs/g7-2.pdf

Parameters

coordinateSystem	Valid coordinate system. Required for the Ellipsoid.
topocentricOrigin	Topocentric origin.
numberOfPoints	Number of points in the arrays.
geographicPoint	Pointer to an array of Geographic points to convert.
topocentricPoint	Pointer to an array of calculated Topocentric points (return)

Returns: true if calculation can be completed.

◆ greatCircleDistance() [1/2]

static double TSLCoordinateConverter::greatCircleDistance	(	double	lat1,
		double	lon1,
		double	lat2,
		double	lon2 )

static

Returns the Great Circle Distance between two points

Reference: Map Projections - A Working Manual, by John P Snyder, page 30.

Parameters

lat1	latitude of first point in degrees
lon1	longitude of first point in degrees
lat2	latitude of second point in degrees
lon2	longitude of second point in degrees

Returns: the great circle distance in meters

◆ greatCircleDistance() [2/2]

static void TSLCoordinateConverter::greatCircleDistance	(	double	lat1,
		double	lon1,
		double	lat2,
		double	lon2,
		double &	range,
		double &	bearing )

static

Returns the range and bearing between two points using Great Circle calculations.

Reference: Map Projections - A Working Manual, by John P Snyder, page 30.

Parameters

lat1	latitude of first point in degrees
lon1	longitude of first point in degrees
lat2	latitude of second point in degrees
lon2	longitude of second point in degrees
range	Returned distance in meters.
bearing	Returned bearing in degrees.

◆ greatCircleDistancePoint()

static void TSLCoordinateConverter::greatCircleDistancePoint	(	double	startLat,
		double	startLon,
		double	bearing,
		double	distance,
		double &	endLat,
		double &	endLon )

static

Given a start position, bearing and distance return the resultant point.

Parameters

startLat	Starting latitude in degrees.
startLon	Starting longitude in degrees.
bearing	Bearing in degrees.
distance	Distance in meters.
endLat	Returned resultant latitude in degrees.
endLon	Returned resultant longitude in degrees.

◆ latLongToGARS() [1/2]

static bool TSLCoordinateConverter::latLongToGARS	(	const double	latitude,
		const double	longitude,
		int &	longBand,
		TSLSimpleString &	latBand,
		int &	quadrant,
		int &	area )

static

Convert from a latitude and longitude to an GARS grid position.

Parameters

latitude	The latitude value.
longitude	The longitude value.
longBand	On output, this will contain the GARS longitude band, 001 - 720.
latBand	On output, this will contain the GARS latitude band, AA - QZ, omitting I & O.
quadrant	On output, this will contain the GARS quadrant, 1 - 4.
area	On output, this will contain the GARS area, 1 - 9.

A true value is returned if the conversion is performed without error.

Function is threadsafe.

◆ latLongToGARS() [2/2]

static bool TSLCoordinateConverter::latLongToGARS	(	const double	latitude,
		const double	longitude,
		TSLSimpleString &	positionString )

static

Convert from a latitude and longitude to an GARS grid position as a string.

Parameters

latitude	The latitude value.
longitude	The longitude value.
positionString	the GARS grid position as a string is returned in this parameter. This will be empty if the conversion failed.

Returns: true if the method succeeds, false otherwise.

◆ latLongToMGRS() [1/2]

static bool TSLCoordinateConverter::latLongToMGRS	(	const double	latitude,
		const double	longitude,
		int &	zone,
		char &	band,
		char &	gridSquareCol,
		char &	gridSquareRow,
		double &	easting,
		double &	northing,
		bool &	polar,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from a latitude and longitude to an MGRS grid position.

Parameters

latitude	The latitude value.
longitude	The longitude value.
zone	On output, this will contain the MGRS zone. If the MGRS position is in a polar region, then the zone will be set to -1.
band	On output, this will contain the MGRS band.
gridSquareCol	On output, this will contain the MGRS grid square column identifier.
gridSquareRow	On output, this will contain the MGRS grid square row identifier.
easting	On output, this will contain the MGRS easting.
northing	On output, this will contain the MGRS northing.
polar	On output this flag will be set true if the MGRS grid position is in a polar region, i.e. if the latitude is above 84N or below 80S.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

A true value is returned if the conversion is performed without error.

◆ latLongToMGRS() [2/2]

static bool TSLCoordinateConverter::latLongToMGRS	(	const double	latitude,
		const double	longitude,
		TSLSimpleString &	positionString,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from a latitude and longitude to an MGRS grid position as a string. If the latitude is above 84N or below 80S then the UPS position string is returned.

Parameters

latitude	The latitude value.
longitude	The longitude value.
positionString	The MGRS grid position as a string is returned in this parameter. This will be empty if the conversion failed.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

Returns: true if the method succeeds, false otherwise.

◆ latLongToUPS() [1/2]

static bool TSLCoordinateConverter::latLongToUPS	(	const double	latitude,
		const double	longitude,
		char &	zone,
		double &	easting,
		double &	northing )

static

Convert the latitude and longitude given into a UPS grid position.

Parameters

latitude	The latitude value.
longitude	The longitude value.
zone	On output, this will contain the UPS zone.
easting	On output, this will contain the UPS easting.
northing	On output, this will contain the UPS northing.

A false value is returned if there is a problem with the conversion (e.g. if the latitude is outside the valid UPS range. The valid UPS range is greater than 84N or less than 80S, i.e. the Polar regions).

◆ latLongToUPS() [2/2]

static bool TSLCoordinateConverter::latLongToUPS	(	const double	latitude,
		const double	longitude,
		TSLSimpleString &	positionString )

static

Convert the latitude and longitude given into a UPS grid position as a string.

Parameters

latitude	The latitude value.
longitude	The longitude value.
positionString	The UPS grid position as a string is returned in this parameter. This will be empty if the conversion failed (e.g. if the latitude is outside the valid UPS range. The valid UPS range is greater than 84N or less than 80S, i.e. the Polar regions).

Returns: true if the method succeeds, false otherwise.

◆ latLongToUTM() [1/2]

static bool TSLCoordinateConverter::latLongToUTM	(	const double	latitude,
		const double	longitude,
		int &	zone,
		char &	band,
		double &	easting,
		double &	northing,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert the latitude and longitude given into a UTM grid position.

Parameters

latitude	The latitude value.
longitude	The longitude value.
zone	On output, this will contain the UTM zone.
band	On output, this will contain the UTM band.
easting	On output, this will contain the UTM easting.
northing	On output, this will contain the UTM northing.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

A false value is returned if there is a problem with the conversion (e.g. if the latitude is outside the valid UTM range 84N-80S).

◆ latLongToUTM() [2/2]

static bool TSLCoordinateConverter::latLongToUTM	(	const double	latitude,
		const double	longitude,
		TSLSimpleString &	positionString,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert the latitude and longitude given into a UTM grid position as a string.

Parameters

latitude	The latitude value.
longitude	The longitude value.
positionString	The UTM grid position as a string is returned in this parameter. This will be empty if the conversion failed (e.g. if the latitude is outside the valid UTM range 84N-80S).
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

Returns: true if the method succeeds, false otherwise.

◆ mgrsToUPS() [1/2]

static bool TSLCoordinateConverter::mgrsToUPS	(	const char *const	mgrs,
		char &	zone,
		double &	easting,
		double &	northing )

static

Convert from the MGRS grid position given into a UPS grid position.

Parameters

mgrs	The MGRS position string.
zone	On output, this will contain the UPS zone.
easting	On output, this will contain the UPS easting.
northing	On output, this will contain the UPS northing.

A false value is returned if there is any problem with the conversion.

◆ mgrsToUPS() [2/2]

static bool TSLCoordinateConverter::mgrsToUPS	(	const char *const	mgrs,
		TSLSimpleString &	positionString )

static

Convert from the MGRS grid position given into a UPS grid position string.

Parameters

mgrs	The MGRS position string.
positionString	The UPS grid position as a string is returned in this parameter. This will be empty if the conversion failed.

Returns: true if the method succeeds, false otherwise.

◆ mgrsToUTM() [1/2]

static bool TSLCoordinateConverter::mgrsToUTM	(	const char *const	mgrs,
		int &	zone,
		char &	band,
		double &	easting,
		double &	northing,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from the MGRS grid position string given into an UTM grid position.

Parameters

mgrs	The MGRS position string.
zone	On output, this will contain the UTM zone.
band	On output, this will contain the UTM band.
easting	On output, this will contain the UTM easting.
northing	On output, this will contain the UTM northing.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

A false value is returned if there is any problem with the conversion.

◆ mgrsToUTM() [2/2]

static bool TSLCoordinateConverter::mgrsToUTM	(	const char *const	mgrs,
		TSLSimpleString &	positionString,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from the MGRS grid position string given into an UTM grid position.

Parameters

mgrs	The MGRS position string.
positionString	The UTM grid position as a string is returned in this parameter. This will be empty if the conversion failed.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

Returns: true if the method succeeds, false otherwise.

◆ normaliseDegrees()

static double TSLCoordinateConverter::normaliseDegrees ( double angle )

static

Ensures the angle is between +- 180 degrees.

Parameters

angle angle specified in degrees.

Returns: the angle in the range +-180 degrees.

◆ rhumbLineDestination()

static bool TSLCoordinateConverter::rhumbLineDestination	(	const TSLLatLongCoord &	startPoint,
		double	trueCourse,
		double	distance,
		TSLLatLongCoord &	destination )

static

To find the latitude/longitude of a point on true course, distance from the specified start point along a rhumbline (initial point cannot be a pole):

See http://en.wikipedia.org/wiki/Rhumb_line.

Parameters

startPoint	Start point.
trueCourse	true course angle between course line and local meridian measured clockwise (in degrees).
distance	distance specified in radians.
destination	Calculated destination point.

Returns: false if calculation can not be performed.

◆ rhumbLineDistance()

static double TSLCoordinateConverter::rhumbLineDistance	(	const TSLLatLongCoord &	startPoint,
		const TSLLatLongCoord &	destinationPoint,
		double &	trueCourse )

static

Calculates the shortest rhumbline connecting two points.

See http://en.wikipedia.org/wiki/Rhumb_line.

Parameters

startPoint	Start point.
destinationPoint	End point.
trueCourse	true course angle between course line and local meridian measured clockwise (in degrees).

Returns: distance as radians.

◆ rhumbLineMidPoint()

static void TSLCoordinateConverter::rhumbLineMidPoint	(	const TSLLatLongCoord &	startPoint,
		const TSLLatLongCoord &	destinationPoint,
		TSLLatLongCoord &	midPoint )

static

Calculates the mid point on a rhumbline between startPoint and destinationPoint.

See See http://en.wikipedia.org/wiki/Rhumb_line..

Parameters

startPoint	start point of rhumbline.
destinationPoint	end point of rhumbline.
midPoint	calculated mid point of rhumbline.

◆ topocentricToGeocentric()

static bool TSLCoordinateConverter::topocentricToGeocentric	(	const TSLCoordinateSystem *	coordinateSystem,
		const TSLGeographicCoord &	geographicOrigin,
		int	numberOfPoints,
		const TSLPoint3D *	topocentricPoint,
		TSLPoint3D *	geocentricPoint )

static

Topocentric to Geocentric coordinate calculation.

The user is responsible for ensuring that sufficient space has been provided for the result.

See http://www.epsg.org/guides/docs/g7-2.pdf

Parameters

coordinateSystem	Valid coordinate system. Required for the Ellipsoid.
geographicOrigin	Geographic origin.
numberOfPoints	Number of points in the arrays.
topocentricPoint	Pointer to an array of Topocentric points to convert
geocentricPoint	Pointer to an array of XYZ points calculated (returned)

Returns: true if calculation can be completed.

◆ topocentricToGeographic()

static bool TSLCoordinateConverter::topocentricToGeographic	(	const TSLCoordinateSystem *	coordinateSystem,
		const TSLGeographicCoord &	geographicOrigin,
		int	numberOfPoints,
		const TSLPoint3D *	topocentricPoint,
		TSLGeographicCoord *	geographicPoint )

static

Topocentric to Geographic coordinate calculation.

The user is responsible for ensuring that sufficient space has been provided for the result.

See http://www.epsg.org/guides/docs/g7-2.pdf

Parameters

coordinateSystem	Valid coordinate system. Required for the Ellipsoid.
geographicOrigin	Geographic origin.
numberOfPoints	Number of points in the arrays.
topocentricPoint	Pointer to an array of Topocentric points to convert
geographicPoint	Pointer to an array of Geographic points calculated (returned)

Returns: true if calculation can be completed.

◆ upsToLatLong()

static bool TSLCoordinateConverter::upsToLatLong	(	const char	zone,
		const double	easting,
		const double	northing,
		double &	latitude,
		double &	longitude )

static

Convert from the UPS grid position given into latitude and longitude

Parameters

zone	The UPS zone.
easting	The UPS easting.
northing	The UPS northing.
latitude	On output, the latitude value.
longitude	On output, the longitude value.

A false value is returned if there is any problem with the conversion.

◆ upsToMGRS() [1/2]

static bool TSLCoordinateConverter::upsToMGRS	(	const char *const	ups,
		TSLSimpleString &	positionString )

static

Convert from the UPS grid position string given into an MGRS grid string in standard format.

Parameters

ups	The UPS position string.
positionString	The MGRS grid position as a string is returned in this parameter. This will be empty if the conversion failed.

Returns: true if the method succeeds, false otherwise.

◆ upsToMGRS() [2/2]

static bool TSLCoordinateConverter::upsToMGRS	(	const char	band,
		const double	easting,
		const double	northing,
		TSLSimpleString &	positionString )

static

Convert from the UPS grid position given into an MGRS grid string in standard format.

Parameters

band	The UPS band.
easting	The UPS easting.
northing	The UPS northing.
positionString	The MGRS grid position as a string is returned in this parameter. This will be empty if the conversion failed.

Returns: true if the method succeeds, false otherwise.

◆ utmToLatLong() [1/2]

static bool TSLCoordinateConverter::utmToLatLong	(	const char *const	utm,
		double &	latitude,
		double &	longitude,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from the UTM grid position string given into latitude and longitude.

Parameters

utm	The UTM position string.
latitude	On output, the latitude value.
longitude	On output, the longitude value.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

A false value is returned if there is any problem with the conversion.

◆ utmToLatLong() [2/2]

static bool TSLCoordinateConverter::utmToLatLong	(	const int	zone,
		const char	band,
		const double	easting,
		const double	northing,
		double &	latitude,
		double &	longitude,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from the UTM grid position given into latitude and longitude.

Parameters

zone	The UTM zone.
band	The UTM zone.
easting	The UTM easting.
northing	The UTM northing.
latitude	On output, the latitude value.
longitude	On output, the longitude value.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

A false value is returned if there is any problem with the conversion.

◆ utmToMGRS() [1/2]

static bool TSLCoordinateConverter::utmToMGRS	(	const char *const	utm,
		TSLSimpleString &	positionString,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from the UTM grid position string given into an MGRS grid string in standard format.

Parameters

utm	The UTM position string.
positionString	The MGRS grid position as a string is returned in this parameter. This will be empty if the conversion failed.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

Returns: true if the method succeeds, false otherwise.

◆ utmToMGRS() [2/2]

static bool TSLCoordinateConverter::utmToMGRS	(	const int	zone,
		const char	band,
		const double	easting,
		const double	northing,
		TSLSimpleString &	positionString,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Convert from the UTM grid position given into an MGRS grid string in standard format.

Parameters

zone	The UTM zone.
band	The UTM zone.
easting	The UTM easting.
northing	The UTM northing.
positionString	The MGRS grid position as a string is returned in this parameter. This will be empty if the conversion failed.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

Returns: true if the method succeeds, false otherwise.

◆ utmToTrueMGRS()

static bool TSLCoordinateConverter::utmToTrueMGRS	(	const int	zone,
		const char	band,
		const double	easting,
		const double	northing,
		double &	latitude,
		double &	longitude,
		int &	trueZone,
		char &	trueBand,
		char &	gridSquareCol,
		char &	gridSquareRow,
		double &	trueEasting,
		double &	trueNorthing,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

This method converts a UTM position (which may be outside the valid range for its zone) into a MGRS position.

Parameters

zone	The UTM zone.
band	The UTM zone.
easting	The UTM easting.
northing	The UTM northing.
latitude	On output, the latitude value.
longitude	On output, the longitude value.
trueZone	On output, this will contain the true MGRS zone.
trueBand	On output, this will contain the true MGRS band.
gridSquareCol	On output, this will contain the MGRS grid square column identifier.
gridSquareRow	On output, this will contain the MGRS grid square row identifier.
trueEasting	On output, this will contain the true MGRS easting.
trueNorthing	On output, this will contain the true MGRS northing.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

If the UTM position was not within the valid range the trueZone and/or trueBand will be different from the zone and band input parameters.

As a side effect the latitude and longitude are computed and are also available as output parameters.

Returns: true if the conversion is successful.

◆ utmToTrueUTM()

static bool TSLCoordinateConverter::utmToTrueUTM	(	const int	zone,
		const char	band,
		const double	easting,
		const double	northing,
		double &	latitude,
		double &	longitude,
		int &	trueZone,
		char &	trueBand,
		double &	trueEasting,
		double &	trueNorthing,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

This method converts a UTM position (which may be outside the valid range for its zone) into a valid UTM position.

Parameters

zone	The UTM zone.
band	The UTM zone.
easting	The UTM easting.
northing	The UTM northing.
latitude	On output, the latitude value.
longitude	On output, the longitude value.
trueZone	On output, this will contain the true UTM zone.
trueBand	On output, this will contain the true UTM band.
trueEasting	On output, this will contain the true UTM easting.
trueNorthing	On output, this will contain the true UTM northing.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

If the UTM position was not within the valid range the trueZone and/or trueBand will be different from the zone and band input parameters.

As a side effect the latitude and longitude are computed and are also available as output parameters.

Returns: true if the conversion is successful.

◆ validateMGRS()

static bool TSLCoordinateConverter::validateMGRS	(	const char *const	mgrs,
		int &	zone,
		char &	band,
		char &	gridSquareCol,
		char &	gridSquareRow,
		double &	easting,
		double &	northing,
		bool &	polar,
		TSLCoordinateSystem::TSLTransverseMercatorFormula	transverseMercatorFormula )

static

Check whether the MGRS grid position string given is valid and decode it into the output parameters.

Parameters

mgrs	The MGRS position string.
zone	On output, this will contain the MGRS zone. If the MGRS position is in a polar region, then the zone will be set to -1.
band	On output, this will contain the MGRS band.
gridSquareCol	On output, this will contain the MGRS grid square column identifier.
gridSquareRow	On output, this will contain the MGRS grid square row identifier.
easting	On output, this will contain the MGRS easting.
northing	On output, this will contain the MGRS northing.
polar	On output this flag will be set true if the MGRS grid position is in a polar region.
transverseMercatorFormula	This should be set to match the Map Projection (TSLCoordinateSystem) being used by the application.

A false value is returned if the MGRS position is not valid.

◆ validateUPS()

static bool TSLCoordinateConverter::validateUPS	(	const char *const	ups,
		char &	zone,
		double &	easting,
		double &	northing )

static

Check whether the UPS grid position string given is valid and decode it into the output parameters.

Parameters

ups	The UPS position string.
zone	On output, this will contain the UPS zone.
easting	On output, this will contain the UPS easting.
northing	On output, this will contain the UPS northing.

A false value is returned if the UPS position is not valid.

◆ validateUTM()

static bool TSLCoordinateConverter::validateUTM	(	const char *const	utm,
		int &	zone,
		char &	band,
		double &	easting,
		double &	northing )

static

Check whether the UTM grid position string given is valid and decode it into the output parameters.

Parameters

utm	The UTM position string.
zone	On output, this will contain the UTM zone.
band	On output, this will contain the UTM band.
easting	On output, this will contain the UTM easting.
northing	On output, this will contain the UTM northing.

A false value is returned if the UTM position is not valid.

◆ vincentyDirect()

static double TSLCoordinateConverter::vincentyDirect	(	const double	startLatitude,
		const double	startLongitude,
		const double	azimuth,
		const double	distance,
		double &	endLatitude,
		double &	endLongitude )

static

Given a starting location in latitude/longitude, a geodetic azimuth and ellipsoidal distance to a second point this method calculates the latitude/longitude of the second point.

The algorithm used by this method is based upon the Vincenty formula (http://en.wikipedia.org/wiki/Vincenty's_formulae). It assumes a WGS84 Ellipsoid.

Parameters

startLatitude	The latitude of the starting point, in degrees.
startLongitude	The longitude of the starting point, in degrees.
azimuth	The azimuth to the end point, in degrees (0 is north, clockwise).
distance	The distance from the starting point to the end point, in metres.
endLatitude	This will be populated with the latitude of the end point, in degrees.
endLongitude	This will be populated with the longitude of the end point, in degrees.

Returns: The reverse azimuth in degrees.

◆ vincentyInverse()

static double TSLCoordinateConverter::vincentyInverse	(	const double	startLatitude,
		const double	startLongitude,
		const double	endLatitude,
		const double	endLongitude,
		double &	azimuth )

static

Given starting and end locations in latitude/longitude, this method calculates the geodetic azimuth and ellipsoidal distance between them.

The algorithm used by this method is based upon the Vincenty formula (http://en.wikipedia.org/wiki/Vincenty's_formulae). It assumes a WGS84 Ellipsoid.

Parameters

startLatitude	The latitude of the starting point, in degrees.
startLongitude	The longitude of the starting point, in degrees.
endLatitude	The latitude of the end point, in degrees.
endLongitude	The longitude of the end point, in degrees.
azimuth	This will be populated with the azimuth from the start point to the end point, in degrees.

Returns: The distance from between the two points, in metres.

Detailed Description

Classes

Static Public Member Functions

Member Function Documentation

◆ azimuth()

◆ garsToLatLong()

◆ geocentricToGeodetic()

◆ geocentricToTopocentric()

◆ geodesicPath()

◆ geodeticToGeocentric()

◆ geographicToTopocentric()

◆ greatCircleDistance() [1/2]

◆ greatCircleDistance() [2/2]

◆ greatCircleDistancePoint()

◆ latLongToGARS() [1/2]

◆ latLongToGARS() [2/2]

◆ latLongToMGRS() [1/2]

◆ latLongToMGRS() [2/2]

◆ latLongToUPS() [1/2]

◆ latLongToUPS() [2/2]

◆ latLongToUTM() [1/2]

◆ latLongToUTM() [2/2]

◆ mgrsToUPS() [1/2]

◆ mgrsToUPS() [2/2]

◆ mgrsToUTM() [1/2]

◆ mgrsToUTM() [2/2]

◆ normaliseDegrees()

◆ rhumbLineDestination()

◆ rhumbLineDistance()

◆ rhumbLineMidPoint()

◆ topocentricToGeocentric()

◆ topocentricToGeographic()

◆ upsToLatLong()

◆ upsToMGRS() [1/2]

◆ upsToMGRS() [2/2]

◆ utmToLatLong() [1/2]

◆ utmToLatLong() [2/2]

◆ utmToMGRS() [1/2]

◆ utmToMGRS() [2/2]

◆ utmToTrueMGRS()

◆ utmToTrueUTM()

◆ validateMGRS()

◆ validateUPS()

◆ validateUTM()

◆ vincentyDirect()

◆ vincentyInverse()