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.ar.epipolar;
17
18 import com.irurueta.geometry.estimators.LockedException;
19 import com.irurueta.geometry.estimators.NotReadyException;
20
21 /**
22 * Compares two fundamental matrices to determine how similar they are.
23 * This is an abstract class, subclasses of this class will implement different
24 * methods to compare fundamental matrices.
25 * This class will typically be used for testing or quality assessment purposes.
26 */
27 public abstract class FundamentalMatrixComparator {
28
29 /**
30 * Fundamental matrix to be considered as ground truth to compare against.
31 */
32 protected FundamentalMatrix groundTruthFundamentalMatrix;
33
34 /**
35 * Other fundamental matrix being compared.
36 */
37 protected FundamentalMatrix otherFundamentalMatrix;
38
39 /**
40 * Listener to handle events generated by this class.
41 */
42 protected FundamentalMatrixComparatorListener listener;
43
44 /**
45 * Indicates whether this instance is busy doing computations.
46 */
47 protected boolean locked;
48
49 /**
50 * Constructor.
51 */
52 protected FundamentalMatrixComparator() {
53 }
54
55 /**
56 * Constructor.
57 *
58 * @param groundTruthFundamentalMatrix fundamental matrix to be considered
59 * as ground truth to compare against.
60 * @param otherFundamentalMatrix other fundamental matrix being compared.
61 */
62 protected FundamentalMatrixComparator(
63 final FundamentalMatrix groundTruthFundamentalMatrix, final FundamentalMatrix otherFundamentalMatrix) {
64 this.groundTruthFundamentalMatrix = groundTruthFundamentalMatrix;
65 this.otherFundamentalMatrix = otherFundamentalMatrix;
66 }
67
68 /**
69 * Constructor.
70 *
71 * @param listener listener to handle events generated by this class.
72 */
73 protected FundamentalMatrixComparator(final FundamentalMatrixComparatorListener listener) {
74 this.listener = listener;
75 }
76
77 /**
78 * Constructor.
79 *
80 * @param groundTruthFundamentalMatrix fundamental matrix to be considered
81 * as ground truth to compare against.
82 * @param otherFundamentalMatrix other fundamental matrix being compared.
83 * @param listener listener to handle events generated by this class.
84 */
85 protected FundamentalMatrixComparator(
86 final FundamentalMatrix groundTruthFundamentalMatrix, final FundamentalMatrix otherFundamentalMatrix,
87 final FundamentalMatrixComparatorListener listener) {
88 this(groundTruthFundamentalMatrix, otherFundamentalMatrix);
89 this.listener = listener;
90 }
91
92 /**
93 * Obtains fundamental matrix to be considered as ground truth to compare
94 * against.
95 *
96 * @return fundamental matrix to be considered as ground truth.
97 */
98 public FundamentalMatrix getGroundTruthFundamentalMatrix() {
99 return groundTruthFundamentalMatrix;
100 }
101
102 /**
103 * Sets fundamental matrix to be considered as ground truth to compare
104 * against.
105 *
106 * @param groundTruthFundamentalMatrix fundamental matrix to be considered
107 * as ground truth.
108 * @throws LockedException if this instance is locked.
109 */
110 public void setGroundTruthFundamentalMatrix(final FundamentalMatrix groundTruthFundamentalMatrix)
111 throws LockedException {
112 if (isLocked()) {
113 throw new LockedException();
114 }
115
116 this.groundTruthFundamentalMatrix = groundTruthFundamentalMatrix;
117 }
118
119 /**
120 * Obtains other fundamental matrix being compared.
121 *
122 * @return other fundamental matrix being compared.
123 */
124 public FundamentalMatrix getOtherFundamentalMatrix() {
125 return otherFundamentalMatrix;
126 }
127
128 /**
129 * Sets other fundamental matrix being compared.
130 *
131 * @param otherFundamentalMatrix other fundamental matrix being compared.
132 * @throws LockedException if this instance is locked.
133 */
134 public void setOtherFundamentalMatrix(final FundamentalMatrix otherFundamentalMatrix) throws LockedException {
135 if (isLocked()) {
136 throw new LockedException();
137 }
138
139 this.otherFundamentalMatrix = otherFundamentalMatrix;
140 }
141
142 /**
143 * Returns listener to handle events generated by instances of this class.
144 *
145 * @return listener to handle events generated by instances of this class.
146 */
147 public FundamentalMatrixComparatorListener getListener() {
148 return listener;
149 }
150
151 /**
152 * Sets listener to handle events generated by instances of this class.
153 *
154 * @param listener listener to handle events generated by instances of this
155 * class.
156 * @throws LockedException if this instance is locked.
157 */
158 public void setListener(final FundamentalMatrixComparatorListener listener) throws LockedException {
159 if (isLocked()) {
160 throw new LockedException();
161 }
162
163 this.listener = listener;
164 }
165
166 /**
167 * Returns boolean indicating whether an instance of this class is busy
168 * doing computations.
169 *
170 * @return true if this instance is locked, false otherwise.
171 */
172 public boolean isLocked() {
173 return locked;
174 }
175
176 /**
177 * Indicates whether this comparator is ready to start the comparison of
178 * two fundamental matrices. This is true when both ground truth and
179 * the other fundamental matrix has been provided and both have their
180 * internal matrices defined.
181 *
182 * @return true if this comparator is ready, false otherwise.
183 */
184 public boolean isReady() {
185 return groundTruthFundamentalMatrix != null && groundTruthFundamentalMatrix.isInternalMatrixAvailable()
186 && otherFundamentalMatrix != null && otherFundamentalMatrix.isInternalMatrixAvailable();
187 }
188
189 /**
190 * Compares two fundamental matrices and returns the comparison value.
191 * Comparison value will depend on the method implemented to compare both
192 * fundamental matrices.
193 *
194 * @return comparison value. Typically, the smaller the absolute value the
195 * more similar the fundamental matrices are.
196 * @throws NotReadyException if this comparator is not yet ready to start
197 * the comparison.
198 * @throws LockedException if this instance is locked.
199 * @throws FundamentalMatrixComparatorException if comparison fails due to
200 * some other reason.
201 */
202 public abstract double compare() throws NotReadyException, LockedException, FundamentalMatrixComparatorException;
203
204 /**
205 * Returns type of comparator.
206 *
207 * @return type of comparator.
208 */
209 public abstract FundamentalMatrixComparatorType getType();
210 }