README.rst

Pysis

Toolkit for using USGS Isis in Python.

• Free software: BSD 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')

Catching ProcessingErrors

Pysis supports catching ISIS processing errors like so:

from pysis.exceptions import ProcessError
from pysis.isis import hi2sis

try:
    hi2isis(from_=filein, to=fileout)
except ProcessError as e:
    print("STDOUT:", e.stdout)
    print("STDERR:", e.stderr)

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.