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

FreeBSD Manual Pages

  
 
  

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

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 ar-
       rays of geographic points (see Geography(3)).  Geolines are represented
       by objects of type GeoLn.

       GeoLnCreate  creates and	initializes a geoline with enough memory allo-
       cated 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	 stor-
       age.   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	 allo-
       cation 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 ge-
       oLn, latMax is the maximum longitude in Angle units, lonMax is the max-
       imum  latitude in Angle units, latMin is	the minimum longitude in Angle
       units, and lonMin is the	minimum	latitude in Angle units.  See the  ge-
       ography (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	GeoPt-
       Nowhere() 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 co-
       ordinate	 system	 with  origin at the Earth's center and	in which Earth
       has unit	radius.	 It is represented by type CartPt declared in  geogra-
       phy.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  or-
       der  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)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | KEYWORDS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=geoLn&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help