BlockMatching¶
Performs block-matching to estimate pixel-wise disparities between two images.
Description¶
This application allows one to performs block-matching to estimate pixel-wise disparities for a pair of images in epipolar geometry.
This application is part of the stereovision pipeline. It can be used after having computed epipolar grids (with StereoRectificationGridGenerator) and resampled each input image into epipolar geometry (with GridBasedImageResampling).
The application searches locally for the displacement between a reference image and a secondary image. The correspondence is evaluated for each pixel, based on a pair of local neighborhood windows. The displacement evaluated can be 1D (along lines) or 2D. Parameters allow setting the minimum and maximum disparities to search (both for horizontal and vertical directions). A winner-take-all approach is used to select the best match. There are different metrics implemented to evaluate the match between two local windows:
SSD: Sum of Squared Distances
NCC: Normalized Cross-Correlation
Lp: Lp pseudo norm
Once the best integer disparity is found, an optional step of sub-pixel disparity estimation can be performed, with various algorithms (triangular interpolation, parabollic interpolation, dichotimic search). As post-processing, there is an optional step of median filtering on the disparities. One can chose input masks (related to the left and right input image) of pixels for which the disparity should be investigated. Additionally, two criteria can be optionally used to disable disparity investigation for some pixel: a no-data value, and a threshold on the local variance. This allows one to speed-up computation by avoiding to investigate disparities that will not be reliable anyway. For efficiency reasons, if the image of optimal metric values is desired, it will be concatenated to the output image (which will then have three bands: horizontal disparity, vertical disparity and metric value). One can split these images afterward.
This application has several output images and supports “multi-writing”. Instead of computing and writing each image independently, the streamed image blocks are written in a synchronous way for each output. The output images will be computed strip by strip, using the available RAM to compute the strip size, and a user defined streaming mode can be specified using the streaming extended filenames (type, mode and value). Note that multi-writing can be disabled using the multi-write extended filename option: &multiwrite=false, in this case the output images will be written one by one. Note that multi-writing is not supported for MPI writers.
Parameters¶
Input and output data¶
This group of parameters allows setting the input and output images.
Left input image -io.inleft image Mandatory
The left input image (reference).
It should have the same size and same physical space as the right input. This image can be generated by GridBasedImageResampling
Right input image -io.inright image Mandatory
The right input (secondary).
It should have the same size and same physical space as the left input. This image can be generated by GridBasedImageResampling
The output disparity map -io.out image [dtype] Mandatory
An image containing the estimated disparities as well as the metric values if the option is used. If no metric is output and no sub-pixel interpolation is done, pixel type canbe a signed integer. In the other cases, floating point pixel is advised.
The output mask corresponding to all criterions -io.outmask image [dtype]
An output mask image corresponding to all citerions (see masking parameters). Only required if variance threshold or nodata criterions are set. Output pixel type is unsigned 8bit by default.
Flag to output optimal metric values as well -io.outmetric bool Default value: false
If enabled, the output image will have a third component with metric optimal values
Image masking parameters¶
This group of parameters allows determining the masking parameters to prevent disparities estimation for some pixels of the left image
Mask to discard left pixels -mask.inleft image
This parameter allows providing a custom mask for the left image. Block matching will be only perform on pixels inside the mask (non-zero values).
Mask to discard right pixels -mask.inright image
This parameter allows providing a custom mask for the right image. Block matching will be perform only on pixels inside the mask (non-zero values).
Discard pixels with no-data value -mask.nodata float Default value: 0
This parameter allows discarding pixels whose value is equal to the user-defined no-data value.
Discard pixels with low local variance -mask.variancet float Default value: 100
This parameter allows discarding pixels whose local variance is too small (the size of the neighborhood is given by the radius parameter)
Block matching parameters¶
This group of parameters allow tuning the block-matching behaviour
Block-matching metric -bm.metric [ssd|ncc|lp] Default value: ssd
Metric to evaluate matching between two local windows.
Sum of Squared Distances
Sum of squared distances between pixels value in the metric windowNormalized Cross-Correlation
Normalized Cross-Correlation between the left and right windowsLp pseudo-norm
Lp pseudo-norm between the left and right windows.
Lp pseudo-norm options¶
p value -bm.metric.lp.p float Default value: 1
Value of the p parameter in Lp pseudo-norm (must be positive).
Radius of blocks -bm.radius int Default value: 3
The radius (in pixels) of blocks in Block-Matching
Minimum horizontal disparity -bm.minhd int Mandatory
Minimum horizontal disparity to explore (can be negative)
Maximum horizontal disparity -bm.maxhd int Mandatory
Maximum horizontal disparity to explore (can be negative)
Minimum vertical disparity -bm.minvd int Mandatory
Minimum vertical disparity to explore (can be negative)
Maximum vertical disparity -bm.maxvd int Mandatory
Maximum vertical disparity to explore (can be negative)
Sub-pixel interpolation -bm.subpixel [none|parabolic|triangular|dichotomy] Default value: none
Estimate disparities with sub-pixel precision
None
No sub-pixel searchParabolic fit
The metric values closest to the best match are used in order to fit a parabola to the local extremum of the metric surface. The peak position of this parabola is output.Triangular fit
The metric values closest to the best match are used in order to fit a triangular peak to the local extremum of the metric surface. The peak position of this triangle is output.Dichotomy search
An iterative dichotomic search is performed to find the best sub-pixel position. The window in the right image is resampled at sub-pixel positions to estimate the match.
Computation step -bm.step int Default value: 1
Location step between computed disparities. Disparities will be computed every ‘step’ pixels in the left image (step for both rows and columns). For instance, a value of 1 corresponds to the classic dense disparity map.To enforce consistency with its spacing, output disparity map values are divided by the step value.
X start index -bm.startx int Default value: 0
X start index of the subsampled grid (wrt the input image grid). See parameter bm.step
Y start index -bm.starty int Default value: 0
Y start index of the subsampled grid (wrt the input image grid). See parameter bm.step
Median filtering of disparity map¶
Use a median filter to get a smooth disparity map
Radius -bm.medianfilter.radius int
Radius (in pixels) for median filter
Incoherence threshold -bm.medianfilter.incoherence float
Incoherence threshold between original and filtered disparity
Initial disparities -bm.initdisp [none|uniform|maps] Default value: none
None
No initial disparity usedUniform initial disparity
Use an uniform initial disparity estimateInitial disparity maps
Use initial disparity maps to define the exploration area. This area in the right image is centered on the current position shifted by the initial disparity estimate, and has a given exploration radius in horizontal and vertical directions.
Uniform initial disparity options¶
Horizontal initial disparity -bm.initdisp.uniform.hdisp int Default value: 0
Value of the uniform horizontal disparity initial estimate (in pixels)
Vertical initial disparity -bm.initdisp.uniform.vdisp int Default value: 0
Value of the uniform vertical disparity initial estimate (in pixels)
Horizontal exploration radius -bm.initdisp.uniform.hrad int Default value: 0
Horizontal exploration radius around the initial disparity estimate (in pixels)
Vertical exploration radius -bm.initdisp.uniform.vrad int Default value: 0
Vertical exploration radius around the initial disparity estimate (in pixels)
Initial disparity maps options¶
Horizontal initial disparity map -bm.initdisp.maps.hmap image Mandatory
Map of the initial horizontal disparities
Vertical initial disparity map -bm.initdisp.maps.vmap image Mandatory
Map of the initial vertical disparities
Horizontal exploration radius -bm.initdisp.maps.hrad int Default value: 0
Horizontal exploration radius around the initial disparity estimate (in pixels)
Vertical exploration radius -bm.initdisp.maps.vrad int Default value: 0
Vertical exploration radius around the initial disparity estimate (in pixels)
Available RAM (MB) -ram int Default value: 256
Available memory for processing (in MB).
Examples¶
From the command-line:
otbcli_BlockMatching -io.inleft StereoFixed.png -io.inright StereoMoving.png -bm.minhd -10 -bm.maxhd 10 -mask.variancet 10 -io.out MyDisparity.tif
From Python:
import otbApplication
app = otbApplication.Registry.CreateApplication("BlockMatching")
app.SetParameterString("io.inleft", "StereoFixed.png")
app.SetParameterString("io.inright", "StereoMoving.png")
app.SetParameterInt("bm.minhd", -10)
app.SetParameterInt("bm.maxhd", 10)
app.SetParameterFloat("mask.variancet", 10)
app.SetParameterString("io.out", "MyDisparity.tif")
app.ExecuteAndWriteOutput()