gcPlanet is an array of eight double precision numbers, mathematical representation of the planetary surface.
gcLatLong is a data object consisting of two double precision numbers, radian measurements of latitude and longitude of a point on the planetary surface represented by an associated gcPlanet object. gcLatLong is an application-semantic rooted numerical representation of a point on Earth (or some other spheroidal planetary surface).
gcPoint is an eight-byte integer that represents an atomic location (point, vertex, "0-cell"...) on the surface of spheroidal body, in a compact form well suited for storage in the computer systems, as well as spherical and spheroidal calculations. On the planet the size of Earth, the granularity of gcPoint is about 6 millimeters (mean, 20 millimeters maximum). gcPoint is transformed from and into gcLatLong object by gcPointToLatLong() and gcLatLongToPoint() functions.
gcDelta is an opaque two byte object that represents the position "rounding error", incurred by transforming a location expressed by a gcLatLong object into a corresponding gcPoint object. If an application requests this value while calling gcLatLongToPoint() and provides it to gcPointToLatLong(), the location returned by the latter is guaranteed to differ less than a third of a millimeter from the one supplied to the former.
gcProximity is an opaque double precision number that describes the proximity relationship between two gcPoint objects. gcProximity is not the same as the distance between two objects, but it has one important property relative to it: in any given vicinity, "proximities" (implied by the gcProximity number magnitude) will order the same as the distances. gcProximity may be transformed into geodesic distance with more or less precision, depending on the items (in addition to the gcPlanet) known and the precision required.
gcCollection is a compund data object representing either an ordered or an aggregate set of gcPoints. The set is assumed to reside in an array of 8-byte (size of an atomic gcPoint) objects. gcCollection is represented by a poitner and three integers. The pointer is the base of the array, and three integers specify the array offset of the first gcPoint, the period of the cgPoints in the array, and the count of the members, respectively. Thus, if 'a' is the base of the array of 8-byte objects, 'o' is the offset of the first gcPoint and 'p' the period, the 'n'-th gcPoint of the collection will be a[(o)+(c)*(p)].
gcExtent is a 16-byte opaque object that describes that part of the planetary surface covered by a gcCollection of point locations. In most instances this will be a rather small part of the surface, but it need not be so. As the part of surface covered by the collection grows, a point is reached when the extent becomes the complete planetary surface.
gcEastNorth is a data object consisting of two double precision numbers that represent Easat and North coordinate in some cartographic projection. The magnitude of numbers is assumed to be such that a short distance in the vicinity of plane coordinate origin is the same as the corresponding distance on the gcPlanet.
gcAzimuthis a data object consisting of two double precision numbers that represent a direction in a tangential or cartographic plane. The numbers are direction cosines of the direction along X (East) and Y (North) coordinate, respectively. By a common surveying/mapping convention, if this direction is expressed as an angle, it will be measured clockwise from Y (North) in the range (0 - 2*PI).
What follows is an inventory of "simple API" library functions, grouped by "chapter". A short description and synopsis is provided for each function. Most functions return an integer number, 0 to indicate successful computation. For details, consult the function preamble comment in its source code file.
Return library version and build time:
int gcLibraryBuild(char **returnedTimestamp);
Given semi major and semi-minor axis, initialize the ellipsoid parameter set:
int gcInitPlanet(double a,
double b,
gcPlanet planet);
Return the address of a static array of parameters of the most common
ellipsoid:
double *gcEarthWgs84();
Transform gcLatLong into gcPoint:
void gcLatLongToPoint(const gcPlanet planet,
const gcLatLong givenPoint,
gcPoint *returnedPoint,
gcDelta *returnedDelta);
Transform gcPoint into gcLatLong:
void gcPointToLatLong(const gcPlanet planet,
gcPoint givenPoint,
gcDelta givenDelta,
gcLatLong returnedPoint);
Create a gcLatLong positioned randomly somewhere on the planetary surface:
void gcRandomLatLong(const gcPlanet planet,
gcLatLong returnedPoint);
Find the proximity measure between two points:
void gcProximity(gcPoint firstGivenPoint,
gcDelta firstGivenDelta,
gcPoint secondGivenPoint,
gcDelta secondGivenDelta);
Determine the planetary surface extent of a gcCollection:
int gcCollectionExtent(const gcPoint *collectionArray,
int offset,
int period
int count,
gcExtent returnedExtent);
gcDirCos is an array of three double precision numbers, i, j, k components of a generic normalized vector.
gcDirCosE is an array of three double precision numbers, vector representing a normal to the ellipsoidal surface in some given point.
gcDirCosF is an array of three double precision numbers, vector representing a location on a near-conformal sphere. The mapping between the ellipsoid and the near-conformal sphere is simple: it consists of substituting ellipsoidal latitude of a point with its geocentric equivalent.
gcRadVect is an array of three double precision numbers, a radius-vector usually representing 3-D cartesian coordinates.
gcDirCos2 is an array of two double precision numbers, components of a normalized vector in plane.
gcRadVect2 is an array of two double precision numbers, a radius-vector usually representing planar cartesian coordinates in some transient meridian or tangential computational plane.
Compute both sine and cosine of an angle given by its radian measure:
void gcSineCosine(double givenAngle,
double *returnedSine,
double *returnedCosine);
Pack a vector into an 8-byte packed object:
void gcPackVector(const gcDirCos givenVector,
gcUnInt8 *returnedPackedVector,
gcUnInt2 *returnedDelta);
Unpack a vector:
void gcUnPackVector(gcUnInt8 givenPackedVector,
gcUnInt2 givenDelta,
gcDirCos returnedVector);
Return a random normalized vector:
void gcRandomDirCos(gcDirCos returnedVector);
Given a square of a chord, return an arc computed by series expansion:
double gcChordSquareToArcS(double givenSquareChord);
Given a planar direction vector, return the azimuth angle (measured
clockwise from North, 0 - 2 * PI).
double gcAzimuthAngle(const gcAzimuth azimuth);
Return an angle-like scalar that can be used to compare or order directions:
double gcDirectionOrder(double dX,
double dY);
Return given chord in radius-vector form:
int gcChordRadiusVector(double chord,
gcRadVect2 returnedRadVect);
Return given chord squared in radius-vector form:
int gcChordSqRadiusVector(double chordSquare,
gcRadVect2 returnedRadVect);
Return radius and center of a circle defined with three points:
double gcCircleRadiusCenter(const gcEastNorth firstGivenPoint,
const gcEastNorth secondGivenPoint,
const gcEastNorth thirdGivenPoint,
gcEastNorth returnedCenter);
Transform spheroidal normal from angular into vector form:
void gcAnglesToVector(const gcLatLong givenAngles,
gcDirCos returnedVector);
Transform spheroidal normal from vector into angular form:
void gcVectorToAngles(const gcDirCos givenVector,
gcLatLong returnedAngles);
Normalize planar vector, return its magnitude:
double gcNormalizeVector2(const gcAzimuth givenVector,
gcAzimuth returnedVector);
Normalize three-dimensional vector, return its magnitude:
double gcNormalizeVector3(const gcDirCos givenVector,
gcDirCos returnedVector);
Return square of a chord between two normalized vectors:
double gcChordSquare(const gcDirCos firstGivenVector,
const gcDirCos secondGivenVector);
Return cross product of two vectors:
void gcVectorCross(const gcDirCos vA,
const gcDirCos vB,
gcDirCos returned_vAxVb);
Return East and North vectors (i.e., normals of meridian and prime vertical
planes) in a given point:
void gcMeridianPrimeVertical(const gcDirCos givenVector,
gcDirCos returnedEastVector,
gcDirCos returnedNorthVector);
Middle vector:
void gcMiddleVector(const gcDirCos firstGivenVector,
const gcDirCos secondGivenVector,
gcDirCos returnedMidVector);
Spherical inverse with chord distance:
double gcInverseSphere(double radius,
const gcDirCos firstGivenPoint,
double elevetionA,
const gcDirCos secondGivenPoint,
double elevetionB,
gcAzimuth returnedDirectAzimuth,
gcAzimuth returnedReverseAzimuth);
Spherical direct problem with chord distance:
int gcDirectSphere(double radius,
const gcDirCos givenPoint,
const gcAzimuth givenAzimuth,
double chordDistance,
gcDirCos returnedPoint);
Return tangent plane free term for a given ellipsoid normal:
double gcTangentPlaneFT(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal);
Return prime vertical plane free term for a given ellipsoid normal:
double gcPrimeVerticalFT(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal);
Return ellipsoid normal inter-axial distance:
double gcInterAxialDistance(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal);
Return radius of curvature of the prime vertical:
double gcPrimeVerticalRadius(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal);
Return Equatorial depth of an ellipsoid normal:
double gcEquatorialDepth(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal);
Return radius of curvature of a meridian at a given ellipsoid normal:
double gcMeridianRadius(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal);
Return mean radius of curvature of the ellipsoid at the location defined
by its normal:
double gcGaussRadius(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal);
Compute geocentric coordinates of an ellipsoid point given by its normal
and elevation:
double gcNormalToRadVect(const gcPlanet planet,
const gcDirCosE givenEllipsoidNormal,
double elevation,
gcRadVect returnedPoint,
gcRadVect returnedCenterNearPoint);
Compute ellipsoid normal of a point (not necessarily on the ellipsoid
surface) given by its geocentric coordinates:
double gcRadVectToNormal(const gcPlanet planet,
const gcRadVect givenPoint,
gcDirCosE returnedEllipsoidNormal,
double *returnedElevation);
Given an ellipsoid normal in latitude/longitude form, return
a normalized radius vector of a point on the near-conformal sphere:
void gcLatLongToDirCosF(const gcPlanet planet,
const gcLatLong givenEllipsoidLatLong,
gcDirCosF returnedNCSdcos);
Given a normalized radius vector of a point on near-conformal sphere, return
the ellipsoid surface normal in latitude/longitude form:
void gcDirCosFToLatLong(const gcPlanet planet,
const gcDirCosF givenNCSdcos,
gcLatLong returnedEllipsoidLatLong);
Transform direction cosine form point coordinates from near-conformal sphere
to ellipsoid:
void gcDirCosFToDirCosE(const gcPlanet planet,
const gcDirCosF givenNCdcos,
gcDirCosE returnedEllipsodDcos);
Transform direction cosine form point coordinates from ellipsoid to
near-conformal sphere:
void gcDirCosEToDirCosF(const gcPlanet planet,
const gcDirCosE givenEllipsodDcos,
gcDirCosF returnedNCdcos);
Return the local scale factor which multiplies the arc length on the
unit sphere to obtain (approximate) length of geodesic on the ellipsoid:
double gcSphereEllipsoidScale(const gcPlanet planet,
const gcDirCosF givenVicinity);
Inverse problem of geodesy with chord distance:
double gcInverseChord(const gcPlanet planet,
const gcDirCosE firstGivenPoint,
double elevationA,
const gcDirCosE secondGivenPoint,
double elevationB,
gcAzimuth returnedDirectAzimuth,
gcAzimuth returnedReverseAzimuth);
Direct problem of geodesy with chord distance:
int gcDirectChord(const gcPlanet planet,
const gcDirCosE givenPoint,
const gcAzimuth givenAzimuth,
double chordDistance,
gcDirCosE returnedPoint);
Return the geodesic distance between two given points using Vincenty's formula:
double gcInverseVincenty(const gcPlanet planet,
const gcLatLong firstGivenPoint,
const gcLatLong secondGivenPoint);
Direct problem of geodesy with geodesic distance using Vincenty's formula:
int gcDirectVincenty(const gcPlanet planet,
const gcDirCosE givenPoint,
const gcAzimuth givenAzimuth,
double geodesicDistance,
gcDirCosE returnedPoint);
Initialize gnomonic projection parameter array:
int gcGnomonicSetup(const gcDirCos tangencyPoint,
double radius,
double[GC_GNOMONIC_PARMS] returnedGnomonicParameters);
Project a point from sphere to a gnomonic plane:
int gcGnomonicSphereToPlane(const double[GC_GNOMONIC_PARMS] gnomonicParameters,
const gcDirCos givenSphericalPoint,
gcEastNorth plpt returnedPlanrPoint);
"UnProject" a point from gnomonic plane to a sphere:
int gcGnomonicPlaneToSphere(const double[GC_GNOMONIC_PARMS] gnomonicParameters,
const gcEastNorth givenPlanrPoint,
gcDirCos returnedSphericalPoint);