NAME

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

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

KEYWORDS

AUTHOR