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