ISIS 3 Documentation

Installing ISIS

Downloading and installing ISIS 3

Home

Overview

Operating System Requirements

ISIS runs on many UNIX variants including:

Ubuntu
RHEL
Debian
Fedora
MacOSX

It does not run on MS Windows.

Hardware Requirements

ISIS has fairly minimal requirements depending on your needs:

64-bit x86 processors (more cores is better)
2 GB memory (more memory is better)
10 GB to 180GB disk storage for ISIS installation
10 GB to many TB disk storage for processing images
Quality graphics card (one that support two monitors can be useful)

Mission Requirements

ISIS supports many planetary missions; in fact, over 40 different instruments including some flown as early as the 1960s. Ancillary data is required to process images from these instruments. For example, translation definition files to help convert from PDS format to ISIS cubes, dark current and flat file images are used for radiometric calibration, and large quantities of SPICE files (spacecraft pointing and position) for map projecting images. If you plan to work with data from all missions then the download will require about 180 GB for all the ancillary data. However, most of this volume is taken up by SPICE files. We have a SPICE Web service that can be used in lieu of downloading all of the SPICE files which can reduce the download size to 10 GB. When downloading ISIS you will have the option of choosing which mission data to acquire as well as if you only want the translation and calibration files and not SPICE files.

DTM Requirements

A strength of ISIS lies in it capabilities for planetary cartography. The image orthorectification process is improved if a digital terrain model is used (DTM). The DTMs can be quite large and take time to download. They exist for many planetary bodies (e.g., Moon, Mars, etc). Therefore there are options for selecting which DTMs to download if you are only working with a particular target body.

Installation

Recommended Installation Process

ISIS 3 now features a downloadable Java-based installer. The installer provides user options for chosing which mission packages and target DEMS (e.g. Mars, Moon) to download. It also includes the sizes of the packages. During the installation process, you can chose to use the ISIS SPICE web service which will eliminate the need to download most of the SPICE data for a mission.

To run the installer, download the isisInstall.sh Bashscript from the link below and execute it. This script will automatically fetch the most recent version of the installer and launch it. Depending on your browser, you may need to right-click and select "Save Link As..." to download:

          Installation Script

After downloading the script, open a terminal in the directory where the script was installed. Give the installation script executable permissions and run it by typing the following:

            chmod +x isisInstall.sh
            ./isisInstall.sh

For additional options and help, give the script the -h option:

            ./isisInstall.sh -h

This script has been written with the goal of never needing to be updated. However, after downloading and setting $ISISROOT, the latest version of the installation script can be obtained at the following location on your local machine:

            $ISISROOT/src/docsys/documents/InstallGuide/assets/isisInstall.sh

Alternate Installation Process

If you are familar with the UNIX rsync command and prefer to use the old installation information follow this link: Rsync Installation

FAQs

Cannot connect to the rsync server

This is one of the biggest issues with downloading ISIS. Most problems stem from a firewall restriction on the user's side. USGS has opened the rsync port to allow access to our server. Your institution likely has a firewall and may not allow the access to our rsync server. Start by making sure you can connect to our rsync server. Type the following command:

            rsync isisdist.wr.usgs.gov::

            or

            rsync isisdist.astrogeology.usgs.gov::

This should list the packages available for download. If you do not receive this list then 1) either both of our servers are down or 2) your firewall does not allow access. In the former case please post a message on our ISIS support board. In the later case, see you local system administrator.

You can also try an alternative port number that we have setup (port 80). This is the standard http port which is open through most firewalls. However, some institutes have appliances that examine this traffic and if it doesn't appear to look like web content disconnects or is so slow the download would take forever.

Example use of port 80:

rsync -azv --delete --partial --port=80 isisdist.astrogeology.usgs.gov::x86-64_linux_RHEL6/isis .

If you are still running into problems you can try a different network path. For example, your home network to see if you can make connections to our rsync server.

How do I know if the rsync commands were successful

Unfortunately rsync sometimes hangs or does not complete because of dropped network connections. The drops can happen on your end, our end, or anywhere in between. Keep rerunning rsync until the command completes.

How do I get updates to ISIS

Just rerun the the rsync commands or GUI installer (which uses rsync) again. Rsync only acquires files that have changed or do not exist in you installation. The update process will typically be much faster than the original download.

How often do you update ISIS

We update our mission data areas often (sometime nightly) as new SPICE files are provided by the active missions. Our binaries (application programs) are updated on a quarterly schedule.

How do I install ISIS 2

If you are looking for ISIS 2, please refer to the ISIS 2 Installation Guide for instructions on downloading and installing ISIS 2.

ISIS 3 and ISIS 2 will have collisions of executable names (e.g., pds2isis exists in both systems). It is best to remove initializations of ISIS 2 from your local startup file (e.g., .cshrc) otherwise you may get unpredictable results.

When will a Windows version be available

Currently we have limited software development staff to support and modify ISIS, which implies directly running on a native Windows environment is not something that will happen in the near future.

What operating systems have been dropped

As operating systems and hardware age security flaws are no longer patched and new APIs are not upgraded, which stunts the growth of ISIS on those systems. Therefore we no longer build ISIS on the following platforms:

                 Linux SUSE 9.X, 10.X, 11.X, SLES 11
                 RedHat Enterprise 3, 4, 5
                 Mac OSX with the Power PC processor
                 Mac OSX 10.4, 10.5

I just can not get ISIS installed. What can I do

If you encounter any problems we will be monitoring our discussion board daily and will respond to any questions as best we can. Other people have posted problems and may have similar issues to you.

ISIS Support Center

Manual Installation

Creating a Download Directory

We suggest you install ISIS 3 in a work area. Change your current working directory to where you want ISIS 3 installed and create a directory named isis3. The rsync commands in the next step will place all of ISIS and the SPICE kernels under this directory. Example:

        $ cd /work1
        $ mkdir isis3
        $ cd isis3

Warning: You must be in the correct directory as shown above, and you must type the below rsync commands correctly. If you do not you could remove files not associated with ISIS. That is ... you could remove personal files on your computer. Please research and understand the rsync command, especially the --delete option.

Choosing an Rsync Server

We are distributing ISIS 3 using two rsync servers. If the "rsync" command is is not available on your system please see your system administrator. To download ISIS 3 follow the example for your hardware and operating system combination. Make sure to include the period "." at the end of the "rsync" commands - if you don't, you will only get a list of available downloads from the rsync server.

We have two rsync servers and suggest using the first server as it is a much faster connection.

100Mbit/sec - isisdist.astrogeology.usgs.gov
10Mbit/sec - isisdist.wr.usgs.gov

All of the example commands below use the faster server name. You can use the slower server name if you need to through simple substitution.

Downloading the ISIS Binaries (Required)

Choose the rsync command for your operating system. Don't forget to type the "space period" at the end of the rsync command line or you will only get a listing of the files.

        
        Example for MacOSX 10.6 64-bit Intel compatible systems:
        
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::x86-64_darwin_OSX10.6/isis .

        
        Example for MacOSX 10.8 64-bit Intel compatible systems:
        
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::x86-64_darwin_OSX10.8/isis .

        
        Example for Fedora 18 Linux x86 64-bit Intel compatible systems:
        
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::x86-64_linux_FEDORA/isis .

        
        Example for Ubuntu 12.04 Linux x86 64-bit Intel compatible systems:
        
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::x86-64_linux_UBUNTU/isis .

        
        Example for Debian 7.0 Linux x86 64-bit Intel compatible systems:
        
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::x86-64_linux_DEBIAN/isis .

        
        Example for RHEL 6.5 Linux x86 64-bit Intel compatible systems:
        
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::x86-64_linux_RHEL6/isis .

Full Data Download

If you have the disk space and network speed you may want to download all of the ISIS data areas which includes all missions supported by ISIS. This takes over 130 GB of disk space!! If you only have a 10 Mbps network connection it will take nearly two days to download. If you want to acquire only certain mission data click here. To download all ISIS 3 data files continue reading.

Remember to use this followng command from the same directory you ran the previous rsync command. In the example it was "/work1/isis3".

      rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data .

Note: The above command downloads all ISIS data including the required base data area and all of the optional mission data areas. After completing this step skip to the Unix Environment Setup. If you chose not to download everything at once then continue below.

Partial Download of ISIS 3 Base Data (Required)

The base data area is separate from the source code. This data area is crucial to ISIS 3 and must be downloaded.

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/base data/

Partial Download of Mission Specific Data

There are many missions supported by ISIS. If you are only working with a few missions then you should download only those specific data areas. One way you can save time and space is to not download the SPICE data for the mission you need. If chose to do so read the next section about the SPICE Web Service that provides instructions for excluding the SPICE kernels. Otherwise jump to the mission specific sections.

ISIS SPICE Web Service

ISIS can now use a service to retrieve the SPICE data for all instruments ISIS supports via the internet. To use this service instead of your local SPICE data, click the WEB check box in the spiceinit program GUI or type spiceinit web=yes at the command line. Using the ISIS SPICE Web Service will significantly reduce the size of the downloads from our data area. If you want to use this new service, without having to download all the SPICE data, add the following argument to the mission-specific rsync command:

            --exclude='kernels'

For example: rsync -azv --exclude='kernels' --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/cassini data/

WARNING: Some missions do not currently support calibration when using the SPICE Web Service exclusively: these include LRO, MRO, Viking, MGS, and MER. These calibration programs are lronaccal, lrowaccal, mical, moccal, ctxcal, hical, vikcal, mocevenodd, and mocnoise50. Some programs designed to run an image from ingestion through the mapping phase do not have an option to use the SPICE Web Service. Known programs are thmproc, mocproc, hicalproc, and mdisproc.

Apollo Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/apollo15 data/
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/apollo16 data/
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/apollo17 data/

Cassini Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/cassini data/

Chan1 Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/chan1 data/

Clementine Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/clementine1 data/

Dawn Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/dawn data/

Galileo Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/galileo data/

Ideal Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/ideal data/

Lunar Orbiter Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/lo data/

Lunar Reconnaissance Orbiter Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/lro data/

Mars Exploration Rover Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/mer data/

Mariner10 Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/mariner10 data/

Messenger Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/messenger data/

Mars Express Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/mex data/

Mars Global Surveyor Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/mgs data/

Mars Reconnaissance Orbiter Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/mro data/

Mars Odyssey Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/odyssey data/

New Horizons Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/newhorizons data/

Rolo Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/rolo data/

Smart1 Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/smart1 data/

Viking Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/viking1 data/
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/viking2 data/

Voyager Mission (kernels can be excluded):

        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/voyager1 data/
        rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/voyager2 data/

Example ISIS 3 Download

This is an example of downloading ISIS onto a RedHat 6 system using tcsh as your shell.

          $ cd /work
          $ mkdir isis3
          $ cd isis3
          $ rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::x86-64_linux_RHEL6/isis .
          $ rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/base data/
          **now pick your missions without kernels**
          **example MRO**
          $ rsync -azv --delete --partial --exclude='kernels' isisdist.astrogeology.usgs.gov::isis3data/data/mro data/
          **example LRO**
          $ rsync -azv --delete --partial --exclude='kernels' isisdist.astrogeology.usgs.gov::isis3data/data/lro data/
          for csh users edit your .cshrc and add
          setenv ISISROOT /work/isis3/isis
          source $ISISROOT/scripts/isis3Startup.csh

UNIX Environment Setup

ISIS 3 needs to know where all its pieces are located. We use an environment variable called "ISISROOT" to do this. Unix commands must be put into your startup shell scripts. Assuming you installed ISIS in the directory /work1/isis3 add the following commands to your startup script:

for C shells:

        setenv ISISROOT /work1/isis3/isis

for Bourne shells:

        ISISROOT=/work1/isis3/isis
        export ISISROOT

Run the startup script for ISIS. This script assumes you installed the ISIS 3 data area in the same directory you installed the ISIS 3 package. If you did not do this, you will need to modify the script to meet your needs.