# disparitySGM

## Description

computes disparity map from a pair of rectified stereo images `disparityMap`

= disparitySGM(`I1`

,`I2`

)`I1`

and
`I2`

, by using semi-global matching (SGM) method. To know more about
rectifying stereo images, see Image Rectification.

specifies options using one or more name-value pair arguments.`disparityMap`

= disparitySGM(`I1`

,`I2`

,`Name,Value`

)

## 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
divisible by 8 and must be less than or equal to 128.

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`

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

Compute Census transform of the rectified stereo pair image.

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

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

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™.

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™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

## Version History

**Introduced in R2019a**

## See Also

### Apps

### Functions

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

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)