disparitySGM

Compute disparity map through semi-global matching

Syntax

disparityMap = disparitySGM(I1,I2)

[disparityMap,disparityRangeUsed] = disparitySGM(I1,I2)

___ = disparitySGM(I1,I2,Name,Value)

Description

disparityMap = disparitySGM(I1,I2) computes disparity map from a pair of rectified stereo images I1 and I2, by using semi-global matching (SGM) method. To know more about rectifying stereo images, see Image Rectification.

[disparityMap,disparityRangeUsed] = disparitySGM(I1,I2) additionally returns the actual values of the disparity range used to estimate disparity, which may differ from those provided using the DisparityRange name-value argument.

___ = disparitySGM(I1,I2,Name,Value) specifies additional options using one or more name-value pair arguments along with any of the previous syntaxes.

Examples

Compute Disparity Map by Using Semi-Global 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 through semi-global matching. Specify the range of disparity as [0, 48], and the minimum value of uniqueness as 20.

disparityRange = [0 48];
disparityMap = disparitySGM(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: disparitySGM(I1,I2,'DisparityRange',[0 64])

DisparityRange — Range of disparity

[0 128] (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.

For input images of width N, the MinDisparity and MaxDisparity must be integers in the range (–N, N). The difference between the MaxDisparity and MinDisparity values must be less than or equal to 128. If the difference is not divisible by 8, the function internally rounds up the disparity range to the nearest multiple of 8. The function returns the actual value used in the disparity map computation in the disparityRangeUsed output argument.

The default value for the range of disparity is [0 128]. For more information on choosing the range of disparity, see Choosing Range of Disparity.

Data Types: integers

UniquenessThreshold — Minimum value of uniqueness

15 (default) | non-negative 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 Hamming distance corresponding to the disparity value K. v is the smallest Hamming distance 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 0.

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 Semi-Global Matching.

Data Types: single

disparityRangeUsed — Range of disparity actually used in the disparity map computation

2 element vector

Range of disparity actually used in the disparity map computation, returned as a two-element vector of the form [MinDisparity MaxDisparity]. MinDisparity is the minimum disparity and MaxDisparity is the maximum disparity. This value can differ from the value specified using the DisparityRange name-value argument in order to satisfy internal numerical constraints, where the difference between the MaxDisparity and MinDisparity values must be divisible by 8.

Data Types: double

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.

Tips

• Ensure accurate rectification — Imperfect rectification can significantly degrade the quality of the disparitySGM function results. Use the rectifyStereoImages function to rectify the input stereo image pair I1 and I2, so that the corresponding points are on the same rows. Use the stereoAnaglyph function to inspect the rectification results by creating an anaglyph image.

• Apply post-processing — For better results, improve disparity maps by applying image processing operations such as median filtering (medfilt2), hole filling (imfill), or bilateral filtering (imbilatfilt).

• Explore deep learning-based alternatives — For well-rectified, narrow-baseline stereo setups where classical SGM struggles with texture-less regions or repeated patterns, try opticalFlowRAFT as a deep learning-based alternative. For more information on comparison between classical SGM and RAFT deep learning model, see Compare RAFT Optical Flow and Semi-Global Matching for Stereo Reconstruction.

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 Semi-Global Matching

1. Compute Census transform of the rectified stereo pair image.

2. Compute Hamming distance between pixels in the census-transformed image to obtain the matching cost matrix.

3. Compute the pixel-wise disparity from matching cost matrix by using the semi-global matching method given in [1].

4. Optionally, mark the pixels for unreliability based on the UniquenessThreshold name-value pair. The function sets the disparity values of the unreliable pixels to NaN.

References

[1] Hirschmuller, H. "Accurate and Efficient Stereo Processing by Semi-Global Matching and Mutual Information." In Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR), pp. 807-814. San Diego, CA: IEEE, 2005.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The name-value pair arguments, 'DisparityRange' and 'UniquenessThreshold' must be compile-time constants.

• Supports code generation only in generic MATLAB Host Computer target platform.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The input images I1 and I2 must be rectified, same size, and of same data type.

• GPU code generation supports the 'UniquenessThreshold' and 'disparityMap' name-value pairs.

• For very large inputs, the memory requirements of the algorithm may exceed the GPU device limits. In such cases, consider reducing the input size to proceed with code generation.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The disparitySGM function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2019a

R2026a: Disparity Range No Longer Required to Be Divisible by 8

When you specify the DisparityRange name-value argument, the difference between the MaxDisparity and MinDisparity values is no longer required to be divisible by 8. If the difference is not divisible by 8, the function internally rounds up the disparity range to the nearest multiple of 8. To see the actual value used in the disparity map computation, use the disparityRangeUsed output argument.