Unverified Commit 5c5396b4 authored by Jesse Mapel's avatar Jesse Mapel Committed by GitHub
Browse files

Updated README data area instructions (#3214) 

* Fixed data area instructions in README and some links

* Fixed bold in block quote

* Fixed legacy install guide link

* extra l

* Testing indentation list

* Testing indentation list again

* Testing indentation list code snippet

* Minor wording clean up

* Removed extra number

* Removed duplicate Mars Odyssey entry
parent 0aba9828

README.md

+113 −130
Original line number Diff line number Diff line
@@ -57,7 +57,7 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0 


        conda install -c usgs-astrogeology isis3



6.a If you would like to work with our latest Release Candidate:

    If you would like to work with our latest Release Candidate instead run:



        conda install -c usgs-astrogeology/label/RC isis3
@@ -74,7 +74,7 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0 
        python $CONDA_PREFIX/scripts/isis3VarInit.py --data-dir=[path to data directory]  --test-dir=[path to test data directory]





    Directions for running rsync to download ISIS3 data can be found [here.](#ISIS3DataDownload) Now everytime the isis3 environment is activated, $ISISROOT, $ISIS3DATA, and $ISIS3TESTDATA will be set to the values passed to isis3VarInit.py. This does not happen retroactively, re-activate the isis3 envionment with one of the following commands:

        More information about the ISIS3DATA environment variable and the ISIS3 Data Area can be found [here]("#The-ISIS3-Data-Area"). Now everytime the isis3 environment is activated, $ISISROOT, $ISIS3DATA, and $ISIS3TESTDATA will be set to the values passed to isis3VarInit.py. This does not happen retroactively, re-activate the isis3 envionment with one of the following commands:



        for Anaconda 3.4 and up - conda activate isis3

        prior to Anaconda 3.4 - source activate isis3
@@ -87,7 +87,7 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0 


### Operating System Requirements



ISIS3 runs on many UNIX variants. ISIS does not run natively on MS Windows, although it has been successfully run on Windows 10 using the Windows Subsystem for Linux (WSL). Instructions for doing this can be found [here.](#RunningOnWindows) The UNIX variants ISIS3 has been successfully built on are:

ISIS3 runs on many UNIX variants. ISIS does not run natively on MS Windows, although it has been successfully run on Windows 10 using the Windows Subsystem for Linux (WSL). Instructions for doing this can be found [here](http://planetarygis.blogspot.com/2017/07/isis3-on-windows-10-bash.html). The UNIX variants ISIS3 has been successfully built on are:



-   Ubuntu 18.04 LTS

-   Mac OS X 10.13.6 High Sierra
@@ -118,21 +118,25 @@ To build and compile ISIS3 requires following the instructions listed below, whi 
-   [Building ISIS3 documentation](https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#building-isis3-documentation)

-   [What to do if you encounter any problems](https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#problems)



### Mission Requirements

## The ISIS3 Data Area



ISIS3 supports many planetary missions; in fact, over 40 different instruments including some flown as early as the 1960s. Ancillary data are 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 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 530 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.

### Ancillary Data



### DTM Requirements

Many ISIS3 applications require ancillary data. For example, ingestion applications require translation tables to convert labels, calibration applications require flat files to do flat field correct, and map projection applications require DTMs to accurately compute intersections. Due to its size, this data is stored in a separate directory called the ISIS3 Data Area. Any location can be used for the ISIS3 Data Area, the software simply requires that the ISIS3DATA environment variable is set to its location.



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

### Structure of the ISIS3 Data Area



<span id="ISIS3DataDownload"></span>

Under the root directory of the ISIS3 Data Area pointed to by the ISIS3DATA environment variable are a variety of sub-directories. Each mission supported by ISIS3 has a sub-directory that contains mission specific processing data such as flat files and mission specific SPICE. There are also data areas used by more generic applications. These sub-directories contain everything from templates to test data.



### Size of the ISIS3 Data Area



If you plan to work with data from all missions, then the download will require about 520 GB for all the ancillary data. However, most of this volume is taken up by SPICE files. We have a [Web service](#isis-spice-web-service) that can be used in lieu of downloading all of the SPICE files. This reduces the total download size to about 10 GB.



### Full ISIS3 Data Download



Mission data is hosted on rsync servers and not through conda channels like the ISIS3 distribution. This requires using the rsync command from within a terminal window within your Unix distribution, or from within WSL if running Windows 10. Downloading all mission data requires over 520 GB of disk space. If you want to acquire only certain mission data [click here](#MissionSpecific). To download all ISIS3 data files, continue reading.

The ISIS3 Data Area is hosted on rsync servers and not through conda channels like the ISIS3 binaries. This requires using the rsync command from within a terminal window within your Unix distribution, or from within WSL if running Windows 10.  Downloading all mission data requires over 520 GB of disk space. If you want to acquire only certain mission data [click here](#Mission-Specific-Data-Downloads). To download all ISIS3 data files, continue reading.



To download all ISIS3 data (approximately 520 GB), enter the following commands at the command prompt:

To download all ISIS3 data, enter the following commands in the location where you want to install the ISIS3 Data Area:



    cd $ISIS3DATA

    rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data.
@@ -143,13 +147,14 @@ To download all ISIS3 data (approximately 520 GB), enter the following commands 


### Partial Download of ISIS3 Base Data (Required)



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

The base data area is separate from the source code. This data area is crucial to ISIS3 and must be downloaded. To do that run the following commands:



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

    cd $ISIS3DATA

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



### Partial Download of Mission Specific Data



There are many missions supported by ISIS. If you are only working with a few missions then you can save disk space by downloading only those specific data areas. If you want to limit the download even further, read the next section about the SPICE Web Service. Otherwise [jump](README.md#ApolloMission) to the mission specific sections.

There are many missions supported by ISIS. If you are only working with a few missions then you can save disk space by downloading only those specific data areas. If you want to limit the download even further, read the next section about the SPICE Web Service. Otherwise [jump](#Mission-Specific-Data-Downloads) to the mission specific sections.



### ISIS SPICE Web Service
@@ -157,201 +162,179 @@ ISIS can now use a service to retrieve the SPICE data for all instruments ISIS s 


    --exclude='kernels'



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



<span style="font-size:120%; color:red; font-weight:bold"> WARNING: Some instruments require mission data to be present for radiometric calibration, which may not be supported by the SPICE Web Server exclusively, and some programs that are designed to run an image from ingestion through the mapping phase do not have an option to use the SPICE Web Service. For information specific to an instrument, see the documentation for radiometric callobration programs. </span>



#### 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/





<span id="CassiniMission"></span>



Cassini Mission (kernels can be excluded):



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





<span id="ChandrayaanMission"></span>



Chandrayaan Mission (kernels can be excluded):



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





<span id="ClementineMission"></span>



Clementine Mission (kernels can be excluded):



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





<span id="DawnMission"></span>



Dawn Mission (kernels can be excluded):



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





ExoMars Trace Gas Orbiter Mission (kernels can be excluded):



<span id="TGOMission"></span>



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





Galileo Mission (kernels can be excluded):

For example:



<span id="GalileoMission"></span>



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

<pre>

cd $ISIS3DATA

rsync -azv <b>--exclude='kernels'</b> --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/cassini .

</pre>



**WARNING:** Some instruments require mission data to be present for radiometric calibration, which may not be supported by the SPICE Web Server exclusively, and some programs that are designed to run an image from ingestion through the mapping phase do not have an option to use the SPICE Web Service. For information specific to an instrument, see the documentation for radiometric callobration programs.



Hayabusa Mission (kernels can be excluded):

### Mission Specific Data Downloads



<span id="HayabusaMission"></span>

**Apollo Mission (kernels can be excluded):**



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

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

    cd $ISIS3DATA

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

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

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





Juno Mission (kernels can be excluded):

**Cassini Mission (kernels can be excluded):**



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

    cd $ISIS3DATA

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





<span id="KaguyaMission"></span>

**Chandrayaan Mission (kernels can be excluded):**



Kaguya Mission (kernels can be excluded):

    cd $ISIS3DATA

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



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



**Clementine Mission (kernels can be excluded):**



<span id="LunarOrbiterMission"></span>

    cd $ISIS3DATA

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



Lunar Orbiter Mission (kernels can be excluded):



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

**Dawn Mission (kernels can be excluded):**



    cd $ISIS3DATA

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



<span id="LunarReconnaissanceOrbiterMission"></span>



Lunar Reconnaissance Orbiter Mission (kernels can be excluded):

**ExoMars Trace Gas Orbiter Mission (kernels can be excluded):**



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

    cd $ISIS3DATA

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





<span id="MarsExplorationRoverMission"></span>

**Galileo Mission (kernels can be excluded):**



Mars Exploration Rover Mission (kernels can be excluded):

    cd $ISIS3DATA

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



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



**Hayabusa Mission (kernels can be excluded):**



<span id="Mariner10Mission"></span>

    cd $ISIS3DATA

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

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



Mariner10 Mission (kernels can be excluded):



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

**Juno Mission (kernels can be excluded):**



    cd $ISIS3DATA

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



<span id="MessengerMission"></span>



Messenger Mission (kernels can be excluded):

**Kaguya Mission (kernels can be excluded):**



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

    cd $ISIS3DATA

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





<span id="MarsExpressMission"></span>

**Lunar Orbiter Mission (kernels can be excluded):**



Mars Express Mission (kernels can be excluded):

    cd $ISIS3DATA

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



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



**Lunar Reconnaissance Orbiter Mission (kernels can be excluded):**



<span id="MarsGlobalSurveyorMission"></span>

    cd $ISIS3DATA

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



Mars Global Surveyor Mission (kernels can be excluded):



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

**Mars Exploration Rover Mission (kernels can be excluded):**



    cd $ISIS3DATA

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



<span id="MarsReconnaissanceOrbiterMission"></span>



Mars Reconnaissance Orbiter Mission (kernels can be excluded):

**Mariner10 Mission (kernels can be excluded):**



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

    cd $ISIS3DATA

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





<span id="MarsOdysseyMission"></span>

**Messenger Mission (kernels can be excluded):**



Mars Odyssey Mission (kernels can be excluded):

    cd $ISIS3DATA

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



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



**Mars Express Mission (kernels can be excluded):**



<span id="NearMission"></span>

    cd $ISIS3DATA

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



Near Mission (kernels can be excluded):



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

**Mars Global Surveyor Mission (kernels can be excluded):**



    cd $ISIS3DATA

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



New Horizons Mission (kernels can be excluded):



<span id="NewHorizonsMission"></span>

**Mars Reconnaissance Orbiter Mission (kernels can be excluded):**



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

    cd $ISIS3DATA

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





Odyssey Mission (kernels can be excluded):

**Mars Odyssey Mission (kernels can be excluded):**



<span id="OdysseyMission"></span>

    cd $ISIS3DATA

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



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



**Near Mission (kernels can be excluded):**



Rolo Mission (kernels can be excluded):

    cd $ISIS3DATA

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



<span id="RoloMission"></span>



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

**New Horizons Mission (kernels can be excluded):**



    cd $ISIS3DATA

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



Rosetta Mission (kernels can be excluded):



<span id="RosettaMission"></span>

**Rolo Mission (kernels can be excluded):**



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

    cd $ISIS3DATA

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





Smart1 Mission (kernels can be excluded):

**Rosetta Mission (kernels can be excluded):**



<span id="Smart1Mission"></span>

    cd $ISIS3DATA

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



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



**Smart1 Mission (kernels can be excluded):**



Viking Mission (kernels can be excluded):

    cd $ISIS3DATA

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



<span id="VikingMission"></span>



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

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

**Viking Mission (kernels can be excluded):**



    cd $ISIS3DATA

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

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



Voyager Mission (kernels can be excluded):



<span id="VoyagerMission"></span>

**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/

    cd $ISIS3DATA

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

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





Installing older versions of ISIS

## Installing older versions of ISIS

---------------------------------



### How do I install ISIS2?
@@ -360,4 +343,4 @@ If you are looking for ISIS2, please [refer to the ISIS 2 Installation Guide](ht 


### How do I install ISIS3.5.2 or earlier?



If you are looking for a version of ISIS3 prior to 3.6.0, please [refer to the Legacy ISIS3 Installation Guide](../../documents/LegacyInstallGuide/index.html) for instructions on downloading and installing ISIS3, versions prior to 3.6.0.
 
If you are looking for a version of ISIS3 prior to 3.6.0, please [refer to the Legacy ISIS3 Installation Guide](https://isis.astrogeology.usgs.gov/documents/LegacyInstallGuide/index.html) for instructions on downloading and installing ISIS3, versions prior to 3.6.0.