Files
file	locator.c
	QRA locator (Maidenhead grid square) and latitude/longitude bearing conversion interface.

Macros
#define	RADIAN (180.0 / M_PI)
	Standard definition of a radian.

#define	ARC_IN_KM 111.2
	arc length for 1 degree in kilometers, i.e. 60 Nautical Miles

#define	MAX_LOCATOR_PAIRS 6
	Longest locator to process, e.g. AA00AA00AA00. More...

#define	MIN_LOCATOR_PAIRS 1
	Shortest locator to process, e.g. AA. More...

Functions
double	dms2dec (int degrees, int minutes, double seconds, int sw)
	Convert Degrees Minutes Seconds (DMS) notation to decimal degrees (D.DDD) angle. More...

double	dmmm2dec (int degrees, double minutes, double seconds, int sw)
	Convert degrees decimal minutes (D M.MMM) notation to decimal degrees (D.DDD) angle. More...

int	dec2dms (double dec, int degrees, int minutes, double seconds, int sw)
	Convert a decimal degrees (D.DDD) angle into Degrees Minutes Seconds (DMS) notation. More...

int	dec2dmmm (double dec, int degrees, double minutes, int *sw)
	Convert a decimal degrees (D.DDD) angle into degrees decimal minutes (D M.MMM) notation. More...

int	locator2longlat (double longitude, double latitude, const char *locator)
	Convert QRA locator (Maidenhead grid square) to Longitude/Latitude. More...

int	longlat2locator (double longitude, double latitude, char *locator, int pair_count)
	Convert longitude/latitude to QRA locator (Maidenhead grid square). More...

int	qrb (double lon1, double lat1, double lon2, double lat2, double distance, double azimuth)
	Calculate the distance and bearing between two points. More...

double	distance_long_path (double distance)
	Calculate the long path distance between two points. More...

double	azimuth_long_path (double azimuth)
	Calculate the long path bearing between two points. More...

Detailed Description

Hamlib general purpose API

Hamlib function call interface for determining QRA locator (Maidenhead grid square), bearing, and conversion between QRA locator and latitude/longitude formats.

Sources used in writing these routines

Code to determine bearing and range was taken from the Great Circle, by Steven R. Sampson, N5OWK.
Ref: "Air Navigation", Air Force Manual 51-40, 1 February 1987
Ref: "ARRL Satellite Experimenters Handbook", August 1990

Code to calculate distance and azimuth between two QRA locators, taken from wwl, by IK0ZSN, Mirko Caserta.

New bearing code added by N0NB was found at: http://williams.best.vwh.net/avform.htm#Crs

Macro Definition Documentation

◆ MAX_LOCATOR_PAIRS

#define MAX_LOCATOR_PAIRS 6

Longest locator to process, e.g. AA00AA00AA00.

Sets the limit locator2longlat() will convert and sets the maximum length longlat2locator() will generate. Each function properly handles any value from 1 to 6 so MAX_LOCATOR_PAIRS should be left at 6.

◆ MIN_LOCATOR_PAIRS

#define MIN_LOCATOR_PAIRS 1

Shortest locator to process, e.g. AA.

Sets a floor on the shortest locator that should be handled.

Function Documentation

◆ azimuth_long_path()

double azimuth_long_path ( double azimuth )

Calculate the long path bearing between two points.

Parameters

azimuth The shortpath bearing–0.0 to 360.0 degrees.

Calculate the long path (opposite of the short path) of a given bearing.

Returns: the azimuth in decimal degrees for the opposite path or RIG_EINVAL (negated value) upon input error (outside the range of 0.0 to 360.0).

See also: qrb()

◆ dec2dmmm()

int dec2dmmm	(	double	dec,
		int *	degrees,
		double *	minutes,
		int *	sw
	)

Convert a decimal degrees (D.DDD) angle into degrees decimal minutes (D M.MMM) notation.

Parameters

dec	Decimal degrees angle.
degrees	Pointer for the calculated whole Degrees.
minutes	Pointer for the calculated decimal Minutes.
sw	Pointer for the calculated SW flag.

Convert a decimal angle into its degree, decimal minute notation common on many GPS units.

When passed a value < -180 or > 180, the value will be normalized within these limits and the sign set apropriately.

Upon return dec2dmmm guarantees 0 >= degrees <= 180, 0.0 >= minutes < 60.0.

When dec is < 0.0 sw will be set to 1. When dec is >= 0.0 sw will be set to 0. This flag allows the application to determine whether the D M.MMM angle should be treated as negative (south or west).

Returns: RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).

Return values

RIG_OK	The conversion was successful.
RIG_EINVAL	Either of the pointers are NULL.

See also: dmmm2dec()

◆ dec2dms()

int dec2dms	(	double	dec,
		int *	degrees,
		int *	minutes,
		double *	seconds,
		int *	sw
	)

Convert a decimal degrees (D.DDD) angle into Degrees Minutes Seconds (DMS) notation.

Parameters

dec	Decimal degrees (D.DDD).
degrees	Pointer for the calculated whole Degrees.
minutes	Pointer for the calculated whole Minutes.
seconds	Pointer for the calculated decimal Seconds.
sw	Pointer for the calculated SW (South/West) flag.

Convert decimal degrees angle (D.DDD) into its Degree Minute Second (DMS) notation.

When dec < -180 or dec > 180, the angle will be normalized within these limits and the sign set appropriately.

Upon return, guarantees 0 >= degrees <= 180, 0 >= minutes < 60, and 0.0 >= seconds < 60.0.

When dec is < 0.0 sw will be set to 1. When dec is >= 0.0 sw will be set to 0. This flag allows the application to determine whether the DMS angle should be treated as negative (South or West).

Returns: RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).

Return values

RIG_OK	The conversion was successful.
RIG_EINVAL	Either of the pointers are NULL.

See also: dms2dec()

◆ distance_long_path()

double distance_long_path ( double distance )

Calculate the long path distance between two points.

Parameters

distance The shortpath distance in kilometers.

Calculate the long path (opposite bearing of the short path) of a given distance.

Returns: The distance in kilometers for the opposite path.

See also: qrb()

◆ dmmm2dec()

double dmmm2dec	(	int	degrees,
		double	minutes,
		double	seconds,
		int	sw
	)

Convert degrees decimal minutes (D M.MMM) notation to decimal degrees (D.DDD) angle.

Parameters

degrees	Degrees, whole degrees.
minutes	Minutes, decimal minutes.
seconds	Seconds, decimal seconds.
sw	South or West.

Convert a degrees decimal minutes (D M.MMM) notation common on many GPS units to a decimal degrees (D.DDD) angle value.

Note: For the parameters degrees > 360, minutes > 60.0, seconds > 60.0 are allowed, but the resulting angle will not be normalized.

When the variable sw is passed a value of 1, the returned decimal degrees value will be negative (South or West). When passed a value of 0 the returned decimal degrees value will be positive (North or East).

Returns: The signed angle in decimal degrees (D.DDD).

See also: dec2dmmm()

◆ dms2dec()

double dms2dec	(	int	degrees,
		int	minutes,
		double	seconds,
		int	sw
	)

Convert Degrees Minutes Seconds (DMS) notation to decimal degrees (D.DDD) angle.

Parameters

degrees	Degrees, whole degrees.
minutes	Minutes, whole minutes.
seconds	Seconds, decimal seconds.
sw	South or West.

Convert a Degrees Minutes Seconds (DMS) notation value to a decimal degrees (D.DDD) angle value.

Note: For the parameters degrees >360, minutes > 60, and seconds > 60.0 are allowed, but the resulting angle will not be normalized.

When the variable sw is passed a value of 1, the returned decimal degrees value will be negative (South or West). When passed a value of 0 the returned decimal degrees value will be positive (North or East).

Returns: The signed angle in decimal degrees (D.DDD).

See also: dec2dms()

◆ locator2longlat()

int locator2longlat	(	double *	longitude,
		double *	latitude,
		const char *	locator
	)

Convert QRA locator (Maidenhead grid square) to Longitude/Latitude.

Parameters

longitude	Pointer for the calculated Longitude.
latitude	Pointer for the calculated Latitude.
locator	The QRA locator–2 through 12 characters + nul string.

Convert a QRA locator string to Longitude/Latitude in decimal degrees (D.DDD). The locator should be 2 through 12 chars long format. locator2longlat is case insensitive, however it checks for locator validity.

Decimal long/lat is computed to center of grid square, i.e. given EM19 will return coordinates equivalent to the southwest corner of EM19mm.

Returns: RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).

Return values

RIG_OK	The conversion was successful.
RIG_EINVAL	The QRA locator exceeds RR99xx99xx99 or exceeds length limit–currently 1 to 6 lon/lat pairs–or is otherwise malformed.

Bug:: The fifth pair ranges from aa to xx, there is another convention that ranges from aa to yy. At some point both conventions should be supported.

See also: longlat2locator()

◆ longlat2locator()

int longlat2locator	(	double	longitude,
		double	latitude,
		char *	locator,
		int	pair_count
	)

Convert longitude/latitude to QRA locator (Maidenhead grid square).

Parameters

longitude	Longitude, decimal degrees.
latitude	Latitude, decimal degrees.
locator	Pointer for the QRA Locator.
pair_count	Requested precision expressed as lon/lat pairs in the returned QRA locator string.

Convert longitude/latitude given in decimal degrees (D.DDD) to a QRA locator (Maidenhead grid square). locator must point to an array length that is at least pair_count * 2 char + '\0'.

Returns: RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).

Return values

RIG_OK	The conversion was successful.
RIG_EINVAL	if locator is NULL or pair_count exceeds length limit. Currently 1 to 6 lon/lat pairs.

Bug:

locator is not tested for overflow.

The fifth pair ranges from aa to yy, there is another convention that ranges from aa to xx. At some point both conventions should be supported.

See also: locator2longlat()

◆ qrb()

int qrb	(	double	lon1,
		double	lat1,
		double	lon2,
		double	lat2,
		double *	distance,
		double *	azimuth
	)

Calculate the distance and bearing between two points.

Parameters

lon1	The local Longitude, decimal degrees.
lat1	The local Latitude, decimal degrees,
lon2	The remote Longitude, decimal degrees.
lat2	The remote Latitude, decimal degrees.
distance	Pointer for the distance, km.
azimuth	Pointer for the bearing, decimal degrees.

Calculate the distance and bearing (QRB) between lon1, lat1 and lon2, lat2.

This version will calculate the QRB to a precision sufficient for 12 character locators. Antipodal points, which are easily calculated, are considered equidistant and the bearing is simply resolved to be true north, e.g. azimuth = 0.0.

Returns: RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).

Return values

RIG_OK	The calculations were successful.
RIG_EINVAL	If a NULL pointer passed or lat and lon values exceed -90 to 90 or -180 to 180.

See also: distance_long_path(), azimuth_long_path()

Files

Macros

Functions

Detailed Description

Hamlib general purpose API

Macro Definition Documentation

◆ MAX_LOCATOR_PAIRS

◆ MIN_LOCATOR_PAIRS

Function Documentation

◆ azimuth_long_path()

◆ dec2dmmm()

◆ dec2dms()

◆ distance_long_path()

◆ dmmm2dec()

◆ dms2dec()

◆ locator2longlat()

◆ longlat2locator()

◆ qrb()