disparityBM
Compute disparity map using block matching
Description
computes disparity map from a pair of rectified stereo images disparityMap
= disparityBM(I1
,I2
)I1
and
I2
, by using the block matching method. To know more about rectifying
stereo images, see Image Rectification.
specifies options using one or more name-value pair arguments.disparityMap
= disparityBM(I1
,I2
,Name,Value
)
Examples
Compute Disparity Map by Using Block Matching Method
Load a rectified stereo pair image.
I1 = imread('rectified_left.png'); I2 = imread('rectified_right.png');
Create the stereo anaglyph of the rectified stereo pair image and display it. You can view the image in 3-D by using red-cyan stereo glasses.
A = stereoAnaglyph(I1,I2);
figure
imshow(A)
title('Red-Cyan composite view of the rectified stereo pair image')
Convert the rectified input color images to grayscale images.
J1 = im2gray(I1); J2 = im2gray(I2);
Compute the disparity map. Specify the range of disparity as [0, 48], and the minimum value of uniqueness as 20.
disparityRange = [0 48]; disparityMap = disparityBM(J1,J2,'DisparityRange',disparityRange,'UniquenessThreshold',20);
Display the disparity map. Set the display range to the same value as the disparity range.
figure imshow(disparityMap,disparityRange) title('Disparity Map') colormap jet colorbar
Input Arguments
I1
— Input image 1
2-D grayscale image | gpuArray
object
Input image referenced as I1
corresponding to camera 1,
specified as a 2-D grayscale image or a gpuArray
(Parallel Computing Toolbox) object. The function uses this image as the reference image for
computing the disparity map. The input images I1
and
I2
must be real, finite, and nonsparse. Also,
I1
and I2
must be of the same size and same
data type.
Data Types: single
| double
| int16
| uint8
| uint16
I2
— Input image 2
2-D grayscale image | gpuArray
object
Input image referenced as I2
corresponding to camera 2,
specified as a 2-D grayscale image or a gpuArray
(Parallel Computing Toolbox) object. The input images I1
and
I2
must be real, finite, and nonsparse. I1
and I2
must be of the same size and same data type.
Data Types: single
| double
| int16
| uint8
| uint16
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: disparityBM(I1,I2,'DisparityRange',[0 64])
DisparityRange
— Range of disparity
[0 64]
(default) | two-element vector
Range of disparity, specified as the comma-separated pair consisting of
'DisparityRange'
and a two-element vector of the form
[MinDisparity
MaxDisparity]. MinDisparity is the minimum
disparity and MaxDisparity is the maximum disparity. The conditions
this range must satisfy depend on the type of input images.
If the input images are grayscale images of width N, then:
MinDisparity and MaxDisparity must be integers in the range (–N, N).
The difference between the MaxDisparity and MinDisparity values must be divisible by 16 and less than the width of the input images.
If the input images are gpuArray
objects of width
N, then:
The value of MinDisparity must be equal to zero.
The value of MaxDisparity must be in the range (16, N). If N is greater than 256, then the MaxDisparity must be chosen as less than or equal to 256.
The difference between the MaxDisparity and MinDisparity values must be divisible by 16.
The default value for the range of disparity is [0 64]
. For
more information on choosing the range of disparity, see Choosing Range of Disparity.
BlockSize
— Size of squared block
15
(default) | odd integer
Size of the squared block, specified as the comma-separated pair consisting of
'BlockSize'
and an odd integer. This value specifies the width of
the search window used for block matching pixels in the rectified stereo pair image.
The range for the size squared block depend on the type of input images.
If the input images are grayscale images, the 'BlockSize'
value
must be an odd integer in the range [5, 255].
If the input images are gpuArray
objects, the
'BlockSize'
value must be an odd integer in the range [5,
51].
The default value is 15.
ContrastThreshold
— Range of contrast threshold
0.5
(default) | scalar in the range (0, 1]
Range of contrast threshold, specified as the comma-separated pair consisting of
'ContrastThreshold'
and a scalar value in the range (0, 1]. The
contrast threshold defines an acceptable range of contrast values. If the contrast
value of a pixel in the reference image is below the contrast threshold, then the
disparity computed for that pixel is considered unreliable.
Increasing this parameter results in disparity for fewer pixels being marked as
unreliable.
UniquenessThreshold
— Minimum value of uniqueness
15
(default) | nonnegative integer
Minimum value of uniqueness, specified as the comma-separated pair consisting of
'UniquenessThreshold'
and a nonnegative integer.
The function marks the estimated disparity value K for a pixel as unreliable, if:
v < V×(1+0.01×UniquenessThreshold
),
where V is the sum of absolute difference (SAD) corresponding to the disparity value K. v is the smallest SAD value over the whole disparity range, excluding K, K–1, and K+1.
Increasing the value of UniquenessThreshold
results in disparity values for more pixels being marked as unreliable. To disable the
use of uniqueness threshold, set this value to []
.
Note
If the input images are gpuArray
objects, then the
'UniquenessThreshold'
name-value pair argument does not
apply.
DistanceThreshold
— Maximum distance between conjugate pixels in stereo pair image
[]
(disabled) (default) | nonnegative integer
Maximum distance between conjugate pixels in stereo pair image, specified as the
comma-separated pair consisting of 'DistanceThreshold'
and a
nonnegative integer. The distance threshold specifies the maximum distance between a
pixel in I1
and the same pixel found in I2
.
For pixel p1 in the reference image
I1
, the function performs a left-to-right check to find its
best matching pixel p2 in image
I2
. For pixel p2, the
function performs a right-to-left check to find its best matching pixel
p3 in the reference image
I1
. If the distance between
p1 and
p3 is greater than the DistanceThreshold
, the function marks the disparity for the
pixel p1 in the reference image
I1
as unreliable.
Increasing the value of DistanceThreshold
results in disparity values for fewer pixels being marked as unreliable. Conversely,
decreasing the value of DistanceThreshold
, increases
the reliability of the disparity map. To disable the use of distance threshold, set
this value to []
.
Note
If the input images are gpuArray
objects, then the
'DistanceThreshold'
name-value pair argument does not
apply.
TextureThreshold
— Minimum texture threshold
0.0002
(default) | scalar value in the range [0, 1)
Minimum texture threshold, specified as the comma-separated pair consisting of
'TextureThreshold'
and a scalar value in the range [0, 1).
The texture of a pixel is defined as the sum of the saturated contrast computed
over the BlockSize
-by-BlockSize
window around the pixel. The texture threshold defines the
minimum texture value for a pixel to have reliable disparity value. The function
considers the disparity for a pixel as unreliable, if:
texture <
intensitymax×TextureThreshold
×BlockSize
2,
where texture is the texture of a pixel.
intensitymax is the maximum value
supported by the data type of input images I1
and
I2
.
Increasing the value of 'TextureThreshold'
results in disparity
values for more pixels being marked as unreliable. To disable the use of texture
threshold, set this value to []
.
Output Arguments
disparityMap
— Disparity map
2-D grayscale image | gpuArray
object
Disparity map for rectified stereo pair image, returned as a 2-D grayscale image or
a gpuArray
object. The function returns the disparity map with the
same size as input images I1
and I2
. Each
value in this output refers to the displacement between conjugate pixels in the stereo
pair image. For details about computing the disparity map, see Computing Disparity Map Using Block Matching.
Data Types: single
More About
Image Rectification
The input images I1
and I2
must be rectified before computing the disparity map. The rectification ensures that the
corresponding points in the stereo pair image are on the same rows. You can rectify the
input stereo pair image by using the rectifyStereoImages
function. The reference image must be the same for
rectification and disparity map computation.
Algorithms
Choosing Range of Disparity
The range of disparity must be chosen to cover the minimum and the maximum amount of
horizontal shift between the corresponding pixels in the rectified stereo pair image. You
can determine the approximate horizontal shift values from the stereo anaglyph of the stereo
pair image. Compute the stereo anaglyph of the rectified images by using the stereoAnaglyph
function. Display the stereo anaglyph in the Image
Viewer app. To measure the amount of horizontal shift between the corresponding
points in the stereo pair image, select Measure Distance
from the Tools menu in Image Viewer. Choose the
minimum and maximum disparity values for the range of disparity based on this measurement.
For example, this figure displays the stereo anaglyph of a rectified stereo pair image and the horizontal shift values measured between the corresponding points in the stereo pair image. The minimum and maximum shift values are computed as 12.3101 and 32.3757 respectively. Based on these values, the range of disparity can be chosen as [0, 48].
Computing Disparity Map Using Block Matching
The function computes the disparity map by following these steps:
Compute the disparity for each pixel by using the block matching method given in [1].
For CPU — The sum of absolute difference (SAD) is used as the cost function in block matching. The cost function estimates the displacement between pixels in the rectified stereo pair image.
Optionally, mark the pixels for unreliability based on the
ContrastThreshold
,UniquenessThreshold
,DistanceThreshold
, andTextureThreshold
name-value pairs. The function sets the unreliable disparity values toNaN
.
References
[1] Konolige, K. "Small Vision Systems: Hardware and Implementation." In Proceedings of the 8th International Symposium in Robotic Research, pp. 203–212. 1997.
[2] Bradski, G. and A. Kaehler. Learning OpenCV : Computer Vision with the OpenCV Library. Sebastopol, CA: O'Reilly Media, Inc. 2008.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Supports code generation only in generic
MATLAB Host Computer
target platform.
Version History
Introduced in R2019aR2022a: GPU Use Being Removed for disparityBM
function
The disparityBM
function no longer supports GPU. You can use the enhanced disparitySGM
on
the GPU instead. Results will not be identical using the disparitySGM
function, but the semi-global algorithm used in the disparitySGM
is
normally recommended over the block matching algorithm in the disparityBM
function.
See Also
Apps
Functions
MATLAB-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)