How to Use Vessels in ASVSim

Introduction

ASVSim provides comprehensive support for maritime vessel simulation with realistic hydrodynamics, environmental disturbances, and sensor modeling. The vessel API enables researchers and developers to create sophisticated maritime autonomous systems, test navigation algorithms, and develop computer vision applications for marine environments.

Getting Started

By default, ASVSim prompts the user for which vessel to use. You can easily change this by setting SimMode. For vessel simulation, set the SimMode in your settings.json file, which you can find in your ~/Documents/AirSim folder:

{
  "SettingsVersion": 2.0,
  "SimMode": "Vessel",
  "PhysicsEngineName": "VesselEngine",
  "Vehicles": {
    "Vessel1": {
      "VehicleType": "MilliAmpere",
      "HydroDynamics": {
        "hydrodynamics_engine": "FossenCurrent"
      },
      "PawnPath": "DefaultVessel",
      "AutoCreate": true
    }
  }
}

Now when you restart ASVSim you should see the vessel spawned automatically. There are a number of options in the settings file. Firstly, you can set which vehicle to use. In this case, we are using the MilliAmpere vessel, but we also support the Qiuxin, Cybership2 and Mariner vessels. We support different hydrodynamics models. In this case, we are using the FossenCurrent model, but we also support the MarinerHydrodynamics model. Lastly, we have included 2 different blueprints for the vessel pawns: CargoVessel and DefaultVessel, which is a small fishers vessel.Add commentMore actions

Broadly speaking, there are two types of vessels: 1. Large Vessels 2. Research Vessels

The research vessels are fully modelled as described in the paper and are controlled by a set of thrusters that can be placed arbitrarily on the vessel. The large vessels are linearized around the operating point, and operate at a constant engine speed. They are only impacted by the effects of the stern rudder angle. The matrix below shows the compatibility of the different hydrodynamics models with the different vessel types. Note that the blueprints only have a visual impact, the visual blueprint is fully independent from the dynamics, which are described by the physics engine, hydrodynamics engine and parameters.

Parameters	Hydrodynamics	Engine	Settings File
milliampere	FossenCurrent	VesselEngine	settings_milliampere.json
cybership2	FossenCurrent	VesselEngine	settings_cybership.json
qiuxin5	FossenCurrent	VesselEngine	settings_qiuxin.json
mariner	MarinerHydrodynamics	LargeVesselEngine	settings_mariner.json

Controlling a Vessel

Vessel API

setVesselControls()

Controls vessel propulsion and steering. Use this to move and steer the vessel.

from cosysairsim.types import VesselControls

controls = VesselControls(thrust=0.7, angle=0.6)  # 70% thrust, slight turn
client.setVesselControls('VesselName', controls)

Parameters: - rudder_thrust (0.0-1.0): Thrust level (0.0 = stop, 1.0 = full power) - rudder_angle (0.0-1.0): Steering angle (0.5 = straight, <0.5 = left, >0.5 = right)

setDisturbanceControls()

Simulates environmental disturbances (wind, current). Use this to test vessel behavior under different environmental conditions.

from cosysairsim.types import DisturbanceControls
import math

disturbances = DisturbanceControls(
    wind_force=15.0, wind_angle=math.pi/4,      # Wind force (N) and direction (rad)
    current_velocity=5.0, current_angle=0.0      # Current velocity (m/s) and direction (rad)
)
client.setDisturbanceControls('VesselName', disturbances)

Parameters: - Forces are in Newtons (N), angles in radians - wind_force/angle: Wind forces affecting the vessel - current_velocity/angle: Water current forces

getVesselState()

Retrieves vessel position, orientation, and motion data. Use this to monitor the vessel's current state.

state = client.getVesselState('VesselName')
pos = state.kinematics_estimated.position
vel = state.kinematics_estimated.linear_velocity

print(f"Position: ({pos.x_val}, {pos.y_val}, {pos.z_val})")
print(f"Velocity: ({vel.x_val}, {vel.y_val}, {vel.z_val})")

Returns: - kinematics_estimated: Contains position, orientation, velocity, and acceleration data - All positions are in world coordinates (meters) - Velocities are in m/s, accelerations in m/s²

Spawning Obstacles

Through the API, you can spawn obstacles in the environment using the simAddObstacle() function. These can be either static (such as buoys) or dynamic (such as other vessels). The function takes the following parameters:

• pose (Pose): Initial pose of the obstacle, containing:
• position (Vector3r): Position in world coordinates (x, y, z)
• orientation (Quaternionr): Orientation as quaternion (w, x, y, z)
• speed (float, optional): Movement speed of the obstacle in cm/s. Default is 1000.0
• obstacle_name (str, optional): Name of the obstacle blueprint to spawn. If empty, uses the default obstacle blueprint, which is a small vessel.

Example usage:

from cosysairsim.types import Pose, Vector3r, Quaternionr

pose = Pose(position=Vector3r(x=100.0, y=100.0, z=0.0), orientation=Quaternionr(w=1.0, x=0.0, y=0.0, z=0.0))
client.simAddObstacle(pose, speed=0.0, obstacle_name="buoy")
client.simAddObstacle(pose, speed=1000.0, obstacle_name="")

Using APIs

You can control the vessel, get state and images by calling APIs in variety of client languages including Matlab and Python. Please see APIs doc for more details.

Changing Views

By default camera will chase the car from the back. You can get the FPV view by pressing F key and switch back to chasing from back view by pressing / key. More keyboard shortcuts can be seen by pressing F1.

For additional examples and advanced usage patterns, see the Vessel Data Generation documentation and Reinforcement Learning documentation and explore the example scripts in PythonClient/Vessel/.