Utility Routines API

Files
file	locator.c
	locator and bearing conversion interface

Functions
double	dms2dec (int degrees, int minutes, double seconds, int sw)
	Convert DMS to decimal degrees. More...
double	dmmm2dec (int degrees, double minutes, int sw)
	Convert D M.MMM notation to decimal degrees. More...
int	dec2dms (double dec, int *degrees, int *minutes, double *seconds, int *sw)
	Convert decimal degrees angle into DMS notation. More...
int	dec2dmmm (double dec, int *degrees, double *minutes, int *sw)
	Convert a decimal angle into D M.MMM notation. More...
int	locator2longlat (double *longitude, double *latitude, const char *locator)
	Convert Maidenhead grid locator to Longitude/Latitude. More...
int	longlat2locator (double longitude, double latitude, char *locator, int pair_count)
	Convert longitude/latitude to Maidenhead grid locator. 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

Here are grouped some often used functions, like locator conversion routines.

Function Documentation

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 (respective of the short path) of a given bearing.

Returns

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

See also

qrb()

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

Convert a decimal angle into D M.MMM notation.

Parameters

dec	Decimal degrees
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).

Return values

-RIG_EINVAL	if any of the pointers are NULL.
RIG_OK	if conversion went OK.

See also

dmmm2dec()

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

Convert decimal degrees angle into DMS notation.

Parameters

dec	Decimal degrees
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 flag

Convert decimal degrees angle into its degree/minute/second notation.

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

Upon return dec2dms 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).

Return values

-RIG_EINVAL	if any of the pointers are NULL.
RIG_OK	if conversion went OK.

See also

dms2dec()

double distance_long_path

(

double

distance

)

Calculate the long path distance between two points.

Parameters

distance

The shortpath distance

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

Returns

the distance in kilometers for the opposite path.

See also

qrb()

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

Convert D M.MMM notation to decimal degrees.

Parameters

degrees	Degrees, whole degrees
minutes	Minutes, decimal minutes
sw	South or West

Convert a degrees, decimal minutes notation common on many GPS units to its decimal degrees value.

degrees > 360, minutes > 60.0 are allowed, but resulting angle won't 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 angle in decimal degrees.

See also

dec2dmmm()

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

Convert DMS to decimal degrees.

Parameters

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

Convert degree/minute/second angle to decimal degrees angle. degrees >360, minutes > 60, and seconds > 60.0 are allowed, but resulting angle won't 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 angle in decimal degrees.

See also

dec2dms()

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

Convert Maidenhead grid locator to Longitude/Latitude.

Parameters

longitude	Pointer for the calculated Longitude
latitude	Pointer for the calculated Latitude
locator	The Maidenhead grid locator–2 through 12 char + nul string

Convert Maidenhead grid locator to Longitude/Latitude (decimal degrees). The locator should be in 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.

Return values

-RIG_EINVAL	if locator exceeds RR99xx99xx99 or exceeds length limit–currently 1 to 6 lon/lat pairs.
RIG_OK	if conversion went OK.

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()

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

Convert longitude/latitude to Maidenhead grid locator.

Parameters

longitude	Longitude, decimal degrees
latitude	Latitude, decimal degrees
locator	Pointer for the Maidenhead Locator
pair_count	Precision expressed as lon/lat pairs in the locator

Convert longitude/latitude (decimal degrees) to Maidenhead grid locator. locator must point to an array at least pair_count * 2 char + '\0'.

Return values

-RIG_EINVAL	if locator is NULL or pair_count exceeds length limit. Currently 1 to 6 lon/lat pairs.
RIG_OK	if conversion went OK.

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()

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 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 (0.0°).

Return values

-RIG_EINVAL	if NULL pointer passed or lat and lon values exceed -90 to 90 or -180 to 180.
RIG_OK	if calculations are successful.

Returns

The distance in kilometers and azimuth in decimal degrees for the short path are stored in distance and azimuth.

See also

distance_long_path(), azimuth_long_path()