Installing UWSim

Requirements

The simulator has been tested in Ubuntu Linux from 9.10 to 18.04. However, it should work on other linux-based distributions. MacOS and Windows have not been tested for now, but it should be possible to run UWSim also on these systems, since all the libraries used are also available for them.

You will need a decent PC, with a good graphics card. It should work well on recent NVidia and ATI cards with good driver support in GNU/Linux. Have a look to the list of cards that are known to be working. If you see strange visualization effects, or it just crashes before beginning, it probably means your card does not meet the requirements (if this is the case, try with the --disableShaders option) or you need to install propietary drivers for your card. As an example, it runs fluently on a MacBook Pro 2.26 Ghz Intel Core 2 Duo, 4 GB DDR3 with an NVIDIA GeForce 9400M, running Ubuntu 11.04.

Finally, you will also need ROS. It has been tested on ROS cturtle, diamondback, electric, fuerte, groovy, hydro, indigo, jade, kinetic and melodic. For ROS installation instructions, refer to the following link:

[ROS installation instructions]

Installation

Depending on your requirements and system there are different installation options:

• Package-based installation: is the easiest one, but it may not have the latest features.
• UWSim Source-based installation: Installs the underwater simulator from source and downloads UWSim libraries from packages. Fast building, latest features, avoids catkin isolated but can't modify libraries (osgocean, bullet, osg_markers).
• Full Source -based installation: Installs simulater and libraries from source. Complete control for developing, latest features but slower and harder building.
• Source-based installation previous to ROS Groovy: Installs UWSim for ROS versions previous to groovy. Old versions of UWSim, not recommended.

Finally you can also try a Virtual Machine with UWSim 1.4.1 already installed under Ubuntu 14.04 Mate and ROS Indigo. To do so just download it from here, virtualize it(user/password: uwsim) and jump to running section.

Package-based installation

There are deb packages pre-compiled for Ubuntu and ROS Groovy / Hydro / Indigo / Jade / Kineetic / Melodic. Assuming you have the ROS repositories already added to your sources.list, the following command will install UWSim and all its dependencies (change melodic for your ROS installation):

 apt-get install ros-melodic-uwsim

UWSim Source-based installation

This section explain how to build UWSim from sources in ROS melodic and downloading other required UWSim libraries from packages (such as uwsim-osgocean) avoiding catkin_make_isolated so you can use catkin_make.

Download sources

Create a catkin workspace and place a .rosinstall file inside it with the following contents:

- git: {local-name: src/underwater_simulation, uri: 'https://github.com/uji-ros-pkg/underwater_simulation.git', version: melodic-devel}

Then download the sources with:

rosws update

Configure & build

Install the dependencies and build the sources with cakin:

rosdep install --from-paths src --ignore-src --rosdistro melodic -y
catkin_make install

Full Source-based installation

This section explain how to build UWSim and its libraries from sources in ROS melodic and later distributions. For later distributions, just replace 'melodic' by the corresponding distro name.

Download sources

Create a catkin workspace and place a .rosinstall file inside it with the following contents:

- git: {local-name: src/uwsim_osgocean, uri: 'https://github.com/uji-ros-pkg/uwsim_osgocean.git', version: melodic-devel}
- git: {local-name: src/uwsim_osgworks, uri: 'https://github.com/uji-ros-pkg/uwsim_osgworks.git', version: melodic-devel}
- git: {local-name: src/uwsim_bullet, uri: 'https://github.com/uji-ros-pkg/uwsim_bullet.git', version: melodic-devel}
- git: {local-name: src/uwsim_osgbullet, uri: 'https://github.com/uji-ros-pkg/uwsim_osgbullet.git', version: melodic-devel}
- git: {local-name: src/visualization_osg, uri: 'https://github.com/uji-ros-pkg/visualization_osg.git', version: melodic-devel}
- git: {local-name: src/dccomms_ros_pkgs, uri: 'https://github.com/dcentelles/dccomms_ros_pkgs.git', version: master}
- git: {local-name: src/underwater_simulation, uri: 'https://github.com/uji-ros-pkg/underwater_simulation.git', version: melodic-devel}

Then download the sources with:

rosws update

Configure & build

Install the dependencies and build the sources with cakin:

rosdep install --from-paths src --ignore-src --rosdistro melodic -y
catkin_make_isolated --install

Source-based installation previous to ROS Groovy

This section explain how to build UWSim from sources in ROS distributions previous to Groovy.

Download sources

Download the underwater_simulation stack to a folder in your ROS_PACKAGE_PATH:

git clone https://github.com/uji-ros-pkg/underwater_simulation.git

Configure & build

First install the UWSim dependencies with the following command:

rosdep install UWSim

This will ask for your password in order to install all the necessary packages with apt-get. After this, you can build the simulator:

rosmake UWSim

This will first download and compile osgOcean. After that the UWSim package will be built.

Running

First be sure that a roscore is already running. If not, start it:

roscore

After that, the following command should start UWSim:

rosrun uwsim uwsim

The first time you run UWSim, it will ask for downloading a data package that will be installed under ~/.uwsim. After that, a window should appear showing a default scenario and robot. Inside the simulator, you can freely move the camera with the mouse. With the simulator running, you can check the list of ROS topics involved:

rostopic list

and subscribe/publish to them with rostopic and rospub, or with your custom ros control nodes. The are some example ROS interface nodes in the interface_examples folder. For example, the following command should update the vehicle position in the default scenario (2 meters along positive X axis):

rosrun uwsim setVehiclePosition /dataNavigator 2 0 0 0 0 0

Now that UWSim is correctly installed and working is time for Configuring and creating scenes or go directly to First steps: Interacting with UWSim.

Issues: If you are getting the following error output when starting uwsim:

...
data/objects/gun.osg
Starting UWSim...
Loading SimulatedDevices plugin: 'AcousticCommsDevice_Factory'
Loading SimulatedDevices plugin: 'CustomCommsDevice_Factory'
Loading SimulatedDevices plugin: 'DredgeTool_Factory'
Loading SimulatedDevices plugin: 'ForceSensor_Factory'
Loading SimulatedDevices plugin: 'SimDev_Echo_Factory'
 . Setting localized world: 7.1e-05s
terminate called after throwing an instance of 'GeographicLib::GeographicErr'
 what():  File not readable /usr/share/GeographicLib/geoids/egm96-5.pgm
/opt/ros/melodic/lib/uwsim/uwsim: line 23:  1452 Aborted                 (core dumped) rosrun uwsim uwsim_binary --dataPath ~/.uwsim/data $@

Run the following commands to fix it:

 wget https://raw.githubusercontent.com/mavlink/mavros/master/mavros/scripts/install_geographiclib_datasets.sh
 chmod u+x install_geographiclib_datasets.sh
 sudo ./install_geographiclib_datasets.sh