Loading...
Searching...
No Matches
Utility Routines API

## 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.
#define | MIN_LOCATOR_PAIRS 1
| Shortest locator to process, e.g. AA.

## Functions

double | dms2dec (int degrees, int minutes, double seconds, int sw)
| Convert Degrees Minutes Seconds (DMS) notation to decimal degrees (D.DDD) angle.
double | dmmm2dec (int degrees, double minutes, double seconds, int sw)
| Convert degrees decimal minutes (D M.MMM) notation to decimal degrees (D.DDD) angle.
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.
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.
int | locator2longlat (double *longitude, double *latitude, const char *locator)
| Convert QRA locator (Maidenhead grid square) to Longitude/Latitude.
int | longlat2locator (double longitude, double latitude, char *locator, int pair_count)
| Convert longitude/latitude to QRA locator (Maidenhead grid square).
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.

## 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 appropriately.

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