1 /*
2 * Copyright (C) 2018 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.indoor.position;
17
18 import com.irurueta.geometry.Point3D;
19 import com.irurueta.navigation.LockedException;
20 import com.irurueta.navigation.indoor.RadioSource;
21 import com.irurueta.navigation.indoor.RadioSourceLocated;
22 import com.irurueta.navigation.indoor.RssiFingerprint;
23 import com.irurueta.navigation.indoor.RssiReading;
24 import com.irurueta.navigation.lateration.LMedSRobustLateration3DSolver;
25 import com.irurueta.numerical.robust.RobustEstimatorMethod;
26
27 import java.util.List;
28
29 /**
30 * Robustly estimated 3D position using located radio sources and their RSSI readings
31 * at unknown locations and using LMedS algorithm to discard outliers.
32 * This kind of estimator can be used to robustly determine the 3D position of a given
33 * device by getting RSSI readings at an unknown location of different radio sources
34 * whose 3D locations are known.
35 */
36 public class LMedSRobustRssiPositionEstimator3D extends RobustRssiPositionEstimator3D {
37 /**
38 * Constructor.
39 */
40 public LMedSRobustRssiPositionEstimator3D() {
41 super();
42 init();
43 }
44
45 /**
46 * Constructor.
47 *
48 * @param sources located radio sources used for lateration.
49 * @throws IllegalArgumentException if provided sources is null or the number of
50 * provided sources is less than the required minimum.
51 */
52 public LMedSRobustRssiPositionEstimator3D(final List<? extends RadioSourceLocated<Point3D>> sources) {
53 super();
54 init();
55 internalSetSources(sources);
56 }
57
58 /**
59 * Constructor.
60 *
61 * @param fingerprint fingerprint containing RSSI readings at an unknown location for
62 * provided located radio sources.
63 * @throws IllegalArgumentException if provided fingerprint is null.
64 */
65 public LMedSRobustRssiPositionEstimator3D(
66 final RssiFingerprint<? extends RadioSource, ? extends RssiReading<? extends RadioSource>> fingerprint) {
67 super();
68 init();
69 internalSetFingerprint(fingerprint);
70 }
71
72 /**
73 * Constructor.
74 *
75 * @param sources located radio sources used for lateration.
76 * @param fingerprint fingerprint containing RSSI readings at an unknown location
77 * for provided located radio sources.
78 * @throws IllegalArgumentException if either provided sources or fingerprint is null
79 * or the number of provided sources is less than the required minimum.
80 */
81 public LMedSRobustRssiPositionEstimator3D(
82 final List<? extends RadioSourceLocated<Point3D>> sources,
83 final RssiFingerprint<? extends RadioSource, ? extends RssiReading<? extends RadioSource>> fingerprint) {
84 super();
85 init();
86 internalSetSources(sources);
87 internalSetFingerprint(fingerprint);
88 }
89
90 /**
91 * Constructor.
92 *
93 * @param listener listener in charge of handling events.
94 */
95 public LMedSRobustRssiPositionEstimator3D(final RobustRssiPositionEstimatorListener<Point3D> listener) {
96 super(listener);
97 init();
98 }
99
100 /**
101 * Constructor.
102 *
103 * @param sources located radio sources used for lateration.
104 * @param listener listener in charge of handling events.
105 * @throws IllegalArgumentException if provided sources is null or the number of
106 * provided sources is less than the required minimum.
107 */
108 public LMedSRobustRssiPositionEstimator3D(
109 final List<? extends RadioSourceLocated<Point3D>> sources,
110 final RobustRssiPositionEstimatorListener<Point3D> listener) {
111 super(listener);
112 init();
113 internalSetSources(sources);
114 }
115
116 /**
117 * Constructor.
118 *
119 * @param fingerprint fingerprint containing RSSI readings at an unknown location
120 * for provided location radio sources.
121 * @param listener listener in charge of handling events.
122 * @throws IllegalArgumentException if provided fingerprint is null.
123 */
124 public LMedSRobustRssiPositionEstimator3D(
125 final RssiFingerprint<? extends RadioSource, ? extends RssiReading<? extends RadioSource>> fingerprint,
126 final RobustRssiPositionEstimatorListener<Point3D> listener) {
127 super(listener);
128 init();
129 internalSetFingerprint(fingerprint);
130 }
131
132 /**
133 * Constructor.
134 *
135 * @param sources located radio sources used for lateration.
136 * @param fingerprint fingerprint containing RSSI readings at an unknown location
137 * for provided located radio sources.
138 * @param listener listener in charge of handling events.
139 * @throws IllegalArgumentException if either provided sources or fingerprint is
140 * null or the number of provided sources is less than the required minimum.
141 */
142 public LMedSRobustRssiPositionEstimator3D(
143 final List<? extends RadioSourceLocated<Point3D>> sources,
144 final RssiFingerprint<? extends RadioSource, ? extends RssiReading<? extends RadioSource>> fingerprint,
145 final RobustRssiPositionEstimatorListener<Point3D> listener) {
146 super(listener);
147 init();
148 internalSetSources(sources);
149 internalSetFingerprint(fingerprint);
150 }
151
152 /**
153 * Returns threshold to be used to keep the algorithm iterating in case that
154 * best estimated threshold using median of residuals is not small enough.
155 * Once a solution is found that generates a threshold below this value, the
156 * algorithm will stop.
157 * The stop threshold can be used to prevent the LMedS algorithm to iterate
158 * too many times in cases where samples have a very similar accuracy.
159 * For instance, in cases where proportion of outliers is very small (close
160 * to 0%), and samples are very accurate (i.e. 1e-6), the algorithm would
161 * iterate for a long time trying to find the best solution when indeed
162 * there is no need to do that if a reasonable threshold has already been
163 * reached.
164 * Because of this behaviour the stop threshold can be set to a value much
165 * lower than the one typically used in RANSAC, and yet the algorithm could
166 * still produce even smaller thresholds in estimated results.
167 *
168 * @return stop threshold to stop the algorithm prematurely when a certain
169 * accuracy has been reached.
170 */
171 public double getStopThreshold() {
172 return ((LMedSRobustLateration3DSolver) laterationSolver).getStopThreshold();
173 }
174
175 /**
176 * Sets threshold to be used to keep the algorithm iterating in case that
177 * best estimated threshold using median of residuals is not small enough.
178 * Once a solution is found that generates a threshold below this value,
179 * the algorithm will stop.
180 * The stop threshold can be used to prevent the LMedS algorithm to iterate
181 * too many times in cases where samples have a very similar accuracy.
182 * For instance, in cases where proportion of outliers is very small (close
183 * to 0%), and samples are very accurate (i.e. 1e-6), the algorithm would
184 * iterate for a long time trying to find the best solution when indeed
185 * there is no need to do that if a reasonable threshold has already been
186 * reached.
187 * Because of this behaviour the stop threshold can be set to a value much
188 * lower than the one typically used in RANSAC, and yet the algorithm could
189 * still produce even smaller thresholds in estimated results.
190 *
191 * @param stopThreshold stop threshold to stop the algorithm prematurely
192 * when a certain accuracy has been reached.
193 * @throws IllegalArgumentException if provided value is zero or negative.
194 * @throws LockedException if this solver is locked.
195 */
196 public void setStopThreshold(final double stopThreshold) throws LockedException {
197 ((LMedSRobustLateration3DSolver) laterationSolver).setStopThreshold(stopThreshold);
198 }
199
200 /**
201 * Returns method being used for robust estimation.
202 *
203 * @return method being used for robust estimation.
204 */
205 @Override
206 public RobustEstimatorMethod getMethod() {
207 return RobustEstimatorMethod.LMEDS;
208 }
209
210 /**
211 * Initializes robust lateration solver.
212 */
213 private void init() {
214 laterationSolver = new LMedSRobustLateration3DSolver(trilaterationSolverListener);
215 }
216 }