===============================
Pysis
===============================

.. image:: https://badge.fury.io/py/pysis.svg
    :target: http://badge.fury.io/py/pysis

.. image:: https://travis-ci.org/wtolson/pysis.svg?branch=master
        :target: https://travis-ci.org/wtolson/pysis

.. image:: https://pypip.in/d/pysis/badge.png
        :target: https://pypi.python.org/pypi/pysis


Toolkit for using USGS Isis in Python.

* Free software: GPLv3 license
* Documentation: http://pysis.readthedocs.org.


How to install
--------------

At the command line::

    $ easy_install pysis

Or, if you have virtualenvwrapper installed::

    $ mkvirtualenv pysis
    $ pip install pysis


Dependencies
~~~~~~~~~~~~

For working with ISIS commands, you must firts have `USGS ISIS 3`_ installed on
your machine. See the ISIS 3 `installation guide`_ for further instructions.
Remember to set your environmental variables (see step 4 of USGS ISIS guide) so
Pysis knows where your installation is.


Quickstart Guide
----------------

How to write ISIS 3 code in python using Pysis.

Using ISIS 3 at the command line you might want to run the following basic
commands (examples for the MDIS camera on the MESSENGER mission)::

    mdis2isis from=filename.IMG to=filename.cub
    spiceinit from=filename.cub
    mdiscal from=filename.cub to=filename.cal.cub

using Pysis the syntax is::

    from pysis.isis import mdis2isis, spiceinit, mdiscal
    from pysis.util import file_variations

    def calibrate_mids(img_name):
        (cub_name, cal_name) = file_variations(img_name, ['.cub', '.cal.cub'])

        mdis2isis(from_=img_name, to=cub_name)
        spiceinit(from_=cub_name)
        mdiscal(from_=cub_name, to=cal_name)

You will notice that we use the keyword `from_` when we call a command  because
`from` is a reserved word in python.


Numerical and String Arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here is an example of the maptemplate and cam2map commands in Pysis::

    from pysis import isis

    isis.maptemplate(map='MDIS_eqr.map', projection='equirectangular',
                     clon=0.0, clat=0.0, resopt='mpp', resolution=1000,
                     rngopt='user', minlat=-10.0, maxlat=10.0, minlon=-10.0,
                     maxlon=10.0)

    isis.cam2map(from_=cal_name, to=proj_name, pixres='map',
                 map='MDIS_eqr.map',defaultrange='map')


Getting values from ISIS commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pysis commands will return the command's STDOUT as a byte string. If the command
returns a nonzero exit code, a `ProcessError` will be thrown. This example
command uses `getkey` to receive values from the label of an ISIS cube::

    from pysis.isis import getkey

    value = getkey(from_='W1467351325_4.map.cal.cub',
                   keyword='minimumringradius', grp='mapping')


Multiprocessing Isis Commands with IsisPool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pysis has built-in support to make multiprocessing isis commands simple. To run
the above MDIS calibration script for multiple images in multiple processes we
could rewrite the function as so::

    from pysis import IsisPool
    from pysis.util import ImageName

    def calibrate_mdis(images):
        images = [ImageName(filename) for filename in images]

        with IsisPool() as isis_pool:
            for filename in images:
                isis_pool.mdis2isis(from_=filename.IMG, to=filename.cub)

        with IsisPool() as isis_pool:
            for filename in images:
                isis_pool.spiceinit(from_=filename.cub)

        with IsisPool() as isis_pool:
            for filename in images:
                isis_pool.mdiscal(from_=filename.cub, to=filename.cal.cub)

When using IsisPool we can't determine which order commands will be executed in
so we much run each command for all the files as a group before moving to the
next command and creating a new IsisPool.


.. _USGS ISIS 3: http://isis.astrogeology.usgs.gov/
.. _installation guide: http://isis.astrogeology.usgs.gov/documents/InstallGuide/
