First steps: Interacting with UWSim

Now that UWSim is already installed and running is time to interact with it and move our AUV through the scene, read some sensors or move the robotic arm. Furthermore we may want to low the ocean level or show where our vehicle sensors are. In this short tutorial we will present the different ways to control UWSim simulations. There are two main ways of interacting, pressing keys and mouse over the main window and using ROS interfaces.

Since UWSim version 1.4, it is also possible to interact through ROS markers and interactive markers.

Main window interaction

Using the main window we can do basic things that will change the view of the simulator, but most of this changes will not be noticeable for sensors or AUV. First of all main camera can be moved using mouse as a trackball, pressing left button will allow us to rotate the camera, right button or mouse wheel will change the zoom and third button is used for moving through the scene. If you get your camera lost dont panick!, pressing space will move it to its initial position. Besides this, the following key buttons have an action:

• c: Enables / Disables camera widgets, pressing this button will show the virtual cameras in small widgets. This widgets can be moved and resized using left and third mouse buttons.
• f: Enables / Disables visible frames for vehicle joints and sensors. Pressing f button will show/hide frame axes (red: x, green: y, blue: z) for every joint and sensor present in the scene. Furthermore a label with its name will be showed.
• t: Enables / Disables trajectory view. Pressing t will show/hide the trajectories shown.
• r: Restarts the scene to its initial values.
• y: Clears trajectory. This key allows user to clear the current trajectory. note: you will need to move the vehicle/object to see it disappear.
• 1: Switch to clear blue sky scene. Changes light and fog conditions.
• 2: Switch to clear dusk scene. Changes light and fog conditions.
• 3: Switch to clear pacific cloudy scene. Changes light and fog conditions.

Furthermore osgOcean provides its own interaction ways, pressing h will show a description of them. Unfortunately some of them DO NOT work due to the integration with UWSim (red color).

• +: Raises the ocean surface.
• -: Lowers the ocean surface.
• <: Decrease the screen resolution (windowed mode).
• >: Increase the screen resolution (windowed mode).
• D: Toggle autodirty (if off, changes will require manual dirty).
• G: Toggle God rays (underwater).
• H: Toggle height lookup for shoreline foam and sine shape (above water).
• K: Increase wave scale factor by 1e-9 (dirties geometry if autodirty is active).
• P: Print out current ocean surface settings.
• R: Toggle refractions (underwater).
• S: Output stats to console.
• T: Toggle scattering (underwater).
• Trackball Space: Reset the viewing position to home.
• W: Increase wind speed by 0.5 (dirties geometry if autodirty is active).
• b: Toggle backface culling.
• d: Dirty geometry manually.
• f: Toggle full screen.
• g: Toggle glare (above water).
• h: onscreen help.
• k: Decrease wave scale factor by 1e-9 (dirties geometry if autodirty is active).
• l: Toggle lightning.
• o: Toggle Depth of Field (DOF) (underwater).
• p: Toggle choppy waves (dirties geometry if autodirty is active).
• r: Toggle reflections (above water).
• s: On screen stats.
• t: toggle texturing.
• w: Toggle polygon fill mode between fill, line (wire frame) and points.

If something of the above is not working as it should, or you have any enhancement idea. Please open an issue on github project.

ROS interfaces interaction

Ros interface interaction allows to send and receive information about sensors and actuators. So this is the main way to move and control your AUV. If you don't know anything about ROS and ROS topics, please check this. Available interfaces must be configured in the XML scene file using rosInterfaces, for a detailed explanation on how to do that take a look at Configuring and creating scenes. Once the simulator has started every configured interface should be available, and can be listed executing:

rostopic list

This will show every available topics in the system, including UWSim if running. Some interface examples are provided inside "interface_examples" folder. These small pieces of code should show basic ROS functionality interacting with UWSim, although not every interface/sensor has an example. Now we will make a brief explanation of each example available and how to use it. You can check the source code here for more information.

Set vehicle velocity

Set vehicle velocity example is one of the most simple interface examples. It just sends an odometry message to ROSOdomToPAT interface with linear and angular velocity. When UWSim receives this message the vehicle with the associated ROS interface will start moving. Take into account this is a kinematic example (no forces, no accelerations. Vehicle will move at the stated velocity), for dynamic examples you can check First steps: Dynamic simulation. To sum up this interface is an example of creating an odometry message and send it. Topic and desired velocities are taken from command line in the format [topic] [x] [y] [z] [r] [p] [y]. Units are m/s and rad/s. In order to use it you can use the following command in the default scene (cirs.xml):

rosrun uwsim setVehicleVelocity /dataNavigator 0.2 0 0 0 0 0

This command will make the vehicle start moving forward at 0.2 m/s until the example program is stopped (ctrl-c). If we want to move the vehicle deeper in the scene we will use:

rosrun uwsim setVehicleVelocity /dataNavigator 0 0 0.5 0 0 0

Finally, the following command will make the vehicle turn.

rosrun uwsim setVehicleVelocity /dataNavigator 0 0 0 0 0 0.2

Set vehicle position

This example is similar to the previous one, but in this case instead of setting a vehicle velocity we will set vehicle position. It also sends an odometry message to ROSOdomToPAT, but it uses pose instead of velocity. As soon as UWSim receives this message it will move the vehicle to the desired position. The usage is exactly the same: [topic] [x] [y] [z] [r] [p] [y], but in this example units are meters and radians. This orders should move the vehicle in the default scene (cirs.xml):

 rosrun uwsim setVehiclePosition /dataNavigator 1.0 0 0 0 0 0

It will move the vehicle to (1.0,0,0) in cartesian space. As can be seen, no matter where the vehicle was, we are moving the vehicle to absolute world coordinates, that is the reason why we don't need to subscribe to any other topic. Using the following command will move the vehicle to (0.0,2.0,2.0) and rotate it 180º.

 rosrun uwsim setVehiclePosition /dataNavigator 0 2.0 2.0 0 0 3.14

Take into account, it is not possible to move the vehicle if this program is running as it is continuously sending a ROS message with the position for the vehicle.

Set vehicle twist

Sometimes using odometry messages to set position and velocities may lead to errors as only one of them is used (if position is different to 0 velocity information will be ignored). Furthermore we may want to disable some kind of interaction in our scenes and only move the vehicle using velocities or positions depending on the situation. That is why this example uses ROSTwistToPAT interface to send only velocity information. The usage is exactly the same as set vehicle velocity. This commands will have the same result as the ones in set vehicle velocity in the default scene:

rosrun uwsim setVehicleTwist /g500/twist 0.2 0 0 0 0 0
rosrun uwsim setVehicleTwist /g500/twist 0 0 0.5 0 0 0
rosrun uwsim setVehicleTwist /g500/twist 0 0 0 0 0 0.2

Set vehicle pose

As in the previous example this example avoids using odometry messages and only sends pose information through a ROSPoseToPAT interface. The usage is analog to set vehicle position, so this commands should have the same result as the set vehicle position ones.

rosrun uwsim setVehiclePose /g500/pose 1.0 0 0 0 0 0
rosrun uwsim setVehiclePose /g500/pose 0 2.0 2.0 0 0 3.14

Set joint position

Now that we already know how to move the vehicle, we may need to move the joints of our AUV. To do so we will need a ROSJointStateToArm interface so we can send joint state information to UWSim. This interface allows positions and joints (as happened with vehicle odometry), and only one of them will be used in each message. In the case of receiving both, UWSim will automatically discard velocity information. Another important thing to take into account is joint names are important, in our message we need to use the same joint names as stated in the URDF file. Although it is not necessary to fill every joint in a joint state message, this example does it. UWSim respects URDF joint limits, and in the case of receiving a message with higher/lower value it will set the max/min allowed.

This example is suitable for ARM5, available in the default scene attached to girona500 vehicle. The usage is [topic] [q1] [q2] [q3] [q4] [q5], being qX the different joints in the ARM5 from the base to the end effector (slew, shoulder, Elbow, jawRotate and jawOpening). The units are radians. This example only sends joint state messages to UWSim in order to move the ARM5 using only position information. Here is an example on how to use it:

rosrun uwsim setJointPosition /uwsim/joint_state_command 0 1.57 0 0 0.5
rosrun uwsim setJointPosition  /uwsim/joint_state_command 0 2.5 0 0 0

In the case of the second order, we are trying to move the arm over the joint limit, UWSim will not let us and it will set it's max value: PI/2, stated in the URDF file.

Set joint velocity

This example uses a ROSJointStateToArm interface to move the robot joints sending velocities instead of positions. Note: the movement is kinematic (no forces, no accelerations). This interface uses the same usage as the previous one, but units are rads/s. Some examples of use:

rosrun uwsim setJointVelocity /uwsim/joint_state_command -0.1 0 0 0 0

This command will rotate the arm slew, while the following will extend the arm forward.

rosrun uwsim setJointVelocity /uwsim/joint_state_command 0 0.1 -0.1 0 0

ROS Markers and interactive markers interaction

Since version 1.4, it is possible to interact with UWSim using ROS markers. To do so, visualization_osg package has been updated and it is used to provide basic OSG visualization capabilities for markers. Although some features are still not working, main functionality is working and available in ros debians and in our github. Although we are using a different library for visualization, messages and interface are the same as ROS examples, so you may use any previous work in UWSim.

By default UWSim, will start "/SpawnMarker" service, which will hear to "underwater_sensor_msgs/SpawnMarker" services, and topics under "uwsim_markers" namespace for interactive markers. The first service allows you to send marker messages to create, modify or destroy markers inside UWSim, while the uwsim marker topics provide interaction capabilities.

Unfortunately the geometry created in the scene through this method will not have physical reactions on the physics engine. This is something still in our To-do list. We hope to add it soon!.

We have created two simple interface examples to show the possibilities of this feature:

Spawn Marker

This simple example, creates, modifies or deletes a mesh marker in the UWSim scene in the desired pose. To do so we can use the following command, which will create a black box near the existing one (cirs.xml scene).

 rosrun uwsim spawnMarker add BB 1 blackbox_uib_trimesh.osg 0 0 4.1 0 3.14 0

The syntax for the example is "rosrun uwsim spawnMarker <action> <name> <id> <mesh> <x> <y> <z> <roll> <pitch> <yaw>". Possible actions are "add" and "del", if we want to modify an existing item using add and setting the existing name and if will do it. Name and id will be the marker identifiers in order to modify or delete it in the future, id must be an integer. Mesh is the 3D model of the object that will be added, it must be available in the data folders of UWSim: "~/.uwsim/data". Finally we must specify the pose of the object.

Taking this into account the following orders will modify and delete the object:

 rosrun uwsim spawnMarker add BB 1 blackbox_uib_trimesh.osg 0 0.4 4.1 0 3.14 0
 rosrun uwsim spawnMarker del BB 1 blackbox_uib_trimesh.osg 0 0.4 4.1 0 3.14 0

Follow Marker

Follow marker example creates an interactive marker in the scene that the desired vehicle will follow. To run this example just execute:

 rosrun uwsim followMarker /dataNavigator

A 6DOF dragger should appear in the scene (position 0, 0, 0) with a small cube marker inside of it. This dragger can be moved through the scene using the mouse while pressing control key (hold control and then click with the mouse in the desired arrow or rotation frame to move it). As soon as the interactive marker has moved the Girona500 vehicle (The vehicle that provides the stated interface in the command) will start following it.