Hamlib  1.2.15
Files | Functions
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:
azimuthThe 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:
decDecimal degrees
degreesPointer for the calculated whole Degrees
minutesPointer for the calculated decimal Minutes
swPointer 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_EINVALif any of the pointers are NULL.
RIG_OKif 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:
decDecimal degrees
degreesPointer for the calculated whole Degrees
minutesPointer for the calculated whole Minutes
secondsPointer for the calculated decimal Seconds
swPointer 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_EINVALif any of the pointers are NULL.
RIG_OKif conversion went OK.
See also:
dms2dec()
double distance_long_path ( double  distance)

Calculate the long path distance between two points.

Parameters:
distanceThe 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:
degreesDegrees, whole degrees
minutesMinutes, decimal minutes
swSouth 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:
degreesDegrees, whole degrees
minutesMinutes, whole minutes
secondsSeconds, decimal seconds
swSouth 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:
longitudePointer for the calculated Longitude
latitudePointer for the calculated Latitude
locatorThe 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_EINVALif locator exceeds RR99xx99xx99 or exceeds length limit--currently 1 to 6 lon/lat pairs.
RIG_OKif 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:
longitudeLongitude, decimal degrees
latitudeLatitude, decimal degrees
locatorPointer for the Maidenhead Locator
pair_countPrecision 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_EINVALif locator is NULL or pair_count exceeds length limit. Currently 1 to 6 lon/lat pairs.
RIG_OKif 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:
lon1The local Longitude, decimal degrees
lat1The local Latitude, decimal degrees
lon2The remote Longitude, decimal degrees
lat2The remote Latitude, decimal degrees
distancePointer for the distance, km
azimuthPointer 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_EINVALif NULL pointer passed or lat and lon values exceed -90 to 90 or -180 to 180.
RIG_OKif 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()
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated by doxygen 1.7.6.1

Hamlib documentation for version 1.2.15 -- Thu Feb 2 2012 21:37:29
Project page: http://www.hamlib.org