1 /*
2 * Copyright (C) 2019 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.RangingAndRssiFingerprint;
23 import com.irurueta.navigation.indoor.RangingAndRssiReading;
24 import com.irurueta.navigation.lateration.RANSACRobustLateration3DSolver;
25 import com.irurueta.numerical.robust.RobustEstimatorMethod;
26
27 import java.util.List;
28
29 /**
30 * Robustly estimates 3D position using located ranging+RSSI radio sources and their
31 * ranging readings at unknown locations and using RANSAC 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 ranging+RSSI readings at an unknown location of different radio
34 * sources whose 3D locations are known.
35 */
36 public class RANSACRobustRangingAndRssiPositionEstimator3D extends RobustRangingAndRssiPositionEstimator3D {
37
38 /**
39 * Constructor.
40 */
41 public RANSACRobustRangingAndRssiPositionEstimator3D() {
42 super();
43 init();
44 }
45
46 /**
47 * Constructor.
48 *
49 * @param sources located radio sources used for lateration.
50 * @throws IllegalArgumentException if provided sources is null or the number of
51 * provided sources is less than the required minimum.
52 */
53 public RANSACRobustRangingAndRssiPositionEstimator3D(final List<? extends RadioSourceLocated<Point3D>> sources) {
54 super();
55 init();
56 internalSetSources(sources);
57 }
58
59 /**
60 * Constructor.
61 *
62 * @param fingerprint fingerprint containing ranging+RSSI readings at an unknown location
63 * for provided located radio sources.
64 * @throws IllegalArgumentException if provided fingerprint is null.
65 */
66 public RANSACRobustRangingAndRssiPositionEstimator3D(
67 final RangingAndRssiFingerprint<? extends RadioSource, ? extends RangingAndRssiReading<?
68 extends RadioSource>> fingerprint) {
69 super();
70 init();
71 internalSetFingerprint(fingerprint);
72 }
73
74 /**
75 * Constructor.
76 *
77 * @param sources located radio sources used for lateration.
78 * @param fingerprint fingerprint containing ranging+RSSI readings at an unknown location for
79 * provided located radio sources.
80 * @throws IllegalArgumentException if either provided sources or fingerprint is null
81 * or the number of provided sources is less than the required minimum.
82 */
83 public RANSACRobustRangingAndRssiPositionEstimator3D(
84 final List<? extends RadioSourceLocated<Point3D>> sources,
85 final RangingAndRssiFingerprint<? extends RadioSource, ? extends RangingAndRssiReading<?
86 extends RadioSource>> fingerprint) {
87 super();
88 init();
89 internalSetSources(sources);
90 internalSetFingerprint(fingerprint);
91 }
92
93 /**
94 * Constructor.
95 *
96 * @param listener listener in charge of handling events.
97 */
98 public RANSACRobustRangingAndRssiPositionEstimator3D(
99 final RobustRangingAndRssiPositionEstimatorListener<Point3D> listener) {
100 super(listener);
101 init();
102 }
103
104 /**
105 * Constructor.
106 *
107 * @param sources located radio sources used for lateration.
108 * @param listener listener in charge of handling events.
109 * @throws IllegalArgumentException if provided sources is null or the number of
110 * provided sources is less than the required minimum.
111 */
112 public RANSACRobustRangingAndRssiPositionEstimator3D(
113 final List<? extends RadioSourceLocated<Point3D>> sources,
114 final RobustRangingAndRssiPositionEstimatorListener<Point3D> listener) {
115 super(listener);
116 init();
117 internalSetSources(sources);
118 }
119
120 /**
121 * Constructor.
122 *
123 * @param fingerprint fingerprint containing ranging+RSSI readings at an unknown
124 * location for provided located radio sources.
125 * @param listener listener in charge of handling events.
126 * @throws IllegalArgumentException if provided fingerprint is null.
127 */
128 public RANSACRobustRangingAndRssiPositionEstimator3D(
129 final RangingAndRssiFingerprint<? extends RadioSource, ? extends RangingAndRssiReading<?
130 extends RadioSource>> fingerprint,
131 final RobustRangingAndRssiPositionEstimatorListener<Point3D> listener) {
132 super(listener);
133 init();
134 internalSetFingerprint(fingerprint);
135 }
136
137 /**
138 * Constructor.
139 *
140 * @param sources located radio sources used for lateration.
141 * @param fingerprint fingerprint containing ranging+RSSI readings at an unknown
142 * location for provided located radio sources.
143 * @param listener listener in charge of handling events.
144 * @throws IllegalArgumentException if either provided sources or fingerprint is
145 * null or the number of provided sources is less than the required minimum.
146 */
147 public RANSACRobustRangingAndRssiPositionEstimator3D(
148 final List<? extends RadioSourceLocated<Point3D>> sources,
149 final RangingAndRssiFingerprint<? extends RadioSource, ? extends RangingAndRssiReading<?
150 extends RadioSource>> fingerprint,
151 final RobustRangingAndRssiPositionEstimatorListener<Point3D> listener) {
152 super(listener);
153 init();
154 internalSetSources(sources);
155 internalSetFingerprint(fingerprint);
156 }
157
158 /**
159 * Gets threshold to determine whether samples are inliers or not when testing
160 * possible solutions.
161 * The threshold refers to the amount of error on distance between estimated
162 * position and distances provided for each sample.
163 *
164 * @return threshold to determine whether samples are inliers or not.
165 */
166 public double getThreshold() {
167 return ((RANSACRobustLateration3DSolver) laterationSolver).getThreshold();
168 }
169
170 /**
171 * Sets threshold to determine whether samples are inliers or not when testing
172 * possible solutions.
173 * The threshold refers to the amount of error on distance between estimated position
174 * and distances provided for each sample.
175 *
176 * @param threshold threshold to determine whether samples are inliers or not.
177 * @throws IllegalArgumentException if provided value is equal or less than zero.
178 * @throws LockedException if this estimator is locked.
179 */
180 public void setThreshold(final double threshold) throws LockedException {
181 ((RANSACRobustLateration3DSolver) laterationSolver).setThreshold(threshold);
182 }
183
184 /**
185 * Indicates whether inliers must be computed and kept.
186 *
187 * @return true if inliers must be computed and kept, false if inliers
188 * only need to be computed but not kept.
189 */
190 public boolean isComputeAndKeepInliersEnabled() {
191 return ((RANSACRobustLateration3DSolver) laterationSolver).isComputeAndKeepInliersEnabled();
192 }
193
194 /**
195 * Specifies whether inliers must be computed and kept.
196 *
197 * @param computeAndKeepInliers true if inliers must be computed and kept,
198 * false if inliers only need to be computed but not
199 * kept.
200 * @throws LockedException if this estimator is locked.
201 */
202 public void setComputeAndKeepInliersEnabled(final boolean computeAndKeepInliers) throws LockedException {
203 ((RANSACRobustLateration3DSolver) laterationSolver).setComputeAndKeepInliersEnabled(computeAndKeepInliers);
204 }
205
206 /**
207 * Indicates whether residuals must be computed and kept.
208 *
209 * @return true if residuals must be computed and kept, false if residuals
210 * only need to be computed but not kept.
211 */
212 public boolean isComputeAndKeepResiduals() {
213 return ((RANSACRobustLateration3DSolver) laterationSolver).isComputeAndKeepResiduals();
214 }
215
216 /**
217 * Specifies whether residuals must be computed and kept.
218 *
219 * @param computeAndKeepResiduals true if residuals must be computed and kept,
220 * false if residuals only need to be computed but not kept.
221 * @throws LockedException if this estimator is locked.
222 */
223 public void setComputeAndKeepResidualsEnabled(final boolean computeAndKeepResiduals) throws LockedException {
224 ((RANSACRobustLateration3DSolver) laterationSolver).setComputeAndKeepResidualsEnabled(computeAndKeepResiduals);
225 }
226
227 /**
228 * Returns method being used for robust estimation.
229 *
230 * @return method being used for robust estimation.
231 */
232 @Override
233 public RobustEstimatorMethod getMethod() {
234 return RobustEstimatorMethod.RANSAC;
235 }
236
237 /**
238 * Initializes robust lateration solver.
239 */
240 private void init() {
241 laterationSolver = new RANSACRobustLateration3DSolver(trilaterationSolverListener);
242 }
243 }