Commit 8f18dfcc authored by Tyler Wilson's avatar Tyler Wilson
Browse files

Updated Install Guide for ISIS 3.

parent 67759e6c

isis/src/docsys/documents/InstallGuide/InstallGuide.xml

+364 −5
Original line number Diff line number Diff line
@@ -24,7 +24,355 @@ you must <em>not</em> upgrade the ISIS Data Files!!! 
-->

  <h2>Overview</h2>



<p>  INSERT NEW INSTRUCTIONS FOR HOW TO INSTALL ISIS3 USING CMAKE HERE OR LINK TO THE INSTRUCTIONS ON GITHUB. </p>

  <h3>Operating System Requirements</h3>

  <p>ISIS runs on many UNIX variants. ISIS does not run on MS Windows. The UNIX variants supported are listed here:</p>

    <ul>

      <li>Ubuntu 18.04 LTS</li>

      <li>Mac OS X 10.13.6 High Sierra</li>

      <li>CentOS Linux 7.2.1511</li>

      <li>Fedora 28</li>

    </ul>



   <h3>Hardware Requirements</h3>

   <p>Here are the minimum hardware requirements</p>

    <ul>

      <li>64-bit (x86) processors</li>

      <li>2 GB memory</li>

      <li>10 GB to 180 GB disk space for ISIS installation</li>

      <li>10 GB to many TB disk space for processing images</li>

      <li>A quality graphics card</li>

    </ul>

<p>Note: More processors, memory, disk storage, and an additional graphcis card (to support the use of two monitors at

one time) may be useful depending on the complexity of your processing requirements

</p>



   <h3>Mission Requirements</h3>

   <p>ISIS 3 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 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.

   </p>



   <h3>DTM Requirements</h3>

   <p>The strength of ISIS 3 strength lies in its capabilities for planetary cartography.

   The image orthorectification process is improved if a digital

   terrain model (DTM) is used.  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.

   </p>



<p>To build and compile ISIS 3 requires following the instructions listed below, which are given on

   the GitHub wiki page for the ISIS 3 project:

  <ul>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#getting-started-with-github">Getting Started With GitHub</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#anaconda-and-isis3-dependencies">Installing Anaconda and satisfying ISIS 3 Dependencies</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#building-isis3">Building ISIS 3 With cmake</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#new-environmental-variable-meanings">New ISIS 3 environmental variables and their meanings</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#custom-data-and-test-data-directories">Custom data and test directories</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#cleaning-builds">Cleaning builds</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#building-individual-isis3-applicationsobjects">Building individual applications/objects</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#building-isis3-documentation">Building ISIS 3 documentation</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Building-ISIS3-with-cmake#problems">What to do if you encounter any problems</a></li>

  </ul>

</p>



<h3>Links for Developers</h3>



  <ul>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developer-Checklists">ISIS 3 Developer Checklist</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Jenkins-CI">Jenkins Continuous Integration Testing</a></li>

    <li><a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Managing-Custom-ISIS-Dependencies-(WIP)">Managing Custom ISIS 3 Dependencies</a></li>

  </ul>



<h3>Full ISIS 3 Data Download</h3>



<p>

    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

     <a href="#MissionSpecific">click here</a>.   To download all ISIS 3 data files continue reading.

</p>

<p>

    Remember to use the following command from the same directory you ran the previous rsync

    command. In the example it was "/work1/isis3".

</p>

      <pre>

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

      </pre>

<p>

 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 <a href="#UnixEnvironment">Unix Environment Setup</a>.  If you chose

 not to download everything at once then continue below.

</p>





 <A NAME="MissionSpecific"> </A>



        <h3>Partial Download of ISIS 3 Base Data (Required)</h3>

        <p>

            The base data area is separate from the source code. This data area is

            crucial to ISIS 3 and must be downloaded.

        </p>

<pre>

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

</pre>



<h3>Partial Download of Mission Specific Data</h3>





        <p>

          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 you chose download the SPICE data, read the next section about the SPICE Web Service that

          provides instructions for excluding the SPICE kernels.  Otherwise <a href="#ApolloMission">jump</a> to the mission

          specific sections.

         </p>





<h3>ISIS SPICE Web Service</h3>



<p>

  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:

 </p>

<pre>

            --exclude='kernels'

</pre>

        <p>

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

        </p>



        <span style="font-size:120%; color:red; font-weight:bold">

          WARNING: Some instruments require mission data to be present for 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>



          <A NAME="ApolloMission"> </A>

<p>

  Apollo Mission (kernels can be excluded):

</p>

        <pre>

        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/

        </pre>



        <A NAME="CassiniMission"> </A>

<p>

  Cassini Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>





        <A NAME="ChandrayaanMission"> </A>

<p>

  Chandrayaan Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="ClementineMission"> </A>

<p>

  Clementine Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



          <A NAME="DawnMission"> </A>

<p>

  Dawn Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>

<p>

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

</p>

        <A NAME="TGOMission"> </A>

        <pre>

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

        </pre>

<p>

  Galileo Mission (kernels can be excluded):

</p>

        <A NAME="GalileoMission"> </A>

        <pre>

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

        </pre>

<p>

  Hayabusa Mission (kernels can be excluded):

</p>

        <A NAME="HayabusaMission"> </A>

        <pre>

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

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

        </pre>



<p>

  Juno Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="KaguyaMission"> </A>

<p>

  Kaguya Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="LunarOrbiterMission"> </A>

<p>

  Lunar Orbiter Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>

        <A NAME="LunarReconnaissanceOrbiterMission"> </A>

<p>

  Lunar Reconnaissance Orbiter Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="MarsExplorationRoverMission"> </A>

<p>

  Mars Exploration Rover Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>

        <A NAME="Mariner10Mission"> </A>



<p>

  Mariner10 Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="MessengerMission"> </A>



<p>

  Messenger Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="MarsExpressMission"> </A>



<p>

  Mars Express Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="MarsGlobalSurveyorMission"> </A>



<p>

  Mars Global Surveyor Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="MarsReconnaissanceOrbiterMission"> </A>



<p>

  Mars Reconnaissance Orbiter Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="MarsOdysseyMission"> </A>

<p>

  Mars Odyssey Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>



        <A NAME="NearMission"> </A>

<p>

  Near Mission (kernels can be excluded):

</p>

        <pre>

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

        </pre>

<p>

  New Horizons Mission (kernels can be excluded):

</p>

        <A NAME="NewHorizonsMission"> </A>

        <pre>

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

        </pre>

<p>

  Odyssey Mission (kernels can be excluded):

</p>

        <A NAME="OdysseyMission"> </A>

        <pre>

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

        </pre>

<p>

  Rolo Mission (kernels can be excluded):

</p>

        <A NAME="RoloMission"> </A>

        <pre>

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

        </pre>

<p>

  Rosetta Mission (kernels can be excluded):

</p>

       <A NAME="RosettaMission"> </A>

        <pre>

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

        </pre>

<p>

  Smart1 Mission (kernels can be excluded):

</p>

        <A NAME="Smart1Mission"> </A>

        <pre>

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

        </pre>

<p>

  Viking Mission (kernels can be excluded):

</p>

        <A NAME="VikingMission"> </A>

        <pre>

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

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

        </pre>

<p>

  Voyager Mission (kernels can be excluded):

</p>

        <A NAME="VoyagerMission"> </A>

        <pre>

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

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

        </pre>



<h2>Installing older versions of ISIS</h2>

    <h3>How do I install ISIS 2?</h3>
@@ -41,6 +389,15 @@ you must <em>not</em> upgrade the ISIS Data Files!!! 
        Guide</a> for instructions on downloading and installing ISIS3, version 3.5.2 or earlier.

    </p>



<A NAME="UnixEnvironment"> </A>



    <h2>UNIX Environment Setup</h2>

    <p>

        Still working on this part...

    </p>







      </body>



      <type>HTML</type>
@@ -61,14 +418,16 @@ you must <em>not</em> upgrade the ISIS Data Files!!! 


  <history>

    <change name="Kristin Berry" date="2018-08-28">Original Version</change>

    <change name ="Tyler Wilson" date="2018-09-26">Added links to installation instructions on the ISIS3 GitHub Wiki</change>

  </history>





  <bibliography>

     <title>Installing ISIS</title>

    <brief>Downloading and installing ISIS 3</brief>

    <description>

      This document describes how to download and install a

      binary version of ISIS.

      This document describes how to download/compile and install a

      binary version of ISIS 3.

    </description>

    <author>Kristin Berry</author>

    <date>2018-08-28</date>