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.
resetCalibrationQuality88   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