CSV export

Since the Surveyor is a multi-beam echo sounder, each time we emit a sonar pulse, we receive multiple signals and combine them to get multiple beams. Each ping consists of multiple “detections” and each detection is a row in the CSV.

Some data is per-detection, and some is per-ping.

The following columns are presented in CSV export:

column	notes
latitude	detection's geodetic latitude in decimal degrees north of equator (or negative south)
longitude	detection's geodetic longitude in decimal degrees east of prime meridian (or negative west)
depth	depth of detection in meters
north (m north)	detection's Cartesian position in meters north. Relative to an arbitrary origin.
east (m east)	detection's Cartesian position in meters east. Relative to an arbitrary origin.
pingNumber	sequence number of the ping which produced this data. Each ping has multiple detections, and thus multiple rows in the CSV.
elapsed (s)	time the ping was sent, in seconds since the session started
datetime	time the ping was sent, in UTC
platform position x (m north)	position of the platform in local Cartesian coordinates
platform position y (m east)	position of the platform in local Cartesian coordinates
platform position z (m down)	position of the platform in local Cartesian coordinates
platform attitude Qx	Rotation of the platform, relative to local Cartesian coordinates.
platform attitude Qy
platform attitude Qz
platform attitude Qw
device position x	where the Surveyor device was at the time of sounding in local Cartesian coordinates
device position y
device position z
device attitude Qx	Rotation of the Surveyor, relative to local Cartesian coordinates.
device attitude Qy
device attitude Qz
device attitude Qw

Positions are represented as Local Cartesian Coordinates (x,y,z). x=north, y=east, z=down.

Quaternions

You can think about quaternions as a convenient and compact shorthand for a rotation matrix. Each quaternion is specified by 4 numbers, Qx, Qy, Qz, Qw (often written [x,y,z,w] or [w,x,y,z] or w+xi+yj+zk). They are mathematically convenient to work with but might be slightly harder to interpret than traditional Tait-Bryan angles (yaw, pitch, roll) or Euler angles.

A great interactive explanation of the math and intuition behind Quaternions as rotations can be found at https://eater.net/quaternions.

To expand out [x,y,z,w] as a rotation matrix (operating on column vectors):

$$\mathbf{R} = \begin{bmatrix} w^2 + x^2 - y^2 - z^2 & 2 (xy-wz)& 2 (xz+wc) \\ 2 (xy+wz) & w^2-x^2+y^2-z^2 & 2(yz-xy) \\ 2 (xz - wy) & 2 (wx+xy) & w^2-x^2-y^2+z^2 \end{bmatrix}$$

Rotation quaternions will have x^2 + y^2 + z^2 + w^2 = 1. Some convenient quaternions to know (expressed as [Qx, Qy, Qz, Qw]):

[0,0,0,1] = no rotation at all

[0.71,0,0,0.71] = 90º rotation about the x-axis (north stays the same, east becomes down)

[0,±0.71,0,±71] = 90° rotation about the y-axis (east axis fixed, down becomes north)

[0,0,±0.71,±0.71] = 90° rotation about the z-axis (down axis fixed, north becomes east)

[0,0,±1,0] = 180° rotation about the down-axis (down stays the same, north becomes south, east becomes west)

If the x and y components are 0, then *all* rotation is around the z-axis (with the vehicle rotation that means it has no pitch/roll)