Installation¶

Bethic Photo Survey (BPS) runs on Linux, Mac, and Windows operating systems. There are a few different ways to install BPS. You can download the code from the bitbucket, you can install with the python pip installer, or you can git to clone the code from the bitbucket repository. More details are provided below along with information about software requirements and details specific to installing on different platforms.

Requirements¶

The following items need to be installed in order for BPS to work. Make sure you read at least to the end of this section before you start installing this stuff. There may be an easier way than installing all these things individually. Then check the section below for your operating system. There may be seperate quirks to the installation process for Windows, Linux, and Mac. I will try to give step-by-step instructions for each operating system below.

Python 2.7 BPS may work on older versions of Python but I wouldn’t bet on it
GDAL 1.8 or greater
Matplotlib 1.1.1 or greater, can be installed as part of SciPy or with PythonXY (see end of this section).
PyQt4
pynmea can be installed with pip by typing pip install pynmea at the command prompt (or sudo pip install pynmea if you’re on Linux or Mac and need root privileges to install).
pyexiv2 has actually been deprecated now. I will eventually rewrite the code to use GExiv2 but, for now, pyexiv2 is required.

That’s kind of a lot of stuff to have to install. Fortunately, items 1 - 4 can be taken care of with the PythonXY installer. PythonXY is a set of free scientific software tools all bundeled together for easy installation. You can download the PythonXY installer, run it, make sure that items 1 - 4 are selected, and it will take care of all those steps for you. If you decide later that you want some of the other items to be installed as well, you just run the installer again and check more boxes. It makes things much easier, especially on Windows.

Ways to Get BPS¶

There are two different ways to get release versions of BPS and one way to get the latest code from the repository. These are outlines of the steps needed that should be applicable to all operating systems. For a more step-by-step approach, check the OS specfic sections further down the page.

Installing the Latest Release with pip¶

Go to the command line and type pip install BenthicPhotoSurvey. Depending on your OS, you may need to type sudo pip install BenthicPhotoSurvey instead and enter your root password.

In order to run BPS, you have to figure out where pip installed the code and that can vary according to OS and configuration. If you have version of pip >= 1.2.1.post1, you can figure it out by typing pip show BenthicPhotoSurvey on your command line. The response should contain the location of the benthic_photo_survey directory. To run BPS, navigate to that directory and start BPS by typing python benthic_photo_survey.py (on Windows, you’ll leave off the python and just type benthic_photo_survey.py).

On my computer it looks somthing like this:

blah@blahbidyblah:~$ pip show BenthicPhotoSurvey
---
Name: BenthicPhotoSurvey
Version: 0.1
Location: /usr/local/lib/python2.7/dist-packages
Requires:

So, to launch, I type:

blah@blahbidyblah:~$ cd /usr/local/lib/python2.7/dist-packages/benthic_photo_survey
blah@blahbidyblah:/usr/local/lib/python2.7/dist-packages/benthic_photo_survey$ python benthic_photo_survey.py

...and the program should run and you can move on to the Tutorial. I will, hopefully, get around to packaging BPS a little better so it’s easier to launch after installing but this will have to do for now.

Downloading and Installing a Release from bitbucket¶

Use your web browser to download the code from bitbucket. Unzip that file somewhere. Navigate into the benthic_photo_survey directory that contains benthic_photo_survey.py and type python benthic_photo_survey.py (on Windows, you’ll leave off the python and just type benthic_photo_survey.py).

Getting the Latest Code from bitbucket¶

First, make sure you have git installed. Then open the command line where you’d like to put the code and type git clone https://jkibele@bitbucket.org/jkibele/benthic_photo_survey.git. That will download the latest code which may not be stable. To run it just follw the instructions from the previous subsection.

Windows¶

The following steps will demostrate how to install the software required to run BPS, use the git version control system to download BPS, and then run BPS on Windows.

Satisify Install Requirements 1 - 4 with PythonXY
1. Download the latest PythonXY installer from the PythonXY Windows Download Page. Just click on one of the .exe files listed under ‘Current Release’. The multiple links all lead to the same file, just on different servers.
2. Run the installer, and make sure that Python2.7.x (currently 2.7.3 but that may change, you just don’t want 3.x), GDAL, PyQt4.x, pip, and Matplotlib are selected. These items are listed under the expandable python menu. You can check whatever additional items you’d like installed as well.
3. Click through the dialogs to finish the installation process.
Install pynmea with pip
1. Go to the command prompt and type pip install pynmea. If you installed pip in the previous step, that command should work and you should be able to move on to the ‘installing pyexiv2’ step below. If there was a problem with pip, you can use the sub-steps below to install it.
2. If you get a message that says something about the ‘command pip not found’, then try typing easy_install pip at the command prompt. If that doesn’t work, you’ll need to install python-distribute and pip as described in the next sub-step. If it does work (and it installs pip), just go back to the previous sub-step and it should work.
3. Download the correct installer for your system architecture (32 or 64 bit) from the list of python-distribute installers. We installed python2.7.x so you want the one that matches your system architecture and ends with py2.7.exe. After running that installer, you should be able to type easy_install pip followed by pip install pynmea. The good news is that python-distribute and pip can be used to install all sorts of useful python stuff and, now that you have them installed, that’ll be easy.
Install pyexiv2
1. Go to the pyexiv2 download page, scroll down to the Windows section appropriate to your system (32 or 64 bit) and download the latest installer for Python 2.7. Note that the latest versions are at the bottom of the list rather than the top.
2. Run the installer
Install git if you don’t already have it
1. Go to the git download page, download the installer for your system, and run it.
2. The default list of components on the ‘Select Components’ screen is fine.
3. The choice of ‘Start Menu Folder’ doesn’t really matter. I used the default.
4. On the next screen, choose “Run Git from the Windows command prompt”.
5. On the ‘Configure Line Ending’ screen, select the default of ‘Checkout Windows-style, commit, unix-style’.
Use git to get BPS
1. Open a command prompt and navigate to a directory where you would like to install BPS
2. Type git clone https://jkibele@bitbucket.org/jkibele/benthic_photo_survey.git. This will clone the contents of BPS code repository to your computer.
3. If, after changes have been made to BPS, you want the latest version you can return to a command prompt in this directory and type git pull.

That should do it. Make sure you make a note of where you installed BPS. Then take a look at the Tutorial. I intend to add a section there specifically about using the test data for a dry run. For now just check out the “Using BPS” section and look for the test_data directory at the same level as the data directory. There are some images, a gps log, and a sensus depth log in there that you can use to get the hang of it.

Mac¶

Need to write up these steps too.

Ubuntu¶

Need to write up these steps too.

Testing¶

I will describe how to run the automated tests and how to use the test data that’s installed with BPS to make sure everything is working.