vpi.stereodisp

vpi.stereodisp(left: vpi.Image, right: vpi.Image, *, backend: vpi.Backend = vpi.Backend.DEFAULT, out: vpi.Image = None, downscale: Optional[int] = 1, out_confmap: vpi.Image = None, window: int = 5, maxdisp: Optional[int] = None, confthreshold: int = 32767, quality: int = 6, conftype: vpi.ConfidenceType = vpi.ConfidenceType.ABSOLUTE, mindisp: int = 0, p1: int = 3, p2: int = 48, p2alpha: int = 0, uniqueness: float = - 1.0, includediagonals: bool = 1, numpasses: int = 3, stream: vpi.Stream = None) → vpi.Image

Runs stereo processing on two images.

Runs stereo processing on a pair of images and outputs a disparity map and (optionally) a confidence map.

See also

Refer to the algorithm explanation for more details and usage examples.

Parameters

  • left (vpi.Image) – Left stereo input image.

  • right (vpi.Image) – Right stereo input image.

  • out (vpi.Image, optional) – Image where the disparity values will be written to. Returned values are in Q10.5 format, i.e., signed fixed point with 5 fractional bits. Divide it by 32 to convert it to floating point.

  • downscale (int, optional) – Output’s downscale factor with respect to the input’s resolution.

  • out_confmap (vpi.Image, optional) – Image containing a confidence score telling how accurate the disparity is. Returned confidence range from 0 to 65535. The higher the confidence, more accurate is the corresponding disparity.

  • window (int, optional) – Represents the median filter size (on PVA+NVENC+VIC or OFA+PVA+VIC backend) or census transform window size (other backends) used in the algorithm.

  • maxdisp (int, optional) – Maximum disparity for matching search.

  • confthreshold (int, optional) – Confidence threshold above which disparity values are considered valid. Only used in CUDA, PVA+NVENC+VIC, and OFA+PVA+VIC backends. Expects value between 1 to 65280, values outside this range get clamped.

  • quality (int, optional) – Quality of disparity output. It’s only applicable when using PVA+NVENC+VIC backend. The higher the value, better the quality and possibly slower perf. Expects a value between 1 and 8.

  • conftype (vpi.ConfidenceType, optional) – Computation type to produce the confidence output.

  • mindisp (int, optional) – Minimum possible disparity value. It’s only applicable when using CUDA backend. Normally it is zero, but it may be adjusted depending on input images.

  • p1 (int, optional) – Penalty on disparity changes of +/- 1 between neighbor pixels. It is normally a small value, in (min, max) disparity range, used to penalize small changes in disparity, i.e. one. Using a lower P1 penalty allows for an adaptation to slanted or curver surfaces. It’s only applicable when using CUDA and OFA backends.

  • p2 (int, optional) – Penalty on disparity changes of more than 1 between neighbor pixels. It is normally a large value, in (min, max) disparity range, used to penalize large changes in disparity. Using a higher P2 penalty avoids abrupt disparity changes, i.e. discontinuities. It’s only applicable when using CUDA and OFA backends.

  • p2alpha (int, optional) – Alpha is used to enable adaptive large penalty (adaptive P2) feature. It’s used to better preserve object boundaries and thin objects. Higher alpha indicates lower adaptation of P2 in accordance to pixel intensities. It’s the alpha value in: P2’ = - (1 / alpha) * abs(I_cur - I_prev) + P2; where P2’ is the adaptive version of the given P2 penalty. The abs(I_cur - I_prev) is the absolute difference in intensity between the current and previous pixel location along the direction of path cost evaluation. The intuition behind this adaptation is that large disparity differences should be penalized less if they coincide with large intensity changes. The alpha value can be 0, 1, 2, 4 or 8. Using an alpha value of 0 disables the adaptive P2 feature. It’s only applicable when using OFA backend.

  • uniqueness (float, optional) – Uniqueness ratio, in [0, 1] range, is a margin by which best cost value should win over the second best. A value of 1 means less pixels are marked invalid, as the full cost is considered when comparing against the current best cost. Values less than 1 mean only a ratio of the cost is considered for the best cost. A value of 0 means more pixels are marked invalid, as only disparity changes of +/- 1 pixels are considered. Use it to improve certainty of computed disparity. Use value outside [0, 1], such as -1, to disregard the uniqueness computation. It’s only applicable when using CUDA backend.

  • includediagonals (bool, optional) – Include diagonals or oblique paths in semi-global matching (SGM) computation. Including diagonal paths makes the stereo disparity estimator slower, but increases the result quality. Including diagonal paths also increases memory usage in the CUDA backend. If False, means not to use diagonal paths, i.e. horizontal and vertical paths only. If True, means to use diagonal paths, i.e. horizontal, vertical and oblique paths. It’s only applicable when using CUDA and OFA backends.

  • numpasses (int, optional) – Number of passes in memory-efficient semi-global matching (eSGM) computation. A value of 1 or 2 means to do one forward or one forward and one backward passes per direction. A value of 3 means to do another forward pass after forward and backward passes. Setting number of passes to 3 makes the stereo disparity estimator slower, but increases the result quality. It’s only applicable when using OFA backends.

  • backend (vpi.Backend, optional) – The backend to be used by the algorithm.

  • stream (vpi.Stream, optional) – The stream to be used by the algorithm.

Returns

The disparity map output of the algorithm.

Return type

vpi.Image

Caution

Restrictions to several arguments may apply. Check the C API references of the submit function and the group concepts for more details.