1 /*
2 * Copyright (C) 2020 Alberto Irurueta Carro (alberto@irurueta.com)
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 package com.irurueta.navigation.inertial.calibration.accelerometer;
17
18 import com.irurueta.algebra.Matrix;
19 import com.irurueta.navigation.LockedException;
20 import com.irurueta.navigation.NotReadyException;
21 import com.irurueta.navigation.inertial.calibration.CalibrationException;
22
23 /**
24 * Interface for accelerometer calibrators.
25 */
26 public interface AccelerometerCalibrator {
27
28 /**
29 * Indicates the type of measurement used by this calibrator.
30 *
31 * @return type of measurement used by this calibrator.
32 */
33 AccelerometerCalibratorMeasurementType getMeasurementType();
34
35 /**
36 * Indicates whether this calibrator requires ordered measurements in a
37 * list or not.
38 *
39 * @return true if measurements must be ordered, false otherwise.
40 */
41 boolean isOrderedMeasurementsRequired();
42
43 /**
44 * Indicates whether this calibrator requires quality scores for each
45 * measurement or not.
46 *
47 * @return true if quality scores are required, false otherwise.
48 */
49 boolean isQualityScoresRequired();
50
51 /**
52 * Indicates whether z-axis is assumed to be common for accelerometer and
53 * gyroscope.
54 * When enabled, this eliminates 3 variables from Ma matrix.
55 *
56 * @return true if z-axis is assumed to be common for accelerometer and gyroscope,
57 * false otherwise.
58 */
59 boolean isCommonAxisUsed();
60
61 /**
62 * Specifies whether z-axis is assumed to be common for accelerometer and
63 * gyroscope.
64 * When enabled, this eliminates 3 variables from Ma matrix.
65 *
66 * @param commonAxisUsed true if z-axis is assumed to be common for accelerometer
67 * and gyroscope, false otherwise.
68 * @throws LockedException if estimator is currently running.
69 */
70 void setCommonAxisUsed(final boolean commonAxisUsed) throws LockedException;
71
72 /**
73 * Gets minimum number of required measurements.
74 *
75 * @return minimum number of required measurements.
76 */
77 int getMinimumRequiredMeasurements();
78
79 /**
80 * Indicates whether calibrator is ready to start the estimator.
81 *
82 * @return true if calibrator is ready, false otherwise.
83 */
84 boolean isReady();
85
86 /**
87 * Indicates whether calibrator is currently running or not.
88 *
89 * @return true if calibrator is running, false otherwise.
90 */
91 boolean isRunning();
92
93 /**
94 * Estimates accelerometer calibration parameters containing scale factors
95 * and cross-coupling errors.
96 *
97 * @throws LockedException if calibrator is currently running.
98 * @throws NotReadyException if calibrator is not ready.
99 * @throws CalibrationException if calibration fails for numerical reasons.
100 */
101 void calibrate() throws LockedException, NotReadyException, CalibrationException;
102
103 /**
104 * Gets estimated accelerometer scale factors and cross coupling errors.
105 * This is the product of matrix Ta containing cross coupling errors and Ka
106 * containing scaling factors.
107 * So tat:
108 * <pre>
109 * Ma = [sx mxy mxz] = Ta*Ka
110 * [myx sy myz]
111 * [mzx mzy sz ]
112 * </pre>
113 * Where:
114 * <pre>
115 * Ka = [sx 0 0 ]
116 * [0 sy 0 ]
117 * [0 0 sz]
118 * </pre>
119 * and
120 * <pre>
121 * Ta = [1 -alphaXy alphaXz ]
122 * [alphaYx 1 -alphaYz]
123 * [-alphaZx alphaZy 1 ]
124 * </pre>
125 * Hence:
126 * <pre>
127 * Ma = [sx mxy mxz] = Ta*Ka = [sx -sy * alphaXy sz * alphaXz ]
128 * [myx sy myz] [sx * alphaYx sy -sz * alphaYz]
129 * [mzx mzy sz ] [-sx * alphaZx sy * alphaZy sz ]
130 * </pre>
131 * This instance allows any 3x3 matrix however, typically alphaYx, alphaZx and alphaZy
132 * are considered to be zero if the accelerometer z-axis is assumed to be the same
133 * as the body z-axis. When this is assumed, myx = mzx = mzy = 0 and the Ma matrix
134 * becomes upper diagonal:
135 * <pre>
136 * Ma = [sx mxy mxz]
137 * [0 sy myz]
138 * [0 0 sz ]
139 * </pre>
140 * Values of this matrix are unit-less.
141 *
142 * @return estimated accelerometer scale factors and cross coupling errors, or null
143 * if not available.
144 */
145 Matrix getEstimatedMa();
146
147 /**
148 * Gets estimated x-axis scale factor.
149 *
150 * @return estimated x-axis scale factor or null if not available.
151 */
152 Double getEstimatedSx();
153
154 /**
155 * Gets estimated y-axis scale factor.
156 *
157 * @return estimated y-axis scale factor or null if not available.
158 */
159 Double getEstimatedSy();
160
161 /**
162 * Gets estimated z-axis scale factor.
163 *
164 * @return estimated z-axis scale factor or null if not available.
165 */
166 Double getEstimatedSz();
167
168 /**
169 * Gets estimated x-y cross-coupling error.
170 *
171 * @return estimated x-y cross-coupling error or null if not available.
172 */
173 Double getEstimatedMxy();
174
175 /**
176 * Gets estimated x-z cross-coupling error.
177 *
178 * @return estimated x-z cross-coupling error or null if not available.
179 */
180 Double getEstimatedMxz();
181
182 /**
183 * Gets estimated y-x cross-coupling error.
184 *
185 * @return estimated y-x cross-coupling error or null if not available.
186 */
187 Double getEstimatedMyx();
188
189 /**
190 * Gets estimated y-z cross-coupling error.
191 *
192 * @return estimated y-z cross-coupling error or null if not available.
193 */
194 Double getEstimatedMyz();
195
196 /**
197 * Gets estimated z-x cross-coupling error.
198 *
199 * @return estimated z-x cross-coupling error or null if not available.
200 */
201 Double getEstimatedMzx();
202
203 /**
204 * Gets estimated z-y cross-coupling error.
205 *
206 * @return estimated z-y cross-coupling error or null if not available.
207 */
208 Double getEstimatedMzy();
209 }