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 com.irurueta.geometry.PinholeCameraIntrinsicParameters;
20
21 import java.util.List;
22
23 /**
24 * Listener to retrieve and store required data to compute a 3D reconstruction from
25 * sparse image point correspondences in multiple views.
26 *
27 * @param <R> type of re-constructor.
28 */
29 public interface BasePairedViewsSparseReconstructorListener<R extends BasePairedViewsSparseReconstructor<?, ?, ?>> {
30
31 /**
32 * Called to determine whether there are more views available to attempt to use for
33 * the reconstruction.
34 *
35 * @param reconstructor reconstructor raising this event.
36 * @return true if there are more views available, false otherwise.
37 */
38 boolean hasMoreViewsAvailable(final R reconstructor);
39
40 /**
41 * Called when samples containing points of interest for current view must be
42 * retrieved.
43 *
44 * @param reconstructor re-constructor raising this event.
45 * @param viewId1 id of 1st view where points will be used in current view pair.
46 * @param viewId2 id of 2nd view where points will be used in current view pair.
47 * @param samples1 samples containing points of interest for 1st view to test in
48 * current pair.
49 * @param samples2 samples containing points of interest for 2nd view to test in
50 * current pair.
51 */
52 void onRequestSamplesForCurrentViewPair(final R reconstructor, final int viewId1, final int viewId2,
53 final List<Sample2D> samples1, final List<Sample2D> samples2);
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 viewId1 id of 1st view whose samples have been accepted in current view pair.
62 * @param viewId2 id of 2nd view whose samples have been accepted in current view pair.
63 * @param samples1 accepted samples on 1st view in current view pair.
64 * @param samples2 accepted samples on 2nd view in current view pair.
65 */
66 void onSamplesAccepted(final R reconstructor, final int viewId1, final int viewId2,
67 final List<Sample2D> samples1, final List<Sample2D> samples2);
68
69 /**
70 * Called when requested samples have been rejected.
71 * This method can be used to remove provided samples.
72 *
73 * @param reconstructor re-constructor raising this event.
74 * @param viewId1 id of 1st view whose samples have been rejected in current view pair.
75 * @param viewId2 id of 2nd view whose samples have been rejected in current view pair.
76 * @param samples1 rejected samples on 1st view in current view pair.
77 * @param samples2 rejected samples on 2nd view in current view pair.
78 */
79 void onSamplesRejected(final R reconstructor, final int viewId1, final int viewId2,
80 final List<Sample2D> samples1, final List<Sample2D> samples2);
81
82 /**
83 * Finds matches for provided samples.
84 *
85 * @param reconstructor re-constructor raising this event.
86 * @param viewId1 id of 1st view where points will be used in current view pair.
87 * @param viewId2 id of 2nd view where points will be used in current view pair.
88 * @param samples1 samples containing points of interest for 1st view to test in
89 * current pair.
90 * @param samples2 samples containing points of interest for 2nd view to test in
91 * current pair.
92 * @param matches instance where matches must be stored.
93 */
94 void onRequestMatches(final R reconstructor, final int viewId1, final int viewId2,
95 final List<Sample2D> samples1, final List<Sample2D> samples2,
96 final List<MatchedSamples> matches);
97
98 /**
99 * Called when a fundamental matrix relating a pair of views has been estimated.
100 * This event can be used to store estimated fundamental matrix relating two views.
101 *
102 * @param reconstructor re-constructor raising this event.
103 * @param viewId1 id of 1st view where points will be used in current view pair.
104 * @param viewId2 id of 2nd view where points will be used in current view pair.
105 * @param estimatedFundamentalMatrix estimated fundamental matrix.
106 */
107 void onFundamentalMatrixEstimated(final R reconstructor, final int viewId1, final int viewId2,
108 final EstimatedFundamentalMatrix estimatedFundamentalMatrix);
109
110 /**
111 * Called when cameras for provided matched pair of views have been estimated in an
112 * Euclidean stratum (up to certain translation and rotation).
113 * Implementations using SLAM techniques by mixing additional sensor data (i.e.
114 * gyroscope and accelerometer) to estimate scale of each view pair, might also have
115 * some inaccuracies in estimated scale.
116 *
117 * @param reconstructor re-constructor raising this event.
118 * @param viewId1 id of previous view (i.e. 1st view).
119 * @param viewId2 id of current view (i.e. 2nd view).
120 * @param scale estimated scale. When using SLAM this is estimated up to a certain
121 * accuracy.
122 * @param camera1 estimated Euclidean camera for previous view (i.e. 1st view).
123 * @param camera2 estimated Euclidean camera for current view (i.e. 2nd view).
124 */
125 void onEuclideanCameraPairEstimated(final R reconstructor, final int viewId1, final int viewId2,
126 final double scale, final EstimatedCamera camera1,
127 final EstimatedCamera camera2);
128
129 /**
130 * Called when reconstructed points have been estimated from a series of 2D matches in a
131 * pair of views in an Euclidean stratum (up to certain translation and rotation).
132 *
133 * @param reconstructor re-constructor raising this event.
134 * @param viewId1 id of previous view (i.e. 1st view).
135 * @param viewId2 id of current view (i.e. 2nd view).
136 * @param scale estimated scale. When using SLAM this is estimated up to a certain
137 * accuracy.
138 * @param points reconstructed 3D points in Euclidean space.
139 */
140 void onEuclideanReconstructedPointsEstimated(final R reconstructor,
141 final int viewId1, final int viewId2, final double scale,
142 final List<ReconstructedPoint3D> points);
143
144 /**
145 * Called when intrinsic parameters are requested for a given view.
146 * This is required if at configuration it was indicated that intrinsic parameters are
147 * known, so that essential matrix method can be used for scene reconstruction.
148 * If intrinsic parameters are unknown, DIAC or DAQ method will be attempted if possible.
149 *
150 * @param reconstructor re-constructor raising this event.
151 * @param viewId id of view whose parameters are requested.
152 * @return intrinsic parameters if known, null otherwise.
153 */
154 PinholeCameraIntrinsicParameters onIntrinsicParametersRequested(final R reconstructor, final int viewId);
155
156 /**
157 * Called when reconstruction starts.
158 *
159 * @param reconstructor re-constructor raising this event.
160 */
161 void onStart(final R reconstructor);
162
163 /**
164 * Called when reconstruction stops.
165 *
166 * @param reconstructor re-constructor raising this event.
167 */
168 void onFinish(final R reconstructor);
169
170 /**
171 * Called when reconstruction is cancelled before it has finished.
172 *
173 * @param reconstructor re-constructor raising this event.
174 */
175 void onCancel(final R reconstructor);
176
177 /**
178 * Called when reconstruction fails.
179 *
180 * @param reconstructor re-constructor raising this event.
181 */
182 void onFail(final R reconstructor);
183 }