Cable vector orientation field confusion - errors likely

[scmcgill0]

We have had problems for cabled vectors where the "z" direction in the processed file is opposite of the correct flow direction. This is introduced by an orientation problem.
The "Orientation" field in the yaml code is not defined and is somewhat confusing. "Orientation" is in reference to the case rather than the probe head, which caused an issue when working with cabled vectors where we now have 2 orientations - case and probe. We think of the probe as "down" as the sampling volume is below the probe. If we add the probe orientation, it will work the same for fixed and cabled vectors. A "down" probe orientation and an "up" case orientation will be the usual configuration for processing.

To clarify the setup, we need: (1) the case orientation read from the "SEN" file (Nortek defines UP for vertical compass cases as with the I/O connector to the sky) (2) a probe orientation in the yaml file we record (for cabled probes this can be different than the case orientation) – this is the direction of the transmit pulse (3) the code cross-checks these and has a flag or a check to confirm.]

The processing code could look to the last digit (bit 0) in the status code (variable 8) in the sen file, this bit indicates the orientation of the instrument, 0 = up and 1 = down. (page 116 in manual)

[rallen-usgs]

Thanks Sam! I'll add that I think that sometimes we use horizontal vectors with a cabled head - I think this should be included in the setup you describe above.

[dnowacki-usgs]

@ssuttles-usgs do you have any input here?

[ssuttles-usgs]

I do but it is complicated and I am getting ready for a family ski trip. Cabled vectors are a challenge and will require special attention and depending on the compass/tilt configuration, if have IMUs, and if are being sampled continuously. Bo & I just had a call with Nortek engineer (Torstein Pedersen) about using cabled vectors with IMUs and take home was either deploy in same orientation as if a fixed stem vector or consult dolfyn package where Levi (Kilcher) has supposedly figured out how to use them with probe in different configurations (see attached paper, again this pertains to vectors w/ IMUs). We have some cabled vectors with standard compass/tilt sensor that are configured for a horizontal housing mount, and we typically deploy them with the housing horizontal (notch on probe end bell down) and with the probe in a downward orientation (samp vol towards seabed). I think we have been able to process those correctly but will need to test with latest stglib. Another thing to be aware of is if sampling continuously, will need to make sure the instrument housing is oriented in the same orientation it will be deployed when the instrument starts sampling as that will be the only time the orientation status bit will be set, otherwise might have a problem. We plan to start processing some vector data soon so can join the conversation and development more at that time. All for now. nrel measuring turbulence from moored ADV.pdf

[rallen-usgs]

Just to add some thoughts here - I think it would be awesome if stglib could handle this, and hopefully be more clear than Nortek in how it does. Currently Nortek has vector orientation defined as:

Bit 0 - Orientation: This bit indicates the orientation of the instrument. Bit 0 Orientation 0 Up 1 Down

Note: For the Vector the instrument is defined to be in the UP orientation when the communication cable end of the canister is on the top of the canister, ie when the probe is pointing down.

[this is bit 0 in the `status word']

But, they acknowledge (separately in the manual) that the housing can be horizontal or vertical, and you can figure out which it is supposed to be by looking at the tilt and roll readings as you move the housing around. I think the other way to figure it out is to look at the probe type: a VEC is set up to be a vertically oriented housing, while a VCH is set up to be a horizontally oriented housing.

IF the instrument is set up correctly (i.e. with the notch on the housing lining up with the orientation of the probe, as outlined in the vector manual), then we should be able to determine everything from the instrument itself, and not need any additional information in the yaml file from the operator.

As a cross check, I checked the DMP23 deployment:

For site X2A, the upper vector (DMP23X2A02, VCH 4997) was a horizontally oriented cabled head vector with the probe oriented down. The last digit of the status word in the .sen file is 1. This indicates that z is pointing DOWN, and that tracks with my read of the Vector manual (section "Orientation of the Vector probes").

For site X2A, lower vector (DMP23X2A03, VEC 5181) was a vertically oriented cabled head vector with the probe oriented down. The last digit of the status word in the .sen file is 0. This indicates that z is pointing UP, and that tracks with my read of the Vector manual (section "Orientation of the Vector probes").

So, I think stglib should do 2 things. (1) pull in the information needed to do the coordinate rotation in all cases. (2) return a note that is more explicit about what it figured out and did.

For (1). It can figure out orientation from bit 0 of the `status word'. If that bit is '0' z is positive UPwards and if that bit is '1' z is positive DOWNwards. This orientation should be all that is needed to do the coordinate rotation.

(2) It can find out instrument type based on the name - VEC for vertically oriented housings and VCH for horizontally oriented housings. Then, combined with the orientation, it can return a note sort of like: VEC + 0: vertically orientated housing with probe oriented DOWN. VEC + 1: vertically oriented housing with probe oriented UP. VCH + 0: horizontally oriented housing with probe oriented UP. VCH + 1: horizontally oriented housing with probe oriented DOWN. I would imagine a note that says something like "stglib determined from the instrument settings the vector housing was VERTICALLY oriented and the probe was pointing DOWN. If this is incorrect the user should adjust ...." (and then, eventually, we can add fields to the yaml that will override these).

I don't think we currently have any horizontally oriented housings with fixed stems. If there are any in rotation, this case would need to be addressed.

Also, as Steve said, if the instrument is sampling continuously, it only checks the orientation once at the start, so if the tripod is fallen over at the end then there's a bit of trouble...

I hope this helps!

[dnowacki-usgs]

I think the referenced PR fixes these issues by clarifying what orientation means for the Vector in the docs, and updating how we handle it in processing and potential coordinate transformations.

[dnowacki-usgs]

Closed by #210. Please raise a new issue if error persist.