lejos.robotics.filter

Class LinearCalibrationFilter

java.lang.Object

lejos.robotics.filter.AbstractFilter

lejos.robotics.filter.AbstractCalibrationFilter

lejos.robotics.filter.LinearCalibrationFilter

All Implemented Interfaces:

Calibrate, SampleProvider

public class LinearCalibrationFilter
extends AbstractCalibrationFilter

This filter is used to calibrate sensors for offset and scale errors using linear interpolation.
The filter has two modes of operation. In operational mode it corrects samples coming from the sensor. In calibration mode the filter calculates calibration parameters.

Operational mode
In operational mode the filter corrects incoming samples for offset and scale errors. The correction algorithm can uses calibration parameters for this. These calibration parameters can be computed in calibration mode. They can also be loaded from the filesystem using the load() method.

How it works
The correction algorithm uses two calibration parameters, offset and scale.
The offset parameter corrects for offset errors. An offset error results in a sample being a fixed amount off the truth: 2 becomes 3, 6 becomes 7. It is corrected by subtracting a constant value (1 in this example) from the sample, the offset error.
The scale parameter corrects for scale errors. As a result of a scale error a sample is always a fixed percentage off the truth: 2 becomes 3, 6 becomes 9. It is corrected by dividing the sample with a constant value, the scale error, 1.5 in this case.
The combined correction formula is correctedValue = ( rawValue - offsetError ) / scaleError. This calibration technique works on all sensors who's output is linear to the input.
If no correction parameters are calculated or loaded the filter uses 0 for offset correction and 1 for scale correction.

How to use the filter in operational mode
In operational mode is the default mode. It is always active while the filter is not calibrating.

Calibration mode
In calibration mode the two calibration parameters are calculated. This is done by comparing samples to a user specified reference value and/or range. Once calibration parameters are calculated they can be used immediately or stored to the filesystem for later use using the store() method.

How it works
The CalibratorFiltersupports both offset and scale calibration. However both are optional and can be enabled or disabled. During calibration the filter collects minimum and maximum sample values. From this it calculates offset (as the average of the minimum and maximum value corrected for the reference value) and scale (as the difference between maximum and minimum value scaled for range). To minimize the effect of sensor noise or sensor movements during calculation sample values are low-passed before they are being used for calibration.

How to use the filter in calibration mode
Calibration is started using the startCalibration method and ended with the endCalibration method. During calibration the program that uses the filter must fetch samples to collect data for the calibration algorithm. At the end the calibration process the calculated calibration settings can be stored using the store(filename) method. Calibration can be paused if needed.

How to tune the calibration process
There are three important parameters to the calibration process that can be modified by the user program.

• The reference value. This is the expected output of the sensor. For calibrating a (motionless) gyro sensor this will be 0. For calibrating a range sensor for example this should be the range to the object the sensor is calibrated to. The reference value is used in calculating the offset parameter, it is not used in calculating scale. The reference has a default value of 0.
• The range value. This is the expected range of the sensor output. For calibrating an accelerometer this could be 2*9.81 when the output should be in m/s^2. The range value is used in calculating the scale parameter, it is not used in calculating offset. The range has a default value of 2, meaning sample values are normalized to a range of -1 to 1.
• The timeConstant value. This is the timeConstant value of a low-pass filter that is used in calibration mode. A low pass filter is used during calibration to for two reasons. First to overcome the effects of sensor noise that could otherwise seriously affect range calculation. Secondly it filters out the side effect of user manipulation when turning the sensor as part of the calibration process (six way tumbling method). The parameter affects the amount of smoothing of the low-pass filter. The higher the value, the smoother the samples. Smoother samples are less affected by sensor noise or external shocks but take longer to settle. The time constant has a default value of 0, meaning no smoothing is done by default.

Author:

Aswin Bouwmeester

Nested Class Summary

Nested classes/interfaces inherited from class lejos.robotics.filter.AbstractCalibrationFilter

AbstractCalibrationFilter.CalibrationFileException

Field Summary

Fields

Modifier and Type	Field and Description
static int	OFFSET_AND_SCALE_CALIBRATION
static int	OFFSET_CALIBRATION

Fields inherited from class lejos.robotics.filter.AbstractCalibrationFilter

calibrating, lowPassFilter, max, min, numberOfSamplesInCalibration, sum

Fields inherited from class lejos.robotics.filter.AbstractFilter

sampleSize, source

Constructor Summary

Constructors

Constructor and Description
LinearCalibrationFilter(SampleProvider source)
LinearCalibrationFilter(SampleProvider source, java.lang.String filename) Construcor

Method Summary

Modifier and Type	Method and Description
void	fetchSample(float[] dst, int off) Fetches a sample from the sensor and updates calibration parameters when the calibration process is running.
int	getCalibrationType()
int	getCallibrationType()
float[]	getOffsetCorrection() Returns an array with the offset correction parameters that are currently in use
float[]	getScaleCorrection() Returns an array with the scale correction paramaters that are currently in use
void	open(java.lang.String name)
void	save(java.lang.String filename) Stores the calibration parameters, offset and/or scale depending on current settings, to a filterProperties file.
void	setCalibrationType(int calibrationType)
void	setOffsetCalibration(float offset)
void	setOffsetCalibration(float[] offset)
void	setScaleCalibration(float ulBound)
void	setScaleCalibration(float[] lBound, float[] uBound)
void	setScaleCalibration(float lBound, float uBound)
void	startCalibration() Starts a calibration process.
void	stopCalibration() Halts the process of updating calibration parameters.
java.lang.String	toString()

Methods inherited from class lejos.robotics.filter.AbstractCalibrationFilter

getProperty, getPropertyArray, load, resumeCalibration, setProperty, setPropertyArray, setTimeConstant, store, suspendCalibration

Methods inherited from class lejos.robotics.filter.AbstractFilter

sampleSize

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OFFSET_CALIBRATION

public static final int OFFSET_CALIBRATION

See Also:

Constant Field Values

OFFSET_AND_SCALE_CALIBRATION

public static final int OFFSET_AND_SCALE_CALIBRATION

See Also:

Constant Field Values

Constructor Detail

LinearCalibrationFilter

public LinearCalibrationFilter(SampleProvider source,
                               java.lang.String filename)

Construcor

Parameters:

source - SampleProvider

filename - Filename to load calibration settings from

LinearCalibrationFilter

public LinearCalibrationFilter(SampleProvider source)

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

setScaleCalibration

public void setScaleCalibration(float ulBound)

setScaleCalibration

public void setScaleCalibration(float lBound,
                                float uBound)

setScaleCalibration

public void setScaleCalibration(float[] lBound,
                                float[] uBound)

setOffsetCalibration

public void setOffsetCalibration(float offset)

setOffsetCalibration

public void setOffsetCalibration(float[] offset)

setCalibrationType

public void setCalibrationType(int calibrationType)

getCallibrationType

public int getCallibrationType()

getOffsetCorrection

public float[] getOffsetCorrection()

Returns an array with the offset correction parameters that are currently in use

Returns:

the offset correction array

getScaleCorrection

public float[] getScaleCorrection()

Returns an array with the scale correction paramaters that are currently in use

Returns:

the scale correction array

startCalibration

public void startCalibration()

Starts a calibration process. Resets collected minimum and maximum values. After starting calibration new minimum and maximum values are calculated on each fetched sample. From this updated offset and scale parameters are calculated.

Specified by:

startCalibration in interface Calibrate

Overrides:

startCalibration in class AbstractCalibrationFilter

stopCalibration

public void stopCalibration()

Description copied from class: AbstractCalibrationFilter

Halts the process of updating calibration parameters.

Specified by:

stopCalibration in interface Calibrate

Overrides:

stopCalibration in class AbstractCalibrationFilter

save

public void save(java.lang.String filename)

Stores the calibration parameters, offset and/or scale depending on current settings, to a filterProperties file. Stored parameters can later be used by the CalibrationFilter.

Parameters:

filename - A name to use for storing calibration parameters

open

public void open(java.lang.String name)

fetchSample

public void fetchSample(float[] dst,
                        int off)

Fetches a sample from the sensor and updates calibration parameters when the calibration process is running.

Specified by:

fetchSample in interface SampleProvider

Overrides:

fetchSample in class AbstractCalibrationFilter

Parameters:

dst - The array to store the sample in.

off - The elements of the sample are stored in the array starting at the offset position.

getCalibrationType

public int getCalibrationType()