.\" 
.\" Copyright (c) 2004 Gordon D. Carrie.  All rights reserved.
.\" 
.\" Licensed under the Open Software License version 2.1
.\" 
.\" Please address questions and feedback to user0@tkgeomap.org
.\"
.\" @(#) $Id: geoLn.3,v 1.6 2004/09/22 21:57:50 tkgeomap Exp $
.so man.macros
.TH geoLn 3 2 Geography "Geography C functions"
.SH NAME
GeoLn, GeoLnCreate, GeoLnClear, GeoLnSetAlloc, GeoLnAddPt, GeoLnInfo, GeoLnGetPt, GeoLnDestroy, GeoLnCtr, GeoLnContainGeoPt \- container for geographic points.
.SH SYNOPSIS
.nf
\fB#include <geoLines.h>\fR
\fBGeoLn  GeoLnCreate(unsigned \fInptsMax\fB);\fR
\fBvoid GeoLnClear(GeoLn \fIgeoLn\fB);\fR
\fBvoid GeoLnSetAlloc(GeoLn \fIgeoLn\fB, unsigned \fInptsMax\fB);\fR
\fBvoid GeoLnDestroy(GeoLn \fIgeoLn\fB);\fR
\fBvoid GeoLnAddPt(GeoPt \fIgeoPt\fB, GeoLn \fIgeoLn\fB);\fR
\fBstruct GeoLnInfo GeoLnGetInfo(GeoLn \fIgeoLn\fB);\fR
\fBGeoPt GeoLnGetPt(GeoLn \fIgeoLn\fB, unsigned \fIn\fB);\fR
\fBCartPt GeoLnCtr(GeoLn \fIln\fB);\fR
\fBint GeoLnContainGeoPt(GeoPt \fIgeoPt\fB, GeoLn \fIgeoLn\fB);\fR
.fi
.SH DESCRIPTION
These functions create, manipulate and access geolines, which are arrays
of geographic points (see Geography(3)).  Geolines are represented by objects
of type \fBGeoLn\fR.
.PP
\fBGeoLnCreate\fR creates and initializes a geoline with enough memory allocated
to store \fInPtsMax\fR 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 \fBGeoLnDestroy\fR.
.PP
\fBGeoLnClear\fR removes all points from \fIgeoLn\fR, but does not free it's
storage.  This reduces memory management overhead for geolines that are reused.
.PP
\fBGeoLnSetAlloc\fR sets the allocation of \fIgeoLn\fR to \fInPtsMax\fR.
.PP
\fBGeoLnDestroy\fR frees all storage associated with \fIgeoLn\fR.
.PP
\fBGeoLnAddPt\fR adds \fIgeoPt\fR to the end of \fIgeoLn\fR.  It increases
\fIgeoLn\fR's allocation automatically, if necessary.
.PP
\fBGeoLnGetInfo\fR returns a structure of form:
.CS
struct GeoLnInfo {
    unsigned	nPts;
    Angle	latMax;
    Angle	lonMax;
    Angle	latMin;
    Angle	lonMin;
};
.CE
in which \fBnPts\fR is the number of points in the \fIgeoLn\fR,
\fBlatMax\fR is the maximum longitude in Angle units,
\fBlonMax\fR is the maximum latitude in Angle units,
\fBlatMin\fR is the minimum longitude in Angle units,
and \fBlonMin\fR is the minimum latitude in Angle units.
See the \fBgeography\fR (3) man page for information on Angle units.
.PP
\fBGeoLnGetPt\fR returns the geographic point at offset \fIn\fR from
\fIgeoLn\fR.  The first point in the line has offset \fB0\fR.
\fBGeoLnGetPt\fR returns \fBGeoPtNowhere()\fR if \fIn\fR is out of bounds.
.PP
\fBGeoLnCtr\fR returns the "center of mass" of \fIgeoLn\fR 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 \fBCartPt\fR declared in \fBgeography.h\fR as
.CS
typedef struct
{
  double		x;
  double		y;
  double		z;
} CartPt;
.CE
\fBGeoLnCtr\fR converts all of the geographic points in \fIgeoLn\fR to Cartesian
points and then computes their mean in 3D space.  This gives a rough measure of
where the points are.
.PP
\fBGeoLnContainGeoPt\fR returns true if \fIgeoPt\fR is contained within
\fIgeoLn\fR.  The algorithm assumes that the segments joining the points
in \fIgeoLn\fR in order never cross and form a closed shape.  The pole
opposite \fIgeoLn\fR's center as computed by \fBGeoLnCtr\fR is assumed to be
outside this shape.  If a segment connecting \fIgeoPt\fR to the far pole
intersects the shape an odd number of times, \fIgeoPt\fR is inside \fIgeoLn\fR
and \fBGeoLnContainGeoPt\fR returns true.  Otherwise it returns false.  Result
is undefined and unreliable if any of the segments cross or if \fIgeoLn\fR's
center of mass is at the center of the Earth, such as if the line is a great
circle.

.SH "SEE ALSO"
geoLnArr, mapLn, mapLnArr, geography

.SH KEYWORDS
GeoLn, geoline, geography, container

.SH AUTHOR
Gordon Carrie (user0@tkgeomap.org)