auvlib

Tools for reading AUV deployment data files and for processing and visualization of side scan and multibeam data. Extensive documentation for the python API is available at this site.

To use auvlib on Linux, it is recommended to build the library on your machine (see the following sections). On Windows, it is instead recommended to use the pre-compiled statically linked python libraries. See the releases page for details on how to install and use the latest release.

Dependencies

auvlib has been tested on Ubuntu 16.04, 18.04 and 20.04. On Ubuntu 16.04, 18.04 and 20.04, use the following command to install all dependencies:

sudo apt-get install libcereal-dev libglfw3-dev libtinyxml2-dev libboost-all-dev libopencv-dev xorg-dev

Building

Once cloned, you need to get the libigl submodule and some of its dependencies:

git submodule update --init

When done, create a build folder in the repo root, and enter:

mkdir build && cd build

Then execute the following cmake command depending on your platform:

• Ubuntu 16.04: cmake -DCMAKEINSTALLPREFIX=../install .. -DAUVLIBUSELIBIGLTINYXML=OFF -DAUVLIBUSELIBIGLGLFW=OFF
• Ubuntu 18.04: cmake -DCMAKEINSTALLPREFIX=../install ..
• Ubuntu 20.04: cmake -DCMAKEINSTALLPREFIX=../install ..

NOTE: If you are using a conda python executable, you first need to change the flag on line 78 from set(PYTHONEXECUTABLE /usr/bin/python3) to something like set(PYTHONEXECUTABLE /home/user/anaconda3/envs/[YOUR ENV NAME]/bin/python).

NOTE: Ignore the errors about the tinyxml2 and glfw targets not being in the export set; build files are still generated properly.

When done, build and intall the code using

make -j4 && make install

You should now have a compiled version of auvlib in the folder /path/to/auvlib/install. When done, please execute

export PYTHONPATH=$PYTHONPATH:/path/to/auvlib/install/lib

in any terminal where you want to use the python version of the library, or add this line to your ~/.bashrc.

Using as a python library

Python 3 is the preferred interface for auvlib. In general, the python bindings have more complete documentation and supports most of the use cases of the c++ library. Extensive documentation is available at this site.

Simple python example

As an example, in the snippet below, we read multibeam data from a .gsf file, and create an image with the vehicle track and a multibeam height map.

from auvlib.datatools import stddata, gsf_data
from auvlib.bathymaps import drawmap
import sys
gsfpings = gsfdata.gsfmbesping.parse_folder(sys.argv[1]) # parse folder of gsf data mbespings = gsfdata.convertpings(gsfpings) # convert to std_data pings
d = drawmap.BathyMapImage(mbespings, 500, 500) # create a bathymetry height map d.drawheightmap(mbes_pings) # draw the height map d.drawtrack(mbespings) # draw the track of the vehicle d.writeimage("heightmap.png") # save the height map to "height_map.png"

Advanced functionality

This example show how to drape a bathymetric mesh with sidescan data, and to generate a visualization similar to the image above. The program allows the user to click on any point in the mesh, and the draping will find all sidescan observations of that point and plot the corresponding intensity images using the datavis.plotpatch_views function.

from auvlib.datatools import stddata, gsfdata, xtfdata, csv_data, utils
from auvlib.bathymaps import meshmap, patchdraper, datavis
import sys, os, math
import numpy as np
sensor_yaw = 5.*math.pi/180. # rotation of sidescan wrt nav frame sensor_offset = np.array([2., -1.5, 0.]) # translation of sidescan wrt nav frame
gsfpings = utils.parseorloadgsf(sys.argv[1]) # parseorload* functions will just parse the first time mbespings = gsfdata.convertpings(gsfpings) # convert to std_data pings V, F, bounds = meshmap.meshfrompings(mbespings, 0.5) # generate a bathymetry mesh
xtfpings = utils.parseorloadxtf(sys.argv[2]) # load sidescan pings naventries = utils.parseorloadcsv(sys.argv[3]) # load gps nav entries xtfpings = csvdata.convertmatchedentries(xtfpings, naventries) # match sidescan with gps xtfpings = xtfdata.correctsensoroffset(xtfpings, sensoroffset) # correct for sidescan translation soundspeeds = csvdata.csvasvpsoundspeed.parsefile(sys.argv[4]) # parse sound speed file
viewer = patchdraper.PatchDraper(V, F, xtfpings, bounds, sound_speeds) # create a draper object viewer.setsidescanyaw(sensor_yaw) # set the rotation of sensor wrt nav frame viewer.setvehiclemesh(*patchdraper.getvehicle_mesh()) # add a vehicle model for visualization viewer.setpatchcallback(lambda patch: datavis.plotpatch_views([patch])) # add a plotter callback viewer.show() # show the visualization and drape

Python documentation and resources

The project directories contains examples and documentation, see pybathy_maps, pydata_tools or pysonar_tracing.

Using as a c++ library

First, initialize the submodules, same as for the previous section. For using auvlib as a library in an external project, check out the example projects. If you just want to use auvlib for reading data, please see the minimal data project.

For more complete documentation on C++ library usage, see the overview document.

Contributors

• @nilsbore
• @dawierha
• @ignaciotb
• @xyp8023
• @iyuner
• @MaxLarsson2

Acknowledgements

This work was supported by Stiftelsen för Strategisk Forskning (SSF) through the Swedish Maritime Robotics Centre (SMaRC) (IRC15-0046). See the SMARC website for details.