OrbNav tools
============

Collocation often begins with a need to determine when satellites of interest
are able to view the same earth location or are able to view a specific
geographic region. Collopak includes a suite of orbital navigation (OrbNav)
tools that suit this purpose (and can be applied to many other problems
related to satellite navigation).

These tools leverage the `SGP4 orbital model
<http://www.celestrak.com/publications/AIAA/2006-6753/>`_ and `NORAD orbital
parameters <http://www.celestrak.com/NORAD/elements/>`_, both available from
CelesTrak.

Running these tools from the command line requires a file named ``TLINSET``
containing orbital parameters for the satellites and time period of interest.
This file must be present in the working directory when the program is run. The
NASA Suomi NPP Atmosphere SIPS hosts a `web interface
<http://sips.ssec.wisc.edu/orbnav/#/tools/tlinset>`_ that makes it easy to get
the required orbital parameters, or allows you to run many of the OrbNav tools
`in your brower <http://sips.ssec.wisc.edu/orbnav/#pages/about>`_ or via a
script-friendly `API <http://sips.ssec.wisc.edu/orbnav/api/v1>`_ without
needing to download orbital parameters at all.

More complete documentation of these tools is coming soon. For now, refer
to the `web interface <http://sips.ssec.wisc.edu/orbnav/>`_ to see what tools
are available. Usage information for each command can be seen by providing a
single ``help`` command line argument.

::

    $ # view usage information for 'where'
    $ where help

     where   satl-id   yymmdd  hhmmss

    $ # download orbital parameters
    $ curl http://sips.ssec.wisc.edu/orbnav/api/v1/tlinset.ascii?sats=AQUA|TERRA&start=2016-01-01T00:00:00Z&end=2016-02-01T00:00:00Z' \
        > TLINSET

    $ # run the command
    $ where AQUA 160101 182800
    ...