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
17 package com.irurueta.ar.sfm;
18
19 import java.util.List;
20
21 /**
22 * Listener to retrieve and store required data to compute a 3D reconstruction from
23 * sparse image point correspondences in multiple views.
24 *
25 * @param <R> type of re-constructor.
26 */
27 public interface BaseSparseReconstructorListener<R extends BaseSparseReconstructor<?, ?, ?>> {
28
29 /**
30 * Called to determine whether there are more views available to attempt to use for
31 * the reconstruction.
32 *
33 * @param reconstructor re-constructor raising this event.
34 * @return true if there are more views available, false otherwise.
35 */
36 boolean hasMoreViewsAvailable(final R reconstructor);
37
38 /**
39 * Called when samples containing points of interest for current view must be retrieved.
40 *
41 * @param reconstructor re-constructor raising this event.
42 * @param previousViewId id of previous view.
43 * @param currentViewId id of current view.
44 * @param previousViewTrackedSamples tracked samples from previous view.
45 * @param currentViewTrackedSamples tracked samples from previous view containing points of
46 * interest on current view.
47 * @param currentViewNewlySpawnedSamples new created samples containing points of interest on current
48 * view.
49 */
50 void onRequestSamples(final R reconstructor, final int previousViewId, final int currentViewId,
51 final List<Sample2D> previousViewTrackedSamples,
52 final List<Sample2D> currentViewTrackedSamples,
53 final List<Sample2D> currentViewNewlySpawnedSamples);
54
55 /**
56 * Called when requested samples have been accepted.
57 * This method can be used to determine whether samples can be stored or
58 * not.
59 *
60 * @param reconstructor re-constructor raising this event.
61 * @param viewId id of view whose samples have been accepted.
62 * @param previousViewTrackedSamples accepted tracked samples on previous view.
63 * Might be null on first view.
64 * @param currentViewTrackedSamples accepted tracked samples on current view.
65 */
66 void onSamplesAccepted(final R reconstructor, final int viewId,
67 final List<Sample2D> previousViewTrackedSamples,
68 final List<Sample2D> currentViewTrackedSamples);
69
70 /**
71 * Called when requested samples have been rejected.
72 * This method can be used to remove provided samples.
73 *
74 * @param reconstructor re-constructor raising this event.
75 * @param viewId id of view whose samples have been rejected.
76 * @param previousViewTrackedSamples rejected samples on previous view.
77 * Might be null on first view.
78 * @param currentViewTrackedSamples rejected samples on current view.
79 */
80 void onSamplesRejected(final R reconstructor, final int viewId,
81 final List<Sample2D> previousViewTrackedSamples,
82 final List<Sample2D> currentViewTrackedSamples);
83
84 /**
85 * Finds matches for provided samples.
86 * Typically, implementations will need to search for closest points of tracked
87 * points in previous view within the whole list of samples in previous view.
88 * The implementation might choose to search for other matches or even include
89 * samples from previous views to increase the accuracy of reconstructed
90 * points.
91 *
92 * @param reconstructor re-constructor raising this event.
93 * @param allPreviousViewSamples all samples on previous views.
94 * @param previousViewTrackedSamples tracked samples on previous view.
95 * @param currentViewTrackedSamples tracked samples on current view.
96 * @param previousViewId id of previous view.
97 * @param currentViewId id of current view.
98 * @param matches instance where matches must be stored.
99 */
100 void onRequestMatches(final R reconstructor,
101 final List<Sample2D> allPreviousViewSamples,
102 final List<Sample2D> previousViewTrackedSamples,
103 final List<Sample2D> currentViewTrackedSamples,
104 final int previousViewId, final int currentViewId,
105 final List<MatchedSamples> matches);
106
107 /**
108 * Called when a fundamental matrix relating two views has been estimated.
109 * This event can be used to store estimated fundamental matrix relating
110 * two views.
111 *
112 * @param reconstructor re-constructor raising this event.
113 * @param estimatedFundamentalMatrix estimated fundamental matrix.
114 */
115 void onFundamentalMatrixEstimated(final R reconstructor,
116 final EstimatedFundamentalMatrix estimatedFundamentalMatrix);
117
118 /**
119 * Notifies when cameras for provided matched pair of views have been
120 * estimated. Cameras returned on this event are defined in a metric stratum (i.e. up to scale).
121 * This event can be used to store cameras associated to such view.
122 *
123 * @param reconstructor re-constructor raising this event.
124 * @param previousViewId id of previous view (i.e. first view).
125 * @param currentViewId id of current view (i.e. second view).
126 * @param previousCamera estimated camera for previous view.
127 * @param currentCamera estimated camera for current view.
128 */
129 void onMetricCameraEstimated(final R reconstructor, final int previousViewId, final int currentViewId,
130 final EstimatedCamera previousCamera, final EstimatedCamera currentCamera);
131
132 /**
133 * Called when reconstructed points have been estimated from a series of 2D
134 * matches. Reconstructed points returned on this event are defined in a metric stratum (i.e. up to
135 * scale).
136 * This event can be used to store reconstructed points and their associated data.
137 *
138 * @param reconstructor re-constructor raising this event.
139 * @param matches 2D matches associated to estimated reconstructed points.
140 * @param points reconstructed 3D points.
141 */
142 void onMetricReconstructedPointsEstimated(final R reconstructor, final List<MatchedSamples> matches,
143 final List<ReconstructedPoint3D> points);
144
145 /**
146 * Called when cameras for provided matched pair of views have been estimated in an Euclidean stratum
147 * (when possible and up to a certain accuracy).
148 * Except {@link SparseReconstructor}, which can only make estimations in a metric stratum, other
149 * reconstructor implementations either have calibration knowledge to estimate scale, or use SLAM
150 * techniques by mixing additional sensor data (i.e. gyroscope and accelerometer) to estimate such
151 * scale.
152 *
153 * @param reconstructor re-constructor raising this event.
154 * @param previousViewId id of previous view (i.e. first view).
155 * @param currentViewId id of current view (i.e. second view).
156 * @param scale estimated scale. This will typically converge to a constant value as more
157 * views are processed. The smaller the variance of estimated scale, the more
158 * accurate the scale will be.
159 * @param previousCamera estimated camera for previous view.
160 * @param currentCamera estimated camera for current view.
161 */
162 void onEuclideanCameraEstimated(final R reconstructor, final int previousViewId,
163 final int currentViewId, final double scale,
164 final EstimatedCamera previousCamera,
165 final EstimatedCamera currentCamera);
166
167 /**
168 * Called when reconstructed points have been estimated from a series of 2D matches.
169 * Except {@link SparseReconstructor}, which can only make estimations in a metric stratum, other
170 * re-constructor implementations either have calibration knowledge to estimate scale, or use SLAM
171 * techniques by mixing additional sensor data (i.e. gyroscope and accelerometer) to estimate such
172 * scale.
173 *
174 * @param reconstructor re-constructor raising this event.
175 * @param scale estimated scale. This will typically converge to a constant value as more views
176 * are processed. The smaller the variance of estimated scale, the more accurate
177 * the scale will be.
178 * @param points reconstructed 3D points.
179 */
180 void onEuclideanReconstructedPointsEstimated(final R reconstructor, final double scale,
181 final List<ReconstructedPoint3D> points);
182
183 /**
184 * Called when reconstruction starts.
185 *
186 * @param reconstructor re-constructor raising this event.
187 */
188 void onStart(final R reconstructor);
189
190 /**
191 * Called when reconstruction stops.
192 *
193 * @param reconstructor re-constructor raising this event.
194 */
195 void onFinish(final R reconstructor);
196
197 /**
198 * Called when reconstruction is cancelled before it has finished.
199 *
200 * @param reconstructor re-constructor raising this event.
201 */
202 void onCancel(final R reconstructor);
203
204 /**
205 * Called when reconstruction fails.
206 *
207 * @param reconstructor re-constructor raising this event.
208 */
209 void onFail(final R reconstructor);
210
211 }