1. Setup and Installation

The purpose of this tutorial is to demonstrate the proper setup of your Python environment so that hs_process properly runs. In this tutorial, we will:

  1. Install hs-process

  2. Confirm you are using the correct Python installation

  3. Verify that the installation was successful by executing a test script


1.1. Installing with Anaconda/conda

With Anaconda installed, please proceed to install hs_process via conda-forge:

conda install -c conda-forge hs-process

This is the easiest, most complete, and most reliable method for installation because it installs all of the dependencies from the same conda-forge channel. Before installing, it is recommended to create a new environment (see the Python Environment setup below).

1.2. Confirming your environment

It can be easy to accidentally open a Python IDE (e.g., Spyder or Jupyter Notebook) for a Python environment different that where hs_process and its dependencies were installed. The following Python command can be used to confirm you are using the Python executable in your new environment:

[1]:
import sys

sys.executable
[1]:
'C:\\Users\\nigo0024\\Anaconda3\\envs\\hs_process\\python.exe'

1.3. Testing hs_process installation

To verify hs_process and its dependencies are properly installed, the test.py can be run. First get local access to test.py:

  1. Fork, clone, or download the hs_process repository.

  2. Download sample files and place into the newly forked/cloned/downloaded hs_process\test\testdata directory (do not change the file names).

Note: There is a hyperspectral datacube that is ~750 MB, and this is why this data is not placed in the testdata folder by default (Github doesn’t allow large files). The small files should be included from Github, but the .spec and .bip files must be copied over. After copying the sample files to your testdata directory, run test.py from your command prompt:

  1. python <path to hs_process\test\test.py> to run through some basic tests to be sure all dependencies are installed properly.


1.4. Other information

1.4.1. Install Python

There are many ways to download and install Python. The Anaconda distribution is recommended becuase it can simplify the installation of package dependencies and streamlines the process of setting up the virtual environment. Anaconda also comes with Spyder and Jupyter notebooks, each of which make working with Python quite easy.


1.4.2. Create a new environment (optional)

Creating a new environment is not strictly necessary, but given that installing other geospatial packages from different channels may cause dependency conflicts, it can be good practice to install the geospatial stack in a clean environment starting fresh.

A Python environment refers to the ecosystem consisting of a particular installed version of Python, as well as any third-party packages it has access to. In Python, every time a package is installed (e.g., pip install some_third_party_package, conda install -c conda-forge some_third_party_package, etc.), your Python environment is gaining functionality that builds upon the Python Standard Library.

This is great because the possibilities of what can be accomplished using Python is virtually limitless. Ideally, the list of packages in a given environment should only include those required in the project we are working on, not all packages that have ever been installed and are needed for any project you’ve ever worked on (this can be dozens or even hundreds of packages). A downside with too many packages is that it is inefficient to share your environment with someone else that would like to use the program. As time goes on, there may also be compatibility issues among package dependencies and your code that can be avoided by creating a tidy little Python environment for your project.

With Anaconda installed, it is first recommended (but not required) to create a new Python 3.8 environment before installing package dependencies. Open an Anaconda console from the start menu as an administrator by clicking Start->Anaconda, right-click Anaconda Console, and choose to Run as Administrator. In the Anaconda Console, execute the following commands:

  1. conda create -n spec python=3.8 to create an Anaconda Python 3.8 environment named spec (you can name this whatever you’d like).

  2. conda activate spec to activate the newly configured environment. IMPORTANT: Anytime you want to use hs_process, be sure to run conda activate spec prior to opening your Python IDE via the command line (e.g. Spyder, Jupyter Notebook, etc.). Otherwise, open your IDE via Anaconda Navigator, being sure the correct environment is active.


1.4.3. System Requirements

hs_process was developed using Python 3 (on Windows 10 OS), so it is recommended to install and use Python 3. This tutorial has only been tested on Windows. It will likely work on other major platforms (i.e., Windows, Linux, Mac), but you will have to be sure to get the required dependencies installed and working on your own.


1.4.4. Software and Libraries

The following software and libraries are required to leverage the full API of hs_process:

Software

Libraries

  1. GeoPandas

  2. Seaborn (if only for visualizing data in the API examples)

  3. Spectral Python

The following libraries are also dependencies of hs_process, but they are also dependencies of GeoPandas, Seaborn, and Spectral. Therefore they will be installed during the install procedures of the above libraries.

  • GDAL *GeoPandas has a GDAL dependency

  • Numpy *GDAL has a numpy dependency

  • Pandas *GeoPandas has a Pandas dependency

  • Matplotlib *Seaborn has a Matplotlib dependency

  • Shapely *GeoPandas has a Shapely dependency


1.4.5. Other methods for installing hs_process

IMPORTANT: Before installing hs_process via any of the following methods, be sure the GeoPandas and Fiona dependencies are installed via conda (see GeoPandas and Fiona dependencies below).

  • pip install git+https://github.com/tnigon/hs_process (link) will install the latest development version directly from Github.

OR another option is to clone the Github repository and install from your local copy. After navigating to the directory of your cloned local copy:

  • pip install .

The recommended folder directory for the hs_process package is in the site-packages folder in your Python Path (alongside all other Python packages).


1.4.6. GeoPandas and Fiona dependencies

IMPORTANT: The GeoPandas and Fiona dependencies MUST installed via conda. GeoPandas has a dependency on Fiona, and because of some nuances with the pip version of Fiona*, GeoPandas MUST be installed via Anaconda (at least on Windows OS).

  • conda install -c conda-forge geopandas (link) will install both GeoPandas and fiona because GeoPandas has a fiona dependency.

*During installation, the pip version of Fiona requires that it is able to discover the locations of header files and libraries needed to compile its C extnesions, and these must be provided by the user when installing on Windows. For more information on this behavior, please refer to the Fiona documentation.