-
Notifications
You must be signed in to change notification settings - Fork 20
/
Copy pathREADME.txt
220 lines (159 loc) · 6.61 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
============
Introduction
============
This is the MGM code written by Gabriele Facciolo,
Carlo de Franchis, and Enric Meinhardt.
If you want to use this software or results obtained with it,
the following paper should be cited within your publication:
- G. Facciolo and C. de Franchis and E. Meinhardt,
"MGM: A Significantly More Global Matching for Stereovision",
in British Machine Vision Conference, BMVC 2015.
Site : http://dev.ipol.im/~facciolo/mgm/
Email: gabriele.facciolo@cmla.ens-cachan.fr
=========================
Overview of the algorithm
=========================
This C++ code can be used for approximately optimizing MRF energies,
defined on the 4- or 8-connected image grids, of the form:
E(D) = \sum_p C_p(D_p) + \sum_{pq} w_{pq} V (D_p, D_q)
where C_p() denotes the unary term for the p-th node, the variables
D_p take values in the range [0,L-1], C_p is represented as a
costvolume of size W x H x L.
V() denotes the distance function used for specifying the pairwise
potentials, it can take one of these two forms (with params P1,P2):
1) SMG's potential (Hirschmuller'08)
| 0 if |a - b|==0
Vh(a,b) = | P1 if |a - b|==1
| P2 otherwise
or
2) any potential described in (Felzenszwalb-Huttenlocher'06),
this code implements truncated linear and linear (P2=inf)
Vl(a,b) = min(P1*|a - b|, P2).
The edge weights are given by w_{pq}, w can actually be used to adapt
the parameters P1 and P2 on the pixel basis as:
V (D_p, D_q, P1(w(p)), P2(w(p)) ),
but the current implementation just multiplies the potential.
The weights are represented as a stack of 8 images. For a pixel p
each image of the stack contain the weight to the corresponding
neighboring pixel: West, Est, S, N, (NW, NE, SE, SW).
That is the first image just contains the weights for pixels to the left.
For 4-connectivity, only the first 4 images are read, while for
8-connectivity the whole stack of 8 images is used.
===========
Stereo code
===========
The code in this directory uses MGM for stereo.
The option of the mgm program are shown when called without parameters.
====================================
Simplified code and Matlab interface
====================================
The matlab subdirectory contains a simplified version of MGM,
and a matlab wrapper for solving optimization problems as
described above.
===========
Compilation
===========
Run make to compile the C++ code (uses OpenMP)
Tested in Linux, OSX and OpenBSD using gcc and clang
=============
Example calls
=============
The following line runs MGM with 8 traversals (-O 8) with 3-neighbor
recursion (TSGM=3, mgm is usually 2, but this is NEW!).
* The cost is measured in absolute differences of the horizontal
sobel derivatives (sobel_x),
* for the regularity it uses the FELZENSZWALB potential V
(USE_TRUNCATED_LINEAR_POTENTIALS=1),
* then refines disparities with V_fitting and postprocesses with
MEDIAN filter.
MEDIAN=1 USE_TRUNCATED_LINEAR_POTENTIALS=1 TSGM=3 ./mgm -P2 20000 -P1 4 -r -120 -R 30 -p sobel_x \
-truncDist 63 -s vfit -O 8 data/fountain23-im?.png /tmp/{disp,cost}.tif
The following line runs MGM with 8 traversals (-O 8) with 3-neighbor recursion (TSGM=3, mgm is usually 2, but this is NEW!)
* the cost is CENSUS on 3x3 neighors,
* for the regularity uses the FELZENSZWALB potential V
(USE_TRUNCATED_LINEAR_POTENTIALS=1),
* then refines disparities with V_fitting and postprocesses
with MEDIAN filter.
MEDIAN=1 CENSUS_NCC_WIN=3 USE_TRUNCATED_LINEAR_POTENTIALS=1 TSGM=3 ./mgm -P2 20000 -P1 2 -r -120 -R 30 \
-t census -s vfit -O 8 data/fountain23-im?.png /tmp/{disp,cost}.tif
The following line runs a similar experiment with a satellite image
OMP_NUM_THREADS=4 MEDIAN=1 CENSUS_NCC_WIN=5 TSGM=3 ./mgm -r -22 -R 19 -s vfit \
-t census -O 8 data/rectified_{ref,sec}.tif /tmp/{disp,cost}.tif
====================
Full list of options
====================
This section describes the options accepted by the ``mgm`` program.
-----
Usage
-----
mgm <options> left_image.tif right_image.tif output_disparity.tif \
[cost_function.tif [back_flow.tif]]
--------------------
Command-line options
--------------------
-r (default=-30):
Minimum horizontal disparity value. (The images are assumed
to be rectified, which eliminates the vertical disparity.)
-R (default=30):
Maximum horizontal disparity value.
-O (default=4):
Number of search directions. Options: 2, 4, 8, 16.
-P1 (default=8)
SGM regularization parameter P1.
-P2 (default=32):
SGM regularization parameter P2.
-p (default=none):
Prefilter algorithm. Options: none, census, sobelx, gblur. The
``census`` mode uses the window of dimensions ``CENSUS_NCC_WIN``.
-t (default=ad):
Distance function. Options: census, ad, sd, ncc, btad, btsd. For
``ncc`` the window of dimensions ``CENSUS_NCC_WIN`` is used. The
``bt`` option is the Birchfield-Tomasi distance.
-truncDist (default=inf):
Truncate distances at nch * truncDist.
-s (default=none):
Subpixel refinement algorithm. Options: none, vfit, parabola,
cubic.
-aP1 (default=1):
Multiplier factor of P1 when sum |I1 - I2|^2 < nch * aThresh^2.
-aP2 (default=1):
Multiplier factor of P2 as above.
-aThresh (default=5):
Threshold for the multiplier factors.
-m FILE (default=none):
A file with minimum input disparity.
-M FILE (default=none):
A file with maximum input disparity.
-l FILE (default=none):
Write here the disparity without the left-to-right test.
-----------------------
Environmental variables
-----------------------
These should be set on the command line before ``mgm`` is invoked.
CENSUS_NCC_WIN=3:
Size of the window for the census prefilter algorithm and NCC
(normalized cross-correlation).
TESTLRRL=1:
If 1, do left-to-right and right-to-left consistency checks.
MEDIAN=0:
Radius of the median filter postprocessing.
TSGM=4:
Regularity level.
TSGM_ITER=1:
Number of iterations.
TSGM_FIX_OVERCOUNT=1:
If 1, fix overcounting of the data term in the energy.
TSGM_DEBUG=0:
If 1, print debug information.
TSGM_2LMIN=0:
Use the improved TSGM cost only for TSGM=2. Overrides the TSGM
value.
USE_TRUNCATED_LINEAR_POTENTIALS=0:
If 1, use the Felzenszwalb-Huttenlocher truncated linear
potential. Then P1 and P2 change meaning. The potential they
describe becomes V(p,q) = min(P2, P1*|p-q|).
==============
Acknowledgment
==============
Special thanks to Oleg Alexandrov for many bugfixes and for updating the
documentation.