geodesic-c.dox

// -*- text -*-
/**
 * \file geodesic-c.dox
 * \brief Documentation for geodesic routines implemented in C
 *
 * Written by Charles Karney <charles@karney.com> and licensed under the
 * MIT/X11 License.  For more information, see
 * https://geographiclib.sourceforge.io/
 **********************************************************************/

/**
\mainpage Geodesic routines implemented in C
\author Charles F. F. Karney (charles@karney.com)
\version 1.50

The documentation for other versions is available at
<tt>https://geographiclib.sourceforge.io/m.nn/C</tt> for versions numbers
<tt>m.nn</tt> &ge; 1.28.

\section abstract-c Abstract

This is a C implementation of the geodesic algorithms from
<a href="https://geographiclib.sourceforge.io">GeographicLib</a>.  This
is a self-contained library (requiring only the standard C math library)
which makes it easy to do geodesic computations for an ellipsoid of
revolution in a C program.  It is included with version 4.9.0 of
<a href="https://proj.org">PROJ</a> and later.
It uses ANSI C as described in B. W. Kernigan and D. M. Ritchie, The C
Programming Language, 2nd Ed. (Prentice Hall, 1988), and so should
compile correctly with just about any C compiler.  However, the C99 math
functions are used if they are available.

\section download-c Downloading the source

The C library is part of %GeographicLib which available for download at
- <a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.50.tar.gz">
  GeographicLib-1.50.tar.gz</a>
- <a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.50.zip">
  GeographicLib-1.50.zip</a>
.
as either a compressed tar file (tar.gz) or a zip file.  After unpacking
the source, the C library can be found in the directory <tt>legacy/C</tt>.
The library consists of two files geodesic.c and geodesic.h.

The library is also included as part of
<a href="https://proj.org">PROJ</a> starting with
version 4.9.0, where it is used as the computational backend for
<a href="https://github.com/OSGeo/proj.4/wiki/Mangeod">geod(1)</a>.
Instructions for how to use the library via proj.4 are given below.

Licensed under the
<a href="http://www.opensource.org/licenses/MIT">MIT/X11 License</a>; see
<a href="https://geographiclib.sourceforge.io/html/LICENSE.txt">LICENSE.txt</a>.

\section doc-c Library documentation

Here is the
\link geodesic.h <i>application programming interface</i>\endlink
for the library (this is just the documentation for the header file,
geodesic.h).  See also the documentation on the structures geod_geodesic,
geod_geodesicline, and geod_polygon.

\section samples-c Sample programs

Also included are 3 small test programs:
 - direct.c is a simple command line utility for solving the
   direct geodesic problem;
 - inverse.c is a simple command line utility for solving the
   inverse geodesic problem;
 - planimeter.c is a simple command line utility for computing the
   area of a geodesic polygon given its vertices.
 .
Here, for example, is inverse.c
\include inverse.c
To compile, link, and run this, you would typically use \verbatim
cc -o inverse inverse.c geodesic.c -lm
echo 30 0 29.5 179.5 | ./inverse \endverbatim
These sample programs can also be built with the supplied cmake file,
CMakeLists.txt, as follows \verbatim
mkdir BUILD
cd BUILD
cmake ..
make
make test
echo 30 0 29.5 179.5 | ./inverse \endverbatim

Alternatively, if you have proj.4 installed, you can compile and link
with \verbatim
cc -c inverse.c
cc -o inverse inverse.o -lproj
echo 30 0 29.5 179.5 | ./inverse \endverbatim
If proj.4 is installed, e.g., in /usr/local, you might have to use
\verbatim
cc -c -I/usr/local/include inverse.c
cc -o inverse inverse.o -lproj -L/usr/local/lib -Wl,-rpath=/usr/local/lib
echo 30 0 29.5 179.5 | ./inverse \endverbatim

\section library-c Using the library

- Put @code{.c}
  #include "geodesic.h"
  @endcode
  in your source code.  If you are using the library via proj.4, change
  this to @code{.c}
  #include <geodesic.h>
  @endcode
- Make calls to the geodesic routines from your code.  The interface to
  the library is documented in geodesic.h.
- Compile and link as described above.
- If linking with proj.4, you might want to check that the version of
  proj.4 contains the geodesic routines.  You can do this with @code{.c}
  #include <proj_api.h>
  #if PJ_VERSION >= 490
  #include <geodesic.h>
  #endif
  ...
  @endcode

- You can check the version of the geodesic library with, e.g.,
  @code{.c}
  #if GEODESIC_VERSION >= GEODESIC_VERSION_NUM(1,40,0)
  ...
  #endif
  @endcode

\section external-c External links

- These algorithms are derived in C. F. F. Karney,
  <a href="https://doi.org/10.1007/s00190-012-0578-z">
  Algorithms for geodesics</a>,
  J. Geodesy <b>87</b>, 43--55 (2013)
  (<a href="https://geographiclib.sourceforge.io/geod-addenda.html"> addenda</a>).
- A longer paper on geodesics: C. F. F. Karney,
   <a href="https://arxiv.org/abs/1102.1215v1">Geodesics
   on an ellipsoid of revolution</a>,
   Feb. 2011
   (<a href="https://geographiclib.sourceforge.io/geod-addenda.html#geod-errata">
   errata</a>).
- <a href="https://sourceforge.net/projects/geographiclib/">
  Main project page</a>
- <a href="https://geographiclib.sourceforge.io/">
  GeographicLib web site</a>
  - Documentation on the C++ classes: GeographicLib::Geodesic,
    GeographicLib::GeodesicLine, GeographicLib::PolygonAreaT.
  - The section in the %GeographicLib documentation on geodesics: \ref
    geodesic.
- <a href="https://sourceforge.net/p/geographiclib/code/ci/release/tree/">
  git repository</a>
- Implementations in various languages
  - C++ (complete library):
    <a href="../index.html">
      documentation</a>,
    <a href="https://sourceforge.net/projects/geographiclib/files/distrib">
      download</a>;
  - C (geodesic routines):
    <a href="../C/index.html">
      documentation</a>, also included with recent versions of
    <a href="https://proj.org">
      PROJ</a>;
  - Fortran (geodesic routines):
    <a href="../Fortran/index.html">
      documentation</a>;
  - Java (geodesic routines):
    <a href="http://repo1.maven.org/maven2/net/sf/geographiclib/GeographicLib-Java/">
      Maven Central package</a>,
    <a href="../java/index.html">
      documentation</a>;
  - JavaScript (geodesic routines):
    <a href="https://www.npmjs.com/package/geographiclib">
      npm package</a>,
    <a href="../js/index.html">
      documentation</a>;
  - Python (geodesic routines):
    <a href="http://pypi.python.org/pypi/geographiclib">
      PyPI package</a>,
    <a href="../python/index.html">
      documentation</a>;
  - Matlab/Octave (geodesic and some other routines):
    <a href="https://www.mathworks.com/matlabcentral/fileexchange/50605">
      Matlab Central package</a>,
    <a href="https://viewer.mathworks.com/?viewer=plain_code&url=https%3A%2F%2Fwww.mathworks.com%2Fmatlabcentral%2Fmlc-downloads%2Fdownloads%2Fsubmissions%2F50605%2Fversions%2F15%2Fcontents%2FContents.m">
      documentation</a>;
  - C# (.NET wrapper for complete C++ library):
    <a href="../NET/index.html">
      documentation</a>.
- <a href="https://geographiclib.sourceforge.io/geodesic-papers/biblio.html">
  A geodesic bibliography</a>.
- The wikipedia page,
  <a href="https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid">
  Geodesics on an ellipsoid</a>.

\section changes-c Change log

 - <a href="https://geographiclib.sourceforge.io/1.50/C">Version 1.50</a>
   (released 2019-09-22)
   - Allow arbitrarily complex polygons in geod_polygon_*.  In the case
     of self-intersecting polygons the area is accumulated
     "algebraically", e.g., the areas of the 2 loops in a figure-8
     polygon will partially cancel.
   - Workaround bugs in fmod and sin in Visual Studio 10, 11, and 12 and
     relax delta for GeodSolve59 in geodtest (tagged v1.49.1-c).
   - Fix bug in geod_polygon_addedge which caused the count of pole
     encirclings to be wrong, sometimes resulting in an incorrect area
     if a polygon vertex had longitude = 0  (tagged v1.49.2-c).

 - <a href="https://geographiclib.sourceforge.io/1.49/C">Version 1.49</a>
   (released 2017-10-05)
   - Fix more warning messages from some compilers; add tests.

 - <a href="https://geographiclib.sourceforge.io/1.48/C">Version 1.48</a>
   (released 2017-04-09)
   - This is the version slated for the version of proj.4 after 4.9.4
     (tagged v1.48.1-c).
   - Fix warnings messages from some compilers.
   - Change default range for longitude and azimuth to
     (&minus;180&deg;, 180&deg;] (instead of
     [&minus;180&deg;, 180&deg;)).

 - <a href="https://geographiclib.sourceforge.io/1.47/C">Version 1.47</a>
   (released 2017-02-15)
   - This is the version incorporated into proj.4 version 4.9.3 (tagged
     v1.46.1-c).
   - Fix the order of declarations, incorporating the patches in version
     1.46.1.
   - Improve accuracy of area calculation (fixing a flaw introduced in
     version 1.46).

 - <a href="https://geographiclib.sourceforge.io/1.46/C">Version 1.46</a>
   (released 2016-02-15)
   - Add s13 and a13 to the geod_geodesicline struct.
   - Add geod_directline, geod_gendirectline, and geod_inverseline.
   - More accurate inverse solution when longitude difference is close
     to 180&deg;.

 - <a href="https://geographiclib.sourceforge.io/1.45/C">Version 1.45</a>
   (released 2015-09-30)
   - The solution of the inverse problem now correctly returns NaNs if
     one of the latitudes is a NaN.
   - Include a test suite that can be run with "make test" after
     configuring with cmake.
   - Add geod_polygon_clear().

 - <a href="https://geographiclib.sourceforge.io/1.44/C">Version 1.44</a>
   (released 2015-08-14)
   - This is the version incorporated into proj.4 version 4.9.2.
   - Improve accuracy of calculations by evaluating trigonometric
     functions more carefully and replacing the series for the reduced
     length with one with a smaller truncation error.
   - The allowed ranges for longitudes and azimuths is now unlimited;
     it used to be [&minus;540&deg;, 540&deg;).
   - Enforce the restriction of latitude to [&minus;90&deg;, 90&deg;] by
     returning NaNs if the latitude is outside this range.
   - The inverse calculation sets \e s12 to zero for coincident points
     at pole (instead of returning a tiny quantity).

 - <a href="https://geographiclib.sourceforge.io/1.40/C">Version 1.40</a>
   (released 2014-12-18)
   - This is the version incorporated into proj.4 version 4.9.1.

 - <a href="https://geographiclib.sourceforge.io/1.40/C">Version 1.32</a>
   (released 2013-07-12)
   - This is the version incorporated into proj.4 version 4.9.0.

**********************************************************************/