Add missing required variables in `Platform` groups

[leewujung]

This was discovered in #516 discussion and is better captured in its own issue:

@emiliom:

Hmm. After reading and rereading the definitions of water_level and vertical_offset, plus the Coordinate Systems chapter in SONAR-netCDF v1 (ch. 4), here are some observations -- some of which I'm sure are obvious, but it helps me to state them:

1. The platform coordinate system is the grounding for all other coordinates. The origin of that coordinate system is arbitrary.
2. There are 3 types of x-y-z offsets defined: position (GPS), MRU and transducer.
3. water_level and vertical_offset are variables that refer exclusively to the vertical (z) axis and are there to enable the generation of depth values relative to actual water level

The generalization to range_offset implies an along-range ("transducer orientation", in my layman's term) axis relative to the platform origin, or relative to actual or nominal water level (I can't remember which). But regardless of the orientation of the transducer, its offsets x-y-z relative to platform origin are already specified by the transducer offsets, and water_level and vertical_offset together provide that vertical referencing to either a constant water level (I assume that's what nominal water level is?) or actual, time varying water level. It's not clear to me what value the generalized, along-range range_offset actually provides when all the other offsets as well as water_level and vertical_offset are available. I think what's potentially missing is more clarity and specificity about the coordinate system for platforms other than ships. This is apparently being addressed in the convention v2 draft (see #517).

Action items

In view of the above above and in the mind set of convention v1:

• [ ] review the convention and echopype's handling of various position and offset variables (water_level, vertical_offset, transducer_offset_x/y/z, MRU_offset_x/y/z
• [ ] ensure compliance of required variables in v0.6.0

[imranmaj]

EK60:

• water_level comes from transducer_depth
• vertical_offset is called heave right now, should we rename this?
• transducer_offset_x/y/z looks fine; comes from pos_x/y/z
  • EK80: comes from transducer_offset_x/y/z
• MRU_offset_x/y/z: could not find in the datagram

[emiliom]

Thanks for this assessment @imranmaj!

MRU_offset_x/y/z: could not find in the datagram

Could you add which EK60 raw file(s) you tested to arrive at this finding? If you know where it came from (say, Hake survey), that'd be great too.

[imranmaj]

I looked through our EK60 parser implementation and the EK60 manual, in particular through the raw file specification (beginning page 194) and the NMEA specification (beginning page 177).

[leewujung]

vertical_offset is called heave right now, should we rename this?

Below is what the convention says:

I found this being different from my intuitive understanding that the mean position would be the vertical_offset and heave is the vertical motion superimposed on top of the mean. Since the heave (offset from the mean) motion can be coupled with other dimensions in the 6 degree of freedom of the vehicle movements, there is an advantage to separate the mean and the deviation from the mean.

However, I can see that in practice in terms of storing data, then the data wouldn't be a "raw" form since to separate these two often requires actually operating on the data, so a combined term is better.

@gavinmacaulay : could you share the reasoning behind this naming? then we can be clear on the intention and use. Thanks!

[leewujung]

EK80: There are separate MRU datagrams that contains the heave, row, pitch, and heading data. See EK80 interface manual p.126-127, p.132-133. But I don't seem to find info about the MRU position (which can be used for MRU_offset_x/y/z) in the datagram. @imranmaj could you please double check that I didn't miss anything?

EK60:

MRU_offset_x/y/z: could not find in the datagram Heave, row, pitch info are in the sample datagram but no the position offset: https://www.simrad.net/ek60_ref_english/default.htm

[gavinmacaulay]

@leewujung - what do you mean by 'mean position'?

Values for MRU_offset_x/y/z are not part of the EK60 nor EK80 format (transducer offsets can be in the EK80 though).

FYI: adding MRU_offset_x/y/z (and the GPS and transducer offsets) to the convention was an effort to encourage sounder manufacturers to provide all the information necessary to fully locate echoes in a global coordinate system.

[leewujung]

@gavinmacaulay : I was thinking along the line below: x(t) = x_bar(t) + x'(t) where x_bar(t) is the mean trajectory and x'(t) is disturbance from the mean trajectory, and x(t) is the measured trajectory.

For a ship on the sea surface, x_bar(t) would be 0, x'(t) would be the heave motion, and x(t) is the measured "depth" which is x'(t) in this case.

[imranmaj]

EK80: There are separate MRU datagrams that contains the heave, row, pitch, and heading data. See EK80 interface manual p.126-127, p.132-133. But I don't seem to find info about the MRU position (which can be used for MRU_offset_x/y/z) in the datagram. @imranmaj could you please double check that I didn't miss anything?

I didn't find anything either

[leewujung]

Thanks @imranmaj for investigating and working on this.

One thing I think we still need for this issue is to add the missing required variables (those marked with "R" in the convention) as NaN in the Platform group. Could you do another PR for that?

The mention of water_level here reminded me of #586. Since you are familiar with where things are now, could you please take on that one also?

Thanks!