1 /*
2 * Copyright (C) 2017 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.Point2D;
19 import com.irurueta.geometry.Point3D;
20 import com.irurueta.numerical.robust.RobustEstimatorMethod;
21
22 import java.util.List;
23
24 /**
25 * Base abstract class for algorithms to robustly find the best pinhole camera
26 * for collections of matched 3D/2D points using DLT (Direct Linear Transform)
27 * algorithm.
28 * Implementations of this class should be able to detect and discard outliers
29 * in order to find the best solution.
30 */
31 public abstract class DLTPointCorrespondencePinholeCameraRobustEstimator
32 extends PointCorrespondencePinholeCameraRobustEstimator {
33
34 /**
35 * Constructor.
36 */
37 protected DLTPointCorrespondencePinholeCameraRobustEstimator() {
38 super();
39 }
40
41 /**
42 * Constructor with lists of points to be used to estimate a pinhole camera.
43 * Points in the lists located at the same position are considered to be
44 * matched. Hence, both lists must have the same size, and their size must
45 * be greater or equal than MIN_NUMBER_OF_POINT_CORRESPONDENCES (6 points).
46 *
47 * @param points3D list of 3D points used to estimate a pinhole camera.
48 * @param points2D list of corresponding projected 2D points used to
49 * estimate a pinhole camera.
50 * @throws IllegalArgumentException if provided lists of points don't have
51 * the same size or their size is smaller than required minimum size (6
52 * correspondences).
53 */
54 protected DLTPointCorrespondencePinholeCameraRobustEstimator(
55 final List<Point3D> points3D, final List<Point2D> points2D) {
56 super(points3D, points2D);
57 }
58
59 /**
60 * Constructor with listener.
61 *
62 * @param listener listener to be notified of events such as when estimation
63 * starts, ends or its progress significantly changes.
64 */
65 protected DLTPointCorrespondencePinholeCameraRobustEstimator(final PinholeCameraRobustEstimatorListener listener) {
66 super(listener);
67 }
68
69 /**
70 * Constructor with listener and lists of points to be used to estimate a
71 * pinhole camera.
72 * Points in the lists located at the same position are considered to be
73 * matched. Hence, both lists must have the same size, and their size must
74 * be greater or equal than MIN_NUMBER_OF_POINT_CORRESPONDENCES (6 points).
75 *
76 * @param listener listener to be notified of events such as when estimation
77 * starts, ends or its progress significantly changes.
78 * @param points3D lists of 3D points used to estimate a pinhole camera.
79 * @param points2D list of corresponding projected 2D points used to
80 * estimate a pinhole camera.
81 * @throws IllegalArgumentException if provided lists of points don't have
82 * the same size or their size is smaller than required minimum size
83 * (6 correspondences).
84 */
85 protected DLTPointCorrespondencePinholeCameraRobustEstimator(
86 final PinholeCameraRobustEstimatorListener listener, final List<Point3D> points3D,
87 final List<Point2D> points2D) {
88 super(listener, points3D, points2D);
89 }
90
91 /**
92 * Creates a pinhole camera robust estimator based on point correspondences
93 * and using provided robust estimator method.
94 *
95 * @param method method of a robust estimator algorithm to estimate the best
96 * pinhole camera.
97 * @return an instance of a pinhole camera robust estimator.
98 */
99 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(final RobustEstimatorMethod method) {
100 return switch (method) {
101 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator();
102 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator();
103 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator();
104 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator();
105 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator();
106 };
107 }
108
109 /**
110 * Creates a pinhole camera robust estimator based on point correspondences
111 * and using provided 2D/3D points and robust estimator method.
112 *
113 * @param points3D list of 3D points used to estimate a pinhole camera.
114 * @param points2D list of corresponding projected 2D points used to
115 * estimate a pinhole camera.
116 * @param method method of a robust estimator algorithm to estimate the best
117 * pinhole camera.
118 * @return an instance of a pinhole camera robust estimator.
119 * @throws IllegalArgumentException if provided lists of points don't have
120 * the same size or their size is smaller than required minimum size
121 * (6 correspondences).
122 */
123 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
124 final List<Point3D> points3D, final List<Point2D> points2D, final RobustEstimatorMethod method) {
125 return switch (method) {
126 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
127 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
128 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
129 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
130 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
131 };
132 }
133
134 /**
135 * Creates a pinhole camera robust estimator based on point
136 * correspondences and using provided listener.
137 *
138 * @param listener listener to be notified of events such as when estimation
139 * starts, ends or its progress significantly changes.
140 * @param method method of a robust estimator algorithm to estimate the best
141 * pinhole camera.
142 * @return an instance of a pinhole camera robust estimator.
143 */
144 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
145 final PinholeCameraRobustEstimatorListener listener, final RobustEstimatorMethod method) {
146 return switch (method) {
147 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
148 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
149 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
150 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
151 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
152 };
153 }
154
155 /**
156 * Creates a pinhole camera robust estimator based on point correspondences
157 * and using provided listener, 2D/3D points and robust estimator method.
158 *
159 * @param listener listener to be notified of events such as when estimation
160 * starts, ends or its progress significantly changes.
161 * @param points3D list of 3D points used to estimate a pinhole camera.
162 * @param points2D list of corresponding projected 2D points used to
163 * estimate a pinhole camera.
164 * @param method method of a robust estimator algorithm to estimate the best
165 * pinhole camera.
166 * @return an instance of a pinhole camera robust estimator.
167 * @throws IllegalArgumentException if provided lists of points don't have
168 * the same size or their size is smaller than required minimum size
169 * (6 correspondences).
170 */
171 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
172 final PinholeCameraRobustEstimatorListener listener, final List<Point3D> points3D,
173 final List<Point2D> points2D, final RobustEstimatorMethod method) {
174 return switch (method) {
175 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
176 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
177 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
178 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
179 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
180 };
181 }
182
183 /**
184 * Creates a pinhole camera robust estimator based on point correspondences
185 * and using provided quality scores and robust estimator method.
186 *
187 * @param qualityScores quality scores corresponding to each pair of matched
188 * points.
189 * @param method method of a robust estimator algorithm to estimate the best
190 * pinhole camera.
191 * @return an instance of a pinhole camera robust estimator.
192 * @throws IllegalArgumentException if provided quality scores length is
193 * smaller than required minimum size (6 samples).
194 */
195 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(final double[] qualityScores,
196 final RobustEstimatorMethod method) {
197 return switch (method) {
198 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator();
199 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator();
200 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator(qualityScores);
201 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator(qualityScores);
202 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator();
203 };
204 }
205
206 /**
207 * Creates a pinhole camera robust estimator based on point correspondences
208 * and using provided 2D/3D points, quality scores and robust estimator
209 * method.
210 *
211 * @param points3D list of 3D points used to estimate a pinhole camera.
212 * @param points2D list of corresponding projected 2D points used to
213 * estimate a pinhole camera.
214 * @param qualityScores quality scores corresponding to each pair of matched
215 * points.
216 * @param method method of a robust estimator algorithm to estimate the best
217 * pinhole camera.
218 * @return an instance of a pinhole camera robust estimator.
219 * @throws IllegalArgumentException if provided lists of points and quality
220 * scores don't have the same size or their size is smaller than required
221 * minimum size (6 correspondences).
222 */
223 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
224 final List<Point3D> points3D, final List<Point2D> points2D, final double[] qualityScores,
225 final RobustEstimatorMethod method) {
226 return switch (method) {
227 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
228 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
229 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator(
230 points3D, points2D, qualityScores);
231 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator(
232 points3D, points2D, qualityScores);
233 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator(points3D, points2D);
234 };
235 }
236
237 /**
238 * Creates a pinhole camera robust estimator based on point
239 * correspondences and using provided listener and quality scores.
240 *
241 * @param listener listener to be notified of events such as when estimation
242 * starts, ends or its progress significantly changes.
243 * @param qualityScores quality scores corresponding to each pair of matched
244 * points.
245 * @param method method of a robust estimator algorithm to estimate the best
246 * pinhole camera.
247 * @return an instance of a pinhole camera robust estimator.
248 * @throws IllegalArgumentException if provided quality scores don't have
249 * the required minimum size (6 correspondences).
250 */
251 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
252 final PinholeCameraRobustEstimatorListener listener, final double[] qualityScores,
253 final RobustEstimatorMethod method) {
254 return switch (method) {
255 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
256 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
257 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener, qualityScores);
258 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator(listener, qualityScores);
259 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener);
260 };
261 }
262
263 /**
264 * Creates a pinhole camera robust estimator based on point correspondences
265 * and using provided listener, 2D/3D points, quality scores and robust
266 * estimator method.
267 *
268 * @param listener listener to be notified of events such as when estimation
269 * starts, ends or its progress significantly changes.
270 * @param points3D list of 3D points used to estimate a pinhole camera.
271 * @param points2D list of corresponding projected 2D points used to
272 * estimate a pinhole camera.
273 * @param qualityScores quality scores corresponding to each pair of matched
274 * points.
275 * @param method method of a robust estimator algorithm to estimate the best
276 * pinhole camera.
277 * @return an instance of a pinhole camera robust estimator.
278 * @throws IllegalArgumentException if provided lists of points and quality
279 * scores don't have the same size or their size is smaller than required
280 * minimum size (6 correspondences).
281 */
282 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
283 final PinholeCameraRobustEstimatorListener listener, final List<Point3D> points3D,
284 final List<Point2D> points2D, final double[] qualityScores, final RobustEstimatorMethod method) {
285 return switch (method) {
286 case LMEDS -> new LMedSDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
287 case MSAC -> new MSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
288 case PROSAC -> new PROSACDLTPointCorrespondencePinholeCameraRobustEstimator(
289 listener, points3D, points2D, qualityScores);
290 case PROMEDS -> new PROMedSDLTPointCorrespondencePinholeCameraRobustEstimator(
291 listener, points3D, points2D, qualityScores);
292 default -> new RANSACDLTPointCorrespondencePinholeCameraRobustEstimator(listener, points3D, points2D);
293 };
294 }
295
296 /**
297 * Creates a pinhole camera robust estimator based on point correspondences
298 * and using default robust estimator method.
299 *
300 * @return an instance of a pinhole camera robust estimator.
301 */
302 public static DLTPointCorrespondencePinholeCameraRobustEstimator create() {
303 return create(DEFAULT_ROBUST_METHOD);
304 }
305
306 /**
307 * Creates a pinhole camera robust estimator based on point correspondences
308 * and using provided 2D/3D points and default robust estimator method.
309 *
310 * @param points3D list of 3D points used to estimate a pinhole camera.
311 * @param points2D list of corresponding projected 2D points used to
312 * estimate a pinhole camera.
313 * @return an instance of a pinhole camera robust estimator.
314 * @throws IllegalArgumentException if provided lists of points don't have
315 * the same size or their size is smaller than required minimum size
316 * (6 correspondences).
317 */
318 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
319 final List<Point3D> points3D, final List<Point2D> points2D) {
320 return create(points3D, points2D, DEFAULT_ROBUST_METHOD);
321 }
322
323 /**
324 * Creates a pinhole camera robust estimator based on point
325 * correspondences and using provided listener and default robust estimator
326 * method.
327 *
328 * @param listener listener to be notified of events such as when estimation
329 * starts, ends or its progress significantly changes.
330 * @return an instance of a pinhole camera robust estimator.
331 */
332 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
333 final PinholeCameraRobustEstimatorListener listener) {
334 return create(listener, DEFAULT_ROBUST_METHOD);
335 }
336
337 /**
338 * Creates a pinhole camera robust estimator based on point correspondences
339 * and using provided listener, 2D/3D points and default robust estimator
340 * method.
341 *
342 * @param listener listener to be notified of events such as when estimation
343 * starts, ends or its progress significantly changes.
344 * @param points3D list of 3D points used to estimate a pinhole camera.
345 * @param points2D list of corresponding projected 2D points used to
346 * estimate a pinhole camera.
347 * @return an instance of a pinhole camera robust estimator.
348 * @throws IllegalArgumentException if provided lists of points don't have
349 * the same size or their size is smaller than required minimum size
350 * (6 correspondences).
351 */
352 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
353 final PinholeCameraRobustEstimatorListener listener,
354 final List<Point3D> points3D, final List<Point2D> points2D) {
355 return create(listener, points3D, points2D, DEFAULT_ROBUST_METHOD);
356 }
357
358 /**
359 * Creates a pinhole camera robust estimator based on point correspondences
360 * and using provided quality scores and default robust estimator method.
361 *
362 * @param qualityScores quality scores corresponding to each pair of matched
363 * points.
364 * @return an instance of a pinhole camera robust estimator.
365 * @throws IllegalArgumentException if provided quality scores length is
366 * smaller than required minimum size (6 samples).
367 */
368 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(final double[] qualityScores) {
369 return create(qualityScores, DEFAULT_ROBUST_METHOD);
370 }
371
372 /**
373 * Creates a pinhole camera robust estimator based on point correspondences
374 * and using provided 2D/3D points, quality scores and default robust
375 * estimator method.
376 *
377 * @param points3D list of 3D points used to estimate a pinhole camera.
378 * @param points2D list of corresponding projected 2D points used to
379 * estimate a pinhole camera.
380 * @param qualityScores quality scores corresponding to each pair of matched
381 * points.
382 * @return an instance of a pinhole camera robust estimator.
383 * @throws IllegalArgumentException if provided lists of points and quality
384 * scores don't have the same size or their size is smaller than required
385 * minimum size (6 correspondences).
386 */
387 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
388 final List<Point3D> points3D, final List<Point2D> points2D, final double[] qualityScores) {
389 return create(points3D, points2D, qualityScores, DEFAULT_ROBUST_METHOD);
390 }
391
392 /**
393 * Creates a pinhole camera robust estimator based on point
394 * correspondences and using provided listener, quality scores and default
395 * robust estimator method.
396 *
397 * @param listener listener to be notified of events such as when estimation
398 * starts, ends or its progress significantly changes.
399 * @param qualityScores quality scores corresponding to each pair of matched
400 * points.
401 * @return an instance of a pinhole camera robust estimator.
402 * @throws IllegalArgumentException if provided quality scores don't have
403 * the required minimum size (6 correspondences).
404 */
405 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
406 final PinholeCameraRobustEstimatorListener listener, final double[] qualityScores) {
407 return create(listener, qualityScores, DEFAULT_ROBUST_METHOD);
408 }
409
410 /**
411 * Creates a pinhole camera robust estimator based on point correspondences
412 * and using provided listener, 2D/3D points, quality scores and default
413 * robust estimator method.
414 *
415 * @param listener listener to be notified of events such as when estimation
416 * starts, ends or its progress significantly changes.
417 * @param points3D list of 3D points used to estimate a pinhole camera.
418 * @param points2D list of corresponding projected 2D points used to
419 * estimate a pinhole camera.
420 * @param qualityScores quality scores corresponding to each pair of matched
421 * points.
422 * @return an instance of a pinhole camera robust estimator.
423 * @throws IllegalArgumentException if provided lists of points and quality
424 * scores don't have the same size or their size is smaller than required
425 * minimum size (6 correspondences).
426 */
427 public static DLTPointCorrespondencePinholeCameraRobustEstimator create(
428 final PinholeCameraRobustEstimatorListener listener, final List<Point3D> points3D,
429 final List<Point2D> points2D, final double[] qualityScores) {
430 return create(listener, points3D, points2D, qualityScores, DEFAULT_ROBUST_METHOD);
431 }
432 }