// -*- 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.32

\section abstract Abstract

This is a C implementation of the geodesic algorithms from <a
href="http://geographiclib.sf.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 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 Downloading the source

The C library is part of %GeographicLib which available for download at
- <a href="http://sf.net/projects/geographiclib/files/distrib/GeographicLib-1.32.tar.gz">
  GeographicLib-1.32.tar.gz</a>
- <a href="http://sf.net/projects/geographiclib/files/distrib/GeographicLib-1.32.zip">
  GeographicLib-1.32.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 GeographicLib-1.32/legacy/C.
The library consists of two files geodesic.c and geodesic.h.

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

\section doc Library documentation

The interface to the library is documented via doxygen in the header
file.  To access this, see geodesic.h.

\section samples 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
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 Using the library

- Put @verbatim
  #include "geodesic.h" @endverbatim
  in your source code.  If you are using the library via proj.4, change
  this to @verbatim
  #include <geodesic.h> @endverbatim
- 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.

\section external External links

- These algorithms are derived in C. F. F. Karney,
  <a href="http://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.sf.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.sf.net/geod-addenda.html#geod-errata">
   errata</a>).
- <a href="http://geographiclib.sf.net">The GeographicLib web site</a>.
- <a href="../index.html">The C++ library</a>.
- <a href="../java/index.html">The Java library</a>.
- <a href="../Fortran/index.html">The Fortran library</a>.
- Documentation on the C++ classes: GeographicLib::Geodesic,
  GeographicLib::GeodesicLine, GeographicLib::PolygonArea.
- The section in the %GeographicLib documentation on geodesics: \ref
  geodesic.
- <a href="http://geographiclib.sf.net/geodesic-papers/biblio.html">
  An online geodesic bibliography</a>.
**********************************************************************/