marine_acoustic_msgs

This package includes messages for three commonly used sensors for research in underwater autonomy:

• DVL
• Multibeam
• Imaging Sonar

Each of the proposed messages is based on an existing message that is currently in use across a variety of manufacturers of the same instrument type. This gives us confidence that they are mature enough to be indexed in the ROS debs and that they will generalize across other sensors.

Coordinate Frame Conventions

Design decisions common across multiple acoustic messages

Looking at the differences among existing open source UUV messages for acoustic sensors, there are a number of overarching design decisions to be made before defining individual messages. The proposed set of messages adheres to these guidelines:

• The messages should be suitable for use across a wide variety of hardware.
  • Any sensor-specific metadata fields should be published in a separate message. Standards for defining these additional messages are beyond the scope of this PR. However, options include:
    • Capture all raw bytes sent to / received from a sensor (e.g. WHOI’s RawData.msg)
    • Publish a separate message corresponding exactly to the datagrams sent by the sensor (e.g. PD0.msg)
    • Publish a separate message with the additional data, but no duplication of the standard message, following the Image/CameraInfo pattern.
  • In order to support generality for a wide range of sensors, there will be some fields that are not applicable to some sensors.
    • If not supported at all, the array may be left empty.
    • If value is constant across the data frame, array may be length 1.
    • Otherwise, the length of each array should match the length of the data.
• “raw/temporal” Underwater acoustic messages should include the speed of sound (field will be called sound_speed) that was used by the sensor, as well as any information required to raytrace the data with a new sound velocity profile.
• “processed/spatial” acoustic messages will have the ray-tracing already performed.
• The beam geometry is specified as a per-beam vector relative to the frame in the header. This is an alternative to other approaches that have been used, including:
  • additional TF frames for individual beams, which will quickly become unwieldy
  • an array of beam messages, where each beam includes its geometry relative to the sensor. Abstracting out the individual beams doesn’t serve to simplify the interpretation of the data, and doesn’t enable using an empty vector to indicate that a field isn’t applicable.
  • follow LaserScan convention and derive the geometry from min/max/step, which doesn’t generalize across sonars, since they do not all have beams spaced equiangualarly.
• Individual message types should be based on how the data is used, rather than similarities in data format. For example:
  • DVL and ADCP messages should not be combined, even though there is significant overlap in hardware and provided data. Consumers of DVL data expect a single velocity. Consumers of ADCP data expect velocities at an array of ranges.
  • There is a need for a difference between SonarImage and SonarRanges (aka multibeam), since they are not typically interchangeable in downstream processing algorithms, even though the newer sensors are blurring the lines. A sonar image consists of intensities-vs-time, while sonar ranges identify discrete returns.
• In order to be consistent with other messages in sensor_msgs, message types should be named after the type of data rather than type of sensor:
  • SonarImage.msg instead of ImagingSonar.msg
  • SonarRanges.msg instead of Multibeam.msg or ProfilingSonar.msg.

DVL

Existing Messages

The most widely used messages appear to be:

• WHOI’s ds_sensor_msgs/Dvl.msg. It is currently in use with both RDI and Nortek instruments.
• UUV Simulator’s uuv_sensor_ros_plugins_msgs/DVL.msg (This was used as the base for marine_ros_conventions_discussion/DVL.msg) The main implementation difference between ds_sensor_msgs and uuv_simulator is whether the top-level DVL message includes the beam data in an array, or whether there is an array of DvlBeam messages.
• UWSim’s underwater_sensor_msgs/DVL.msg. It is not particularly idiomatic for a ROS message: Rather than using a Vector3 for velocity, it has individual fields (wi_{x,y,z}_axis); and rather than using TF to transform between frames, it includes the data in instrument-referenced and vehicle-referenced frames within the same message.

While all options agree that the DVL message should include aggregate data from the instrument (estimated altitude and velocity), they differ in what else is included:

• Per-beam data (range, velocity, and their covariances): WHOI & UUV Simulator
• Both bottom-track and water-track velocities: WHOI & UWSim
• Additional details about the sensor configuration: WHOI

DVL-specific design decisions

• Is there broad support for including water-track velocity in addition to ground-track in the same message definition?
  • NPS is currently interleaving DVL & ADCP messages from the same driver for an instrument that provides both an ADCP profile and a DVL bottom-track velocity. I like this approach.
  • If the same message type supports both bottom track and water track (single reading, not profile), maybe there should be a convention that bottom track / water track are published on different topics so subscribing nodes can ignore water track velocities if they don’t use them.
• Whether the additional information about the sensor configuration (DVL_TYPE) belongs in the top-level message. Other messages in sensor_msgs do not tend to have similar flags; however, this depends on whether we want to be able to perform sound velocity corrections using the data in the DVL message.
• Does a quality flag belong in the standardized message?

Proposed Message

https://github.com/apl-ocean-engineering/marine_msgs/blob/main/marine_acoustic_msgs/msg/Dvl.msg

File truncated at 100 lines see the full file

Changelog for package marine_acoustic_msgs

2.1.0 (2024-03-15)

• Update CMake files to follow established standards
• Add Roland Arsenault as maintainer
• Update ros2 CI to use current ROS2 distributions (#56)
• Updated ros2 branch to be in line with revisions in main (#44)
• Contributors: Roland Arsenault, Sean Fish, Laura Lindzey

1.1.0 (2022-11-30)

• Fix ProjectedSonarImage comments about frame (#26)
• Add CI, pre-commit, prerelease and dependabot (#27) Co-authored-by: Laura Lindzey <<lindzey@uw.edu>>
• Merge pull request #25 from apl-ocean-engineering/add_migration_rule Add migration rule from v0.0.1 to 28ec6a7
• Add migration rule from v0.0.1 to 28ec6a7
• Merge pull request #22 from rolker/fix_variable_name
• Rename num_beams to beam_count.
• Merge pull request #21 from CaptKrasno/acoustic_msg_devel
• Contributors: CaptKrasno, Laura Lindzey, Roland Arsenault, Vatan Aksoy Tezer, lauralindzey

1.0.0 (2022-05-05)

• Merge pull request #20 from CaptKrasno/acoustic_msg_devel Acoustic msg devel
• Removed unused (old) sonarImage message
• Merge remote-tracking branch 'apl-ocean-engineering/main' into acoustic_msg_devel
• added ping info to sonar ranges
• Number of beams has been added to sonarImageData so it can be decoded independently
• Update README.md
• Merge remote-tracking branch 'origin/main' into acoustic_msg_devel
• committing changes from meeting
• Update README.md
• Changes after pull request discussion
• update internal documentation
• Merge branch 'main' into acoustic_msg_devel
• Add multibeam detections and watercolumn
• Contributors: CaptKrasno, Kristopher Krasnosky, lauralindzey

0.0.1 (2021-11-23)

• Merge pull request #13 from amarburg/feature/revise-sonar-image-comment Feature/revise sonar image comment
• Revised comments based on PR feedback.
• Revised based on comments on PR Removed language on 2D sonars Revised language on azimuth and elevation angles Revised language on header timestamp.
• Added note on sound speed.
• Very minor update in spelling.
• Significant rewrite of the explanatory comment in SonarImage.msg
• Merge pull request #10 from valschmidt/main Fixed broken links for proposed messages.
• Merge pull request #1 from valschmidt/valschmidt-fixed_broken_msg_links Fixed broken links to proposed messages.
• Fixed broken links to proposed messages.
• Create Contributing.md First pass at the contributing doc adapted from MBARI's LRAUV contributing guide
• Move acoustic_msgs package out of repo's root directory.
• Contributors: Aaron Marburg, CaptKrasno, Laura Lindzey, braanan, lauralindzey, valschmidt