Home | History | Annotate | Download | only in common_data 
      1 /*
      2  * Copyright (C) 2018 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 /*
     18  * This module provides quality definitions that represent the accuracy
     19  * associated with calibration data. This information may be used to affect how
     20  * a system uses available sensor calibration data.
     21  */
     22 
     23 #ifndef LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_QUALITY_H_
     24 #define LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_QUALITY_H_
     25 
     26 #include <float.h>
     27 #include <stdint.h>
     28 
     29 namespace online_calibration {
     30 
     31 /*
     32  * In general, calibration quality values may be thought of in terms of
     33  * something akin to an error standard deviation. That is, it's a non-negative
     34  * value where lower values imply higher calibration quality, and larger values
     35  * indicate poorer quality. However, the units and numerical interpretation is
     36  * ultimately dictated by the sensor type and calibration algorithm. Consult the
     37  * calibration code implementation for the actual calibration quality metric
     38  * details.
     39  */
     40 
     41 /*
     42  * Bitmask used to provide a qualitative ranking of the calibration data's
     43  * accuracy. Many systems use this sort of interpretation for calibration
     44  * quality (e.g., Android).
     45  *
     46  * [Bit Flag]   | [Qualitative Calibration Quality]
     47  * UNDETERMINED    - Calibration quality has not yet been determined (e.g., a
     48  *                   calibration hasn't occurred, or a metric hasn't been
     49  *                   established).
     50  * LOW_QUALITY     - Sensor calibration is needed. System properties have
     51  *                   changed that may have affected the applicability of the
     52  *                   current calibration (e.g., calibration data is old, anomaly
     53  *                   detected, etc.).
     54  * MEDIUM_QUALITY  - The reported sensor calibration has an average level of
     55  *                   accuracy, updated calibration may improve the readings.
     56  * HIGH_QUALITY    - The reported calibration has maximal accuracy.
     57  */
     58 enum class CalibrationQualityLevel : uint8_t {
     59   UNDETERMINED = 0x00,
     60   LOW_QUALITY = 0x01,
     61   MEDIUM_QUALITY = 0x02,
     62   HIGH_QUALITY = 0x04,
     63 };
     64 
     65 // Sets the calibration quality value when this metric is either not
     66 // implemented, or has not yet been determined (e.g., a calibration hasn't
     67 // occurred).
     68 constexpr float kUndeterminedCalibrationQuality = -1.0f;
     69 
     70 /*
     71  * Calibration quality structure that contains a quantitative (float) and
     72  * qualitative (enum) measure of a sensor's calibration accuracy. Both entries
     73  * should be co-defined by the algorithm providing the calibration update. The
     74  * enum sets the qualitative interpretation of the float value, this is often
     75  * used in systems (Android, etc.) to label quality and affect the use of the
     76  * calibration data.
     77  */
     78 struct CalibrationQuality {
     79   // Provides a qualitative measure for sensor calibration accuracy.
     80   CalibrationQualityLevel level = CalibrationQualityLevel::UNDETERMINED;
     81 
     82   // Quantitative metric for the reported calibration accuracy. The behavior and
     83   // definition depends on the sensor calibration type. See the calibration
     84   // algorithm documentation for details.
     85   float value = kUndeterminedCalibrationQuality;
     86 
     87   // Helper function that resets the calibration quality to an initial state.
     88   void reset() {
     89     level = CalibrationQualityLevel::UNDETERMINED;
     90     value = kUndeterminedCalibrationQuality;
     91   }
     92 };
     93 
     94 }  // namespace online_calibration
     95 
     96 #endif  // LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_QUALITY_H_
     97