Introduction to Isis

From Isis Workshop

[edit] What is Isis?

Isis is an image processing software package. The focus of the software is to manipulate imagery collected by current and past NASA planetary missions sent to Mars, Jupiter, Saturn, and other solar system bodies.

If you're familiar with commercial image processing packages (for example: Adobe Photoshop, PaintShop Pro, Envi, or ERDAS Imagine) you'll recognize many of the standard image processing operations Isis is capable of, such as contrast stretch, image algebra, filters, and statistical analysis. Mars - Valles Marineris

This famous mosaic of the Valles Marineris hemisphere of Mars was created using Isis. The mosaic is composed of 102 Viking Orbiter images of Mars, and is projected into point perspective, a view similar to that which one would see from a spacecraft at a distance of 2500 kilometers from the surface of the planet.

This famous mosaic of the Valles Marineris hemisphere of Mars was created using Isis. The mosaic is composed of 102 Viking Orbiter images of Mars, and is projected into point perspective, a view similar to that which one would see from a spacecraft at a distance of 2500 kilometers from the surface of the planet.

However, the real power of Isis is its unique capabilities for processing data from NASA spacecraft missions such as Voyager, Viking, Galileo, Mars Global Surveyor, and Mars Odyssey. Isis is able to import raw mission data into a usable geospatial image product, and has tools for digital mosaicking of adjacent images, photometric modeling and normalization, removal of systematic noise patterns, overlaying graticules, and numerous other cartographic and scientific analysis functions.

The following are just a few examples of how those of us at the USGS Astrogeology Research Program have used Isis in our work (links open in a new window):

• Global mosaics: mosaicking hundreds or thousands of images collected by space exploration missions to create seamless, cartographically accurate, global image maps for use by the planetary science community for research and mapping. See our Map-a-Planet site to view these products.
• Geologic Mapping: we create accurate base image maps for geologists to use in creating geologic maps. See our Planetary Geologic Mapping Program for more information about this work.
• Scientific Research: Using Isis to mosaic images of a region of interest to create a scientifically accurate image product, and analyzing the imagery based on spectral, textural, or other attributes. See the following Science Magazine abstract for examples of images from the Mars Exploration Rover Mission Microscopic Image that were processed and analyzed using Isis as part of the scientific research resulting from the mission: Textures of the Soils and Rocks at Gusev Crater from Spirit's Microscopic Imager.

[edit] Getting Started

To run Isis 3 applications, two things must happen. First, the Isis3 software has to be installed. The installation procedure will change from time to time so please see the Isis Download and Installation Guide for the most recent instructions. Second, your environment must be setup so you can execute Isis3 applications. To set your environment up correctly you should first find out where Isis 3 has been installed. The default location is /usgs/pkgs/isis3/isis.

The setup process will modify your environment:

• The environment variables PATH and LD_LIBRARY_PATH will be modified to include the Isis 3 directories
• If not already defined, the environment variable ISISROOT will be set to its default value

The setup for Isis3 on a "Unix" type system depends on which shell you work under. Follow the instructions below for your shell.

[edit] Setup for Linux/Unix

C Shell

If you are using C Shell (i.e. csh) or some variant (such as tcsh):

1. Step 1: If Isis3 is installed in the default location (/usgs/pkgs/isis3/isis) go to step 2. If Isis3 is not installed in the default location you need to set the environment variable ISISROOT. On the command line use setenv to set the ISISROOT variable to the proper location (replace the x's and y's with the complete path to where Isis 3 is installed):

  > setenv ISISROOT /xxxxx/yyyyy/isis

2. Step 2: Use the source command to execute the Isis 3 startup script:

  > source /xxxxx/yyyyy/isis/scripts/isis3Startup.csh isis3

If you want Isis 3 to be initialized when you login, place the above commands in your .cshrc file.

Bourne Shell

If you are using the Bourne shell (i.e. sh) or one of its variants (bash, ksh):

1. Step 1: If Isis3 is installed in the default location (/usgs/pkgs/isis3/isis) go to step 2. If Isis3 is not installed in the default location you need to set the environment variable ISISROOT. On the command line set ISISROOT to the proper location and export the variable using:

  > ISISROOT=/xxxxx/yyyyy/isis
  > export ISISROOT

2. Step 2: Use the .(dot) command to execute the Isis 3 startup script:

  > . /xxxxx/yyyyy/isis/scripts/isis3Startup.sh isis3

If you want Isis 3 to be initialized when you login, place the above commands in your .profile file.

For those of you who need to work in both version 2 and 3 of Isis, we suggest you keep them separate by having different terminal windows for each instance. For example, have one xterm with the environment set for version 2 and another set for version 3.

[edit] Getting Help

The Isis Support Center is our online knowledge base, bug tracking, announcements, and user support center in the form of an online discussion board. If you need help, want to get the latest news, find out about the status of a bug (i.e. software glitch), or just want to learn more and interact with other Isis users, the Isis Support Center is the place to go! The Isis Support Center provides access to help on Isis 3, Isis 2, and Planetary GIS.

Here, you can search for posts from other Isis users and the Isis Support Team -- a post about your subject may already have been answered. If you can't find what you are looking for, you can register for a user name and then post your questions to the forum. Please read the policies before registering.

When you post to the forum it is important that you:

• Post to the correct board. Versions 2 and 3 have separate categories
• Start a new topic when the subject changes
• Give complete details about your problem. Include as much information as possible. Consider the following:
  • Include the command line you used to run a program
  • Include a screen shot of the GUI with the parameters filled in
  • Include the operating system and version number you are using
  • Include the full text of any error messages
  • Include the relevant section of the print.prt file
  • If possible supply a URL to the input and output files
• Check for replies to your post often. Your answer or a request for more information may be posted at anytime. One way to do this is to check the Notify me when a reply is posted checkbox before you submit your post, and you will be sent an e-mail when someone posts a reply.

[edit] User Interface for Isis

Isis 3 programs fall into two main groups interactive and non-interactive. Interactive programs allow you to observe the results of actions you take almost immediately. The main interactive program is qview, the image display program for Isis. However, most programs in Isis 3 fall into the non-interactive group. These programs process the data you supply, usually one or more image files, and write the results to a new file. Some examples are lowpass, ratio and moc2isis. At this point we will concentrate on the user interface for non-interactive programs because their interfaces are all similar. Interactive programs are somewhat unique, so they each have their own documentation.

qview, Isis's image display application, is an interactive application

All Isis 3 programs are launched via the command line. The command line refers to the text typed at the prompt of a terminal window such as xterm, console, or putty, or in a script like cshell, or perl. Isis 3 programs are started by typing the name of the program followed by any arguments. All arguments must be separated from each other by at least one space.

Command line arguments are broken into two categories, reserved, and parameter. Reserved arguments always begin with a dash (-) and change major things about how the program runs while parameter arguments supply data to the application and control how it processes that input data to create output data.

[edit] Reserved Command Line Arguments

Reserved arguments all begin with a dash (-), and are not sensitive to case (i.e., -help is the same as -HElp). A list of basic reserved arguments includes:

• -webhelp Launch a web browser showing the Isis help page for that program. All other arguments will be ignored.
• -help Display a list of the program's parameters showing their default values. For example:

     > equalizer -help
     FROMLIST = Null
     TO       = Null
     HOLDLIST = Null
     APPLY    = TRUE
     ADJUST   = (*BOTH, CONTRAST, BRIGHTNESS)
     CMODE    = (*SD, PCA)
     MINCOUNT = 1000
     WEIGHT   = FALSE

• -last Run the program using the same parameter arguments from the most recent time the program was run. This does not include any reserved arguments.
• -restore=filename Run the program using the arguments from the file specified in filename.

Reserved arguments come in two forms, solitary keyword or keyword value pair. Solitary keywords tell the program to perform some special action such as the -help keyword above. Keyword value pairs also tell the program to perform some special action, but use additional information for that action like in the –restore argument above. The keyword and value must be separated from each other with an equals sign (=). The equals sign may have spaces on either or both sides of it.

[edit] Parameter Command Line Arguments

Parameter arguments are always made up of keyword value pairs. The keyword and value are separated by an equals sign just like reserved arguments, but they begin with an alphabetic letter instead of a dash. Parameters control what input data to use, what settings to use to process that input data, and where to put the output data. There are six different types of parameters:

• Cube file names - A cube file name is the location on disk of an Isis cube. It can be either the input to this program or where to place the output. Input cubes, must be the output from some other Isis 3 program. Most programs can process cubes from Isis 2, but some information may be interpreted differently. Output cubes, will always be the location to place processed results from the application. When entering the filename of a cube it is not necessary to enter the .cub extension. It will be added for you if you do not type it.

     from=r0700563_lev1.cub
     to= f431a62

• Data file names - A data file name is the location on disk of a file which is not an Isis cube. This includes input files from missions such as Mars Global Surveyor or Viking, and output files such as that produced by the program stats or isis2std.

     to=myStatistic.dat

• Floating point numbers Floating point numbers are numeric values with a whole part and/or a fractional part. Parameters with this type can be given values like 1.0, 0.7823, 127 or 0.31416E+1

     radius=317.681

• Integers Integer numbers have only a whole part. Parameters of this type can be given values like 0, 2, -18223 or 255.

     lines=1024

• Boolean parameters are used as flags to indicate true or false. The Isis 3 user interface allows true values to be represented by True, T, Yes or Y. False values can be False, F, No or N. Any mixture of upper and lower case letters is allowed. The name of the parameter for boolean's is usually a question such as USEDEM. This should be read as "Do you want the program to use a DEM when it processes the input?"

     CREATESPECIAL=FALSE
     emission=true

• String A string is a simple sequence of printable characters. For example "MARS", "BiLinear" or "The quick brown fox."

     bittype=real

[edit] Application Running Modes

All non-interactive programs can run in one of two modes, text mode (runs without launching a window) or graphical mode (launches a window for providing parameters). Which mode the program runs in depends on what arguments you supplied on the command line. If any parameter arguments are present on the command line, the program will run in text mode unless explicitly overridden using the reserved argument -gui.

lowpass, a non-interactive application running in graphical mode

lowpass, a non-interactive application running in text mode

[edit] Isis Graphical Mode

To run an Isis 3 program in graphical mode, simply type the name of the program followed by the Enter key. The program will display a window that allows you to set parameters for the program, start/stop running the algorithm on the data, observe the current status of the program, and see any logged information.

As mentioned earlier, if there are any parameter arguments on the command line the program will run in text mode. You can override this feature by supplying the -gui reserved argument on the command line. The gui flag refers to the term Graphical User Interface (or, simply GUI, pronounced gooey), and forces the application to run in graphical mode. The program will then load any parameter arguments and launch the program in graphical mode instead of text mode. The following command will launch the lowpass program in graphical mode with the parameters set according to what was on the command line:

>lowpass from=f431a63.cub to=f431a63_lpf3x3.cub lines=3 samples=3 pixels=valid -gui

lowpass, regular graphical mode when run with no parameters, lowpass opens in graphical mode to let you fill in the parameters

lowpass, forced into graphical mode with -gui here, lowpass was run with parameters, but by using the -gui flag, lowpass opens in graphical mode and automatically fills in values for any parameters you passed it on the command line

As you can see the parameter arguments on the command line were used to set the values for the lowpass application, and the -gui reserved argument caused the program to run in graphical mode instead of in text mode.

[edit] Isis Text Mode

For text mode, Isis 3 programs get all their parameters from you via the command line arguments, process the data, and then exit. Programs may or may not show a status message and results on the terminal window. While running, an application that encounters an error will show the error message on the terminal window and then exit. It is then up to you to correct the error and try again.

lowpass, running in text mode: We ran the lowpass application, passing all the parameters along on the command line. Oops! We spelled "samples" wrong, but lowpass gives us a handy error message to let us know what the problem was. We run it again, it shows us its status as it runs, and returns us to the command line prompt when it's finished.

[edit] Using QView to View Cubes

Select Open from the File menu

Select Isis Cubes (images) to open

Two Isis Cubes open in the viewer

Naturally, one of the first things anyone wants to do when they get their hands on image data is look at it! The QView application is the image viewer for Isis. QView has a number of tools to let you zoom in and out, change the contrast, choose color combinations, compare, and otherwise interact with and look at your images. We'll talk about some of these tools in detail later. For now, let's just learn how to open an image in QView.

[edit] Opening an Image in QView

1. Run QView by typing qview on the command line. The QView viewer application window will open.
2. Select Open... from the File menu. A dialog box labeled "Select Isis Cubes to Open" will appear. Images in the native Isis format are called Isis cubes or simply cubes.
   • Find the directory containing your Isis cubes
   • Select one or more to open
   • Click the Open button
3. Your image(s)will appear in the QView window!

[edit] Bonus

Now that you know how to run Isis programs go experiment with some of the basic ones like stats, hist or mirror.

Download the Isis cube linked below - the cube is compressed in a GZIP archive file. Use gunzip to uncompress the cube. The filename of the cube is Intro2isis.cub.gz.

Run each of the following applications, using intro2isis.cub as your input '(FROM)' file. Try running in both the GUI and command line modes. The following links to application documentation open in a new window:

• stats: The stats application computes statistics (such as average, mode, minimum, maximum, etc.) for the pixels in a single band. To choose a band other than the default (band 1), click the ATT (Attributes) button on the GUI and type a different band number.

• hist: The hist application creates a tabular representation of the histogram of a single band in a cube. Like stats, the default band is band 1 and can be changed in the file attributes in the GUI.

• mirror: The mirror application flips a cube from left to right (making an output cube that looks like the mirror-image of the input cube). Make sure your output '(TO)' filename is different than your input '(FROM)' filename!

After running the mirror application, open both the input cube (intro2isis.cub) and output cube in QView to see the results!