% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/adv.R
\name{xyzToEnuAdv}
\alias{xyzToEnuAdv}
\title{Convert an adv Object From XYZ to ENU Coordinates}
\usage{
xyzToEnuAdv(
  x,
  declination = 0,
  cabled = FALSE,
  horizontalCase,
  sensorOrientation,
  debug = getOption("oceDebug")
)
}
\arguments{
\item{x}{an \linkS4class{adv} object.}

\item{declination}{magnetic declination to be added to the heading after
"righting" (see below), to get ENU with N as "true" north.  If this
is set to NULL, then the returned object is set up without adjusting
the compass for declination.  That means that \code{north} in its \code{metadata}
slot will be set to \code{"magnetic"}, and also that there will be no item
named \code{declination} in that slot.  Note that \code{\link[=applyMagneticDeclination]{applyMagneticDeclination()}}
can be used later, to set a declination.}

\item{cabled}{boolean value indicating whether the sensor head is connected
to the pressure case with a cable.  If \code{cabled=FALSE}, then
\code{horizontalCase} is ignored.  See \dQuote{Details}.}

\item{horizontalCase}{optional boolean value indicating whether the sensor
case is oriented horizontally.  Ignored unless \code{cabled} is \code{TRUE}.
See \dQuote{Details}.}

\item{sensorOrientation}{optional string indicating the direction in which
the sensor points.  The value, which must be \code{"upward"} or
\code{"downward"}, over-rides the value of \code{orientation},
in the \code{metadata} slot,
which will have been set by \code{\link[=read.adv]{read.adv()}}, \emph{provided} that the
data file contained the full header.  See \dQuote{Details}.}

\item{debug}{a flag that, if non-zero, turns on debugging.  Higher values
yield more extensive debugging.}
}
\description{
Convert ADV velocity components from a xyz-based coordinate system to
an enu-based coordinate system.
}
\details{
The coordinate transformation is done using the heading, pitch, and roll
information contained within \code{x}.  The algorithm is similar to that
used for Teledyne/RDI ADCP units, taking into account the different
definitions of heading, pitch, and roll as they are defined for the
velocimeters.

Generally, the transformation must be done on a time-by-time basis, which is
a slow operation.  However, this function checks whether the vectors for
heading, pitch and roll, are all of unit length, and in that case, the
calculation is altered, resulting in shorter execution times.  Note that
the angles are held in (\code{data$timeSlow}, \code{data$headingSlow}, ...)
for Nortek instruments and (\code{data$time}, \code{data$heading}, ...) for
Sontek instruments.

Since the documentation provided by instrument manufacturers can be vague on
the coordinate transformations, the method used here had to be developed
indirectly.  (This is in contrast to the RDI ADCP instruments, for which
there are clear instructions.)  documents that manufacturers provide.  If
results seem incorrect (e.g. if currents go east instead of west), users
should examine the code in detail for the case at hand.  The first step is
to set \code{debug} to 1, so that the processing will print a trail of
processing steps.  The next step should be to consult the table below, to
see if it matches the understanding (or empirical tests) of the user.  It
should not be difficult to tailor the code, if needed.

The code handles every case individually, based on the table given below.
The table comes from Clark Richards, a former PhD student at Dalhousie
University (reference 2), who developed it based on instrument documentation,
discussion on user groups, and analysis of measurements acquired with Nortek
and Sontek velocimeters in the SLEIWEX experiment.

The column labelled \verb{Cabled'' indicates whether the sensor and the pressure case are connected with a flexible cable, and the column labelled }H.case''
indicates whether the pressure case is oriented horizontally.  These two
properties are not discoverable in the headers of the data files, and so
they must be supplied with the arguments \code{cabled} and
\code{horizontalCase}.  The source code refers to the information in this
table by case numbers.  (Cases 5 and 6 are not handled.)  Angles are
abbreviated as follows:: heading \verb{H,'' pitch }P,'' and roll ``R''.
Entries X, Y and Z refer to instrument coordinates of the same names.
Entries S, F and M refer to so-called ship coordinates starboard, forward,
and mast; it is these that are used together with a rotation matrix to get
velocity components in the east, north, and upward directions.

\tabular{rrrrrrrrrrrr}{
\strong{\code{Case}} \tab \strong{\code{Mfr.}} \tab
\strong{\code{Instr.}} \tab \strong{\code{Cabled}} \tab \strong{\verb{H. case}} \tab
\strong{\code{Orient.}} \tab \strong{\code{H}} \tab \strong{\code{P}} \tab \strong{\code{R}} \tab
\strong{\code{S}} \tab \strong{\code{F}} \tab \strong{\code{M}}\cr

1 \tab Nortek \tab vector \tab
no \tab - \tab up \tab H-90 \tab R \tab -P \tab X \tab -Y \tab -Z\cr

2 \tab Nortek \tab vector \tab no \tab - \tab down \tab H-90 \tab R \tab -P \tab X
\tab Y \tab Z\cr

3 \tab Nortek \tab vector \tab yes \tab yes \tab up \tab
H-90 \tab R \tab -P \tab X \tab Y \tab Z\cr

4 \tab Nortek \tab vector \tab
yes \tab yes \tab down \tab H-90 \tab R \tab P \tab X \tab -Y \tab -Z\cr

5 \tab Nortek \tab vector \tab yes \tab no \tab up \tab - \tab - \tab - \tab -
\tab - \tab -\cr

6 \tab Nortek \tab vector \tab yes \tab no \tab down \tab -
\tab - \tab - \tab - \tab - \tab -\cr

7 \tab Sontek \tab adv \tab - \tab -
\tab up \tab H-90 \tab R \tab -P \tab X \tab -Y \tab -Z\cr

8 \tab Sontek \tab adv \tab - \tab - \tab down \tab H-90 \tab R \tab -P \tab X \tab Y \tab Z\cr
}
}
\references{
\enumerate{
\item \verb{https://nortek.zendesk.com/hc/en-us/articles/360029820971-How-is-a-Coordinate-transformation-done-}
\item Clark Richards, 2012, PhD Dalhousie University Department of
Oceanography.
}
}
\seealso{
See \code{\link[=read.adv]{read.adv()}} for notes on functions relating to
\code{adv} objects.

Other things related to adv data: 
\code{\link{[[,adv-method}},
\code{\link{[[<-,adv-method}},
\code{\link{adv}},
\code{\link{adv-class}},
\code{\link{advSontekAdrFileTrim}()},
\code{\link{applyMagneticDeclination,adv-method}},
\code{\link{beamName}()},
\code{\link{beamToXyz}()},
\code{\link{enuToOther}()},
\code{\link{enuToOtherAdv}()},
\code{\link{plot,adv-method}},
\code{\link{read.adv}()},
\code{\link{read.adv.nortek}()},
\code{\link{read.adv.sontek.adr}()},
\code{\link{read.adv.sontek.serial}()},
\code{\link{read.adv.sontek.text}()},
\code{\link{rotateAboutZ}()},
\code{\link{subset,adv-method}},
\code{\link{summary,adv-method}},
\code{\link{toEnu}()},
\code{\link{toEnuAdv}()},
\code{\link{velocityStatistics}()},
\code{\link{xyzToEnu}()}
}
\author{
Dan Kelley, in collaboration with Clark Richards
}
\concept{things related to adv data}
