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.gyroscope;
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 gyroscope calibrators.
25 */
26 public interface GyroscopeCalibrator {
27
28 /**
29 * Indicates the type of measurement or sequence used by this calibrator.
30 *
31 * @return type of measurement or sequence used by this calibrator.
32 */
33 GyroscopeCalibratorMeasurementOrSequenceType getMeasurementOrSequenceType();
34
35 /**
36 * Indicates whether this calibrator requires ordered measurements or sequences
37 * in a list or not.
38 *
39 * @return true if measurements or sequences must be ordered, false otherwise.
40 */
41 boolean isOrderedMeasurementsOrSequencesRequired();
42
43 /**
44 * Indicates whether this calibrator requires quality scores for each
45 * measurement/sequence 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 Mg 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 Mg 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 calibrator is currently running.
69 */
70 void setCommonAxisUsed(final boolean commonAxisUsed) throws LockedException;
71
72 /**
73 * Gets minimum number of required measurements or
74 * sequences.
75 *
76 * @return minimum number of required measurements
77 * or sequences.
78 */
79 int getMinimumRequiredMeasurementsOrSequences();
80
81 /**
82 * Indicates whether calibrator is ready to start the calibration.
83 *
84 * @return true if calibrator is ready, false otherwise.
85 */
86 boolean isReady();
87
88 /**
89 * Indicates whether calibrator is currently running or not.
90 *
91 * @return true if calibrator is running, false otherwise.
92 */
93 boolean isRunning();
94
95 /**
96 * Estimates gyroscope calibration parameters containing bias, scale factors,
97 * cross-coupling errors and g-dependant cross biases.
98 *
99 * @throws LockedException if calibrator is currently running.
100 * @throws NotReadyException if calibrator is not ready.
101 * @throws CalibrationException if calibration fails for numerical reasons.
102 */
103 void calibrate() throws LockedException, NotReadyException, CalibrationException;
104
105 /**
106 * Gets estimated gyroscope scale factors and cross coupling errors.
107 * This is the product of matrix Tg containing cross coupling errors and Kg
108 * containing scaling factors.
109 * So that:
110 * <pre>
111 * Mg = [sx mxy mxz] = Tg*Kg
112 * [myx sy myz]
113 * [mzx mzy sz ]
114 * </pre>
115 * Where:
116 * <pre>
117 * Kg = [sx 0 0 ]
118 * [0 sy 0 ]
119 * [0 0 sz]
120 * </pre>
121 * and
122 * <pre>
123 * Tg = [1 -alphaXy alphaXz ]
124 * [alphaYx 1 -alphaYz]
125 * [-alphaZx alphaZy 1 ]
126 * </pre>
127 * Hence:
128 * <pre>
129 * Mg = [sx mxy mxz] = Tg*Kg = [sx -sy * alphaXy sz * alphaXz ]
130 * [myx sy myz] [sx * alphaYx sy -sz * alphaYz]
131 * [mzx mzy sz ] [-sx * alphaZx sy * alphaZy sz ]
132 * </pre>
133 * This instance allows any 3x3 matrix however, typically alphaYx, alphaZx and alphaZy
134 * are considered to be zero if the gyroscope z-axis is assumed to be the same
135 * as the body z-axis. When this is assumed, myx = mzx = mzy = 0 and the Mg matrix
136 * becomes upper diagonal:
137 * <pre>
138 * Mg = [sx mxy mxz]
139 * [0 sy myz]
140 * [0 0 sz ]
141 * </pre>
142 * Values of this matrix are unit-less.
143 *
144 * @return estimated gyroscope scale factors and cross coupling errors.
145 */
146 Matrix getEstimatedMg();
147
148 /**
149 * Gets estimated x-axis scale factor.
150 *
151 * @return estimated x-axis scale factor or null if not available.
152 */
153 Double getEstimatedSx();
154
155 /**
156 * Gets estimated y-axis scale factor.
157 *
158 * @return estimated y-axis scale factor or null if not available.
159 */
160 Double getEstimatedSy();
161
162 /**
163 * Gets estimated z-axis scale factor.
164 *
165 * @return estimated z-axis scale factor or null if not available.
166 */
167 Double getEstimatedSz();
168
169 /**
170 * Gets estimated x-y cross-coupling error.
171 *
172 * @return estimated x-y cross-coupling error or null if not available.
173 */
174 Double getEstimatedMxy();
175
176 /**
177 * Gets estimated x-z cross-coupling error.
178 *
179 * @return estimated x-z cross-coupling error or null if not available.
180 */
181 Double getEstimatedMxz();
182
183 /**
184 * Gets estimated y-x cross-coupling error.
185 *
186 * @return estimated y-x cross-coupling error or null if not available.
187 */
188 Double getEstimatedMyx();
189
190 /**
191 * Gets estimated y-z cross-coupling error.
192 *
193 * @return estimated y-z cross-coupling error or null if not available.
194 */
195 Double getEstimatedMyz();
196
197 /**
198 * Gets estimated z-x cross-coupling error.
199 *
200 * @return estimated z-x cross-coupling error or null if not available.
201 */
202 Double getEstimatedMzx();
203
204 /**
205 * Gets estimated z-y cross-coupling error.
206 *
207 * @return estimated z-y cross-coupling error or null if not available.
208 */
209 Double getEstimatedMzy();
210
211 /**
212 * Gets estimated G-dependent cross biases introduced on the gyroscope by the
213 * specific forces sensed by the accelerometer.
214 *
215 * @return a 3x3 matrix containing g-dependent cross biases.
216 */
217 Matrix getEstimatedGg();
218 }