NAME

SYNOPSIS

#include <geography.h>

double REarth(void);
void SetREarth(double r);

Angle AngleFmDeg(double deg);
double AngleToDeg(Angle a);
Angle AngleFmRad(double rad);
double AngleToRad(Angle a);
Angle BadAngle(void);
int AngleIsOK(Angle a);
int AngleIsBad(Angle a);
double ISin(Angle a);
double ICos(Angle a);
GeoPt GeoPtFmDeg(double dLat, double dLon);
GeoPt GeoPtFmRad(double dLat, double dLon);
void GeoPtGetDeg(GeoPt geoPt, double *dLatPtr, double *dLonPtr);
void GeoPtGetRad(GeoPt geoPt, double *dLatPtr, double *dLonPtr);
CartPt LatLonToCart(GeoPt geoPt);
int GeoPtIsSomewhere(GeoPt geoPt);
int GeoPtIsNowhere(GeoPt geoPt);
GeoPt GeoPtNowhere(void);
int MapPtIsSomewhere(MapPt mapPt);
int MapPtIsNowhere(MapPt mapPt);
MapPt MapPtNowhere(void);

MapPt ScaleMapPt(MapPt mapPt, double scale);
GeoPt GeoStep(GeoPt geoPt, Angle dir, Angle dist);
Angle GeoDistance(GeoPt p1, GeoPt p2);
double GeoQuickDistance(GeoPt p1, GeoPt p2);
Angle Azimuth(GeoPt p1, GeoPt p2);
GeoPt GCircleX(GeoPt ln1pt1, GeoPt ln1pt2, GeoPt ln2pt1, GeoPt ln2pt2);

Angle DomainLat(Angle lat);
Angle DomainLon(Angle lon, Angle refLon);
Angle GwchLon(Angle lon);
GeoPt DomainLonPt(GeoPt geoPt, Angle refLon);
GeoPt GwchLonPt(GeoPt geoPt);
enum LonSgn LonCmp(Angle lon0, Angle lon1);
enum LatSgn LatCmp(Angle lat0, Angle lat1);
int AngleCmp(Angle d0, Angle d1);
int LonBtwn(Angle lon, Angle lon0, Angle lon1);
int LonBtwn1(Angle lon, Angle lon0, Angle lon1);

Rotation NewRotation(double angle);
void SetRotation(Rotation rxn, double angle);
void DeleteRotation(Rotation rxn);
double GetRotation(Rotation rxn);
MapPt Rotate(MapPt mapPt, Rotation rxn);

struct GeoTime_Cal GeoTime_CalSet(int year, int month, int day, int hour, int minute, float second);
struct GeoTime_Jul GeoTime_JulSet(int day, float second);
struct GeoTime_Jul GeoTime_CalToJul(struct GeoTime_Cal cal);
struct GeoTime_Cal GeoTime_JulToCal(struct GeoTime_Jul jul);
void GeoTime_Incr(struct GeoTime_Jul *jul, double ds);
int GeoTime_Cmp(struct GeoTime_Jul jul1, struct GeoTime_Jul jul2);
float GeoTime_Diff(struct GeoTime_Jul jul1, struct GeoTime_Jul jul2);

DESCRIPTION

Most geography functions require that angles be given as the Angle data type. Functions should convert between double values giving degree and radian measurements and Angle values using the AngleFmDeg, AngleToDeg, RadFmDeg, and RadToDeg functions described below. Currently, the Angle data type is an integer giving the angle in microdegrees. Using integers helps reduce round off errors. A microdegree of latitude is about 0.11 meters.

A geographic point is a latitude-longitude pair. It is represented by the GeoPt data type, declared as follows: typedef struct { Angle lat; Angle lon; } GeoPt;

"Map point" refers to an abscissa-ordinate pair on a 2D map. It is represented by the MapPt data type, declared as follows: typedef struct { float abs; float ord; } MapPt;

The BadAngle procedure returns a bogus Angle value. It can be used to indicate an error condition. AngleIsOK returns true if a is not the value returned by BadAngle. AngleIsBad returns true if a is the value returned by BadAngle.

AngleFmDeg returns the Angle corresponding to deg degrees. It returns BadAngle() if deg is out of range. AngleToDeg returns the degree measure corresponding to Angle a. AngleFmRad returns the Angle corresponding to rad radians. It returns BadAngle() if rad is out of range. AngleToRad returns the radian measure corresponding to Angle a.

REarth returns the radius of the Earth, in meters. SetREarth sets the radius of the Earth to new value r assumed to be given in meters.

GeoPtFmDeg returns a geopoint with latitude lat and longitude lon, given as decimal degrees. It returns GeoPtNowhere() if either lat or lon is out of range for the Angle data type.

GeoPtGetDeg puts the latitude and longitude values from geoPt into latPtr and lonPtr as decimal degrees.

GeoPtFmRad returns a geopoint with latitude lat and longitude lon, given as decimal radians. It returns GeoPtNowhere() if either lat or lon is out of range for the Angle data type.

GeoPtGetRad puts the latitude and longitude values from geoPt into latPtr and lonPtr as decimal radians.

GeoPtNowhere returns a bogus geographic point. Functions should return GeoPtNowhere() when asked to perform undefined calculations, such as finding the intersection of parallel lines. GeoPointIsSomewhere and GeoPtIsNowhere test for bogus points. GeoPtIsNowhere returns true if given the result of GeoPtNowhere, otherwise false. GeoPtIsSomewhere returns false if given the result of GeoPtNowhere, otherwise true.

MapPtNowhere returns a bogus map point. It serves the same purpose as GeoPtNowhere. MapPtIsNowhere returns true if given the result of MapPtNowhere, otherwise false. MapPtIsSomewhere returns false if given the result of MapPtNowhere, otherwise true.

Scale scales the abscissa and ordinate of mapPt by the given value and returns the scaled map point.

GeoStep returns a geographic point at distance dist and direction dir from geographic point geoPt .

GeoDistance returns the distance between two geographic points p1 and p2.

GeoQuickDistance returns the absolute distance between geographic points p1 and p2 in 3D Cartesian space with origin at Earth's center and in which Earth has unit radius. This is faster than computing the distance in great circle degrees, making it useful for repeated comparisons.

Azimuth returns the azimuth from geographic point p1 to geographic point p2 clockwise from North.

GCircleX returns the intersection of two great circles, identified by two points on each. The first great circle contains points ln1pt1 and ln1pt2. The second great circle contains points ln2pt1 and ln2pt2. Great circles intersect at two points. GCircleX returns the intersection closer to the average position of the four given points. It returns GeoPtNowhere() if all four points are on the same great circle.

ANGLE COMPARISONS

Comparison results have values enum LatSgn {North, Eq, South}; enum LonSgn {West, PrMd, East}; where North and East mean more positive, Eq (Equator) and PrMD (Prime Meridian) mean equal, and South and West mean more negative. The comparison functions should be used when comparing latitudes and longitudes to reduce the effect of round off errors and to take account of discontinuities on the globe (e.g. 170 E is usually considered to be west of 170 W).

DomainLat returns a latitude value with the same sine as lat in the range -pi / 2 <= latitude <= pi / 2

DomainLon returns a longitude value equivalent to lon in the range rLon - pi <= longitude <= rLon + pi GwchLon(lon) is the same as DomainLon(lon, 0). DomainLonPt(geoPt, rLon) returns a point at the same location as geoPt with a longitude value within 180 degrees of rLon. GwchLonPt(geoPt) is the same as DomainLonPt(geoPt, 0).

LonCmp returns East if lon0 is east of lon1, PrMd if lon0 and lon1 are on the same meridian, and West if lon0 is west of lon1. It makes the comparison on the smaller arc connecting the meridians for lon0 and lon1.

LatCmp returns North if lat0 is north of lat1, Eq if lat0 is the same latitude as lat1, and South if lat0 is south of lat1.

AngleCmp returns -1 if d0 < d1, 0 if d0 == d1, and 1 if d0 > d1

LonBtwn returns true if longitude lon is between lon0 and lon1. Otherwise it returns false.

LonBtwn1 returns true if lon is between lon0 and lon1, or lon is equal to lon0, or lon is equal to lon1. Otherwise it returns false.

ROTATING MAP POINTS

NewRotation creates a new Rotation structure. It returns the new rotation, or NULL if there is a failure. When no longer needed, the rotation should be destroyed with a call to DeleteRotation.

DeleteRotation eliminates rxn and associated storage.

SetRotation changes the rotation angle of rxn to angle.

GetRotation returns the rotation angle currently residing in rxn.

TIME VALUES

SEE ALSO

KEYWORDS

AUTHOR