Installing ISIS¶

Install via script¶

You can install miniforge and ISIS at the same time using a bash script. This will walk you through the process and set environmment variables for you.

bash <(curl https://raw.githubusercontent.com/DOI-USGS/ISIS3/refs/heads/dev/isis/scripts/install_isis.sh)

If you use conda/miniconda and not miniforge

This script requires replacing anaconda/miniconda with miniforge. Miniforge is far faster. ISIS can take hours to resolve in anaconda, compared to a few minutes in miniforge.

Script Details

The install_isis.sh script is a bash script that automates the installation process of the USGS ISIS software.

Prerequisites¶

Before running the installation script, ensure you have:

A Linux or macOS operating system
Sufficient disk space (at least 40GB recommended for software + base data)
Internet connection
Bash shell

Script Parameters¶

The script accepts several command-line arguments to customize the installation:

Parameter	Description
`-m, --miniforge-dir`	Installation directory
`-l, --anaconda-label`	Conda channel to use (default: `usgs-astrogeology`)
`-p, --data-prefix`	The directory where ISISDATA is located
`-v, --isis-version`	ISIS version to install, `latest` always installs latest
`-n, --env-name`	Name of the conda environment
`--no-data`	Skip Data Downloads (flag)
`--download-base`	Download Base Data
`-h, --help`	Display help information

Installation Process¶

The script performs the following steps:

Install Miniforge (if method is conda): Downloads and installs Miniconda if not already available
Create Environment: Sets up a conda environment with required packages
Install ISIS: Installs ISIS software either from conda packages or source code
Download Data: Fetches required data files based on specified options
Set Up Environment Variables: Configures necessary environment variables

CLI Examples

wgetcurl

wget -O install_isis.sh https://raw.githubusercontent.com/DOI-USGS/ISIS3/refs/heads/dev/isis/scripts/install_isis.sh"

curl -fsSLo install_isis.sh https://raw.githubusercontent.com/DOI-USGS/ISIS3/refs/heads/dev/isis/scripts/install_isis.sh"

In order to install ISIS in a CI or other automated pipeline, set flags for the label, version, env name and --no-data to skip data install. Install data via downloadIsisData.py.

Specific Install Examples¶

Latest mainLatest devLatest ltsSpecific Version

./install_isis.sh -l main -v latest -n isislatest -p $HOME/isisdata --no-data

./install_isis.sh -l dev -m $HOME/miniforge -v latest -n isisdev -p $HOME/isisdata --no-data

./install_isis.sh -l lts -v latest -n isislts -p $HOME/isisdata --no-data

./install_isis.sh --force-mamba -m $HOME/miniforge/ -l main -v 8.3.0 -n isis8.3.0 -p $HOME/isisdata --download-base

After install consideratrions¶

ISIS DATA¶

The script can download various types of ISIS data:

Base Data: Essential data required for ISIS functionality
Mission-specific Data: Data for specific planetary missions

We recommend only installing base, and use web spice for most spice operations. See ISIS Data Docs for more information.

Environment Variables¶

Key environment variables set up by the script:

ISISROOT: Points to the ISIS installation directory
ISISDATA: Points to the ISIS data directory
PATH: Updated to include ISIS binaries

On activation, the environment will automatically set ISISROOT, ISISDATA, and PATH for you. To change these variables after installation (in case they were set incorrectly or your ISISDATA folder changes) see setting environment variables.

Updating ISIS¶

Warning

Mamba is bad at updating envs after they have been created. This often causes conflicts and long resolve times. If you installed ISIS using this script, we recommend simply deleting the old environment and creating new one, or versioning your env names.

# initial install 
./install_isis.sh -l main -v 8.0.0 -n isis8.0.0 -p $HOME/isisdata --download-base

# After 8.3.0 release 
./install_isis.sh -l main -v 8.3.0 -n isis8.3.0 -p $HOME/isisdata --no-data

Additional Resources¶

Install Manually Via Miniforge¶

Prerequisites¶

Mamba/Miniforge

If you don't have mamba yet, download and install it. We recommend getting mamba through MiniForge.

# Via Miniforge:
curl -L -O "https://github.com/mamba-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

x86 emulation on ARM Macs - Rosetta

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

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

Mamba Environment¶

Native Mac/Unixx86 on ARM Macs

# Create mamba environment, then activate it.
mamba create -n isis 
mamba activate isis

# ARM Macs Only - Setup the new environment as x86_64
export CONDA_SUBDIR=osx-64

#Create a new mamba environment to install ISIS in
mamba create -n isis python>=3.9

#Activate the environment
mamba activate isis

# ARM Macs Only - Force installation of x86_64 packages, not ARM64
conda config --env --set subdir osx-64

Channels¶

# Add conda-forge and usgs-astrogeology channels
conda config --env --add channels conda-forge
conda config --env --add channels usgs-astrogeology

# Check channel order
conda config --show channels

Channel Order: usgs-astrogeology must be higher than conda-forge

Show the channel order with:

conda config --show channels

You should see:

channels:
    - usgs-astrogeology
    - conda-forge
    - defaults

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

conda config --env --add channels usgs-astrogeology
conda config --env --set channel_priority flexible

Downloading ISIS¶

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

Latest ReleaseLTSRelease CandidateDev

mamba install -c usgs-astrogeology isis

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

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

mamba install -c usgs-astrogeology/label/dev isis

Setting Environmental Variables¶

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

ISISROOT - Directory path containing your ISIS install
ISISDATA - Directory path containing the ISIS Data Area

Setting Environmental Variables

The conda env method is recommended, and the Python Script automates that method:

conda envPython Scriptexport (shell)ISIS <4.2.0

Requires conda 4.8 or above

Check your conda version, and update if needed:

# Check version
conda --version

# Update
conda update -n base conda

Activate your ISIS environment.

mamba activate isis

# Now you can set variables with:
# mamba env config vars set KEY=VALUE

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

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

Re-activate your isis environment.
```
mamba deactivate
mamba activate isis
```

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

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

python $CONDA_PREFIX/scripts/isisVarInit.py

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:

mamba deactivate
mamba activate isis

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.

export ISISROOT=[path to ISIS]
export ISISDATA=[path to data]

Use the python script per instructions from the old readme.

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.

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 mamba, you can update it with:

Latest ReleaseLTSRelease Candidate

mamba update -c usgs-astrogeology isis

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

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

Uninstalling ISIS¶

To uninstall ISIS, deactivate the ISIS mamba Environment, and then remove it. If you want to uninstall mamba as well, see your mamba installation's website (Miniforge if you installed mamba with the above instructions).

mamba deactivate
mamba env remove -n isis

ISIS in Docker¶

The ISIS production Dockerfile automates the mamba installation process above. You can either build the Dockerfile yourself or use the usgsastro/isis image from DockerHub.

Prebuilt ImageBuilding the Dockerfile

docker run -it usgsastro/isis bash

Download the production Docker file, build, and run it:

# 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/mamba/data -v /my/testdata/dir:/opt/mamba/testData -it usgsastro/isis bash

Then download the data into /my/data/dir to make it accessible inside your container.