Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
geography(3)		     Geography C functions		  geography(3)

       REarth,	SetREarth, BadAngle, AngleIsOK,	AngleIsBad, AngleFmDeg,	Angle-
       ToDeg, AngleFmRad, AngleToRad, ISin,  ICos,  GeoPtSetDeg,  GeoPtSetRad,
       GeoPtGetDeg,   GeoPtGetRad,  GeoPtIsSomewhere,  GeoPtIsNowhere,	GeoPt-
       Nowhere,	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_CalTo-
       Jul,  GeoTime_JulToCal, GeoTime_Incr, GeoTime_Cmp, GeoTime_Diff - basic
       geographic calculations and comparisons.

       #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);

       These functions do calculations with geographic locations.  Unless oth-
       erwise  noted,  latitudes  and longitudes are measured in degrees, dis-
       tances in great circle degrees, azimuths	(directions) in	degrees	clock-
       wise  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	 inte-
       gers 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  mea-
       sure  corresponding  to	Angle  a.  AngleFmRad returns the Angle	corre-
       sponding	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

       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 compar-

       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 intersec-
       tion closer to the average position of the four given points.   It  re-
       turns GeoPtNowhere() if all four	points are on the same great circle.

       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 geogra-

       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  Domain-
       Lon(lon,	 0).  DomainLonPt(geoPt, rLon) returns a point at the same lo-
       cation 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

       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.	Other-
       wise 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.

       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 rota-
       tion,  or NULL if there is a failure.  When no longer needed, the rota-
       tion 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.

       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 Ju-
       lian representation of a	given calendar time.  GeoTime_JulToCal returns
       the  calendar  representation of	a given	Julian time.  GeoTime_Incr in-
       crements	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.


       geography, geographic point, map	point, distance, azimuth

       Gordon Carrie (

Geography			       2			  geography(3)


Want to link to this manual page? Use this URL:

home | help