From 64535757dff0a54dd4a2ffa7b0d00982e0f5cf69 Mon Sep 17 00:00:00 2001 From: Aditya Jha Date: Sun, 23 Mar 2025 13:18:17 +0530 Subject: [PATCH] Add documentation for StereoBM parameters (fixes #26816) --- modules/calib3d/include/opencv2/calib3d.hpp | 119 +++++++++++++++++--- 1 file changed, 102 insertions(+), 17 deletions(-) diff --git a/modules/calib3d/include/opencv2/calib3d.hpp b/modules/calib3d/include/opencv2/calib3d.hpp index 6e3ed8c3b5..31961a369a 100644 --- a/modules/calib3d/include/opencv2/calib3d.hpp +++ b/modules/calib3d/include/opencv2/calib3d.hpp @@ -3346,52 +3346,137 @@ public: }; -/** @brief Class for computing stereo correspondence using the block matching algorithm, introduced and -contributed to OpenCV by K. Konolige. +/** + * @class StereoBM + * @brief Class for computing stereo correspondence using the block matching algorithm, introduced and contributed to OpenCV by K. Konolige. + * @details This class implements a block matching algorithm for stereo correspondence, which is used to compute disparity maps from stereo image pairs. It provides methods to fine-tune parameters such as pre-filtering, texture thresholds, uniqueness ratios, and regions of interest (ROIs) to optimize performance and accuracy. */ class CV_EXPORTS_W StereoBM : public StereoMatcher { public: - enum { PREFILTER_NORMALIZED_RESPONSE = 0, - PREFILTER_XSOBEL = 1 - }; + /** + * @brief Pre-filter types for the stereo matching algorithm. + * @details These constants define the type of pre-filtering applied to the images before computing the disparity map. + * - PREFILTER_NORMALIZED_RESPONSE: Uses normalized response for pre-filtering. + * - PREFILTER_XSOBEL: Uses the X-Sobel operator for pre-filtering. + */ + enum { + PREFILTER_NORMALIZED_RESPONSE = 0, ///< Normalized response pre-filter + PREFILTER_XSOBEL = 1 ///< X-Sobel pre-filter + }; + /** + * @brief Gets the type of pre-filtering currently used in the algorithm. + * @return The current pre-filter type: 0 for PREFILTER_NORMALIZED_RESPONSE or 1 for PREFILTER_XSOBEL. + */ CV_WRAP virtual int getPreFilterType() const = 0; + + /** + * @brief Sets the type of pre-filtering used in the algorithm. + * @param preFilterType The type of pre-filter to use. Possible values are: + * - PREFILTER_NORMALIZED_RESPONSE (0): Uses normalized response for pre-filtering. + * - PREFILTER_XSOBEL (1): Uses the X-Sobel operator for pre-filtering. + * @details The pre-filter type affects how the images are prepared before computing the disparity map. Different pre-filtering methods can enhance specific image features or reduce noise, influencing the quality of the disparity map. + */ CV_WRAP virtual void setPreFilterType(int preFilterType) = 0; + /** + * @brief Gets the current size of the pre-filter kernel. + * @return The current pre-filter size. + */ CV_WRAP virtual int getPreFilterSize() const = 0; + + /** + * @brief Sets the size of the pre-filter kernel. + * @param preFilterSize The size of the pre-filter kernel. Must be an odd integer, typically between 5 and 255. + * @details The pre-filter size determines the spatial extent of the pre-filtering operation, which prepares the images for disparity computation by normalizing brightness and enhancing texture. Larger sizes reduce noise but may blur details, while smaller sizes preserve details but are more susceptible to noise. + */ CV_WRAP virtual void setPreFilterSize(int preFilterSize) = 0; + /** + * @brief Gets the current truncation value for prefiltered pixels. + * @return The current pre-filter cap value. + */ CV_WRAP virtual int getPreFilterCap() const = 0; + + /** + * @brief Sets the truncation value for prefiltered pixels. + * @param preFilterCap The truncation value. Typically in the range [1, 63]. + * @details This value caps the output of the pre-filter to [-preFilterCap, preFilterCap], helping to reduce the impact of noise and outliers in the pre-filtered image. + */ CV_WRAP virtual void setPreFilterCap(int preFilterCap) = 0; + /** + * @brief Gets the current texture threshold value. + * @return The current texture threshold. + */ CV_WRAP virtual int getTextureThreshold() const = 0; + + /** + * @brief Sets the threshold for filtering low-texture regions. + * @param textureThreshold The threshold value. Must be non-negative. + * @details This parameter filters out regions with low texture, where establishing correspondences is difficult, thus reducing noise in the disparity map. Higher values filter more aggressively but may discard valid information. + */ CV_WRAP virtual void setTextureThreshold(int textureThreshold) = 0; + /** + * @brief Gets the current uniqueness ratio value. + * @return The current uniqueness ratio. + */ CV_WRAP virtual int getUniquenessRatio() const = 0; + + /** + * @brief Sets the uniqueness ratio for filtering ambiguous matches. + * @param uniquenessRatio The uniqueness ratio value. Typically in the range [5, 15], but can be from 0 to 100. + * @details This parameter ensures that the best match is sufficiently better than the next best match, reducing false positives. Higher values are stricter but may filter out valid matches in difficult regions. + */ CV_WRAP virtual void setUniquenessRatio(int uniquenessRatio) = 0; + /** + * @brief Gets the current size of the smaller block used for texture check. + * @return The current smaller block size. + */ CV_WRAP virtual int getSmallerBlockSize() const = 0; + + /** + * @brief Sets the size of the smaller block used for texture check. + * @param blockSize The size of the smaller block. Must be an odd integer between 5 and 255. + * @details This parameter determines the size of the block used to compute texture variance. Smaller blocks capture finer details but are more sensitive to noise, while larger blocks are more robust but may miss fine details. + */ CV_WRAP virtual void setSmallerBlockSize(int blockSize) = 0; + /** + * @brief Gets the current Region of Interest (ROI) for the left image. + * @return The current ROI for the left image. + */ CV_WRAP virtual Rect getROI1() const = 0; + + /** + * @brief Sets the Region of Interest (ROI) for the left image. + * @param roi1 The ROI rectangle for the left image. + * @details By setting the ROI, the stereo matching computation is limited to the specified region, improving performance and potentially accuracy by focusing on relevant parts of the image. + */ CV_WRAP virtual void setROI1(Rect roi1) = 0; + /** + * @brief Gets the current Region of Interest (ROI) for the right image. + * @return The current ROI for the right image. + */ CV_WRAP virtual Rect getROI2() const = 0; + + /** + * @brief Sets the Region of Interest (ROI) for the right image. + * @param roi2 The ROI rectangle for the right image. + * @details Similar to setROI1, this limits the computation to the specified region in the right image. + */ CV_WRAP virtual void setROI2(Rect roi2) = 0; - /** @brief Creates StereoBM object - - @param numDisparities the disparity search range. For each pixel algorithm will find the best - disparity from 0 (default minimum disparity) to numDisparities. The search range can then be - shifted by changing the minimum disparity. - @param blockSize the linear size of the blocks compared by the algorithm. The size should be odd - (as the block is centered at the current pixel). Larger block size implies smoother, though less - accurate disparity map. Smaller block size gives more detailed disparity map, but there is higher - chance for algorithm to find a wrong correspondence. - - The function create StereoBM object. You can then call StereoBM::compute() to compute disparity for - a specific stereo pair. + /** + * @brief Creates StereoBM object + * @param numDisparities The disparity search range. For each pixel, the algorithm will find the best disparity from 0 (default minimum disparity) to numDisparities. The search range can be shifted by changing the minimum disparity. + * @param blockSize The linear size of the blocks compared by the algorithm. The size should be odd (as the block is centered at the current pixel). Larger block size implies smoother, though less accurate disparity map. Smaller block size gives more detailed disparity map, but there is a higher chance for the algorithm to find a wrong correspondence. + * @return A pointer to the created StereoBM object. + * @details The function creates a StereoBM object. You can then call StereoBM::compute() to compute disparity for a specific stereo pair. */ CV_WRAP static Ptr create(int numDisparities = 0, int blockSize = 21); };