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.
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
Once cloned, you need to get the libigl submodule and some of its dependencies:
git submodule update --init
NOTE: If you are using 20.04, you need to change a few things because you are probabaly using OpenCV 4.2.0. Change all CV_AA to cv::LINE_AA in the following files: src/bathy_maps/src/draw_map.cpp, src/data_tools/src/benchmark.cpp and src/data_tools/src/test_submap_tracks.cpp. See this Reference.
NOTE: If you want to use python3 (which I recommend) you need to change a few lines of the src/CMakeLists.txt before compling:
If you are using the default /usr/bin/python3, you only need to change the flag AUVLIB_USE_PYTHON3 in src/CMakeLists.txt to ON; if you are using the conda,
you need to change the flag AUVLIB_USE_PYTHON3 to ON AND line 78 from set(PYTHON_EXECUTABLE /usr/bin/python3) to set(PYTHON_EXECUTABLE /home/user/anaconda3/envs/envname/bin/python)
NOTE: On 18.04 and 20.04 you currently also need to provide the flags
-DAUVLIB_USE_LIBIGL_TINYXML=ON -DAUVLIB_USE_LIBIGL_GLFW=ON to cmake below.
In that case, ignore the error about the tinyxml2 and glfw targets not being in the export set;
build files are still generated properly.
When done, create a build folder in the repo root, and run
cd build
cmake -DCMAKE_INSTALL_PREFIX=../install ..
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 2.7 version of
the library, or add this line to your ~/.bashrc.
Python 2.7 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.
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.data_tools import std_data, gsf_data
from auvlib.bathy_maps import draw_map
import sys
gsf_pings = gsf_data.gsf_mbes_ping.parse_folder(sys.argv[1]) # parse folder of gsf data
mbes_pings = gsf_data.convert_pings(gsf_pings) # convert to std_data pings
d = draw_map.BathyMapImage(mbes_pings, 500, 500) # create a bathymetry height map
d.draw_height_map(mbes_pings) # draw the height map
d.draw_track(mbes_pings) # draw the track of the vehicle
d.write_image("height_map.png") # save the height map to "height_map.png"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 data_vis.plot_patch_views
function.
from auvlib.data_tools import std_data, gsf_data, xtf_data, csv_data, utils
from auvlib.bathy_maps import mesh_map, patch_draper, data_vis
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
gsf_pings = utils.parse_or_load_gsf(sys.argv[1]) # parse_or_load* functions will just parse the first time
mbes_pings = gsf_data.convert_pings(gsf_pings) # convert to std_data pings
V, F, bounds = mesh_map.mesh_from_pings(mbes_pings, 0.5) # generate a bathymetry mesh
xtf_pings = utils.parse_or_load_xtf(sys.argv[2]) # load sidescan pings
nav_entries = utils.parse_or_load_csv(sys.argv[3]) # load gps nav entries
xtf_pings = csv_data.convert_matched_entries(xtf_pings, nav_entries) # match sidescan with gps
xtf_pings = xtf_data.correct_sensor_offset(xtf_pings, sensor_offset) # correct for sidescan translation
sound_speeds = csv_data.csv_asvp_sound_speed.parse_file(sys.argv[4]) # parse sound speed file
viewer = patch_draper.PatchDraper(V, F, xtf_pings, bounds, sound_speeds) # create a draper object
viewer.set_sidescan_yaw(sensor_yaw) # set the rotation of sensor wrt nav frame
viewer.set_vehicle_mesh(*patch_draper.get_vehicle_mesh()) # add a vehicle model for visualization
viewer.set_patch_callback(lambda patch: data_vis.plot_patch_views([patch])) # add a plotter callback
viewer.show() # show the visualization and drapeThe project directories contains examples and documentation, see pybathy_maps, pydata_tools or pysonar_tracing.
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.
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.