DragonFly On-Line Manual Pages
geoLn(3) Geography C functions geoLn(3)
See the file man.macros.
NAME
GeoLn, GeoLnCreate, GeoLnClear, GeoLnSetAlloc, GeoLnAddPt, GeoLnInfo,
GeoLnGetPt, GeoLnDestroy, GeoLnCtr, GeoLnContainGeoPt - container for
geographic points.
SYNOPSIS
#include <geoLines.h>
GeoLn GeoLnCreate(unsigned nptsMax);
void GeoLnClear(GeoLn geoLn);
void GeoLnSetAlloc(GeoLn geoLn, unsigned nptsMax);
void GeoLnDestroy(GeoLn geoLn);
void GeoLnAddPt(GeoPt geoPt, GeoLn geoLn);
struct GeoLnInfo GeoLnGetInfo(GeoLn geoLn);
GeoPt GeoLnGetPt(GeoLn geoLn, unsigned n);
CartPt GeoLnCtr(GeoLn ln);
int GeoLnContainGeoPt(GeoPt geoPt, GeoLn geoLn);
DESCRIPTION
These functions create, manipulate and access geolines, which are
arrays of geographic points (see Geography(3)). Geolines are
represented by objects of type GeoLn.
GeoLnCreate creates and initializes a geoline with enough memory
allocated to store nPtsMax geographic points. It returns the new
geoline, or NULL if there is a failure. When no longer needed, the
geoline should be destroyed with a call to GeoLnDestroy.
GeoLnClear removes all points from geoLn, but does not free it's
storage. This reduces memory management overhead for geolines that are
reused.
GeoLnSetAlloc sets the allocation of geoLn to nPtsMax.
GeoLnDestroy frees all storage associated with geoLn.
GeoLnAddPt adds geoPt to the end of geoLn. It increases geoLn's
allocation automatically, if necessary.
GeoLnGetInfo returns a structure of form: struct GeoLnInfo {
unsigned nPts;
Angle latMax;
Angle lonMax;
Angle latMin;
Angle lonMin; }; in which nPts is the number of points in the
geoLn, latMax is the maximum longitude in Angle units, lonMax is the
maximum latitude in Angle units, latMin is the minimum longitude in
Angle units, and lonMin is the minimum latitude in Angle units. See
the geography (3) man page for information on Angle units.
GeoLnGetPt returns the geographic point at offset n from geoLn. The
first point in the line has offset 0. GeoLnGetPt returns
GeoPtNowhere() if n is out of bounds.
GeoLnCtr returns the "center of mass" of geoLn as a Cartesian point. A
Cartesian point is a point on the globe described in a 3D Cartesian
coordinate system with origin at the Earth's center and in which Earth
has unit radius. It is represented by type CartPt declared in
geography.h as typedef struct {
double x;
double y;
double z; } CartPt; GeoLnCtr converts all of the geographic
points in geoLn to Cartesian points and then computes their mean in 3D
space. This gives a rough measure of where the points are.
GeoLnContainGeoPt returns true if geoPt is contained within geoLn. The
algorithm assumes that the segments joining the points in geoLn in
order never cross and form a closed shape. The pole opposite geoLn's
center as computed by GeoLnCtr is assumed to be outside this shape. If
a segment connecting geoPt to the far pole intersects the shape an odd
number of times, geoPt is inside geoLn and GeoLnContainGeoPt returns
true. Otherwise it returns false. Result is undefined and unreliable
if any of the segments cross or if geoLn's center of mass is at the
center of the Earth, such as if the line is a great circle.
SEE ALSO
geoLnArr, mapLn, mapLnArr, geography
KEYWORDS
GeoLn, geoline, geography, container
AUTHOR
Gordon Carrie (user0@tkgeomap.org)
Geography 2 geoLn(3)