1 /*
2 * Copyright (C) 2015 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.geometry.estimators;
17
18 import com.irurueta.geometry.AffineTransformation2D;
19 import com.irurueta.geometry.CoincidentPointsException;
20 import com.irurueta.geometry.CoordinatesType;
21 import com.irurueta.geometry.Point2D;
22 import com.irurueta.numerical.robust.PROSACRobustEstimator;
23 import com.irurueta.numerical.robust.PROSACRobustEstimatorListener;
24 import com.irurueta.numerical.robust.RobustEstimator;
25 import com.irurueta.numerical.robust.RobustEstimatorException;
26 import com.irurueta.numerical.robust.RobustEstimatorMethod;
27
28 import java.util.List;
29
30 /**
31 * Finds the best affine 2D transformation for provided collections of matched
32 * 2D points using PROSAC algorithm.
33 */
34 @SuppressWarnings("DuplicatedCode")
35 public class PROSACPointCorrespondenceAffineTransformation2DRobustEstimator
36 extends PointCorrespondenceAffineTransformation2DRobustEstimator {
37
38 /**
39 * Constant defining default threshold to determine whether points are
40 * inliers or not.
41 * By default, 1.0 is considered a good value for cases where measures are
42 * done on pixels, since typically the minimum resolution is 1 pixel.
43 */
44 public static final double DEFAULT_THRESHOLD = 1.0;
45
46 /**
47 * Minimum value that can be set as threshold.
48 * Threshold must be strictly greater than 0.0.
49 */
50 public static final double MIN_THRESHOLD = 0.0;
51
52 /**
53 * Indicates that by default inliers will only be computed but not kept.
54 */
55 public static final boolean DEFAULT_COMPUTE_AND_KEEP_INLIERS = false;
56
57 /**
58 * Indicates that by default residuals will only be computed but not kept.
59 */
60 public static final boolean DEFAULT_COMPUTE_AND_KEEP_RESIDUALS = false;
61
62 /**
63 * Threshold to determine whether points are inliers or not when testing
64 * possible estimation solutions.
65 * The threshold refers to the amount of error (i.e. distance) a possible
66 * solution has on a matched pair of points.
67 */
68 private double threshold;
69
70 /**
71 * Quality scores corresponding to each pair of matched points.
72 * The larger the score value the better the quality of the matching.
73 */
74 private double[] qualityScores;
75
76 /**
77 * Indicates whether inliers must be computed and kept.
78 */
79 private boolean computeAndKeepInliers;
80
81 /**
82 * Indicates whether residuals must be computed and kept.
83 */
84 private boolean computeAndKeepResiduals;
85
86 /**
87 * Constructor.
88 */
89 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator() {
90 super();
91 threshold = DEFAULT_THRESHOLD;
92 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
93 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
94 }
95
96 /**
97 * Constructor with lists of points to be used to estimate an affine 2D
98 * transformation.
99 * Points in the list located at the same position are considered to be
100 * matched. Hence, both lists must have the same size, and their size must
101 * be greater or equal than MINIMUM_SIZE.
102 *
103 * @param inputPoints list of input points to be used to estimate an
104 * affine 2D transformation.
105 * @param outputPoints list of output points to be used to estimate an
106 * affine 2D transformation.
107 * @throws IllegalArgumentException if provided lists of points don't have
108 * the same size or their size is smaller than MINIMUM_SIZE.
109 */
110 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator(
111 final List<Point2D> inputPoints, final List<Point2D> outputPoints) {
112 super(inputPoints, outputPoints);
113 threshold = DEFAULT_THRESHOLD;
114 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
115 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
116 }
117
118 /**
119 * Constructor.
120 *
121 * @param listener listener to be notified of events such as when estimation
122 * starts, ends or its progress significantly changes.
123 */
124 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator(
125 final AffineTransformation2DRobustEstimatorListener listener) {
126 super(listener);
127 threshold = DEFAULT_THRESHOLD;
128 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
129 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
130 }
131
132 /**
133 * Constructor with listener and lists of points to be used to estimate an
134 * affine 2D transformation.
135 * Points in the list located at the same position are considered to be
136 * matched. Hence, both lists must have the same size, and their size must
137 * be greater or equal than MINIMUM_SIZE.
138 *
139 * @param listener listener to be notified of events such as when estimation
140 * stars, ends or its progress significantly changes.
141 * @param inputPoints list of input points to be used to estimate an
142 * affine 2D transformation.
143 * @param outputPoints list of output points to be used to estimate an
144 * affine 2D transformation.
145 * @throws IllegalArgumentException if provided lists of points don't have
146 * the same size or their size is smaller than MINIMUM_SIZE.
147 */
148 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator(
149 final AffineTransformation2DRobustEstimatorListener listener,
150 final List<Point2D> inputPoints, final List<Point2D> outputPoints) {
151 super(listener, inputPoints, outputPoints);
152 threshold = DEFAULT_THRESHOLD;
153 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
154 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
155 }
156
157 /**
158 * Constructor.
159 *
160 * @param qualityScores quality scores corresponding to each pair of matched
161 * points.
162 * @throws IllegalArgumentException if provided quality scores length is
163 * smaller than MINIMUM_SIZE (i.e. 3 samples).
164 */
165 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator(final double[] qualityScores) {
166 super();
167 threshold = DEFAULT_THRESHOLD;
168 internalSetQualityScores(qualityScores);
169 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
170 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
171 }
172
173 /**
174 * Constructor with lists of points to be used to estimate an affine 2D
175 * transformation.
176 * Points in the list located at the same position are considered to be
177 * matched. Hence, both lists must have the same size, and their size must
178 * be greater or equal than MINIMUM_SIZE.
179 *
180 * @param inputPoints list of input points to be used to estimate an
181 * affine 2D transformation.
182 * @param outputPoints list of output points to be used to estimate an
183 * affine 2D transformation.
184 * @param qualityScores quality scores corresponding to each pair of matched
185 * points.
186 * @throws IllegalArgumentException if provided lists of points and array
187 * of quality scores don't have the same size or their size is smaller than
188 * MINIMUM_SIZE.
189 */
190 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator(
191 final List<Point2D> inputPoints, final List<Point2D> outputPoints, final double[] qualityScores) {
192 super(inputPoints, outputPoints);
193
194 if (qualityScores.length != inputPoints.size()) {
195 throw new IllegalArgumentException();
196 }
197
198 threshold = DEFAULT_THRESHOLD;
199 internalSetQualityScores(qualityScores);
200 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
201 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
202 }
203
204 /**
205 * Constructor.
206 *
207 * @param listener listener to be notified of events such as when estimation
208 * starts, ends or its progress significantly changes.
209 * @param qualityScores quality scores corresponding to each pair of matched
210 * points.
211 * @throws IllegalArgumentException if provided quality scores length is
212 * smaller than MINIMUM_SIZE (i.e. 3 samples).
213 */
214 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator(
215 final AffineTransformation2DRobustEstimatorListener listener, final double[] qualityScores) {
216 super(listener);
217 threshold = DEFAULT_THRESHOLD;
218 internalSetQualityScores(qualityScores);
219 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
220 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
221 }
222
223 /**
224 * Constructor with listener and lists of points to be used to estimate an
225 * affine 2D transformation.
226 * Points in the list located at the same position are considered to be
227 * matched. Hence, both lists must have the same size, and their size must
228 * be greater or equal than MINIMUM_SIZE.
229 *
230 * @param listener listener to be notified of events such as when estimation
231 * stars, ends or its progress significantly changes.
232 * @param inputPoints list of input points to be used to estimate an
233 * affine 2D transformation.
234 * @param outputPoints list of output points to be used to estimate an
235 * affine 2D transformation.
236 * @param qualityScores quality scores corresponding to each pair of matched
237 * points.
238 * @throws IllegalArgumentException if provided lists of points don't have
239 * the same size or their size is smaller than MINIMUM_SIZE.
240 */
241 public PROSACPointCorrespondenceAffineTransformation2DRobustEstimator(
242 final AffineTransformation2DRobustEstimatorListener listener,
243 final List<Point2D> inputPoints, final List<Point2D> outputPoints, final double[] qualityScores) {
244 super(listener, inputPoints, outputPoints);
245
246 if (qualityScores.length != inputPoints.size()) {
247 throw new IllegalArgumentException();
248 }
249
250 threshold = DEFAULT_THRESHOLD;
251 internalSetQualityScores(qualityScores);
252 computeAndKeepInliers = DEFAULT_COMPUTE_AND_KEEP_INLIERS;
253 computeAndKeepResiduals = DEFAULT_COMPUTE_AND_KEEP_RESIDUALS;
254 }
255
256 /**
257 * Returns threshold to determine whether points are inliers or not when
258 * testing possible estimation solutions.
259 * The threshold refers to the amount of error (i.e. Euclidean distance) a
260 * possible solution has on a matched pair of points.
261 *
262 * @return threshold to determine whether points are inliers or not when
263 * testing possible estimation solutions.
264 */
265 public double getThreshold() {
266 return threshold;
267 }
268
269 /**
270 * Sets threshold to determine whether points are inliers or not when
271 * testing possible estimation solutions.
272 * The threshold refers to the amount of error (i.e. Euclidean distance) a
273 * possible solution has on a matched pair of points.
274 *
275 * @param threshold threshold to determine whether points are inliers or not
276 * when testing possible estimation solutions.
277 * @throws IllegalArgumentException if provided values is equal or less than
278 * zero.
279 * @throws LockedException if robust estimator is locked because an
280 * estimation is already in progress.
281 */
282 public void setThreshold(final double threshold) throws LockedException {
283 if (isLocked()) {
284 throw new LockedException();
285 }
286 if (threshold <= MIN_THRESHOLD) {
287 throw new IllegalArgumentException();
288 }
289 this.threshold = threshold;
290 }
291
292 /**
293 * Returns quality scores corresponding to each pair of matched points.
294 * The larger the score value the better the quality of the matching.
295 *
296 * @return quality scores corresponding to each pair of matched points.
297 */
298 @Override
299 public double[] getQualityScores() {
300 return qualityScores;
301 }
302
303 /**
304 * Sets quality scores corresponding to each pair of matched points.
305 * The larger the score value the better the quality of the matching.
306 *
307 * @param qualityScores quality scores corresponding to each pair of matched
308 * points.
309 * @throws LockedException if robust estimator is locked because an
310 * estimation is already in progress.
311 * @throws IllegalArgumentException if provided quality scores length is
312 * smaller than MINIMUM_SIZE (i.e. 3 samples).
313 */
314 @Override
315 public void setQualityScores(final double[] qualityScores) throws LockedException {
316 if (isLocked()) {
317 throw new LockedException();
318 }
319 internalSetQualityScores(qualityScores);
320 }
321
322 /**
323 * Indicates if estimator is ready to start the affine 2D transformation
324 * estimation.
325 * This is true when input data (i.e. lists of matched points and quality
326 * scores) are provided and a minimum of MINIMUM_SIZE points are available.
327 *
328 * @return true if estimator is ready, false otherwise.
329 */
330 @Override
331 public boolean isReady() {
332 return super.isReady() && qualityScores != null && qualityScores.length == inputPoints.size();
333 }
334
335 /**
336 * Indicates whether inliers must be computed and kept.
337 *
338 * @return true if inliers must be computed and kept, false if inliers
339 * only need to be computed but not kept.
340 */
341 public boolean isComputeAndKeepInliersEnabled() {
342 return computeAndKeepInliers;
343 }
344
345 /**
346 * Specifies whether inliers must be computed and kept.
347 *
348 * @param computeAndKeepInliers true if inliers must be computed and kept,
349 * false if inliers only need to be computed but not kept.
350 * @throws LockedException if estimator is locked.
351 */
352 public void setComputeAndKeepInliersEnabled(final boolean computeAndKeepInliers) throws LockedException {
353 if (isLocked()) {
354 throw new LockedException();
355 }
356 this.computeAndKeepInliers = computeAndKeepInliers;
357 }
358
359 /**
360 * Indicates whether residuals must be computed and kept.
361 *
362 * @return true if residuals must be computed and kept, false if residuals
363 * only need to be computed but not kept.
364 */
365 public boolean isComputeAndKeepResidualsEnabled() {
366 return computeAndKeepResiduals;
367 }
368
369 /**
370 * Specifies whether residuals must be computed and kept.
371 *
372 * @param computeAndKeepResiduals true if residuals must be computed and
373 * kept, false if residuals only need to be computed but not kept.
374 * @throws LockedException if estimator is locked.
375 */
376 public void setComputeAndKeepResidualsEnabled(final boolean computeAndKeepResiduals) throws LockedException {
377 if (isLocked()) {
378 throw new LockedException();
379 }
380 this.computeAndKeepResiduals = computeAndKeepResiduals;
381 }
382
383 /**
384 * Estimates an affine 2D transformation using a robust estimator and
385 * the best set of matched 2D point correspondences found using the robust
386 * estimator.
387 *
388 * @return an affine 2D transformation.
389 * @throws LockedException if robust estimator is locked because an
390 * estimation is already in progress.
391 * @throws NotReadyException if provided input data is not enough to start
392 * the estimation.
393 * @throws RobustEstimatorException if estimation fails for any reason
394 * (i.e. numerical instability, no solution available, etc).
395 */
396 @Override
397 public AffineTransformation2D estimate() throws LockedException, NotReadyException, RobustEstimatorException {
398 if (isLocked()) {
399 throw new LockedException();
400 }
401 if (!isReady()) {
402 throw new NotReadyException();
403 }
404
405 final var innerEstimator = new PROSACRobustEstimator<>(
406 new PROSACRobustEstimatorListener<AffineTransformation2D>() {
407
408 // point to be reused when computing residuals
409 private final Point2D testPoint = Point2D.create(CoordinatesType.HOMOGENEOUS_COORDINATES);
410
411 @Override
412 public double getThreshold() {
413 return threshold;
414 }
415
416 @Override
417 public int getTotalSamples() {
418 return inputPoints.size();
419 }
420
421 @Override
422 public int getSubsetSize() {
423 return AffineTransformation2DRobustEstimator.MINIMUM_SIZE;
424 }
425
426 @Override
427 public void estimatePreliminarSolutions(
428 final int[] samplesIndices, final List<AffineTransformation2D> solutions) {
429 final var inputPoint1 = inputPoints.get(samplesIndices[0]);
430 final var inputPoint2 = inputPoints.get(samplesIndices[1]);
431 final var inputPoint3 = inputPoints.get(samplesIndices[2]);
432
433 final var outputPoint1 = outputPoints.get(samplesIndices[0]);
434 final var outputPoint2 = outputPoints.get(samplesIndices[1]);
435 final var outputPoint3 = outputPoints.get(samplesIndices[2]);
436
437 try {
438 final var transformation = new AffineTransformation2D(inputPoint1, inputPoint2, inputPoint3,
439 outputPoint1, outputPoint2, outputPoint3);
440 solutions.add(transformation);
441 } catch (final CoincidentPointsException e) {
442 // if points are coincident, no solution is added
443 }
444 }
445
446 @Override
447 public double computeResidual(final AffineTransformation2D currentEstimation, final int i) {
448 final var inputPoint = inputPoints.get(i);
449 final var outputPoint = outputPoints.get(i);
450
451 // transform input point and store result in mTestPoint
452 currentEstimation.transform(inputPoint, testPoint);
453
454 return outputPoint.distanceTo(testPoint);
455 }
456
457 @Override
458 public boolean isReady() {
459 return PROSACPointCorrespondenceAffineTransformation2DRobustEstimator.this.isReady();
460 }
461
462 @Override
463 public void onEstimateStart(final RobustEstimator<AffineTransformation2D> estimator) {
464 if (mListener != null) {
465 mListener.onEstimateStart(
466 PROSACPointCorrespondenceAffineTransformation2DRobustEstimator.this);
467 }
468 }
469
470 @Override
471 public void onEstimateEnd(final RobustEstimator<AffineTransformation2D> estimator) {
472 if (mListener != null) {
473 mListener.onEstimateEnd(
474 PROSACPointCorrespondenceAffineTransformation2DRobustEstimator.this);
475 }
476 }
477
478 @Override
479 public void onEstimateNextIteration(
480 final RobustEstimator<AffineTransformation2D> estimator, final int iteration) {
481 if (mListener != null) {
482 mListener.onEstimateNextIteration(
483 PROSACPointCorrespondenceAffineTransformation2DRobustEstimator.this,
484 iteration);
485 }
486 }
487
488 @Override
489 public void onEstimateProgressChange(
490 final RobustEstimator<AffineTransformation2D> estimator, final float progress) {
491 if (mListener != null) {
492 mListener.onEstimateProgressChange(
493 PROSACPointCorrespondenceAffineTransformation2DRobustEstimator.this,
494 progress);
495 }
496 }
497
498 @Override
499 public double[] getQualityScores() {
500 return qualityScores;
501 }
502 });
503
504 try {
505 locked = true;
506 inliersData = null;
507 innerEstimator.setComputeAndKeepInliersEnabled(computeAndKeepInliers || refineResult);
508 innerEstimator.setComputeAndKeepResidualsEnabled(computeAndKeepResiduals || refineResult);
509 innerEstimator.setConfidence(confidence);
510 innerEstimator.setMaxIterations(maxIterations);
511 innerEstimator.setProgressDelta(progressDelta);
512 final var transformation = innerEstimator.estimate();
513 inliersData = innerEstimator.getInliersData();
514 return attemptRefine(transformation);
515 } catch (final com.irurueta.numerical.LockedException e) {
516 throw new LockedException(e);
517 } catch (final com.irurueta.numerical.NotReadyException e) {
518 throw new NotReadyException(e);
519 } finally {
520 locked = false;
521 }
522 }
523
524 /**
525 * Returns method being used for robust estimation.
526 *
527 * @return method being used for robust estimation.
528 */
529 @Override
530 public RobustEstimatorMethod getMethod() {
531 return RobustEstimatorMethod.PROSAC;
532 }
533
534 /**
535 * Gets standard deviation used for Levenberg-Marquardt fitting during
536 * refinement.
537 * Returned value gives an indication of how much variance each residual
538 * has.
539 * Typically, this value is related to the threshold used on each robust
540 * estimation, since residuals of found inliers are within the range of
541 * such threshold.
542 *
543 * @return standard deviation used for refinement.
544 */
545 @Override
546 protected double getRefinementStandardDeviation() {
547 return threshold;
548 }
549
550 /**
551 * Sets quality scores corresponding to each pair of matched points.
552 * This method is used internally and does not check whether instance is
553 * locked or not.
554 *
555 * @param qualityScores quality scores to be set.
556 * @throws IllegalArgumentException if provided quality scores length is
557 * smaller than MINIMUM_SIZE.
558 */
559 private void internalSetQualityScores(final double[] qualityScores) {
560 if (qualityScores.length < MINIMUM_SIZE) {
561 throw new IllegalArgumentException();
562 }
563
564 this.qualityScores = qualityScores;
565 }
566 }