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
>>> import matplotlib.pyplot as plt
>>> 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))
...    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

PlanetaryImage uses three main classes: PlanetaryImage, PDS3Image, and CubeFile. PlanetaryImage is the base class for PDS3Image and CubeFile and can be inherited for other image readers. PDS3Image and CubeFile are used to read images. See Usage to see more in depth examples using PDS3Image and CubeFile.

PlanetaryImage

class planetaryimage.image.PlanetaryImage(stream_string_or_array, filename=None, compression=None)[source]

A generic image reader. Parent object for PDS3Image and CubeFile

Parameters:

stream

file object to read as an image file

filename : string

an optional filename to attach to the object

compression : string

an optional string that indicate the compression type ‘bz2’ or ‘gz’

Examples

>>> from planetaryimage import PDS3Image
>>> testfile = 'tests/mission_data/2p129641989eth0361p2600r8m1.img'
>>> image = PDS3Image.open(testfile)
>>> # Examples of attributes
>>> image.bands
1
>>> image.lines
64
>>> image.samples
64
>>> str(image.format)
'BAND_SEQUENTIAL'
>>> image.data_filename
>>> image.dtype
dtype('>i2')
>>> image.start_byte
34304
>>> image.shape
(1, 64, 64)
>>> image.size
4096

See https://planetaryimage.readthedocs.io/en/latest/usage.html to see how to open images to view them and make manipulations.

Attributes

compression (string) Compression type (i.e. ‘gz’, ‘bz2’, or None).
data (numpy array) A numpy array representing the image.
filename (string) The filename given.
label (pvl module) The image’s label in dictionary form.
bands

Number of image bands.

data = None

A numpy array representing the image

data_filename

Return detached filename else None.

dtype

Pixel data type.

filename = None

The filename if given, otherwise none.

format

Image format.

image

An Image like array of self.data convenient for image processing tasks

  • 2D array for single band, grayscale image data
  • 3D array for three band, RGB image data

Enables working with self.data as if it were a PIL image.

See https://planetaryimage.readthedocs.io/en/latest/usage.html to see how to open images to view them and make manipulations.

label = None

The parsed label header in dictionary form.

lines

Number of lines per band.

classmethod open(filename)[source]

Read an image file from disk

Parameters:

filename : string

Name of file to read as an image file. This file may be gzip (.gz) or bzip2 (.bz2) compressed.
samples

Number of samples per line.

shape

Tuple of images bands, lines and samples.

size

Total number of pixels

start_byte

Index of the start of the image data (zero indexed).

PDS3Image

class planetaryimage.pds3image.PDS3Image(stream_string_or_array, filename=None, compression=None)[source]

Bases: planetaryimage.image.PlanetaryImage

A PDS3 image reader.

Examples

>>> from planetaryimage import PDS3Image
>>> testfile = 'tests/mission_data/2p129641989eth0361p2600r8m1.img'
>>> image = PDS3Image.open(testfile)
>>> # Examples of PDS3Image Attributes
>>> image.dtype
dtype('>i2')
>>> image.record_bytes
128
>>> image.data_filename
dtype

Pixel data type.

record_bytes

Number of bytes for fixed length records.

CubeFile

class planetaryimage.cubefile.CubeFile(stream_string_or_array, filename=None, compression=None)[source]

Bases: planetaryimage.image.PlanetaryImage

A Isis Cube file reader.

Examples

>>> from planetaryimage import CubeFile
>>> image = CubeFile.open('tests/data/pattern.cub')
>>> # Examples of CubeFile Attributes
>>> image.base
0.0
>>> image.multiplier
1.0
>>> image.specials['His']
-3.4028233e+38
>>> image.tile_lines
128
>>> image.tile_samples
128
>>> image.tile_shape
(128, 128)
apply_numpy_specials(copy=True)[source]

Convert isis special pixel values to numpy special pixel values.

Isis Numpy
Null nan
Lrs -inf
Lis -inf
His inf
Hrs inf
Parameters:

copy : bool [True]

Whether to apply the new special values to a copy of the pixel data and leave the original unaffected
Returns:

Numpy Array

A numpy array with special values converted to numpy’s nan, inf, and -inf
apply_scaling(copy=True)[source]

Scale pixel values to there true DN.

Parameters:

copy: bool [True]

Whether to apply the scaling to a copy of the pixel data and leave the original unaffected
Returns:

Numpy Array

A scaled version of the pixel data
base

An additive factor by which to offset pixel DN.

data_filename

Return detached filename else None.

get_image_array()[source]

Create an array for use in making an image.

Creates a linear stretch of the image and scales it to between 0 and 255. Null, Lis and Lrs pixels are set to 0. His and Hrs pixels are set to 255.

Usage:

from planetaryimage import CubeFile
from PIL import Image

# Read in the image and create the image data
image = CubeFile.open('test.cub')
data = image.get_image_array()

# Save the first band to a new file
Image.fromarray(data[0]).save('test.png')
Returns:A uint8 array of pixel values.
multiplier

A multiplicative factor by which to scale pixel DN.

specials

Return the special pixel values

specials_mask()[source]

Create a pixel map for special pixels.

Returns:

An array where the value is False if the pixel is special

and True otherwise
tile_lines

Number of lines per tile.

tile_samples

Number of samples per tile.

tile_shape

Shape of tiles.

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.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