Welcome to Benthic Photo Survey’s documentation!¶
Benthic Photo Survey (BPS) is a software tool (written in Python) that is intended to simplify the task of collecting reference data (sometimes called groundtruth data) for remote sensing of the marine environment. Using a digital camera in a water proof housing, a consumer grade handheld GPS, and (optionally) a depth logger a user can collect data in the field.
-
The photos and logs (GPS and Depth) are then loaded into BPS. BPS can then tag the photos with position, depth, and temperature (if using the Sensus Ultra depth/temperature logger). The the users can view each photo in BPS and tag each photo with a substrate and habitat type. All data (position, depth, temperature, habitat, and substrate) are stored in the exif portion of the jpeg photos.
Once the photos are all tagged, BPS can export a GIS Shapefile with habitat, substrate, depth, and temperature attributed points for each photo’s location. This shapefile can then be used to create a training set for supervised classification or as reference data for accuracy assessment.
+
Contents¶
ContentsWhat BPS Actually Does -
-
-
- Requirements -
- Ways to Get BPS -
- Windows -
- Mac -
- Ubuntu -
- Testing +
- Installation +
- Learning BPS
-
+
- WARNING! +
- Tutorial +
- Field Work -
- Tutorial
- Code Documentation @@ -141,7 +136,7 @@
- next | -
- Benthic Photo Survey 1.0.0 documentation » +
- Benthic Photo Survey 1.0.1 documentation »
Navigation
Navigation
IMPORTANT NOTE:¶
-Most of this information is out of date. Go to the GitHub Repository or BPS page for up to date information. I will update these docs but haven’t had time yet.
-Installation¶
-Bethic Photo Survey (BPS) can run on Linux, Mac, and Windows operating systems. There are a few different ways to install BPS.
-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 a different library 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 -
-
-
- 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. -
- 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. -
- Click through the dialogs to finish the installation process. -
-
--
-
- Install pynmea with pip -
-
-
- 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. -
- 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. -
- 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 -
-
-
- 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. -
- Run the installer -
-
--
-
- Install git if you don’t already have it -
-
-
- Go to the git download page, download the installer for your system, and run it. -
- The default list of components on the ‘Select Components’ screen is fine. -
- The choice of ‘Start Menu Folder’ doesn’t really matter. I used the default. -
- On the next screen, choose “Run Git from the Windows command prompt”. -
- On the ‘Configure Line Ending’ screen, select the default of ‘Checkout Windows-style, commit, unix-style’. -
-
--
-
- Use git to get BPS -
-
-
- Open a command prompt and navigate to a directory where you would like to install BPS -
- Type git clone https://jkibele@bitbucket.org/jkibele/benthic_photo_survey.git. This will clone the contents of BPS code repository to your computer. -
- 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.
-Bethic Photo Survey (BPS) can run on Linux, Mac, and Windows operating systems. For installation instructions please see the BPS Installation Page.
Testing
@@ -63,7 +63,7 @@ What You Need to use BPSPanasonic Lumix DMC-TS4 in an Ikelite housing. This camera has a built in compass that records the direction that the camera is facing when the photo is taken and BPS passes the direction into the shapefile that is created. However, this is not a requirement and any camera that produces jpeg images should be compatible with BPS.
A GPS that can be towed by a snorkeler or diver. If you’re working with fairly high resolution imagery, you’ll want a GPS receiver with WAAS capability. I am using a Garmin GPS 60 CSX. I tow mine in a small waterproof plastic box on a float. See GPS Photo Transects for Benthic Cover Manual by Roelfsema and Phinn [RP2010] for details on how to build a float. BPS can import NMEA text files and GPX files.
A depth logger is optional but if you’re going to spend the time and money to go in the field, it seems worthwhile. BPS is set up to import log files from the Sensus Ultra depth and temperature logger. It should be fairly easy to adapt it to deal with a different logger but that would require a bit of coding.
-A computer to run BPS. BPS was developed on Ubuntu but should work on Windows and Mac as well.
+A computer to run BPS. BPS was developed on Ubuntu but is also available for Windows. In theory it will run on Mac as well but has almost no testing there.
What BPS Actually DoesThere are 4 steps to what BPS does.
- It imports your GPS and/or depth and temperature logs into a database.
-- It writes data from those logs to the exif portion of each of your jpeg photos based on the time stamp on each photo and the time stamps in the respective logs.
-- You use BPS to tag each photo with a habitat and/or depth and temperature.
+- It writes data from those logs to the Exif portion of each of your jpeg photos based on the time stamp on each photo and the time stamps in the respective logs.
+- You use BPS to tag each photo with habitat and/or substrate information. This is also written to the Exif portion of each photo.
- BPS can export a point shapefile with a point at each location where a photo was taken. Each point is attributed with the habitat, substrate, depth, temperature, direction, and file path to the photo.
-Citations
+References
-| [RP2009] | Roelfsema, C., Phinn, S.R., 2009. A Manual for Conducting Georeferenced Photo Transects Surveys to Assess the Benthos of Coral Reef and Seagrass Habitats version 3.0. |