Installation Instructions

If you are comfortable with Git and the command prompt, check out the Minimal Installation instructions!

Here is a set of installation instructions to help you get up and running with PINGMapper. Screenshots and additional detail are provided to aid navigating this somewhat cumbersome installation procedure.

PINGMapper is a software (i.e. package) written in Python. PINGMapper uses a variety of Python packages (NumPy, Pandas, Tensorflow, etc.), or dependencies, that allow you to process Humminbird® sonar recordings and generate a variety of GIS datasets. To ensure that all the dependencies are configured correctly, we will first install a software called Miniconda, the lightweight version of Anaconda. Miniconda allows you to create virtual environments which are containers storing all the correct versions of the dependencies required to run Python software packages, ensuring everything runs as expected.

After installing Miniconda, we will procede with downloading the latest version of PINGMapper hosted on GitHub. Then, we will create a virtual environment called ping and install all the required dependencies to run PINGMapper.

Let’s get started!

Step 1 - Install Miniconda

Click this to open a web browser and navigate to the Miniconda download page.

There is a seperate installation file depending on the type of computer you are using. This tutorial was made on a Windows machine but the process should be similar on other operation systems. Click the file and it will download to your Downloads folder, or you can right-click and select “Save Link As…” and choose an alternative location to save the install file.

Double click the file to begin the installation file. This will open an installation window:

Click Next and you will see the license agreement:

After reviewing the license agreement, you must select I Agree to continue with the installation. After you agree, you will have an option to install Miniconda for Just Me or All Users.

You want to install Miniconda in your user folder so that you have the necessary permissions to install the Python dependencies, so select Just Me and click Next.

Accept the default installation location and click Next. This will open the Advanced Installation Options window.

We will accept the default options, shown above, and click Next. Once installation is complete, you will see the following window indicating Miniconda was successfully installed:

You can choose to see additional documentation on conda and Anaconda by keeping the the boxes checked. Click Finish to close the window.

Step 2

Now for the scary part! We are going to open a command prompt so that we can submit a series of commands to Miniconda. At this time, the prompt is the primary interface for installing and running PINGMapper. If you want to gain some familiarity with navigating with the prompt, you can watch this video:

Miniconda includes a command prompt called Anaconda Powershell Prompt that we will use to install and run PINGMapper. On Windows, click the start button and scroll through your installed applications until you find the Miniconda3 folder.

Click the folder are click Anaconda Powershell Prompt. This will open the prompt.

What are we seeing here? First we see the word (base). The word that is in the parenthesis tells us the name of the virtual environment that is currently activated. The base environment is activated by default. After we install PINGMapper, we will need to activate the ping environment, but more on that later. Next we see PS which I assume means Power Shell, but I’m not certain. Next, we can see what drive and folder the prompt is currently pointed to. In the case of the image above, the prompt is opened in the base of the C drive, as indicated with C:\. It may be possible that your prompt opened in your user folder, which might look like C:\Users\Cam. The key here is that whatever this path says, that is directory where the prompt is currently pointed to, and subsequently, where PINGMapper will be installed. Following the directory is the > which is where our typed commands will appear.

We need to change to a directory where we have permission to edit files, so lets first navigate to the user folder by typing the cd (i.e., change directory) command. Insert a space with the spacebar. We can begin to type the word us and use the tab key on the keyboard to autocomplete (keep clicking tab to cycle through all folders in the current directory which begin with us) to see .\Users\ and Enter or Return on the keyboard. Now we can see that we are in the directory C:\Users folder.

Now you want to go into your user folder by again issuing the cd command and beginning to type your username. My username on this computer is csb67 so I start by typing cd c then click tab until I see .\csb67 and hit Enter to step into the C:\Users\csb67 directory.

Now I am in a directory that I control and can make edits to. This is the location where your Documents, Pictures, etc. folders are located (if you are on Windows). Let’s use the prompt to make a new folder, or directory, called PythonPackages (or whatever you like) to store PINGMapper and any other Python packages you may use in the future. Issue the following command and hit Enter:

mkdir PythonPackages

Now lets move the prompt into that new folder with the following command and hit Enter:

cd PythonPackages

If you accidently moved into the wrong folder, you can use cd .. to move back one folder from the current location: Then type the directory you want to go into cd PythonPackages:

Now we are in a location where we can install PINGMapper, but we want to do something else first!

Step 3

Even though we just installed Miniconda, we want to make sure it is up-to-date with the latest packages. We can do this by running the following and hitting Enter:

conda update -n base conda

Miniconda will search for all the necessary updates and will ask if you want to proceed:

Hit Enter to accept the default answer of yes as indicated by a y in brackets [y], and the updates will be downloaded and installed. Once complete, you will see the following screen waiting for the next command:

Step 4

Miniconda has an environment solver that is built-in which it uses to make sure that the appropriate versions of package dependencies are correctly installed. It works (usually), but is pretty slow. Conda has released a new environment solver called libmamba that is considerably faster then installing environments with the classic installer. Install libmamba with the following command and hit Enter:

conda install -n base conda-libmamba-solver

Hit Enter and Miniconda will download the necessary packages and ask if you want to proceed with installation.

Hit Enter to proceed. After succcessfully installing libmamba, you will see the following indicating everything installed correctly:

To set libmamba as the default solver, submit the following and hit Enter:

conda config --set solver libmamba

You can revert to the classic installer by running:

conda config --set solver classic

Step 5

Make sure that you have git installed by running the following, hitting Enter, and proceeding with the installation by hitting Enter again:

conda install git

Step 6

Great! Now we have Miniconda installed, we are using libmamba to speed up installing package dependencies, and the prompt is located in the directory where we want to install PINGMapper (e.g., C:\Users\Cam\PythonPackages) as indicated in the prompt. Now we can download the latest version of PINGMapper by cloning the GitHub repository. We do that by issuing the following command and hitting Enter:

git clone --depth 1 https://github.com/CameronBodine/PINGMapper

We have now downloaded all the necessary scripts to run PINGMapper.

Step 7

Now we need to move the prompt into the new PINGMapper directory by issuing the following command and hitting Enter:

cd PINGMapper

The prompt must always be pointing to the PINGMapper directory in order to use the software. Use the cd command to navigate to the PINGMapper folder every time you start a session.

Step 8

Now we are going to install all the necessary packages that PINGMapper depends on in order to run. We will create a virtual environment called ping and install all the packages that are listed in a file that were previously downloaded from the repository. We do this by running the following command and hitting Enter:

conda env create --file conda/PINGMapper.yml

libmamba will solve all the package dependencies, download the packages, and install them. Once complete, you will see the following:

As instructed in the prompt, to activate the newly installed environment and use PINGMapper, issue the following command and hit Enter:

conda activate ping

We can see that ping is activated because it is listed in parenthesis (ping) instead of the default environment (base).

You must activate the ping environment every time you start a new PINGMapper session.

Step 9

Now let’s run a test to make sure everything is functioning as expected.

Back to top

This study was made possible by a partnership between the U.S. Fish and Wildlife Service and Northern Arizona University. Funding for this work was provided by the Open Ocean Trustee Implementation Group to restore natural resources injured by the 2010 Deepwater Horizon oil spill in the Gulf of Mexico. The contents of this website are those of the authors and do not necessarily represent the views of the U.S. Fish and Wildlife Service or Northern Arizona University. Copyright © 2024 Cameron Bodine.