DragonFly On-Line Manual Pages
geography(3) Geography C functions geography(3)
See the file man.macros.
NAME
REarth, SetREarth, BadAngle, AngleIsOK, AngleIsBad, AngleFmDeg,
AngleToDeg, AngleFmRad, AngleToRad, ISin, ICos, GeoPtSetDeg,
GeoPtSetRad, GeoPtGetDeg, GeoPtGetRad, GeoPtIsSomewhere,
GeoPtIsNowhere, GeoPtNowhere, MapPtIsSomewhere, MapPtIsNowhere,
MapPtNowhere, ScaleMapPt, GeoStep, GeoDistance, GeoQuickDistance,
Azimuth, GCircleX, DomainLat, DomainLon, GwchLon, DomainLonPt,
GwchLonPt, LonCmp, LatCmp, AngleCmp, LonBtwn, LonBtwn1, Rotation,
NewRotation, SetRotation, GetRotation, DeleteRotation, Rotate,
GeoTime_CalSet, GeoTime_JulSet, GeoTime_CalToJul, GeoTime_JulToCal,
GeoTime_Incr, GeoTime_Cmp, GeoTime_Diff - basic geographic calculations
and comparisons.
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
These functions do calculations with geographic locations. Unless
otherwise noted, latitudes and longitudes are measured in degrees,
distances in great circle degrees, azimuths (directions) in degrees
clockwise from north, and distances on the plane in meters.
Calculations assume a spherical Earth.
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
The following functions compare latitude and longitude values or modify
them so that they are more appropriate for geographic calculations.
Note that angle arguments are given with the Angle data type. Angles
can be converted between the internal representation and double degree
values with the AngleToDeg and AngleFmDeg functions declared in
geography.h.
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
The following functions rotate map points about the origin. Rotation
information is stored in objects of type Rotation.
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
The GeoTime functions store and manipulate time values stored in either
of two structures. Structures of form: struct GeoTime_Jul {
int day;
float second; }; store a time instant as a Julian day and seconds
within that day. GeoTime_JulSet returns a GeoTime_Jul struct with the
given day and second values. Structures of form: struct GeoTime_Cal {
int year;
int month;
int day;
int hour;
int minute;
float second; }; store a time instant with its calendar and clock
values. GeoTime_CalSet returns a structure containing the given year,
month, day, hour, minute, and second. GeoTime_CalToJul returns the
Julian representation of a given calendar time. GeoTime_JulToCal
returns the calendar representation of a given Julian time.
GeoTime_Incr increments jul by ds seconds. GeoTime_Cmp returns -1 if
jul1 is before jul2, 1 if jul1 is after jul2 or 0 if jul1 and jul2 are
the same time. GeoTime_Diff returns jul1 minus jul2 in seconds.
SEE ALSO
geoProj(3)
KEYWORDS
geography, geographic point, map point, distance, azimuth
AUTHOR
Gordon Carrie (user0@tkgeomap.org)
Geography 2 geography(3)