JNRowe / upoints

``earth_distance``
==================

Modules for working with points on a spherical object
-----------------------------------------------------

Introduction
------------

``earth_distance`` is a collection of `GPL v3`_ licensed modules for
working with points on a spherical object.  It allows you to calculate
the distance and bearings between points, mangle xearth_/xplanet_ data
files, work with online UK trigpoint databases, `GNU miscfiles`_ city
databases and NOAA_'s weather station database.

Requirements
------------

``earth_distance`` does not depend on any modules that aren't included
in Python_'s standard library, and as such should run with Python 2.5 or
newer [#]_.  If ``earth_distance`` doesn't work with the version of
Python you have installed, drop me a mail_ and I'll endeavour to fix it.

The modules have been tested on many UNIX-like systems, including Linux,
Solaris and OS X, but it should work fine on other systems too.  The
modules contain a large collection of ``doctest`` tests that will be run
if any of the modules are executed directly or with Python's ``-m``
switch [#]_.  You can also run the testsuite by executing ``make check`` in
the source tree.

.. [#] If you still use Python v2.4 only small changes are required, for
       example to the base class definitions and the removal of
       conditional statements.

.. [#] Some tests may fail due to rounding errors depending on the system
       the tests are being run on, but such instances should be obvious
       even to the casual user and some effort has been put in to reduce
       the likelihood of such failures.

Example
-------

The simplest way to show how ``earth_distance`` works is by example, and
here goes::

    >>> from earth_distance import point
    >>> Home = point.Point(52.015, -0.221)
    >>> Telford = point.Point(52.6333, -2.5000)
    >>> print "%d kM, with an initial bearing of %d°(%s)" % \
    ...       (Home.distance(Telford), Home.bearing(Telford),
    ...        Home.bearing(Telford, "string")
    169 kM, with an initial bearing of 294°(West-Northwest)

All the class definitions, methods and independent functions contain
hopefully useful docstrings with ``doctest``-based examples.  The
``html/`` directory contains the preprocessed epydoc_ output for
reference.

There is some accompanying text and examples for ``point.py``, formerly
``edist.py``, available in `geolocation and path cross`_.  More examples
are available for ``xearth.py`` in `xearth and path cross`_.  Some
background and more examples for ``trigpoints.py`` is online in
`Trigpointing and point.py`_.  Usage examples for ``cities.py`` is
available in `Cities and cities.py`_.  And finally, `Pythons on
a plane`_ contains information on ``weather_stations.py``.

Limitations
-----------

The modules assume the caller will take care of significant digits, and
output formatting [#]_.  All results are returned with whatever
precision your Python install or system generates; unintuitive float
representation, rounding errors, warts and all.

The reasoning is simple, the caller should always know what is required
and any heuristics added to the code would be just that -- guesses,
which can and will be wrong.

.. [#] A future release may include more standard output definitions,
       but there is no intention to add "magic" data mangling.

Bugs
----

If you find a bug don't hesitate to drop me a mail_ preferably including
a minimal testcase, or even better a patch!

.. _GPL v3: http://www.gnu.org/licenses/
.. _xearth: http://www.cs.colorado.edu/~tuna/xearth/
.. _xplanet: http://xplanet.sourceforge.net/
.. _Python: http://www.python.org/
.. _epydoc: http://epydoc.sourceforge.net/
.. _geolocation and path cross: http://www.jnrowe.ukfsn.org/articles/geolocation_and_pathcross.html
.. _xearth and path cross: http://www.jnrowe.ukfsn.org/articles/xearth_and_pathcross.html
.. _Trigpointing and point.py: http://www.jnrowe.ukfsn.org/articles/trigpointing_and_point_py.html
.. _Cities and cities.py: /articles/python_cities.html
.. _Pythons on a plane: /articles/pythons_on_a_plane.html
.. _GNU miscfiles: http://www.gnu.org/directory/miscfiles.html
.. _NOAA: http://weather.noaa.gov/
.. _mail: jnrowe@ukfsn.org

..
    :vim: set ft=rst ts=2 sw=2 et: