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