search

patrykcieslak / stonefish

Stonefish - an advanced C++ simulation library designed for (but not limited to) marine robotics.
https://stonefish.readthedocs.io/
GNU General Public License v3.0
126 stars 32 forks source link
auv fluid-dynamics marine research robotics rov simulation sonar underwater-robotics

readme

Stonefish logo

Stonefish

An advanced simulation tool developed for marine robotics.

Stonefish is a C++ library combining a physics engine and a lightweight rendering pipeline. The physics engine is based on the core functionality of the Bullet Physics library, extended to deliver realistic simulation of marine robots. It is directed towards researchers in the field of marine robotics but can as well be used as a general purpose robot simulator.

Stonefish includes advanced hydrodynamic computations based on actual geometry of bodies, to better approximate hydrodynamic forces and allow for effects not possible when using symbolic models. The rendering pipeline, developed from the ground up, delivers realistic rendering of atmosphere, ocean and underwater environment. Special focus was put on the latter, where effects of wavelength-dependent light absorption and scattering were considered (other simulators often use only blue fog).

Stonefish can be used to create standalone applications or combined with a Robot Operating System (ROS) package _stonefishros, which implements standard simulator node and facilitates easy integration with ROS architecture.

There are two sources of documentation for the library: html documentation generated with Sphinx and code documentation generated with Doxygen, based on comments in the code (instructions below).

Requirements

The simulation is CPU heavy and requires a recent GPU. The minimum requirement is the support for OpenGL 4.3.

Install official manufacturer drivers for your graphics card before using Stonefish!

The software is developed and tested on Linux Ubuntu. It should work on any Unix based platform. A version for Windows is not available at this time. MacOS is not supported due to its lack of support for OpenGL 4.3.

Installation

  1. Dependencies

    • OpenGL Mathematics library (libglm-dev, version >= 0.9.9.0)
    • SDL2 library (libsdl2-dev, may need the following fix!)
      1. Install SDL2 library from the repository.
      2. cd /usr/lib/x86_64-linux-gnu/cmake/SDL2/
      3. sudo vim sdl2-config.cmake
      4. Remove space after "-lSDL2".
      5. Save file.
    • Freetype library (libfreetype6-dev)

  2. Building

    1. Clone stonefish repository.
    2. cd stonefish
    3. mkdir build
    4. cd build
    5. cmake ..
    6. make -jX (where X is the number of threads)
    7. sudo make install

  3. Documentation

    1. Go to "stonefish" directory.
    2. doxygen doxygen
    3. Open "docs/html/index.html".

Credits

This software was written and is continuously developed by Patryk Cieślak. Parts of the software based on code developed by other authors are clearly marked as such.

If you find this software useful in your research, please cite:

Patryk Cieślak, "Stonefish: An Advanced Open-Source Simulation Tool Designed for Marine Robotics, With a ROS Interface", In Proceedings of MTS/IEEE OCEANS 2019, June 2019, Marseille, France

@inproceedings{stonefish,
   author = {Cie{\'s}lak, Patryk},
   booktitle = {OCEANS 2019 - Marseille},
   title = {{Stonefish: An Advanced Open-Source Simulation Tool Designed for Marine Robotics, With a ROS Interface}},
   month = jun,
   year = {2019},
   doi={10.1109/OCEANSE.2019.8867434}}

Support

I offer paid support on setting up the simulation of your own systems, including necessary 3D modelling (simplification of CAD models for physics, preparation of accurate visualisations, etc.), setup of simulation scenarios, development of new sensors, actuators, and custom features that do not require significant changes to the code base. Please contact me at patryk.cieslak@udg.edu.

Funding

Currently there is no funding of this work. It is developed by the author following his needs and requests from other users. The work was started during his PhD studies and was mainly developed in his free time. Parts of this work were developed in the context of the project titled ”Force/position control system to enable compliant manipulation from a floating I-AUV”, which received funding from the European Community H2020 Programme, under the Marie Sklodowska-Curie grant agreement no. 750063. The work was also extended under a project titled ”EU Marine Robots”, which received funding from the European Community H2020 Programme, grant agreement no. 731103.

License

This is free software, published under the General Public License v3.0.