// -*- 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
 * http://geographiclib.sourceforge.net/
 **********************************************************************/

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

The documentation for other versions is available at
<tt>http://geographiclib.sourceforge.net/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="http://geographiclib.sourceforge.net">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 the recent version of
<a href="https://github.com/OSGeo/proj.4/wiki">proj.4</a>.
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.

\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.46.tar.gz">
  GeographicLib-1.46.tar.gz</a>
- <a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.46.zip">
  GeographicLib-1.46.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://github.com/OSGeo/proj.4/wiki">proj.4</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="http://geographiclib.sourceforge.net/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://dx.doi.org/10.1007/s00190-012-0578-z">
  Algorithms for geodesics</a>,
  J. Geodesy <b>87</b>, 43--55 (2013)
  (<a href="http://geographiclib.sourceforge.net/geod-addenda.html"> addenda</a>).
- A longer paper on geodesics: C. F. F. Karney,
   <a href="http://arxiv.org/abs/1102.1215v1">Geodesics
   on an ellipsoid of revolution</a>,
   Feb. 2011
   (<a href="http://geographiclib.sourceforge.net/geod-addenda.html#geod-errata">
   errata</a>).
- <a href="https://sourceforge.net/projects/geographiclib/">
  Main project page</a>
- <a href="http://geographiclib.sourceforge.net/">
  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="http://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://github.com/OSGeo/proj.4/wiki">
      proj.4</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="http://www.mathworks.com/matlabcentral/fileexchange/50605">
      Matlab Central package</a>,
    <a href="http://www.mathworks.com/matlabcentral/fileexchange/50605/content/Contents.m">
      documentation</a>;
  - C# (.NET wrapper for complete C++ library):
    <a href="../NET/index.html">
      documentation</a>.
- <a href="http://geographiclib.sourceforge.net/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="http://geographiclib.sourceforge.net/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="http://geographiclib.sourceforge.net/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="http://geographiclib.sourceforge.net/1.44/C">Version 1.44</a>
   (released 2015-08-14)
   - 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).
**********************************************************************/
