calibrate.axes: Calibrate two accelerometer/magnetometer axes. Axes are...
In animalTrack: Animal track reconstruction for high frequency 2-dimensional (2D) or 3-dimensional (3D) movement data.

Description Usage Arguments Details Value Warning Note Author(s) References See Also Examples

Hard iron distortion compass calibration. Hard iron error arises from magnetized iron or steel on the compass platform that creates a constant offset for the compass axes. This offset is additive and constant.

1	calibrate.axes(x, y, scale = 1, xcal = NULL, ycal = NULL)

`x`	a numeric vector of axis values. This should be calibration rotations (i.e. yaw, pitch, roll)
`y`	a numeric vector of axis values. This should be calibration rotations (i.e. yaw, pitch, roll)
`scale`	the maximum value `x` and `y` will have after being scaled (i.e. values will range from `-scale` to `+scale`. Defaults to 1.
`xcal`	a numeric vector of axis values (corresponding to `x`). This should be track data that should be scaled according to the scale factor, offset, and `scale` variable. Optional.
`ycal`	a numeric vector of axis values (corresponding to `y`). This should be track data that should be scaled according to the scale factor, offset, and `scale` variable. Optional.

A common source of compass error is hard and/or soft iron disturbance. Hard iron error arises from magnetized iron or steel on the compass platform that creates a constant offset for the compass axes. To account for the additive shift, an offset value is determined for each axis and applied by adding or subtracting the offset value from x or y. Soft iron error results from the interaction of soft iron near the compass and the earth's magnetic field. Soft iron error is a much more complicated distortion to account for and is not handled in this function.

returns a list containing scale factors, offset values, and scaled axes

`xsf`	scale factor for x.
`ysf`	scale factor for y.
`xoff`	offset value for x.
`yoff`	offset value for y.
`xh`	calibrated x value. Scale factor and offset applied.
`yh`	calibrated y value. Scale factor and offset applied.
`xhscaled`	calibrated x value. Scale factor and offset applied, and scaled using `scale`.
`yhscaled`	calibrated y value. Scale factor and offset applied, and scaled using `scale`.
`xcal`	calibrated independent `xcal` value. Scale factor and offset applied to `xcal`, and scaled using `scale`. Optional. Will be NULL if `xcal` is not provided.
`ycal`	calibrated independent `ycal` value. Scale factor and offset applied to `ycal`, and scaled using `scale`. Optional. Will be NULL if `ycal` is not provided.

If any dynamic acceleration is present during the calibration procedure or track, it will result in an erroneous calibration. This can be avoided by keeping the sensor still and by pausing during rotations. Once the calibration constants are known for the instrument, they can be applied to the raw signal from the deployment on the animal. The raw accelerometer signal will include both static and dynamic acceleration, so the accelerometer signal must be filtered using a low-pass filter to extract the "static" portion of the signal.

If no distortion is present, plot(x,y) will be circular and centered on (0,0). If hard-iron distortion is present, the center of the circle will not be (0,0), it will be shifted along the x, y, or both axes. However, the plot should still be circular. If the plot is not circular (e.g. ellipsoid), then soft-iron effects may be at play. In which case, a more complex calibration is needed. See Caruso (2000) for a discussion of compass and accelerometer errors. The hard-iron calibration used in this function is commonly implemented and can be found in Grygorenko (2011), among others.

Ed Farrell <edward.farrell27@gmail.com>

Caruso, M. J. (2000), Applications of magnetic sensors for low cost compass systems. Proc. Position Location and Navigation Symp., IEEE 2000, Mar. 2000, pp. 177-184

Grygorenko, V. (2011), Sensing - magnetic compass with tilt compensation. Cypress Perform, AN2272, Document No. 001-32379 Rev. B.

calibrate.axis

## Import the missionbay_calib2 dataset. There is a calibration sequence 
## at Mission Bay, CA. Use help(missionbay_calib2) for info.

data(missionbay_calib2)

# Uncalibrated raw values
mx <- missionbay_calib2$mx_raw
my <- missionbay_calib2$my_raw

plot(mx,col='blue',type='l',lwd=3)
lines(my,col='green',lwd=3)

## Scale and center the x and y magnetometer axes against one another. Also, make 
## sure that each axis is in the NED (north-east-down) orientation.
cal <- calibrate.axes(mx, my)
attributes(cal)

plot(cal$xhscaled,col='blue',type='l',lwd=3)
lines(cal$yhscaled,col='green',lwd=3)