installing isis and setting up the data area (#125)

## Setting Up NAIF Data

For use of NAIF Data with ISIS, see [The ISIS Data Area](https://github.com/DOI-USGS/ISIS3/blob/dev/README.md#the-isis-data-area).  For use of NAIF data with ALE, continue below.

For use of NAIF Data with ISIS, see the [ISIS Data Area](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md).  For use of NAIF data with ALE, continue below.

### Downloading NAIF SPICE Data with wget

    Some ISIS software updates include mission specific command updates motivated by new information (updated kernels, format changes, etc.) from mission teams. When the software is updated the data area should also be updated, see [Mission Specific Data Downloads][5].

    [3]: https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html

    [4]: https://github.com/DOI-USGS/ISIS3?tab=readme-ov-file#full-isis-data-download

    [5]: https://github.com/DOI-USGS/ISIS3?tab=readme-ov-file#mission-specific-data-downloads

    [6]: https://github.com/DOI-USGS/ISIS3?tab=readme-ov-file#isis-spice-web-service

    [4]: ../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#full-download

    [5]: ../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#mission-specific-data-areas

    [6]: ../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#isis-spice-web-service

    [7]: ../../getting-started/using-isis-first-steps/locating-and-ingesting-image-data.md

???+ abstract "Additional Helpful Docs"

## Prerequisites 

1. Clone and build [ISIS](https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake) locally.

1. Download base and mission kernels related to the driver you plan to implement.  One means of downloading this kernels is through ISIS's [downloadIsisData script](https://github.com/DOI-USGS/ISIS3/blob/dev/README.md#partial-download-of-isis-base-data).

1. Download base and mission kernels related to the driver you plan to implement.  One means of downloading this kernels is through ISIS's [downloadIsisData script](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#downloading-isisdata).

1. Fork [the ALE repository](https://github.com/USGS-Astrogeology/ale)

1. Clone from your fork (with the recursive flag to clone submodules as well):

    ```sh

# Installation

# Installing ISIS

This installation guide is for ISIS users interested in installing ISIS (3.6.0)+ through conda.

## Prerequisites

## ISIS Installation With Conda

??? "Conda"

1. Download either the Anaconda or Miniconda installation script for your OS platform. Anaconda is a much larger distribution of packages supporting scientific python, while Miniconda is a minimal installation and not as large: [Anaconda installer](https://www.anaconda.com/download), [Miniconda installer](https://conda.io/miniconda.html)

1. If you are running on some variant of Linux, open a terminal window in the directory where you downloaded the script, and run the following commands. In this example, we chose to do a full install of Anaconda, and our OS is Linux-based. Your file name may be different depending on your environment.

    If you don't have conda yet, download and install it.  We recommend getting conda through [MiniForge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge).

    ```bash

    chmod +x Anaconda3-5.3.0-Linux-x86_64.sh

    ./Anaconda3-5.3.0-Linux-x86_64.sh

    ```sh

    # Via Miniforge:

    curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"

    bash Miniforge3-$(uname)-$(uname -m).sh

    ```

    This will start the Anaconda installer which will guide you through the installation process.

1. If you are running Mac OS X, a pkg file (which looks similar to Anaconda3-5.3.0-MacOSX-x86\_64.pkg) will be downloaded. Double-click on the file to start the installation process.

1. After the installation has finished, open up a bash prompt in your terminal window.

1. If you have an ARM64 Mac (M1/M2) running Catalina (or later), additional prerequisites must be installed for ISIS to run in emulation:

 - Install [XQuartz](https://www.xquartz.org/). (Tested with XQuartz 2.8.5 on MacOS Catalina)

 - Install Rosetta2. From the terminal run: `/usr/sbin/softwareupdate --install-rosetta --agree-to-license`

 - Include the `# MacOS ARM64 Only` lines below

1. Next setup your Anaconda environment for ISIS. In the bash prompt, run the following commands:

??? "x86 emulation on ARM Macs - Rosetta"

    ```bash

    If you have an ARM mac and want to run the x86 version of ISIS, you will need Rosetta.

    #MacOS ARM64 Only - Setup the new environment as an x86_64 environment

    export CONDA_SUBDIR=osx-64

    ```sh

    /usr/sbin/softwareupdate --install-rosetta --agree-to-license

    ```

## Conda Environment

=== "Native Mac/Unix"

    ```sh

    # Create conda environment, then activate it.

    conda create -n isis 

    conda activate isis

    ```

=== "x86 on ARM Macs"

    #Create a new conda environment to install ISIS in

    conda create -n isis python>=3.9

    ```sh

    # ARM Macs Only - Setup the new environment as x86_64

    export CONDA_SUBDIR=osx-64

    #Activate the environment

    # Create conda environment, then activate it.

    conda create -n isis

    conda activate isis

    #MacOS ARM64 Only - Force installation of x86_64 packages instead of ARM64

    # ARM Macs Only - Force installation of x86_64 packages, not ARM64

    conda config --env --set subdir osx-64

    ```

### Channels

    #Add the following channels to the environment

```sh

# Add conda-forge and usgs-astrogeology channels

conda config --env --add channels conda-forge

conda config --env --add channels usgs-astrogeology

    #Verify you have the correct channels:

# Check channel order

conda config --show channels

```

??? warning "Channel Order: `usgs-astrogeology` must be higher than `conda-forge`"

    #You should see:

    Show the channel order with:

    ```sh

    conda config --show channels

    ```

    You should see:

    ```

    channels:

        - usgs-astrogeology

        - conda-forge

        - defaults

    ```

    #The order is important.  If conda-forge is before usgs-astrogeology, you will need to run:

    If `conda-forge` is before `usgs-astrogeology`, add usgs-astrogeology again to bring up.  Set channel priority to flexible instead of strict.

    ```sh

    conda config --env --add channels usgs-astrogeology

    #Then set channel_priority to flexible in case there is a global channel_priority=strict setting

    conda config --env --set channel_priority flexible

    ```

1. The environment is now ready to download ISIS and its dependencies:

## Downloading ISIS

The environment is now ready to download ISIS and its dependencies:

    ```bash

=== "Latest Release"

    ```sh

    conda install -c usgs-astrogeology isis

    ```

1. Finally, setup the environment variables:

=== "LTS"

    ```sh

    conda install -c usgs-astrogeology/label/LTS isis

    ```

    ISIS requires several environment variables to be set in order to run correctly.

    The variables include: ISISROOT and ISISDATA.

=== "Release Candidate"

    The following steps are only valid for versions of ISIS after 4.2.0.

    For older versions of ISIS follow the instructions in [this readme file.](https://github.com/USGS-Astrogeology/ISIS3/blob/adf52de0a04b087411d53f3fe1c9218b06dff92e/README.md)

    ```sh

    conda install -c usgs-astrogeology/label/RC isis

    ```

    There are two methods to configure the environment variables for ISIS:

    A. Using `conda env config vars` *preferred*

## Environmental Variables

       Conda has a built in method for configuring environment variables that are specific to a conda environment since version 4.8.

       This version number applies only to the conda package, not to the version of miniconda or anaconda that was installed.

ISIS requires these environment variables to be set in order to run correctly:

       To determine if your version of conda is recent enough run:

- `ISISROOT` - Directory path containing your ISIS install

- `ISISDATA` - Directory path containing the [ISIS Data Area](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md)

           conda --version

???+ example "Setting Environmental Variables"

       If the version number is less than 4.8, update conda to a newer version by running:

    The **Conda Env** method is recommended, and the **Python Script** automates that method:

           conda update -n base conda

    === "Conda Env"

       The version number should now be greater than 4.8.

        ??? "Requires Conda 4.8 or above"

       To use the built in environment variable configuration feature, first activate the environment by first running:

            Check your conda version, and update if needed:

            ```sh

            # Check version

            conda --version

            # Update

            conda update -n base conda

            ```

        1.  Activate your ISIS environment.  

            ```

            conda activate isis

       After activation, the environment variables can be set using the syntax: `conda config vars set KEY=VALUE`.

       To set all the environment variables ISIS requires, run the following command, updating the path to `ISISDATA` as needed:

            # Now you can set variables with:

            # conda config vars set KEY=VALUE

            ```

           conda env config vars set ISISROOT=$CONDA_PREFIX ISISDATA=[path to data directory]

        1.  This command sets both required variables (fill in your `ISISDATA` path):

       To make these changes take effect, re-activate the isis environment by running:

                conda env config vars set ISISROOT=$CONDA_PREFIX ISISDATA=[your data path]

        1.  Re-activate your isis environment. 

            ```sh

            conda deactivate

            conda activate isis

            ```

       The environment variables are now set and ISIS is ready for use every time the isis environment is activated.

        The environment variables are now set and ISIS is ready for use every time the isis conda environment is activated.

    !!! Warning "The above method will not enable tab completion for arguments in C-Shell."

-----

    B. Using the provided isisVarInit.py script:

    === "Python Script"

       To use the default values for: `$ISISROOT` and `$ISISDATA`, run the ISIS variable initialization script with default arguments:

        By default, running this script will set `ISISROOT=$CONDA_PREFIX` and `ISISDATA=$CONDA_PREFIX/data`:

            python $CONDA_PREFIX/scripts/isisVarInit.py

       Executing this script with no arguments will result in $ISISROOT=$CONDA\_PREFIX and $ISISDATA=$CONDA\_PREFIX/data. The user can specify different directories for `$ISISDATA` using the optional value:

        You can specify a different path for `$ISISDATA` using the optional value:

            python $CONDA_PREFIX/scripts/isisVarInit.py --data-dir=[path to data directory]

       Now every time the isis environment is activated, $ISISROOT and $ISISDATA will be set to the values passed to isisVarInit.py.

       This does not happen retroactively, so re-activate the isis environment with one of the following commands:

        Now every time the isis environment is activated, `$ISISROOT` and `$ISISDATA` will be set to the values passed to isisVarInit.py.

        This does not happen retroactively, so re-activate the isis environment:

            conda deactivate

            conda activate isis

    === "export (shell)"

        `export` sets a variable in your current shell environment until you close it.  Adding `export` commands to your `.bashrc` or `.zshrc` can make them persistent.

        ```sh

        export ISISROOT=[path to ISIS]

        export ISISDATA=[path to data]

        ```

           for Anaconda 3.4 and up - conda activate isis

           prior to Anaconda 3.4 - source activate isis

    === "ISIS <4.2.0"

        Use the python script per instructions from [the old readme](https://github.com/USGS-Astrogeology/ISIS3/blob/adf52de0a04b087411d53f3fe1c9218b06dff92e/README.md).

## The ISIS Data Area

Many ISIS apps need extra data to carry out their functions.  This data varies depending on the mission, and may be quite large, so it is not included with ISIS; You will need to [download it separately](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md).

-----

!!! success "Installation Complete"

    If you followed the above steps and didn't encounter any errors, you have completed your installation of ISIS.

-----

## Updating ISIS

If ISIS was already installed with Conda, you can update it with:

=== "Latest Release"

    ```sh

    conda update -c usgs-astrogeology isis

    ```

=== "LTS"

    ```sh

    conda update -c usgs-astrogeology/label/LTS isis

    ```

=== "Release Candidate"

    ```sh

    conda update -c usgs-astrogeology/label/RC isis

    ```

## Uninstalling ISIS

To uninstall ISIS, deactivate the ISIS Conda Environment, and then remove it.  If you want to uninstall conda as well, see your conda installation's website ([Miniforge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#uninstallation) if you installed conda with the above instructions).

```sh

conda deactivate

conda env remove -n isis

```

-----

## ISIS in Docker

!!! quote ""

    The ISIS production Dockerfile automates the conda installation process above.

    You can either build the Dockerfile yourself or use the

    [usgsastro/isis](https://hub.docker.com/repository/docker/usgsastro/isis)

    image from DockerHub.

    === "Prebuilt Image"

        ```sh

        docker run -it usgsastro/isis bash

        ```

    === "Building the Dockerfile"

        Download [the production Docker file](https://github.com/DOI-USGS/ISIS3/blob/dev/docker/production.dockerfile), build, and run it:

        ```sh

        # Build

        docker build -t isis -f production.dockerfile .

        # Run

        docker run -it isis bash

        ```

    ### Mounting the ISIS data area

    Usually you'll want to mount an external directory containing the ISIS data.

    The data is not included in the Docker image.

    ```

    docker run -v /my/data/dir:/opt/conda/data -v /my/testdata/dir:/opt/conda/testData -it usgsastro/isis bash

    ```

    Then [download the data](#the-isis-data-area) into /my/data/dir to make it accessible inside your

    container.

# Setting Up the ISIS Data Area

Many ISIS apps need extra data to carry out their functions.  This data varies depending on the mission, and may be **quite large**, so it is **not included** with the ISIS binaries. It resides in the **ISIS Data Area**.

??? info "More Info on the ISIS Data Area"

    ### Structure

    Each mission supported by ISIS has a directory with mission-specific processing data (like flat files and SPICE kernels).  There is also a base data area with shared data, and a test data area for ISIS testing and development.

    #### Output of `tree -L 2 $ISISDATA`

    ```sh

    ~/isis_data/

    ├── apollo15

    │   ├── calibration

    │   ├── kernels

    │   └── reseaus

    ├── apollo16

    │   ├── kernels

    │   └── reseaus

    ├── base

    │   ├── dems

    │   ├── examples

    │   ├── kernelTesting

    │   └── kernels

    ├── cassini

    │   ├── calibration

    │   ├── kernels

    │   └── unitVectors

    ├── chandrayaan1

    │   ├── bandBin

    │   └── kernels

    ├── clementine1

    │   ├── calibration

    │   └── kernels

    ├── dawn

    │   └── kernels

    ...

    ```

    ### Hosting

    The ISIS Data Area is hosted on a combination of AWS S3 buckets and public http servers (NAIF, Jaxa, ESA), not through conda like ISIS binaries.  The `downloadIsisData` script facilitates downloading ISIS data from various sources.

    ### Versions

    For ISIS 4.1.0 and above, some apps require the [`base`](#__tabbed_2_1) and/or [mission-specific](#mission-specific-data-areas) data areas, while other apps may run without them.

    Apps from ISIS versions lower than 4.1.0 require the [`legacybase`](#__tabbed_2_2) area.

    ### Example ISISDATA usage in ISIS Apps

    - **Calibration** apps need **flat files** to do _flat field corrections_.

    - **Map Projection** apps need **DTMs** to accurately _compute intersections_.

    - `spiceinit` uses SPICE Data is used to _initialize ISIS cubes_.

    ### Size

    All the ISIS data from various missions adds up to a total of over 2TB.  But, using the [ISIS SPICE Web Service](#isis-spice-web-service) (instead of downloading all the SPICE files) reduces the necessary download to a much more manageable ~10GB base.

## Setting the ISISDATA Environmental Variable

Any location can be used for the ISIS Data Area, ISIS just needs the `$ISISDATA` environmental variable to point to it.

=== "Conda"

    ```sh

    # Activate your environment (assuming it's named isis)

    conda activate isis

    # Set the variable

    conda env config vars set ISISDATA=<path/to/isisdata>

    # Reactivate your environment

    conda deactivate

    conda activate isis

    ```

=== "Shell"

    ```sh

    export ISISDATA=<path/to/isisdata>

    ```

## Downloading ISISDATA

You can use the `downloadIsisData` script to download ISIS data.

```sh

# General Usage

downloadIsisData [mission] [download destination] [optional flags]

# More Info

downloadIsisData --help

```

### Full Download

To download **ALL** Isis data, including the base and all of the mission data areas:

```sh

downloadIsisData all $ISISDATA

```

!!! warning "That's a lot of data!"

    Downloading *all* takes over 2TB of space!  See [Partial Downloads](#partial-downloads) if you want a smaller subset, or try the [ISIS SPICE Web Service](#isis-spice-web-service).

### Partial Downloads

#### The Base Data Area

Some data (like DEMs and Leap Second Kernels) are shared between multiple missions; this is the base data area.

If you work with camera models (using `cam2map`, `campt`, `qview`, etc.), or are using a legacy version of ISIS, we recommend downloading the base data area:

=== "Current"

    ```sh

    # For ISIS versions 4.1.0 and up

    downloadIsisData base $ISISDATA

    ```

=== "Legacy"

    ```sh

    # For ISIS versions before 4.1.0

    downloadIsisData legacybase $ISISDATA

    ```

</br>

#### Mission Specific Data Areas

If you are only working with a few missions, save space by downloading just those data areas (find your download command on the following list).

??? abstract "Mission Names & Download Commands"

    - For versions of ISIS prior to ISIS 4.1.0, please use the `--legacy` flag.

    - Reference [`rclone.conf`](https://github.com/DOI-USGS/ISIS3/blob/dev/isis/config/rclone.conf) if you can't find/download data for your mission with one of these commands.

    | Mission | Command |

    | ------ | ------ |

    | Apollo 15 | `downloadIsisData apollo15 $ISISDATA` |

    | Apollo 16 | `downloadIsisData apollo16 $ISISDATA` |

    | Apollo 17 | `downloadIsisData apollo17 $ISISDATA` |

    | Cassini | `downloadIsisData cassini $ISISDATA` | 

    | Chandrayaan 1 | `downloadIsisData chandrayaan1 $ISISDATA` |

    | Clementine 1 | `downloadIsisData clementine1 $ISISDATA` |

    | Dawn | `downloadIsisData dawn $ISISDATA` |

    | ExoMars | `downloadIsisData tgo $ISISDATA` |

    | Galileo | `downloadIsisData galileo $ISISDATA` | 

    | Hayabusa 2 | `downloadIsisData hayabusa2 $ISISDATA` |

    | Juno | `downloadIsisData juno $ISISDATA` |

    | Kaguya | `downloadIsisData kaguya $ISISDATA` |

    | Lunar Orbiter | `downloadIsisData lo $ISISDATA` |

    | Lunar Reconnaissance Orbiter | `downloadIsisData lro $ISISDATA` |

    | Mars Exploration Rover  | `downloadIsisData mer $ISISDATA` |

    | Mariner10  | `downloadIsisData mariner10 $ISISDATA` |

    | Messenger | `downloadIsisData messenger $ISISDATA` |

    | Mars Express  | `downloadIsisData mex $ISISDATA` |

    | Mars Global Surveyor  | `downloadIsisData mgs $ISISDATA` |

    | Mars Reconnaissance Orbiter  | `downloadIsisData mro $ISISDATA` |

    | Mars Science Laboratory  | `downloadIsisData msl $ISISDATA` |

    | Mars Odyssey  | `downloadIsisData odyssey $ISISDATA` |

    | Near  | `downloadIsisData near $ISISDATA` |

    | New Horizons  | `downloadIsisData newhorizons $ISISDATA` |

    | OSIRIS-REx  | `downloadIsisData osirisrex $ISISDATA` |

    | Rolo  | `downloadIsisData rolo $ISISDATA` |

    | Rosetta  | `downloadIsisData rosetta $ISISDATA` |

    | Smart1  | `downloadIsisData smart1 $ISISDATA` |

    | Viking 1 | `downloadIsisData viking1 $ISISDATA` |

    | Viking 2 | `downloadIsisData viking2 $ISISDATA` |

    | Voyager 1 | `downloadIsisData voyager1 $ISISDATA` |

    | Voyager 2 | `downloadIsisData voyager2 $ISISDATA` |

-----

## ISIS SPICE Web Service

ISIS can retrieve the SPICE data over the internet with a web service.

Using the ISIS SPICE Web Service significantly reduces the size 

of the required downloads from the data area.

??? warning "Not all operations are supported by the SPICE Web Service"

    Some instruments require mission data to be present for **radiometric calibration**, which is not supported by the SPICE Web Server.

    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. 

    - **MEX HRSC** is a commonly used unsupported instrument.

    - For info on specific apps/instruments, see the [ISIS Application Docs](https://isis.astrogeology.usgs.gov/Application/index.html).

### Enabling the Web Service for `spiceinit`

To use this instead of local SPICE data, 

click the `WEB` check box in the `spiceinit` window. 

Or at the command line:

```sh

spiceinit from=<yourimage.cub> web=yes

```

### Skipping Kernel Downloads with `downloadIsisData`

#### --exclude

To skip downloading the SPICE kernels, use the `exclude` argument (like a blacklist) on a mission-specific `downloadIsisData` command.  For example:

    downloadIsisData cassini $ISISDATA --exclude="kernels/**"

#### --include

You can also use the `include` argument (like a whitelist) to partially download specific kernels. For example, to include only `ck`s and `fk`s in your LRO mission download:

    downloadIsisData lro $ISISDATA --include="{ck/**,fk/**}"

## The ISIS Test Data Area

There is an ISISTESTDATA area containing files needed to run some of ISIS's older Makefile-based tests.  See [ISIS Test Data](../../how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md) for more info.

 No newline at end of file