class cv::StereoSGBM

Overview

The class implements the modified H. Hirschmuller algorithm [39] that differs from the original one as follows: More…

#include <calib3d.hpp>

class StereoSGBM: public cv::StereoMatcher
{
public:
    // enums

    enum
    {
        MODE_SGBM      = 0,
        MODE_HH        = 1,
        MODE_SGBM_3WAY = 2,
        MODE_HH4       = 3,
    };

    // methods

    virtual
    int
    getMode() const = 0;

    virtual
    int
    getP1() const = 0;

    virtual
    int
    getP2() const = 0;

    virtual
    int
    getPreFilterCap() const = 0;

    virtual
    int
    getUniquenessRatio() const = 0;

    virtual
    void
    setMode(int mode) = 0;

    virtual
    void
    setP1(int P1) = 0;

    virtual
    void
    setP2(int P2) = 0;

    virtual
    void
    setPreFilterCap(int preFilterCap) = 0;

    virtual
    void
    setUniquenessRatio(int uniquenessRatio) = 0;

    static
    Ptr<StereoSGBM>
    create(
        int minDisparity = 0,
        int numDisparities = 16,
        int blockSize = 3,
        int P1 = 0,
        int P2 = 0,
        int disp12MaxDiff = 0,
        int preFilterCap = 0,
        int uniquenessRatio = 0,
        int speckleWindowSize = 0,
        int speckleRange = 0,
        int mode = StereoSGBM::MODE_SGBM
        );
};

Inherited Members

public:
    // enums

    enum
    {
        DISP_SHIFT = 4,
        DISP_SCALE = (1 <<DISP_SHIFT),
    };

    // methods

    virtual
    void
    clear();

    virtual
    bool
    empty() const;

    virtual
    String
    getDefaultName() const;

    virtual
    void
    read(const FileNode& fn);

    virtual
    void
    save(const String& filename) const;

    virtual
    void
    write(FileStorage& fs) const;

    template <typename _Tp>
    static
    Ptr<_Tp>
    load(
        const String& filename,
        const String& objname = String()
        );

    template <typename _Tp>
    static
    Ptr<_Tp>
    loadFromString(
        const String& strModel,
        const String& objname = String()
        );

    template <typename _Tp>
    static
    Ptr<_Tp>
    read(const FileNode& fn);

    virtual
    void
    compute(
        InputArray left,
        InputArray right,
        OutputArray disparity
        ) = 0;

    virtual
    int
    getBlockSize() const = 0;

    virtual
    int
    getDisp12MaxDiff() const = 0;

    virtual
    int
    getMinDisparity() const = 0;

    virtual
    int
    getNumDisparities() const = 0;

    virtual
    int
    getSpeckleRange() const = 0;

    virtual
    int
    getSpeckleWindowSize() const = 0;

    virtual
    void
    setBlockSize(int blockSize) = 0;

    virtual
    void
    setDisp12MaxDiff(int disp12MaxDiff) = 0;

    virtual
    void
    setMinDisparity(int minDisparity) = 0;

    virtual
    void
    setNumDisparities(int numDisparities) = 0;

    virtual
    void
    setSpeckleRange(int speckleRange) = 0;

    virtual
    void
    setSpeckleWindowSize(int speckleWindowSize) = 0;

protected:
    // methods

    void
    writeFormat(FileStorage& fs) const;

Detailed Documentation

The class implements the modified H. Hirschmuller algorithm [39] 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 [4] 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).
• (Python) An example illustrating the use of the StereoSGBM matching algorithm can be found at opencv_source_code/samples/python/stereo_match.py

Methods

static
Ptr<StereoSGBM>
create(
    int minDisparity = 0,
    int numDisparities = 16,
    int blockSize = 3,
    int P1 = 0,
    int P2 = 0,
    int disp12MaxDiff = 0,
    int preFilterCap = 0,
    int uniquenessRatio = 0,
    int speckleWindowSize = 0,
    int speckleRange = 0,
    int mode = StereoSGBM::MODE_SGBM
    )

Creates StereoSGBM object.

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.

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*SADWindowSize*SADWindowSize and 32*number_of_image_channels*SADWindowSize*SADWindowSize , 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 .