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
21 /**
22 * Interface for non-linear gyroscope calibrators.
23 */
24 public interface GyroscopeNonLinearCalibrator extends GyroscopeCalibrator {
25 /**
26 * Gets initial x scaling factor.
27 *
28 * @return initial x scaling factor.
29 */
30 double getInitialSx();
31
32 /**
33 * Sets initial x scaling factor.
34 *
35 * @param initialSx initial x scaling factor.
36 * @throws LockedException if calibrator is currently running.
37 */
38 void setInitialSx(final double initialSx) throws LockedException;
39
40 /**
41 * Gets initial y scaling factor.
42 *
43 * @return initial y scaling factor.
44 */
45 double getInitialSy();
46
47 /**
48 * Sets initial y scaling factor.
49 *
50 * @param initialSy initial y scaling factor.
51 * @throws LockedException if calibrator is currently running.
52 */
53 void setInitialSy(final double initialSy) throws LockedException;
54
55 /**
56 * Gets initial z scaling factor.
57 *
58 * @return initial z scaling factor.
59 */
60 double getInitialSz();
61
62 /**
63 * Sets initial z scaling factor.
64 *
65 * @param initialSz initial z scaling factor.
66 * @throws LockedException if calibrator is currently running.
67 */
68 void setInitialSz(final double initialSz) throws LockedException;
69
70 /**
71 * Gets initial x-y cross coupling error.
72 *
73 * @return initial x-y cross coupling error.
74 */
75 double getInitialMxy();
76
77 /**
78 * Sets initial x-y cross coupling error.
79 *
80 * @param initialMxy initial x-y cross coupling error.
81 * @throws LockedException if calibrator is currently running.
82 */
83 void setInitialMxy(final double initialMxy) throws LockedException;
84
85 /**
86 * Gets initial x-z cross coupling error.
87 *
88 * @return initial x-z cross coupling error.
89 */
90 double getInitialMxz();
91
92 /**
93 * Sets initial x-z cross coupling error.
94 *
95 * @param initialMxz initial x-z cross coupling error.
96 * @throws LockedException if calibrator is currently running.
97 */
98 void setInitialMxz(final double initialMxz) throws LockedException;
99
100 /**
101 * Gets initial y-x cross coupling error.
102 *
103 * @return initial y-x cross coupling error.
104 */
105 double getInitialMyx();
106
107 /**
108 * Sets initial y-x cross coupling error.
109 *
110 * @param initialMyx initial y-x cross coupling error.
111 * @throws LockedException if calibrator is currently running.
112 */
113 void setInitialMyx(final double initialMyx) throws LockedException;
114
115 /**
116 * Gets initial y-z cross coupling error.
117 *
118 * @return initial y-z cross coupling error.
119 */
120 double getInitialMyz();
121
122 /**
123 * Sets initial y-z cross coupling error.
124 *
125 * @param initialMyz initial y-z cross coupling error.
126 * @throws LockedException if calibrator is currently running.
127 */
128 void setInitialMyz(final double initialMyz) throws LockedException;
129
130 /**
131 * Gets initial z-x cross coupling error.
132 *
133 * @return initial z-x cross coupling error.
134 */
135 double getInitialMzx();
136
137 /**
138 * Sets initial z-x cross coupling error.
139 *
140 * @param initialMzx initial z-x cross coupling error.
141 * @throws LockedException if calibrator is currently running.
142 */
143 void setInitialMzx(final double initialMzx) throws LockedException;
144
145 /**
146 * Gets initial z-y cross coupling error.
147 *
148 * @return initial z-y cross coupling error.
149 */
150 double getInitialMzy();
151
152 /**
153 * Sets initial z-y cross coupling error.
154 *
155 * @param initialMzy initial z-y cross coupling error.
156 * @throws LockedException if calibrator is currently running.
157 */
158 void setInitialMzy(final double initialMzy) throws LockedException;
159
160 /**
161 * Sets initial scaling factors.
162 *
163 * @param initialSx initial x scaling factor.
164 * @param initialSy initial y scaling factor.
165 * @param initialSz initial z scaling factor.
166 * @throws LockedException if calibrator is currently running.
167 */
168 void setInitialScalingFactors(
169 final double initialSx, final double initialSy, final double initialSz) throws LockedException;
170
171 /**
172 * Sets initial cross coupling errors.
173 *
174 * @param initialMxy initial x-y cross coupling error.
175 * @param initialMxz initial x-z cross coupling error.
176 * @param initialMyx initial y-x cross coupling error.
177 * @param initialMyz initial y-z cross coupling error.
178 * @param initialMzx initial z-x cross coupling error.
179 * @param initialMzy initial z-y cross coupling error.
180 * @throws LockedException if calibrator is currently running.
181 */
182 void setInitialCrossCouplingErrors(
183 final double initialMxy, final double initialMxz, final double initialMyx,
184 final double initialMyz, final double initialMzx, final double initialMzy) throws LockedException;
185
186 /**
187 * Sets initial scaling factors and cross coupling errors.
188 *
189 * @param initialSx initial x scaling factor.
190 * @param initialSy initial y scaling factor.
191 * @param initialSz initial z scaling factor.
192 * @param initialMxy initial x-y cross coupling error.
193 * @param initialMxz initial x-z cross coupling error.
194 * @param initialMyx initial y-x cross coupling error.
195 * @param initialMyz initial y-z cross coupling error.
196 * @param initialMzx initial z-x cross coupling error.
197 * @param initialMzy initial z-y cross coupling error.
198 * @throws LockedException if calibrator is currently running.
199 */
200 void setInitialScalingFactorsAndCrossCouplingErrors(
201 final double initialSx, final double initialSy, final double initialSz,
202 final double initialMxy, final double initialMxz, final double initialMyx,
203 final double initialMyz, final double initialMzx, final double initialMzy) throws LockedException;
204
205 /**
206 * Gets initial scale factors and cross coupling errors matrix.
207 *
208 * @return initial scale factors and cross coupling errors matrix.
209 */
210 Matrix getInitialMg();
211
212 /**
213 * Gets initial scale factors and cross coupling errors matrix.
214 *
215 * @param result instance where data will be stored.
216 * @throws IllegalArgumentException if provided matrix is not 3x3.
217 */
218 void getInitialMg(final Matrix result);
219
220 /**
221 * Sets initial scale factors and cross coupling errors matrix.
222 *
223 * @param initialMg initial scale factors and cross coupling errors matrix.
224 * @throws IllegalArgumentException if provided matrix is not 3x3.
225 * @throws LockedException if calibrator is currently running.
226 */
227 void setInitialMg(final Matrix initialMg) throws LockedException;
228
229 /**
230 * Gets initial G-dependent cross biases introduced on the gyroscope by the
231 * specific forces sensed by the accelerometer.
232 *
233 * @return a 3x3 matrix containing initial g-dependent cross biases.
234 */
235 Matrix getInitialGg();
236
237 /**
238 * Gets initial G-dependent cross biases introduced on the gyroscope by the
239 * specific forces sensed by the accelerometer.
240 *
241 * @param result instance where data will be stored.
242 * @throws IllegalArgumentException if provided matrix is not 3x3.
243 */
244 void getInitialGg(final Matrix result);
245
246 /**
247 * Sets initial G-dependent cross biases introduced on the gyroscope by the
248 * specific forces sensed by the accelerometer.
249 *
250 * @param initialGg g-dependent cross biases.
251 * @throws LockedException if calibrator is currently running.
252 */
253 void setInitialGg(final Matrix initialGg) throws LockedException;
254
255 /**
256 * Gets estimated covariance matrix for estimated position.
257 *
258 * @return estimated covariance matrix for estimated position.
259 */
260 Matrix getEstimatedCovariance();
261
262 /**
263 * Gets estimated chi square value.
264 *
265 * @return estimated chi square value.
266 */
267 double getEstimatedChiSq();
268
269 /**
270 * Gets estimated chi square degrees of freedom. Degrees of freedom is equal to the number of sampled data minus the
271 * number of estimated parameters.
272 *
273 * @return estimated degrees of freedom of chi square value
274 */
275 int getEstimatedChiSqDegreesOfFreedom();
276
277 /**
278 * Gets estimated reduced chi square value. This is equal to estimated chi square value divided by its degrees of
279 * freedom. Ideally this value should be close to 1.0, indicating that fit is optimal.
280 * A value larger than 1.0 indicates that fit is not good or noise has been underestimated, and a value smaller than
281 * 1.0 indicates that there is overfitting or noise has been overestimated.
282 *
283 * @return estimated reduced chi square value
284 */
285 double getEstimatedReducedChiSq();
286
287 /**
288 * Gets estimated mean square error respect to provided measurements.
289 *
290 * @return estimated mean square error respect to provided measurements.
291 */
292 double getEstimatedMse();
293
294 /**
295 * Gets estimated probability of finding a smaller chi square value expressed as a value between 0.0 and 1.0. The
296 * smaller the found chi square value is, the better the fit of the estimated parameters to the actual parameter.
297 * Thus, the smaller the chance of finding a smaller chi square value, then the better the estimated fit is.
298 *
299 * @return estimated probability of finding a smaller chi square value or null if there were numerical unstabilities
300 * to compute such value.
301 */
302 double getEstimatedP();
303
304 /**
305 * Gets estimated measure of quality of estimated fit as a value between 0.0 and 1.0. The larger the quality value
306 * is, the better the fit that has been estimated.
307 *
308 * @return estimated measure of quality of estimated fit.
309 */
310 double getEstimatedQ();
311 }