Rotate Functions

Contains functions for rotating data through frames of reference (FoR):

  1. ‘beam’: Follows the acoustic beam FoR, where velocity data is organized by beam number 1-3 or 1-4.

  2. ‘inst’: The instrument’s XYZ Cartesian directions. For ADVs, this orientation is from the mark on the ADV body/battery canister, not the sensor head. For TRDI 4-beam instruments, the fourth velocity term is the error velocity (aka XYZE). For Nortek 4-beam instruments, this is XYZ1 Z2, where E=Z2-Z1.

  3. ‘earth’: East North UP (ENU) FoR. Based on either magnetic or true North, depending on whether or not DOLfYN has a magnetic declination associated with the dataset. Instruments do not internally record magnetic declination, unless it has been supplied via external software like TRDI’s VMDAS.

  4. ‘principal’: Rotates velocity data into a streamwise, cross-stream, and vertical FoR based on the principal flow direction. One must calculate principal heading first.

rotate2

Rotate a dataset to a new coordinate system.

set_declination

Set the magnetic declination

calc_principal_heading

Compute the principal angle of the horizontal velocity.

set_inst2head_rotmat

Set the instrument to head rotation matrix for the Nortek ADV if it hasn't already been set through a '.userdata.json' file.

euler2orient

Calculate the orientation matrix from DOLfYN-defined euler angles.

orient2euler

Calculate DOLfYN-defined euler angles from the orientation matrix.

quaternion2orient

Calculate orientation from Nortek AHRS quaternions, where q = [W, X, Y, Z] instead of the standard q = [X, Y, Z, W] = [q1, q2, q3, q4]

These functions pertain to both ADCPs and ADVs:

>> import dolfyn as dlfn
>> dat = dlfn.read_example('burst_mode01.VEC')

>> dat_mag = dlfn.set_declination(dat, 12)
>> dat_earth = dlfn.rotate2(dat_mag, 'earth')

>> dat_earth.attrs['principal_heading'] = dlfn.calc_principal_heading(dat_earth['vel'])
>> dat_flow = dlfn.rotate2(dat_earth, 'principal')
dolfyn.rotate.api.rotate2(ds, out_frame='earth', inplace=False)[source]

Rotate a dataset to a new coordinate system.

Parameters

  • ds (xr.Dataset) – The dolfyn dataset (ADV or ADCP) to rotate.

  • out_frame (string {'beam', 'inst', 'earth', 'principal'}) – The coordinate system to rotate the data into.

  • inplace (bool) – Operate on the input data dataset (True), or return a copy that has been rotated (False, default).

Returns

ds (xarray.Dataset) – The rotated dataset

Notes

This function rotates all variables in ds.attrs['rotate_vars'].

dolfyn.rotate.api.calc_principal_heading(vel, tidal_mode=True)[source]

Compute the principal angle of the horizontal velocity.

Parameters

  • vel (np.ndarray (2,...,Nt), or (3,...,Nt)) – The 2D or 3D Veldata array (3rd-dim is ignored in this calculation)

  • tidal_mode (bool (default: True)) –

Returns

p_heading (float or ndarray) – The principal heading in degrees clockwise from North.

Notes

The tidal mode follows these steps:

  1. rotates vectors with negative velocity by 180 degrees

  2. then doubles those angles to make a complete circle again

  3. computes a mean direction from this, and halves that angle again.

  4. The returned angle is forced to be between 0 and 180. So, you may need to add 180 to this if you want your positive direction to be in the western-half of the plane.

Otherwise, this function simply computes the average direction using a vector method.

dolfyn.rotate.api.set_declination(ds, declin)[source]

Set the magnetic declination

Parameters

declination (float) – The value of the magnetic declination in degrees (positive values specify that Magnetic North is clockwise from True North)

Returns

ds (xarray.Dataset) – Dataset adjusted for the magnetic declination

Notes

This method modifies the data object in the following ways:

  • If the dataset is in the earth reference frame at the time of setting declination, it will be rotated into the “True-East, True-North, Up” (hereafter, ETU) coordinate system

  • dat['orientmat'] is modified to be an ETU to instrument (XYZ) rotation matrix (rather than the magnetic-ENU to XYZ rotation matrix). Therefore, all rotations to/from the ‘earth’ frame will now be to/from this ETU coordinate system.

  • The value of the specified declination will be stored in dat.attrs['declination']

  • dat['heading'] is adjusted for declination (i.e., it is relative to True North).

  • If dat.attrs['principal_heading'] is set, it is adjusted to account for the orientation of the new ‘True’ earth coordinate system (i.e., calling set_declination on a data object in the principal coordinate system, then calling dat.rotate2(‘earth’) will yield a data object in the new ‘True’ earth coordinate system)

dolfyn.rotate.api.set_inst2head_rotmat(ds, rotmat)[source]

Set the instrument to head rotation matrix for the Nortek ADV if it hasn’t already been set through a ‘.userdata.json’ file.

Parameters

rotmat (float) – 3x3 rotation matrix

Returns

ds (xarray.Dataset) – Dataset with rotation matrix applied

dolfyn.rotate.base.euler2orient(heading, pitch, roll, units='degrees')[source]

Calculate the orientation matrix from DOLfYN-defined euler angles.

This function is not likely to be called during data processing since it requires DOLfYN-defined euler angles. It is intended for testing DOLfYN.

The matrices H, P, R are the transpose of the matrices for rotation about z, y, x as shown here https://en.wikipedia.org/wiki/Rotation_matrix. The transpose is used because in DOLfYN the orientation matrix is organized for rotation from EARTH –> INST, while the wiki’s matrices are organized for rotation from INST –> EARTH.

Parameters

  • heading (numpy.ndarray (Nt)) – The heading angle.

  • pitch (numpy.ndarray (Nt)) – The pitch angle.

  • roll (numpy.ndarray (Nt)) – The roll angle.

  • units (str {'degrees' (default), 'radians'}) –

Returns

omat (|np.ndarray| (3x3xNt)) – The orientation matrix of the data. The returned orientation matrix obeys the following conventions:

  • a “ZYX” rotation order. That is, these variables are computed assuming that rotation from the earth -> instrument frame happens by rotating around the z-axis first (heading), then rotating around the y-axis (pitch), then rotating around the x-axis (roll). Note this requires matrix multiplication in the reverse order.

  • heading is defined as the direction the x-axis points, positive clockwise from North (this is opposite the right-hand-rule around the Z-axis), range 0-360 degrees.

  • pitch is positive when the x-axis pitches up (this is opposite the right-hand-rule around the Y-axis)

  • roll is positive according to the right-hand-rule around the instrument’s x-axis

dolfyn.rotate.base.orient2euler(omat)[source]

Calculate DOLfYN-defined euler angles from the orientation matrix.

Parameters

omat (numpy.ndarray) – The orientation matrix

Returns

  • heading (|np.ndarray|) – The heading angle. Heading is defined as the direction the x-axis points, positive clockwise from North (this is opposite the right-hand-rule around the Z-axis), range 0-360 degrees.

  • pitch (np.ndarray) – The pitch angle (degrees). Pitch is positive when the x-axis pitches up (this is opposite the right-hand-rule around the Y-axis).

  • roll (np.ndarray) – The roll angle (degrees). Roll is positive according to the right-hand-rule around the instrument’s x-axis.

dolfyn.rotate.base.quaternion2orient(quaternions)[source]

Calculate orientation from Nortek AHRS quaternions, where q = [W, X, Y, Z] instead of the standard q = [X, Y, Z, W] = [q1, q2, q3, q4]

Parameters

quaternions (xarray.DataArray) – Quaternion dataArray from the raw dataset

Returns

orientmat (|np.ndarray|) – The inst2earth rotation maxtrix as calculated from the quaternions

See also

scipy.spatial.transform.Rotation