Struct opencv::calib3d::StereoSGBM

pub struct StereoSGBM { /* private fields */ }

The class implements the modified H. Hirschmuller algorithm HH08 that differs from the original one as follows:

• By default, the algorithm is single-pass, which means that you consider only 5 directions instead of 8. Set mode=StereoSGBM::MODE_HH in createStereoSGBM to run the full variant of the algorithm but beware that it may consume a lot of memory.
• The algorithm matches blocks, not individual pixels. Though, setting blockSize=1 reduces the blocks to single pixels.
• Mutual information cost function is not implemented. Instead, a simpler Birchfield-Tomasi sub-pixel metric from BT98 is used. Though, the color images are supported as well.
• Some pre- and post- processing steps from K. Konolige algorithm StereoBM are included, for example: pre-filtering (StereoBM::PREFILTER_XSOBEL type) and post-filtering (uniqueness check, quadratic interpolation and speckle filtering).

Note:

• (Python) An example illustrating the use of the StereoSGBM matching algorithm can be found at opencv_source_code/samples/python/stereo_match.py

Implementations

impl StereoSGBM

pub fn create( min_disparity: i32, num_disparities: i32, block_size: i32, p1: i32, p2: i32, disp12_max_diff: i32, pre_filter_cap: i32, uniqueness_ratio: i32, speckle_window_size: i32, speckle_range: i32, mode: i32 ) -> Result<Ptr<StereoSGBM>>

Creates StereoSGBM object

Parameters

• minDisparity: Minimum possible disparity value. Normally, it is zero but sometimes rectification algorithms can shift images, so this parameter needs to be adjusted accordingly.
• numDisparities: Maximum disparity minus minimum disparity. The value is always greater than zero. In the current implementation, this parameter must be divisible by 16.
• blockSize: Matched block size. It must be an odd number >=1 . Normally, it should be somewhere in the 3..11 range.
• P1: The first parameter controlling the disparity smoothness. See below.
• P2: The second parameter controlling the disparity smoothness. The larger the values are, the smoother the disparity is. P1 is the penalty on the disparity change by plus or minus 1 between neighbor pixels. P2 is the penalty on the disparity change by more than 1 between neighbor pixels. The algorithm requires P2 > P1 . See stereo_match.cpp sample where some reasonably good P1 and P2 values are shown (like 8*number_of_image_channels*blockSize*blockSize and 32*number_of_image_channels*blockSize*blockSize , respectively).
• disp12MaxDiff: Maximum allowed difference (in integer pixel units) in the left-right disparity check. Set it to a non-positive value to disable the check.
• preFilterCap: Truncation value for the prefiltered image pixels. The algorithm first computes x-derivative at each pixel and clips its value by [-preFilterCap, preFilterCap] interval. The result values are passed to the Birchfield-Tomasi pixel cost function.
• uniquenessRatio: Margin in percentage by which the best (minimum) computed cost function value should “win” the second best value to consider the found match correct. Normally, a value within the 5-15 range is good enough.
• speckleWindowSize: Maximum size of smooth disparity regions to consider their noise speckles and invalidate. Set it to 0 to disable speckle filtering. Otherwise, set it somewhere in the 50-200 range.
• speckleRange: Maximum disparity variation within each connected component. If you do speckle filtering, set the parameter to a positive value, it will be implicitly multiplied by 16. Normally, 1 or 2 is good enough.
• mode: Set it to StereoSGBM::MODE_HH to run the full-scale two-pass dynamic programming algorithm. It will consume O(W*H*numDisparities) bytes, which is large for 640x480 stereo and huge for HD-size pictures. By default, it is set to false .

The first constructor initializes StereoSGBM with all the default parameters. So, you only have to set StereoSGBM::numDisparities at minimum. The second constructor enables you to set each parameter to a custom value.

C++ default parameters

• min_disparity: 0
• num_disparities: 16
• block_size: 3
• p1: 0
• p2: 0
• disp12_max_diff: 0
• pre_filter_cap: 0
• uniqueness_ratio: 0
• speckle_window_size: 0
• speckle_range: 0
• mode: StereoSGBM::MODE_SGBM

pub fn create_def() -> Result<Ptr<StereoSGBM>>

Creates StereoSGBM object

Parameters

• minDisparity: Minimum possible disparity value. Normally, it is zero but sometimes rectification algorithms can shift images, so this parameter needs to be adjusted accordingly.
• numDisparities: Maximum disparity minus minimum disparity. The value is always greater than zero. In the current implementation, this parameter must be divisible by 16.
• blockSize: Matched block size. It must be an odd number >=1 . Normally, it should be somewhere in the 3..11 range.
• P1: The first parameter controlling the disparity smoothness. See below.
• P2: The second parameter controlling the disparity smoothness. The larger the values are, the smoother the disparity is. P1 is the penalty on the disparity change by plus or minus 1 between neighbor pixels. P2 is the penalty on the disparity change by more than 1 between neighbor pixels. The algorithm requires P2 > P1 . See stereo_match.cpp sample where some reasonably good P1 and P2 values are shown (like 8*number_of_image_channels*blockSize*blockSize and 32*number_of_image_channels*blockSize*blockSize , respectively).
• disp12MaxDiff: Maximum allowed difference (in integer pixel units) in the left-right disparity check. Set it to a non-positive value to disable the check.
• preFilterCap: Truncation value for the prefiltered image pixels. The algorithm first computes x-derivative at each pixel and clips its value by [-preFilterCap, preFilterCap] interval. The result values are passed to the Birchfield-Tomasi pixel cost function.
• uniquenessRatio: Margin in percentage by which the best (minimum) computed cost function value should “win” the second best value to consider the found match correct. Normally, a value within the 5-15 range is good enough.
• speckleWindowSize: Maximum size of smooth disparity regions to consider their noise speckles and invalidate. Set it to 0 to disable speckle filtering. Otherwise, set it somewhere in the 50-200 range.
• speckleRange: Maximum disparity variation within each connected component. If you do speckle filtering, set the parameter to a positive value, it will be implicitly multiplied by 16. Normally, 1 or 2 is good enough.
• mode: Set it to StereoSGBM::MODE_HH to run the full-scale two-pass dynamic programming algorithm. It will consume O(W*H*numDisparities) bytes, which is large for 640x480 stereo and huge for HD-size pictures. By default, it is set to false .

The first constructor initializes StereoSGBM with all the default parameters. So, you only have to set StereoSGBM::numDisparities at minimum. The second constructor enables you to set each parameter to a custom value.

Note

This alternative version of StereoSGBM::create function uses the following default values for its arguments:

• min_disparity: 0
• num_disparities: 16
• block_size: 3
• p1: 0
• p2: 0
• disp12_max_diff: 0
• pre_filter_cap: 0
• uniqueness_ratio: 0
• speckle_window_size: 0
• speckle_range: 0
• mode: StereoSGBM::MODE_SGBM

Trait Implementations

impl AlgorithmTrait for StereoSGBM

fn as_raw_mut_Algorithm(&mut self) -> *mut c_void

fn clear(&mut self) -> Result<()>

Clears the algorithm state

fn read(&mut self, fn_: &impl FileNodeTraitConst) -> Result<()>

Reads algorithm parameters from a file storage

impl AlgorithmTraitConst for StereoSGBM

fn as_raw_Algorithm(&self) -> *const c_void

fn write(&self, fs: &mut impl FileStorageTrait) -> Result<()>

Stores algorithm parameters in a file storage

fn write_1(&self, fs: &mut impl FileStorageTrait, name: &str) -> Result<()>

Stores algorithm parameters in a file storage

fn write_with_name(&self, fs: &Ptr<FileStorage>, name: &str) -> Result<()>

@deprecated

fn write_with_name_def(&self, fs: &Ptr<FileStorage>) -> Result<()>

👎Deprecated:

Note

Deprecated: ## Note This alternative version of AlgorithmTraitConst::write_with_name function uses the following default values for its arguments:

fn empty(&self) -> Result<bool>

Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read

fn save(&self, filename: &str) -> Result<()>

Saves the algorithm to a file. In order to make this method work, the derived class must implement Algorithm::write(FileStorage& fs).

fn get_default_name(&self) -> Result<String>

Returns the algorithm string identifier. This string is used as top level xml/yml node tag when the object is saved to a file or string.

impl Boxed for StereoSGBM

unsafe fn from_raw(ptr: <StereoSGBM as OpenCVFromExtern>::ExternReceive) -> Self

Wrap the specified raw pointer

fn into_raw(self) -> <StereoSGBM as OpenCVTypeExternContainer>::ExternSendMut

Return the underlying raw pointer while consuming this wrapper.

fn as_raw(&self) -> <StereoSGBM as OpenCVTypeExternContainer>::ExternSend

Return the underlying raw pointer.

fn as_raw_mut( &mut self ) -> <StereoSGBM as OpenCVTypeExternContainer>::ExternSendMut

Return the underlying mutable raw pointer

impl Debug for StereoSGBM

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for StereoSGBM

fn drop(&mut self)

Executes the destructor for this type.

impl From<CUDA_StereoSGM> for StereoSGBM

fn from(s: CUDA_StereoSGM) -> Self

Converts to this type from the input type.

impl From<StereoSGBM> for Algorithm

fn from(s: StereoSGBM) -> Self

Converts to this type from the input type.

impl From<StereoSGBM> for StereoMatcher

fn from(s: StereoSGBM) -> Self

Converts to this type from the input type.

impl StereoMatcherTrait for StereoSGBM

fn as_raw_mut_StereoMatcher(&mut self) -> *mut c_void

fn compute( &mut self, left: &impl ToInputArray, right: &impl ToInputArray, disparity: &mut impl ToOutputArray ) -> Result<()>

Computes disparity map for the specified stereo pair

fn set_min_disparity(&mut self, min_disparity: i32) -> Result<()>

fn set_num_disparities(&mut self, num_disparities: i32) -> Result<()>

fn set_block_size(&mut self, block_size: i32) -> Result<()>

fn set_speckle_window_size(&mut self, speckle_window_size: i32) -> Result<()>

fn set_speckle_range(&mut self, speckle_range: i32) -> Result<()>

fn set_disp12_max_diff(&mut self, disp12_max_diff: i32) -> Result<()>

impl StereoMatcherTraitConst for StereoSGBM

fn as_raw_StereoMatcher(&self) -> *const c_void

fn get_min_disparity(&self) -> Result<i32>

fn get_num_disparities(&self) -> Result<i32>

fn get_block_size(&self) -> Result<i32>

fn get_speckle_window_size(&self) -> Result<i32>

fn get_speckle_range(&self) -> Result<i32>

fn get_disp12_max_diff(&self) -> Result<i32>

impl StereoSGBMTrait for StereoSGBM

fn as_raw_mut_StereoSGBM(&mut self) -> *mut c_void

fn set_pre_filter_cap(&mut self, pre_filter_cap: i32) -> Result<()>

fn set_uniqueness_ratio(&mut self, uniqueness_ratio: i32) -> Result<()>

fn set_p1(&mut self, p1: i32) -> Result<()>

fn set_p2(&mut self, p2: i32) -> Result<()>

fn set_mode(&mut self, mode: i32) -> Result<()>

impl StereoSGBMTraitConst for StereoSGBM

fn as_raw_StereoSGBM(&self) -> *const c_void

fn get_pre_filter_cap(&self) -> Result<i32>

fn get_uniqueness_ratio(&self) -> Result<i32>

fn get_p1(&self) -> Result<i32>

fn get_p2(&self) -> Result<i32>

fn get_mode(&self) -> Result<i32>

impl TryFrom<StereoMatcher> for StereoSGBM

type Error = Error

The type returned in the event of a conversion error.

fn try_from(s: StereoMatcher) -> Result<Self>

Performs the conversion.

impl Send for StereoSGBM