Package lejos.robotics.filter

Class 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

    • 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

      • 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()