# disparity

Disparity map between stereo images

## Syntax

• `disparityMap = disparity(I1,I2)` example
• `d = disparity(I1,I2,Name,Value)`

## Description

example

````disparityMap = disparity(I1,I2)` returns the disparity map, `disparityMap`, for a pair of stereo images, `I1` and `I2`. ```
````d = disparity(I1,I2,Name,Value)` Additional control for the disparity algorithm requires specification of parameters and corresponding values. One or more `Name,Value` pair arguments specifies an additional option.Code Generation Support:Compile-time constant input: `Method`Supports MATLAB Function block: NoGenerated code for this function uses a precompiled platform-specific shared library.Code Generation Support, Usage Notes, and Limitations```

## Examples

collapse all

### Compute the Disparity Map for a Pair of Stereo Images

Load the images and convert them to grayscale.

``` I1 = rgb2gray(imread('scene_left.png')); I2 = rgb2gray(imread('scene_right.png')); figure; imshowpair(I1,I2,'ColorChannels','red-cyan'); title('Red-cyan composite view of the stereo images'); ```

Compute the disparity map.

``` disparityMap = disparity(I1, I2, 'BlockSize', 15,'DisparityRange', [-6 10], 'Method','SemiGlobal'); ```

For the purpose of visualizing the disparity, replace the -realmax('single') marker with the minimum disparity value.

``` marker_idx = (disparityMap == -realmax('single')); disparityMap(marker_idx) = min(disparityMap(~marker_idx)); ```

Show the disparity map. Brighter pixels indicate objects which are closer to the camera.

``` figure; imshow(mat2gray(disparityMap)); ```

## Input Arguments

collapse all

### `I1` — Input image 1M-by-N 2-D grayscale image

Input image referenced as `I1` corresponding to camera 1, specified in 2-D grayscale. The stereo images, `I1` and `I2`, must be rectified such that the corresponding points are located on the same rows. You can perform this rectification with the `rectifyStereoImages` function.

You can improve the speed of the function by setting the class of `I1` and `I2` to `uint8`, and the number of columns to be divisible by 4. Input images `I1` and `I2` must be real, finite, and nonsparse. They must be the same class.

Data Types: `uint8` | `uint16` | `int16` | `single` | `double`

### `I2` — Input image 2M-by-N 2-D grayscale image

Input image referenced as `I2` corresponding to camera 2, specified in 2-D grayscale. The input images must be rectified such that the corresponding points are located on the same rows. You can improve the speed of the function by setting the class of `I1` and `I2` to `uint8`, and the number of columns to be divisible by 4. Input images `I1` and `I2` must be real, finite, and nonsparse. They must be the same class.

Data Types: `uint8` | `uint16` | `int16` | `single` | `double`

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `'Method'`,`'BlockMatching'`, specifies the `'Method'` property be set to `'BlockMatching'`.

### `'Method'` — Disparity estimation algorithm`'SemiGlobal'` (default) | `'BlockMatching'`

Disparity estimation algorithm, specified as the comma-separated pair consisting of '`Method`' and the string `'BlockMatching'` or `'SemiGlobal'`. The disparity function implements the basic Block Matching[1] and the Semi-Global Block Matching[3] algorithms. In the `'BlockMatching'` method, the function computes disparity by comparing the sum of absolute differences (SAD) of each block of pixels in the image. In the `'SemiGlobal'` matching method, the function additionally forces similar disparity on neighboring blocks. This additional constraint results in a more complete disparity estimate than in the `'BlockMatching'` method.

The algorithms perform these steps:

1. Compute a measure of contrast of the image by using the Sobel filter.

2. Compute the disparity for each pixel in `I1`.

3. Mark elements of the disparity map, `disparityMap`, that were not computed reliably. The function uses –`realmax`(`'single'`) to mark these elements.

### `'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. The two-element vector must be in the format [MinDisparity, MaxDisparity]. Both elements must be an integer. The difference between MaxDisparity and MinDisparity must be divisible by `16`. `DisparityRange` must be real, finite, and nonsparse.

### `'BlockSize'` — Square block size`15` (default) | odd integer

Square block size, specified as the comma-separated pair consisting of '`BlockSize`' and an odd integer in the range [5,255]. This value sets the width for the square block size. The function uses the square block of pixels for comparisons between `I1` and I2. `BlockSize` must be real, finite, and nonsparse.

### `'ContrastThreshold'` — Contrast threshold range`0.5` (default) | scalar value

Contrast threshold range, 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. Increasing this parameter results in fewer pixels being marked as unreliable.`ContrastThreshold` must be real, finite, and nonsparse.

### `'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. Increasing this parameter results in the function marking more pixels unreliable. When the uniqueness value for a pixel is low, the disparity computed for it is less reliable. Setting the threshold to `0` disables uniqueness thresholding. `UniquenessThreshold` must be real, finite, and nonsparse.

The function defines uniqueness as a ratio of the optimal disparity estimation and the less optimal disparity estimation. For example:

 Let K be the best estimated disparity, and let V be the corresponding SAD (Sum of Absolute Difference) value. Consider V as the smallest SAD value over the whole disparity range, and v as the smallest SAD value over the whole disparity range, excluding K, K-1, and K+1. If v < V * (`1`+`0.01`*`UniquenessThreshold`), then the function marks the disparity for the pixel as unreliable.

### `'DistanceThreshold'` — Maximum distance for left-to-right image checking`[]` (disabled) (default) | non-negative integer

Maximum distance for left-to-right image checking between two points, specified as the comma-separated pair consisting of '`DistanceThreshold`' and a nonnegative integer. Increasing this parameter results in fewer pixels being marked as unreliable. Conversely, when you decrease the value of the distance threshold, you increase the reliability of the disparity map. You can set this parameter to an empty matrix `[]` to disable it. `DistanceThreshold` must be real, finite, and nonsparse.

The distance threshold specifies the maximum distance between a point in `I1` and the same point found from `I2`. The function finds the distance and marks the pixel in the following way:

 Let p1 be a point in image I1. Step 1: The function searches for point p1's best match in image I2 (left-to-right check) and finds point p2. Step 2: The function searches for p2's best match in image I1 (right-to-left check) and finds point p3. If the search returns a distance between p1 and p3 greater than `DistanceThreshold`, the function marks the disparity for the point p1 as unreliable.

### `'TextureThreshold'` — Minimum texture threshold`0.0002` (default) | scalar value

Minimum texture threshold, specified as the comma-separated pair consisting of '`TextureThreshold`' and a scalar value in the range [0, 1]. The texture threshold defines the minimum texture value for a pixel to be reliable. The lower the texture for a block of pixels, the less reliable the computed disparity is for the pixels. Increasing this parameter results in more pixels being marked as unreliable. You can set this parameter to `0` to disable it. This parameter applies only when you set `Method` to `'BlockMatching'`.

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 function considers the disparity computed for the pixel unreliable and marks it, when the texture falls below the value defined by:

Texture < X* `TextureThreshold` * `BlockSize`2

X represents the maximum value supported by the class of the input images, `I1` and `I2`.

`TextureThreshold` must be real, finite, and nonsparse.

## Output Arguments

collapse all

### `disparityMap` — Disparity mapM-by-N 2-D grayscale image

Disparity map for a pair of stereo images, returned as an M-by-N 2-D grayscale image. The function returns the disparity map with the same size as the input images, `I1` and `I2`. Each element of the output specifies the disparity for the corresponding pixel in the image references as `I1`. The returned disparity values are rounded to $1}{16}$th pixel.

The function computes the disparity map in three steps:

1. Compute a measure of contrast of the image by using the Sobel filter.

2. Compute the disparity for each of the pixels by using block matching and the sum of absolute differences (SAD).

3. Optionally, mark the pixels which contain unreliable disparity values. The function sets the pixel to the value returned by -`realmax`('`single`').

## References

[1] Konolige, K., Small Vision Systems: Hardware and Implementation, Proceedings of the 8th International Symposium in Robotic Research, pages 203-212, 1997.

[2] Bradski, G. and A. Kaehler, Learning OpenCV : Computer Vision with the OpenCV Library, O'Reilly, Sebastopol, CA, 2008.

[3] Hirschmuller, H., Accurate and Efficient Stereo Processing by Semi-Global Matching and Mutual Information, International Conference on Computer Vision and Pattern Recognition, 2005.