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.
double dmmm2dec (int degrees, double minutes, int sw)
 Convert D M.MMM notation to decimal degrees.
int dec2dms (double dec, int *degrees, int *minutes, double *seconds, int *sw)
 Convert decimal degrees angle into DMS notation.
int dec2dmmm (double dec, int *degrees, double *minutes, int *sw)
 Convert a decimal angle into D M.MMM notation.
int locator2longlat (double *longitude, double *latitude, const char *locator)
 Convert Maidenhead grid locator to Longitude/Latitude.
int longlat2locator (double longitude, double latitude, char *locator, int pair_count)
 Convert longitude/latitude to Maidenhead grid locator.
int qrb (double lon1, double lat1, double lon2, double lat2, double *distance, double *azimuth)
 Calculate the distance and bearing between two points.
double distance_long_path (double distance)
 Calculate the long path distance between two points.
double azimuth_long_path (double azimuth)
 Calculate the long path bearing between two points.

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

Returns:
the azimuth in decimal degrees for the opposite path.
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.
Bug:
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()


Hamlib documentation for version 1.2.7 -- Tue Aug 26 21:43:29 2008
Project page: http://hamlib.org