Welcome to planetaryimage’s documentation!

Contents:

planetaryimage - Open PDS and Isis CubeFiles in Python

https://travis-ci.org/planetarypy/planetaryimage.svg?branch=master

NOTE This is Alpha quality software that is being actively developed, use at your own risk.

Planetary image parser

Features

  • Reads in PDS Images as NumPy arrays.
    • Supports GZIP and BZ2 compressed PDS Images.
    • Supports writing out PDS3 images.
  • Reads in Isis Cube Files as NumPy arrays.

Check out a few simple examples of opening and viewing PDS and Isis CubeFiles in an IPython notebook.

Quickstart

The example below will walk you through setting up a Python virtual environment and installing the necessary software as well as a few handy extras. It then downloads a sample Pancam PDS image, opens and displays that image in your web browser in an IPython Notebook. The example assumes you have Python, virtualenv, and pip installed on your system. If you don’t, don’t know what this means or aren’t thrilled by the opportunity to learn what this means, this software may be a little too immature for you to use at this point.

Create and activate a virtual environment:

virtualenv venv
source venv/bin/activate

Upgrade pip, then pip install the package and IPython notebook and matplotlib to help display the image:

pip install -U pip
pip install planetaryimage matplotlib ipython[notebook]

This quick example will show how to open and display a Pancam PDS image using this module. First, grab a sample image:

wget http://pds-imaging.jpl.nasa.gov/data/mer/opportunity/mer1po_0xxx/data/sol2840/edr/1p380322615effbr43p2443l1m1.img

Now run python in an IPython Notebook (a browser window should pop up after entering the following command):

$ ipython notebook

Create a new notebook in your web browser and then paste the following code into a cell and execute it by pressing Shift+ENTER. This will load and display the image:

%matplotlib inline
import matplotlib.pyplot as plt
from planetaryimage import PDS3Image
image = PDS3Image.open('1p380322615effbr43p2443l1m1.img')
plt.imshow(image.image, cmap='gray')

See Usage for full documentation on how to use planetaryiamge.

Installation

At the command line:

$ easy_install planetaryimage

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv planetaryimage
$ pip install planetaryimage

Usage

Quick Explanation

The example below shows how to use planetaryimage‘s PDS3Image class to open a PDS image, inspect it’s label and display the image data:

>>> from planetaryimage import PDS3Image
>>> testfile = 'tests/mission_data/2p129641989eth0361p2600r8m1.img'
>>> image = PDS3Image.open(testfile)
>>> print(image.record_bytes)               # access attribute
128
>>> print(image.label['FILE_RECORDS'])      # access label
332
>>> plt.imshow(image.image, cmap='gray')  # display image

Examples

Setup:

>>> %matplotlib inline
>>> from glob import glob
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> import matplotlib.image as mpimg
>>> from planetaryimage import PDS3Image, CubeFile

Gather the Images:

>>> pdsfiles = glob("*.*")
>>> images = []
>>> for pdsfile in pdsfiles:
       try:
           images.append(PDS3Image.open(pdsfile))
           print pdsfile
       except:
           pass
>>> for n, image in enumerate(images):
       print n, image
0 1p190678905erp64kcp2600l8c1.img
1 mk19s259.img
2 m0002320.imq
3 mg00n217.sgr
4 h2225_0000_dt4.img
5 0044ML0205000000E1_DXXX.img

One can use the try statement in-case any of the images you have are not compatible with PDS3image. See Suppored Planetary Images List to know what image types are compatible. The for loop will show what index number to use in future use of the image.

To see the information about each image:

>>> for i in images:
       print i.data.dtype, i.data.shape, i.shape
>i2 (1, 1024, 32) (1, 1024, 32)
uint8 (1, 1331, 1328) (1, 1331, 1328)
uint8 (1, 1600, 384) (1, 1600, 384)
uint8 (1, 960, 964) (1, 960, 964)
>i2 (1, 10200, 1658) (1, 10200, 1658)
uint8 (3, 1200, 1648) (3, 1200, 1648)

To display a three band, color, image:

>>> caltarget = images[5]
>>> plt.imshow(caltarget.image)
<matplotlib.image.AxesImage at 0x10a13c250>
_images/caltarget_1.png

It is important to look at the first number in i.shape (See attributes) or the value from i.bands. If this number is 3, then the above example works, otherwise, you should use cmap=='gray' parameter like in the below example.

To display a single band, grayscale, image:

>>> image1 = images[1]
>>> plt.imshow(image1.image, cmap='gray')
<matplotlib.image.AxesImage at 0x125817a50>
_images/output_3_1.png

The cmap keyword argument defines which colormap a grayscale image should be displayed with. In the case where i.bands is 3, it means the image is an RGB color image which does not need a colormap to be displayed properly. If i.bands is 1, then the image is grayscale and imshow would use its default colormap, which is not grayscale.

To see a subframe of an image:

>>> plt.imshow(image1.image[370:620, 0:250], cmap = 'gray')
<matplotlib.image.AxesImage at 0x11c014450>
_images/output_4_1.png

To see the different bands of a colored image:

>>> plt.imshow(np.hstack([
       mcam1.image[700:1100, 600:1000, 0],
       mcam1.image[700:1100, 600:1000, 1],
       mcam1.image[700:1100, 600:1000, 2],
   ]), cmap='gray')
<matplotlib.image.AxesImage at 0x10fccd210>
_images/caltarget_2.png

To save an image as a .png file for later viewing:

>>> crater = image1.image[370:620, 0:250]
>>> plt.imsave('crater.png', crater, cmap='gray')

To do some image processing:

>>> plt.hist(image1.image.flatten(), 2000)
(array([ 2.,  0.,  0., ...,  0.,  0.,  1.]),
array([  32.   ,   32.036,   32.072, ...,  175.928,  175.964,  176.   ]),
<a list of 4000 Patch objects>)
_images/output_8_1.png

Using this Histogram can produce a clearer picture:

>>> plt.imshow(image1.image, cmap='gray', vmin=115, vmax=135)
<matplotlib.image.AxesImage at 0x1397a2790>
_images/output_9_1.png

See documentation for plt.imshow and Image tutorial for pyplot to see more methods of image processing.

You can also use planetaryimage to process Isis Cube Files:

>>> from planetaryimage import CubeFile
>>> isisimage = CubeFile.open("tests/data/pattern.cub")
>>> isisimage.data.dtype, isisimage.data.shape, isisimage.shape
(dtype('<f4'), (90, 90), (1, 90, 90))
>>> plt.imshow(isisimage.image, cmap='gray')
<matplotlib.image.AxesImage at 0x114010610>
_images/Isisimage.png

Supported Planetary Image Types

Table of Contents

General Information

Structure

  • Mission - Launch Year - Destination
    • Camera (Acronym)
      • Volume - Description
        • Symbol Image: Link_to_file
        • Label: Link_to_file
      • Volume - Description
        • Symbol Image: Link_to_file
        • Label: Link_to_file

  • Mission - Launch Year - Destination

This list is in chronological order, based on launch date, with the most recent mission at the top of the list and older missions at the bottom.

Symbols

  • good = image works
  • bad = image does not work
  • none = image has not been tested
  • nodisp = planetaryimage can open the file but plt.imshow does not work

Editing

If editing this document, to mark an image as good with a green square (good) add |good|, mark bad with a red square (bad) add |bad|, mark that imshow does not work with a blue square (nodisp) add |nodisp| and unknown/not tested with a white sqaure (none) add |none| before “Image” like so:

|good| Image: image.img
|bad| Image: image.img
|none| Image: image.img
|nodisp| Image: image.img

See Usage for documentation on how to open the images.

PDS List

  • Mars Global Surveyor (MGS) - 1996 - Mars

    • Mars Orbiter Camera (MOC)

      • mgsc_0005 - Decompressed Standard Data Products

      • mgsc_1006 - Standard Data Records

      • RDRs

        • This data set is being prepared for peer review; it has not been reviewed by PDS and is NOT PDS-compliant and is NOT considered to be Certified Data.

  • Viking Lander - 1975 - Mars

    • Experiment Data Records

    • Processed Images

      • The following are NOT PDS formatted volumes. They were produced by the Science Digital Data Preservation Task by copying data directly off of old, decaying tape media onto more stable CD-WO media. They have not been otherwise reformatted.

      • vl_2111 - Viking Lander 1

      • vl_2112 Viking Lander 2

  • Mariner 10 - 1973 - Mercury and Venus

    • Experiment Data Records

      • “The following are NOT PDS formatted volumes. They were produced by the Science Digital Data Preservation Task by copying data directly from old, decaying tape media onto more stable CD-WO media, then transferred online. They have not been otherwise reformatted.”

      • mvm_0013

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/planetarypy/planetaryimage/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation

planetaryimage could always use more documentation, whether as part of the official planetaryimage docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/planetarypy/planetaryimage/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up planetaryimage for local development.

  1. Fork the planetaryimage repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/planetaryimage.git

  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv planetaryimage
$ cd planetaryimage/
$ pip install -r requirements.txt

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ make lint
$ make test
$ make test-all

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4, and 3.5. Check https://travis-ci.org/planetarypy/planetaryimage/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

py.test tests/test_planetaryimage

Credits

Development Lead

Contributors

History

0.5.0 (2016-04-13)

  • Added ability to generate PDS3Image objects from NumPy arrays.

0.4.1 (2016-03-26)

  • Fixes to saving PDS3 images files after modification of the data.

0.4.0 (2016-03-05)

  • Added basic support for saving PDS3 images.

0.3.0 (2015-09-29)

  • Added support for opening PDS images that are gzip or bz2 compressed.

0.2.0 (2015-06-17)

  • Improved support for float type PDS3 image types. Many types still not supported.

0.1.0 (2015-06-03)

  • First release on PyPI. Basic PDS and Isis Cube File parsing works.

Indices and tables