File format definitions

mission.yaml file format definition

Version 0

One node each for the “standard nodes” velocity, orientation, depth, altitude and usbl, as well as one node origin and one node image
The standard nodes have the fields format, filepath, filename, timezone (optional, default: utc), timeoffset (optional, default: 0) and headingoffset (optional, default: 0).
The node origin has the fields latitude, longitude, coordinate_reference_system and date. The only supported coordinate reference system is wgs84. The date has to be indicated in the format YYYY/MM/DD.
The node image contains the fields format, filepath, camera1, camera2, camera3 (optional), timezone and timeoffset.
No field indicating the file format version.

Partial example:

#YAML 1.0
origin:
  latitude: 26.674083
  longitude: 127.868054
  coordinate_reference_system: wgs84
  date: 2017/08/17

velocity:
  format: phins
  filepath: nav/phins/
  filename: 20170817_phins.txt
  timezone: utc
  timeoffset: 0.0
  headingoffset: -45.0

usbl:
  format: gaps
  filepath: nav/gaps/
  timezone: utc
  timeoffset: 0.0

image:
  format: acfr_standard
  filepath: image/r20170817_022018_UG115_sesoko/i20170817_022018/
  camera1: LC
  camera2: RC
  timezone: utc
  timeoffset: 0.0

Version 1

Changes since verison 0:

Node version indicating the file format version (1).
headingoffset in the standard nodes is no longer supported. This is now indicated in vehicle.yaml
The standard nodes have 3 additional fields: origin (optional, default determined depending on type of node), std_factor (optional, default: 0) and std_offset (optional, default: 0). origin has to be the name of a node in the vehicle.yaml file. The coordinates in that node in the vehicle indicate where the device is located on the vehicle
Additional standard node tide
The ndoe usbl has an optional field id (or label)
The node image now has the fields format, timezone, timeoffset as well as a node cameras containing the list of cameras (maximum 3 cameras currently supported by auv_nav). Each item in the list of cameras has the fields name, origin (optional, default: same as the name), type, bit_depth (currently unused) and path. origin (resp. if origin is not indicated then name) indicates where the camera is located on the vehicle, and the name stated must exist as a node in the vehicle.yaml file.

Partial example:

version: 1 # Node version has been added

origin:
  latitude: 22.8778145
  longitude: 153.38397866666668
  coordinate_reference_system: wgs84
  date: 2018/11/19

velocity:
  format: autosub
  filepath: nav/
  filename: M155.mat
  timezone: utc
  timeoffset: 0.0
  std_factor: 0.001 # Field std_factor has been added
  std_offset: 0.2   # Field std_offset has been added
  # Field headingoffset has been removed

usbl:
  format: gaps
  filepath: nav/gaps/
  timezone: 0
  timeoffset: .0
  id: 4             # Field id has been added
  std_factor: 0.01
  std_offset: 2.0
  

image:
  format: seaxerocks_3
  cameras: # Cameras are defined now as a list
    - name: fore
      type: bayer_rggb
      bit_depth: 12
      path: image/SeaXerocksData20181119_073812_laserCal/Xviii/Cam51707923
    - name: aft
      type: bayer_rggb
      bit_depth: 12
      path: image/SeaXerocksData20181119_073812_laserCal/Xviii/Cam51707925
    - name: laser
      type: grayscale
      bit_depth: 12
      path: image/SeaXerocksData20181119_073812_laserCal/LM165
  timezone: 10
  timeoffset: 0.0

Version 2

Changes since verison 1: The camera nodes do not have a type or bit_depth node anymore, but they have an (optional) field records_laser, which is set to true for the laser observing camera. The type of filter and the bit depth are now stored in camera.yaml.

version: 2

image:
  format: seaxerocks_3  # acfr_standard or seaxerocks_3
  cameras:
    - name: Cam51707923 # fore
      path: image/SeaXeroxData20171123_095119/Xviii/Cam51707923
    - name: Cam51707925 # aft
      path: image/SeaXeroxData20171123_095119/Xviii/Cam51707925
    - name: LM165
      path: image/SeaXeroxData20171123_095119/LM165
      records_laser: true
  timezone: jst
  timeoffset: 0.0

Version 3

Changes since version 2: Support for an arbitrary number of payloads was added. They need to be indicated under the nonde “payloads” and need be named the same as they are in the vehicle.yaml file. The path, file format (currently “generic_csv” is the only supported format), the column where the timestamp is indicated (in the csv), timezone (hours from GMT) and timeoffset (seconds from master clock) need to be indicated. Example:

version: 3

payloads:
  chelsea_pah_plus:
    path: payloads/chelsea_pah_plus_format_fixed_time_corrected_20221006.csv
    format: generic_csv
    columns: [{'name': 'corrected_timestamp', 'content':'eeeeeeeeee.fffuuu'}]
    timezone: 0
    timeoffset: 0
  franatech_mets:
    path: payloads/franatech_mets_time_corrected_20221006.csv
    format: generic_csv
    columns: [{'name': 'corrected_timestamp'}]
    timezone: 0
    timeoffset: 0

auv_nav computes the nav solutions at the timestamps in the file at the given path, prepend it to the data in each row and write the result to disk again as csv.

vehicle.yaml file format definition

Currently only file format version 2 is supported. For examples check the subfolders of auv_nav/default_yaml/.

Version 0

One node each for the “standard nodes” origin, usbl, ins, dvl, depth, chemical (optional).
One node for each of the cameras, named camera1, camera2, camera3 (optional).
Each of the standard and camera nodes has a fields x_offset, y_offset and z_offset, which references each item described by a node with respect to the origin of the vehicle. The x-axis is aligned with the forward direction of the vehicle, the y-axis points to the right-hand side and the z-axis points downwards with respect to the vehicle.
Nodes do not contain information about orientation.
No field indicating the file format version.

Partial example:

origin:
  x_offset: 0
  y_offset: 0
  z_offset: 0

camera1: # Cameras named camera1, camera2, camera3
  x_offset: -0.05
  y_offset: -0.3
  z_offset: 0.18

Version 1

Changes since version 0:

x, y and z-offsets have been renamed surge_m, sway_m and heave_m.
Nodes contain Euler angles roll_deg, pitch_deg and yaw_deg for determining the orienation of each item. The rotations are carried out in the following order: Roll about x-axis, pitch about y-axis, yaw abour z-axis.

Partial example:

origin:
  surge_m: 0 # fomer x_offset
  sway_m:  0 # fomer y_offset
  heave_m: 0 # fomer z_offset
  roll_deg: 0
  pitch_deg: 0
  yaw_deg: 0

camera1: # Cameras named camera1, camera2, camera3
  surge_m: 0.262875
  sway_m: 0.
  heave_m: 0.5
  roll_deg: 0
  pitch_deg: 0
  yaw_deg: 0

Version 2

Changes since version 1:

Camera nodes are named after the name given in mission.yaml instead of camera1, camera2, camera3. The maximum number of cameras currently supported is 3.

Partial example:

origin:
  surge_m: 0
  sway_m: 0
  heave_m: 0
  roll_deg: 0
  pitch_deg: 0
  yaw_deg: 0

cam61003146: # Cameras name corresponding to camera label in mission.yaml
  surge_m: 1.484
  sway_m: 0
  heave_m: 0.327
  roll_deg: 0
  pitch_deg: -90
  yaw_deg: 0

Version 3

Changes since version 2: Node “chemical” is no longer used. Instead a node “payloads” is used, which can have an arbitrary number of payloads in subnodes. Example:

version: 3

payloads:
  chelsea_pah_plus:
    surge_m: 1.820
    sway_m: 0.245
    heave_m: -0.385
    roll_deg: 0
    pitch_deg: 0
    yaw_deg: 0
  franatech_mets:
    surge_m: 1.820
    sway_m: 0.245
    heave_m: -0.385
    roll_deg: 0
    pitch_deg: 0
    yaw_deg: 0

The mission.yaml needs to have matching payload nodes.

Compatibility with auv_nav

Currently both file format versions of mission.yaml and all 3 versions of vehicle.yaml are supported. However, when using vehicle.yaml file formats 0 or 1, the cameras in mission.yaml have to have their names fields set to “camera1”, “camera2” and (if present) “camera3”. Also, in file format verison 0 of both files the heading offset of sensors (e.g. DVL) is set in the mission.yaml file (headingoffset), whereas from format version 1 of both files it is set in vehicle.yaml (yaw_deg). It is therefore important not to mix these file format versions.