Installing USGS ISIS on Windows

The United Sates Geological Survey provides the Integrated Software for Imagers and Spectrometers (ISIS) to support processing of planetary imagery . Utilizing the Windows Subsystem for Linux (WSL) feature of Windows 10, ISIS can now be run directly (essentially natively) in Windows, which is faster and uses fewer resources than running a virtual machine. These step-by-step instructions borrow heavily from the official ISIS documentation and a more-or-less official blog post, and are inspired by the (now partially outdated) blog post of a labmate. They are also designed to be as accessible as possible, no matter your prior experience with ISIS or Linux.

At time of writing, the following instructions resulted in a total storage footprint of ~19.0-45.8 GB on disk (14.0-40.8 GB total file size), including file sizes of ~0.03 GB for VcXsrv, ~1.5 GB for Ubuntu, ~0.5 GB for Miniconda, ~5.8 GB for the ISIS environment and install, ~13.8 GB for the base ISIS data, and ~19.5 GB for all mission data excluding kernels (i.e., processing will rely on a Web service, as necessary). However, the base data are not required for some operations, and you only need (at most) those mission data corresponding to the missions for which you will be performing processing.

Blog Post Versions
Oct. 11, 2020: ISIS 1.4.1, Ubuntu 20.04 LTS, on Windows 10 (version 2004).

INSTALL VCXSRV AND CONFIGURE IT

VcXsrv is a display server that will support the visual display of windows for Linux programs, including ISIS. Although there are other options (including Xming), I've found VcXsrv to work well and avoid some annoying quirks (e.g., false warnings) in WSL.

1. Go to: https://sourceforge.net/projects/vcxsrv/
   
2. Download: VcXsrv
   Note: If you have another X window server (e.g., Xming) running, I recommend that you exit that server before continuing and try to avoid both servers running simultaneously in the future. If you have no idea what that means, chances are that you do not have such a server running.
   
3. Install: VcXsrv
   Note: Run the installation program that you just downloaded, as you would to install any other program.
4. Click: Windows button (bottom left corner of your screen)
5. Type: xlaunch
6. Click: XLaunch
7. Choose the following settings (pictured below):
   Note: Pictures are shown further below, but each window may look different depending on your system.
   On the first window, choose "Multiple windows", and set "Display number" to -1 or, if that's disallowed, to 0.
   On the second window, choose "Start no client."
   On the third window, uncheck "Native opengl" (if that option is available), and check "Disable access control."
   On the fourth window, do not click the Finish button yet!.
   
8. Click: Save configuration
   
   Option 1: Start VcXsrv whenever Windows starts.
   Having VcXsrv start automatically when Windows starts avoids you having to manually start it every time you want to use ISIS (and having to remember that step to begin with). It also is very light on resources, so even if you don't use it in a particular Windows session, it won't really slow anything down.)
9. Enter (in address bar of File Explorer): startup
   Note: Equivalently, you could navigate to C:\Users\[YourUsername]\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
10. Click: Save
    Note: By saving this configuration to this location, VcXsrv will be started, with the correct configuration, every time that Windows starts. The file name that you choose does not matter.
    
    Option 2: Manually start VcXsrv whenever it is needed.
    
11. Save the configuration file wherever you choose.
    Note: Whenever you need Linux programs, including ISIS, to display windows, you will need to remember to double-click on this file to launch VcXsrv with the configuration that you just set.
    
    
12. Click: Finish
    

ENABLE WINDOWS SUBSYSTEM FOR LINUX

As described by Wikipedia, this is a "compatibility layer for running Linux binary executables (in ELF format) natively on Windows 10". It is a built-in feature to Windows and merely must be enabled, which makes it far preferable to virtualization (e.g., faster, less resource use).

1. Click: Windows button (bottom left corner of your screen) 
   
2. Type: powershell 
   
3. Right-click: Windows PowerShell
   
4. Click: Run as administrator 
   
5. Enter (in PowerShell):
   Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   Note: To paste into PowerShell or (further below) Ubuntu, simply copy text as usual and right-click within the appropriate window.
6. Restart your computer when prompted. 

INSTALL AND LAUNCH UBUNTU

Ubuntu is a popular distribution of Linux that is expressly supported by ISIS.

1. Click: Windows button (bottom left corner of your screen) 
   
2. Type: store

3. Click: Microsoft Store

4. Search: ubuntu 
   

5. Click: Ubuntu 20.04 LTS 
   Note: To reduce the risk of issues later, choose this version specifically.
   

6. Click: Get
   Note: There is no need to sign in. If prompted, you can click "No, thanks."
   

7. Click: Install
   Note: If you are prompted to sign in, you can generally close the window and the download will proceed anyway. (The exception is if you already have a Microsoft account set up on the computer, in which case it seems that you may be required to sign in.)

8. Wait: For download to finish.
   

9. Click: Launch
   

10. Ubuntu will report that it is installing.
    Note: The curious can typically find the primary Ubuntu file system by navigating to C:\Users\[YourUsername]\AppData\Local\Packages and looking for a folder with a name that resembles CanonicalGroupLimited.Ubuntu20.04onWindows_79rhkp1fndgsc, though the exact name will depend on the version installed.
    Warning: Other than measuring its size, you really shouldn't do must of anything else with this folder, as modification can corrupt Ubuntu! 

SET UP AND UPDATE UBUNTU

1. When prompted (in Ubuntu), enter a username and password for Linux.
   Note: I suggest a username with all lowercase letters.
   
2. Enter:
   sudo apt update
   Note: You will be prompted for the password you just created for every sudo call.
   Note: If you ever forget what command you most recently entered, just use the up arrow on your keyboard to scroll through each command in order. You can then use the down arrow to ultimately return to the command you started to type (if any).
3. Enter:
   sudo apt upgrade -y
   Note: The update command simply updates the list of what packages are available. The upgrade command actually upgrades those packages.
   

SET UP UBUNTU TO SUPPORT DISPLAY OF ISIS (AND OTHER) WINDOWS

1. Enter (in Ubuntu):
   sudo apt install -y xclip gnome-themes-standard gtk2-engines-murrine dbus dbus-x11 x11-apps libgl1-mesa-glx
   
   Note: The next commands each add one line of text to the bottom of the file <.bashrc> or <.bash_profile>. These files, in turn, are shell scripts that run whenever Bash is started interactively (e.g., whenever you start the Ubuntu program) or a user logs in, respectively. Therefore, these lines represent commands that, from now on, will be executed automatically whenever you start Ubuntu (or otherwise start Bash interactively) or first log into Ubuntu so that you don't have to enter them yourself each time.
2. Enter:
   echo export DISPLAY=:0 >> ~/.bashrc
   Note: This line ensures that the local monitor is used as the default display.
   
3. Enter:
   echo export LC_ALL=C >> ~/.bashrc
   Note: This line sets the default localization (think something like "local alphabet') to the simplest computer-friendly option, thus minimizing hazards such as unrecognized characters. Settings this default explicitly avoids warnings later.
   
4. Enter:
   echo rm -rf /tmp/runtime-$USER >> ~/.bash_profile
   Note: This command delete a user-specific directory (folder) for storing small, temporary files, if that directory exists. (If the directory does not exist, no error is raised.) According to the XDG_RUNTIME_DIR specification, this directory must be unique to each login session. This behavior is achieved by the combination of this command and the next one.
5. Enter:
   echo mkdir -m 700 /tmp/runtime-$USER >> ~/.bash_profile
   Note: This command creates a user-specific directory (folder) for storing small, temporary files.
6. Enter:
   echo export XDG_RUNTIME_DIR=/tmp/runtime-$USER >> ~/.bashrc
   Note: This command sets the directory from the previous command as the default for storing small, temporarily files. Settings this default explicitly avoids warnings later.
   
   
7. Enter:
   source ~/.bash_profile
   Note: This command simply re-executes <.bash_profile>, which now has the extra lines added above. (<.bash_profile> was already executed at the start of the session, but without those lines.) Of course, now that those lines are present in <.bash_profile>, every future session will start with those lines already executed. In fact, if you preferred, you could simply close and restart Ubuntu rather than executing this command (and the following one) at all.
8. Enter:
   source ~/.bashrc
   Note: This command simply re-executes <.bashrc>, which now has the extra lines added above. (See note on the immediately previous step for more explanation.)
   

LAUNCH AND TEST THE VCXSRV CONFIGURATION

1. Start the VcXsrv configuration that you saved earlier.
   

   Note: If you opted to have the VcXsrv configuration launch when Windows starts (Option 1 further above), simply skip this step.
   Note: VcXsrv is launched as a background process. There will be no obvious indication that it has launched, except for an icon in the task bar (bottom left of your screen) which may not be visible unless the task bar is expanded (^ button on task bar). 

2. Enter (in Ubuntu):
   xclock
   Note: This is simply to test that VcXsrv and Ubuntu are working together. You should see a clock display, though it may appear below other windows. Hopefully you will see no errors or warnings. 🤞 Regardless, as long as the clock displays, you're probably OK. (If you see no errors reported in Ubuntu, look carefully for the clock window before assuming that it did not display.)
3. Close the clock window.

INSTALL "CONDA" (ANACONDA OR MINICONDA)

Anaconda is a popular distribution of the Python programming language focused on supporting scientific computing. Miniconda is its bare-bones counterpart. "Conda" as a name may be used to refer to either Anaconda or Miniconda; conda is also a command common to both distributions.

1. Enter (in Ubuntu):
   cd /tmp
   Note: This command simply moves you into the standard folder where temporary files are stored.
   
   Option 1: Install Miniconda
   This option uses significantly less storage space.
2. Enter:
   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
3. Enter:
   bash Miniconda3-latest-Linux-x86_64.sh
   Note: This command will install Miniconda. There will be a series of prompts and a EULA to read. It is recommended that you choose to initialize Miniconda3 when prompted.
   
4. Enter:
   rm Miniconda3-latest-Linux-x86_64.sh
   Note: This command deletes the installation program. 
   
5. Enter:
   source ~/.bashrc
   Note: This command simply re-executes <.bashrc>, which now has extra lines that will initiate Conda (including modification of the PATH variable). Now that those lines are present in <.bashrc>, every future session will start with those lines already executed. In fact, if you preferred, you could simply close and restart Ubuntu rather than executing this command at all.
   
   Option 2: Install Anaconda
6. Enter:
   wget https://repo.anaconda.com/archive/Anaconda3-2020.07-Linux-x86_64.sh
   Note: This command will download the specific version of Anaconda specified above. Instead, if you want to ensure that you have the latest version of Anaconda, you could navigate to https://www.anaconda.com/products/individual, click the Download button, and locate the "64-bit (x86) Installer" link under Linux. Right-click, choose "Copy link address", and paste the link into the command above instead of the link shown. (Use right-click in the Ubuntu window to paste.)
   
7. Enter:
   bash Anaconda3-2020.07-Linux-x86_64.sh
   Note: This command will install Anaconda. There will be a series of prompts and a EULA to read. Anaconda recommends that you choose to initialize Anaconda3 when prompted.
   Note: If you navigated to find a link in the previous step, change the filename in the above command to match that filename. 
   
8. Enter:
   rm Anaconda3-2020.07-Linux-x86_64.sh
   Note: This command deletes the installation program. 
   Note: If you navigated to find a link earlier, change the filename in the above command to match that filename. 
   
9. Enter:
   source ~/.bashrc
   Note: This command simply re-executes <.bashrc>, which now has extra lines that will initiate Conda (including modification of the PATH variable). Now that those lines are present in <.bashrc>, every future session will start with those lines already executed. In fact, if you preferred, you could simply close and restart Ubuntu rather than executing this command at all.

INSTALL ISIS

1. Enter (in Ubuntu):
   conda create -y -n isis python=3.6
   Note: This command creates a Conda environment, named isis, into which ISIS will be installed. 
   
2. Enter:
   conda activate isis
   Note: This command activates the environment just created.
   
3. Enter:
   conda config --env --add channels conda-forge
   Note: This command adds a channel (download source) required to install ISIS dependencies.
   
4. Enter:
   conda config --env --add channels usgs-astrogeology
   Note: This command adds a channel (download source) required to install ISIS. 
   
5. Enter:
   conda install -y -c usgs-astrogeology isis=4.1.1
   Note: This command will take several minutes. ☕ 
   Note: In my case, I saw some warnings about failed environment solutions but a solution was eventually found automatically (without user interaction)
   Note: This command installs ISIS 4.1.1. At the time of writing, 4.2.0 is the most recent version. However, that version unfortunately depends on a later version of the GSL library (namely, requires libgsl.so.25) than is supported by the Ubuntu 20.04 repositories, and Ubuntu 20.04, in turn, is the most recent version of Ubuntu that can be installed from the Microsoft store at the time of writing. Put more simply, ISIS 4.1.1 is the latest version of ISIS that can be simply and safely installed to Ubuntu running on WSL at the time of writing.
   
6. Enter:
   python $CONDA_PREFIX/scripts/isis3VarInit.py
   
   OR, to customize the paths
   
   Enter:
   python $CONDA_PREFIX/scripts/isis3VarInit.py --data-dir=path/to/data --test-dir=path/to/testdata
   
   Note: Either command will permanently set the data and testdata paths. The first command option implicitly applies reasonable defaults. If using the second command option, change the placeholder paths <place/to/x> to the desired paths and be careful to use forward slashes (/'s) rather than backslashes (\'s). The directories (folders) at those paths, and their parents, will be created if necessary by this command.
   Note: For all versions through 4.2.0, which is the most recent at the time of writing, the above command options are correct. Moreover, if you have followed the directions so far, you have specifically installed version 4.1.1. Nonetheless, I note there that for versions after 4.2.0, the filename drops the 3: <isisVarInit.py>.
   
7. Enter:
   conda activate isis
   Note: Reactivate the isis environment (even though it's already active). This ensures that important environment variables are set. (They could not be set when the environment was first activated, because <isis[3]VarInit.py> had not been run, nor was ISIS installed.) If you ever have to change these paths (by running <isis[3]VarInit.py> again), you'll likewise need to reactive the isis environment before that change will take effect.
8. Optionally, enter:
   echo conda activate isis >> ~/.bashrc
   Note: This command simply adds the line conda activate isis to the bottom of the file <.bashrc>. <.bashrc>, in turn, is a shell script that runs whenever Bash (the interpreter) is started interactively, for example, whenever you start Ubuntu. This line ensures that the isis environment is activated by default.

DOWNLOAD ISIS DATA

Option 1: Download all ISIS data.

This will download data for all missions and the base data. At the time of writing, the unrestricted operation required ~700 GB! However, you can reduce this footprint significantly by relying on the Web service (in which case some processing will require an Internet connection). At the time of writing, this reduced download was ~33.3 GB.

1. Enter (in Ubuntu):
   conda activate isis
   Note: Although there is no need to enter this command two times in a row, doing so won't hurt anything, and in case you took a break between the last step and this one (and potentially deactivated the environment), it is safer. 
2. To rely on the Web service
   Enter:
   rsync -azv --progress --delete --partial isisdist.astrogeology.usgs.gov::isisdata/data/ --exclude='kernels' $ISISDATA
   
   For the unrestricted download
   Enter:
   rsync -azv --progress --delete --partial isisdist.astrogeology.usgs.gov::isisdata/data/ $ISISDATA
   
   Note: The first download option (that relies on the Web service) took about 10 hours for me, as a point of reference.
3. Enter:
   qview $ISISDATA/base/dems/MSGR_DEM_USG_EQ_I_V02_prep.cub
   Note: This simply tests whether you can open a DEM (digital elevation model) that was among the data you just downloaded. 
   

USING ISIS

Now that you have everything installed and set up, using ISIS is relatively simple. I give three examples of how ISIS may be accessed and used.

Tip: To access a file on the C drive from Linux, use the address /mnt/c/... For example, to display C:/Users/Name/Documents/my_image.cub, you would use "qview /mnt/c/Users/Name/Documents/my_image.cub". Note that, unlike in Windows, paths are case-sensitive when specified in Linux.
Tip: Although it is strongly recommended that you not modify Linux files from Windows, see here for how to access Linux files from within Windows.

Option 1: From an Ubuntu terminal.

1. Start the VcXsrv configuration that you saved earlier.
   Note: You may skip this step if you do not need to display any windows, or If you opted to have the VcXsrv configuration launch when Windows starts (Option 1 much further above).
2. Launch: Ubuntu
   Note: You launch Ubuntu just like any other Windows program. For example, you can click on the Start menu (which is accessed by clicking the Windows button at the bottom left corner of your screen) and type 'ubuntu' (without quotes), and the Ubuntu 20.04 LTS icon will appear in the results list. Click on that icon to start Ubuntu and bring up a window (terminal). You can also create a shortcut on your desktop, if you prefer.
   
3. Enter (into the Ubuntu window): whatever ISIS (or Linux) command you wish
   Note: The window that comes up when you launched Ubuntu is a terminal. Simply type ISIS (or Linux) commands directly into that terminal, just as you did when displaying the DEM further above.

Option 2: From PowerShell / Command Prompt,

1. Start the VcXsrv configuration that you saved earlier.
   Note: You may skip this step if you do not need to display any windows, or If you opted to have the VcXsrv configuration launch when Windows starts (Option 1 much further above).
2. Launch: Windows PowerShell or Command Prompt
   
3. Enter (in PowerShell):
   bash -i -c '[ISIS or Linux command]'
   Note: Use single quotes in PowerShell.
   Example: bash -i -c qview '$ISISDATA/base/dems/MSGR_DEM_USG_EQ_I_V02_prep.cub'
   
   OR
   
   Enter (in Command Prompt):
   bash -i -c "[ISIS or Linux command]"
   Note: Use double quotes in Command Prompt.
   Example: bash -i -c qview "$ISISDATA/base/dems/MSGR_DEM_USG_EQ_I_V02_prep.cub"

Option 3: From Windows Python.
For example, this opens up the possibility of calling both ArcGIS (through the arcpy module) and ISIS operations in the same script.

1. Start the VcXsrv configuration that you saved earlier.
   Note: You may skip this step if you do not need to display any windows, or If you opted to have the VcXsrv configuration launch when Windows starts (Option 1 much further above).
2. Launch: Python
   
3. Enter (in Python):
   import subprocess
   p = subprocess.Popen('bash -i -c "[ISIS or Linux command]"')
   Note: Single and double quotes must be used as shown.
   Example: p = subprocess.Popen('bash -i -c "qview $ISISDATA/base/dems/MSGR_DEM_USG_EQ_I_V02_prep.cub"')

If you use the procedure described on this page, I'd love to hear about it! Success? Failure? Something in between? Please comment below! 🙂