119 lines
4.6 KiB
Plaintext
119 lines
4.6 KiB
Plaintext
// -*- 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>.
|
|
**********************************************************************/
|