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.magnetometer;
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 magnetometer calibrators.
25 */
26 public interface MagnetometerCalibrator {
27
28 /**
29 * Indicates the type of measurement used by this calibrator.
30 *
31 * @return type of measurement used by this calibrator.
32 */
33 MagnetometerCalibratorMeasurementType 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,
53 * gyroscope and magnetometer.
54 * When enabled, this eliminates 3 variables from Mm (soft-iron) matrix.
55 *
56 * @return true if z-axis is assumed to be common for accelerometer,
57 * gyroscope and magnetometer, 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 Mm matrix.
65 *
66 * @param commonAxisUsed true if z-axis is assumed to be common for
67 * accelerometer, gyroscope and magnetometer, false
68 * otherwise.
69 * @throws LockedException if estimator is currently running.
70 */
71 void setCommonAxisUsed(final boolean commonAxisUsed) throws LockedException;
72
73 /**
74 * Gets minimum number of required measurements.
75 *
76 * @return minimum number of required measurements.
77 */
78 int getMinimumRequiredMeasurements();
79
80 /**
81 * Indicates whether calibrator is ready to start the estimator.
82 *
83 * @return true if calibrator is ready, false otherwise.
84 */
85 boolean isReady();
86
87 /**
88 * Indicates whether calibrator is currently running or no.
89 *
90 * @return true if calibrator is running, false otherwise.
91 */
92 boolean isRunning();
93
94 /**
95 * Estimates accelerometer calibration parameters containing scale factors
96 * and cross-coupling errors.
97 *
98 * @throws LockedException if calibrator is currently running.
99 * @throws NotReadyException if calibrator is not ready.
100 * @throws CalibrationException if calibration fails for numerical reasons.
101 */
102 void calibrate() throws LockedException, NotReadyException, CalibrationException;
103
104 /**
105 * Gets estimated magnetometer soft-iron matrix containing scale factors
106 * and cross coupling errors.
107 * This is the product of matrix Tm containing cross coupling errors and Km
108 * containing scaling factors.
109 * So tat:
110 * <pre>
111 * Mm = [sx mxy mxz] = Tm*Km
112 * [myx sy myz]
113 * [mzx mzy sz ]
114 * </pre>
115 * Where:
116 * <pre>
117 * Km = [sx 0 0 ]
118 * [0 sy 0 ]
119 * [0 0 sz]
120 * </pre>
121 * and
122 * <pre>
123 * Tm = [1 -alphaXy alphaXz ]
124 * [alphaYx 1 -alphaYz]
125 * [-alphaZx alphaZy 1 ]
126 * </pre>
127 * Hence:
128 * <pre>
129 * Mm = [sx mxy mxz] = Tm*Km = [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 accelerometer z-axis is assumed to be the same
135 * as the body z-axis. When this is assumed, myx = mzx = mzy = 0 and the Mm matrix
136 * becomes upper diagonal:
137 * <pre>
138 * Mm = [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 magnetometer soft-iron scale factors and cross coupling errors,
145 * or null if not available.
146 */
147 Matrix getEstimatedMm();
148
149 /**
150 * Gets estimated x-axis scale factor.
151 *
152 * @return estimated x-axis scale factor or null if not available.
153 */
154 Double getEstimatedSx();
155
156 /**
157 * Gets estimated y-axis scale factor.
158 *
159 * @return estimated y-axis scale factor or null if not available.
160 */
161 Double getEstimatedSy();
162
163 /**
164 * Gets estimated z-axis scale factor.
165 *
166 * @return estimated z-axis scale factor or null if not available.
167 */
168 Double getEstimatedSz();
169
170 /**
171 * Gets estimated x-y cross-coupling error.
172 *
173 * @return estimated x-y cross-coupling error or null if not available.
174 */
175 Double getEstimatedMxy();
176
177 /**
178 * Gets estimated x-z cross-coupling error.
179 *
180 * @return estimated x-z cross-coupling error or null if not available.
181 */
182 Double getEstimatedMxz();
183
184 /**
185 * Gets estimated y-x cross-coupling error.
186 *
187 * @return estimated y-x cross-coupling error or null if not available.
188 */
189 Double getEstimatedMyx();
190
191 /**
192 * Gets estimated y-z cross-coupling error.
193 *
194 * @return estimated y-z cross-coupling error or null if not available.
195 */
196 Double getEstimatedMyz();
197
198 /**
199 * Gets estimated z-x cross-coupling error.
200 *
201 * @return estimated z-x cross-coupling error or null if not available.
202 */
203 Double getEstimatedMzx();
204
205 /**
206 * Gets estimated z-y cross-coupling error.
207 *
208 * @return estimated z-y cross-coupling error or null if not available.
209 */
210 Double getEstimatedMzy();
211 }