Added StereoDense, StereoBM and StereoSGBM doc and tests

corelib/include/rtabmap/core/StereoDense.h

@@ -35,24 +35,97 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 namespace rtabmap {
 
+/**
+ * @class StereoDense
+ * @brief Abstract base class for dense stereo matching algorithms
+ * 
+ * This class provides the interface for dense stereo matching algorithms that
+ * compute disparity maps from stereo image pairs. It uses a factory pattern
+ * to create specific implementations (Block Matching or Semi-Global Block Matching).
+ * 
+ * The disparity map is a 16-bit signed integer image (CV_16SC1) where each pixel
+ * value represents the horizontal displacement between corresponding pixels in
+ * the left and right stereo images. Higher disparity values indicate closer objects.
+ * 
+ * @note Both input images must have the same size and be either grayscale (CV_8UC1)
+ *       or color (CV_8UC3). Color images are automatically converted to grayscale.
+ */
 class RTABMAP_CORE_EXPORT StereoDense {
 public:
+	/**
+	 * @enum Type
+	 * @brief Enumeration of available stereo matching algorithm types
+	 */
 	enum Type {
-		kTypeBM = 0,
-		kTypeSGBM = 1
+		kTypeBM = 0,    ///< Block Matching algorithm (faster, less accurate)
+		kTypeSGBM = 1  ///< Semi-Global Block Matching algorithm (slower, more accurate)
 	};
+	
+	/**
+	 * @brief Factory method to create a StereoDense instance from parameters
+	 * 
+	 * Creates a StereoDense instance based on the stereo dense strategy parameter
+	 * in the provided parameters map. The strategy is determined by the
+	 * Parameters::kStereoDenseStrategy() parameter.
+	 * 
+	 * @param parameters Parameters map containing configuration values
+	 * @return Pointer to the created StereoDense instance (caller owns the memory)
+	 * @see create(Type, const ParametersMap&)
+	 */
 	static StereoDense * create(const ParametersMap & parameters);
+	
+	/**
+	 * @brief Factory method to create a StereoDense instance of a specific type
+	 * 
+	 * Creates a StereoDense instance of the specified type with the given parameters.
+	 * 
+	 * @param type The type of stereo matching algorithm to create
+	 * @param parameters Optional parameters map containing configuration values
+	 * @return Pointer to the created StereoDense instance (caller owns the memory)
+	 * @see create(const ParametersMap&)
+	 */
 	static StereoDense * create(StereoDense::Type type, const ParametersMap & parameters = ParametersMap());
 
 public:
+	/**
+	 * @brief Virtual destructor
+	 */
 	virtual ~StereoDense() {}
 
+	/**
+	 * @brief Parse parameters from a parameters map
+	 * 
+	 * Updates the algorithm's configuration based on the provided parameters map.
+	 * Derived classes should override this method to parse their specific parameters.
+	 * 
+	 * @param parameters Parameters map containing configuration values
+	 */
 	virtual void parseParameters(const ParametersMap & parameters) {}
+	
+	/**
+	 * @brief Compute disparity map from stereo image pair
+	 * 
+	 * Computes a disparity map from the given left and right stereo images.
+	 * The images must have the same size and be either grayscale (CV_8UC1) or
+	 * color (CV_8UC3). Color images are automatically converted to grayscale.
+	 * 
+	 * @param leftImage Left stereo image (CV_8UC1 or CV_8UC3)
+	 * @param rightImage Right stereo image (CV_8UC1 or CV_8UC3), must have same size as leftImage
+	 * @return Disparity map as a 16-bit signed integer image (CV_16SC1)
+	 * @note The disparity values are stored as fixed-point numbers with 4 fractional bits.
+	 *       To get the actual disparity, divide by 16.
+	 * @note Invalid disparities are typically represented by negative values or zero.
+	 */
 	virtual cv::Mat computeDisparity(
 			const cv::Mat & leftImage,
 			const cv::Mat & rightImage) const = 0;
 
 protected:
+	/**
+	 * @brief Protected constructor
+	 * 
+	 * @param parameters Optional parameters map for initialization
+	 */
 	StereoDense(const ParametersMap & parameters = ParametersMap()) {}
 };
 

corelib/include/rtabmap/core/stereo/StereoBM.h

@@ -34,28 +34,88 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 namespace rtabmap {
 
+/**
+ * @class StereoBM
+ * @brief Block Matching algorithm for dense stereo matching
+ * 
+ * This class implements the Block Matching (BM) algorithm for computing disparity
+ * maps from stereo image pairs.
+ * 
+ * @note This class wraps OpenCV's cv::StereoBM implementation.
+ * @see StereoSGBM for a more accurate but slower alternative
+ */
 class RTABMAP_CORE_EXPORT StereoBM : public StereoDense {
 public:
+	/**
+	 * @brief Constructor with explicit block size and number of disparities
+	 * 
+	 * @param blockSize Size of the block window for matching (must be odd, typically 5-21)
+	 * @param numDisparities Number of disparity levels to search (must be divisible by 16)
+	 */
 	StereoBM(int blockSize, int numDisparities);
+	
+	/**
+	 * @brief Constructor with parameters map
+	 * 
+	 * Creates a StereoBM instance and initializes it from the provided parameters map.
+	 * 
+	 * @param parameters Parameters map containing configuration values
+	 */
 	StereoBM(const ParametersMap & parameters = ParametersMap());
+	
+	/**
+	 * @brief Virtual destructor
+	 */
 	virtual ~StereoBM() {}
 
+	/**
+	 * @brief Parse parameters from a parameters map
+	 * 
+	 * Updates the algorithm's configuration based on the provided parameters map.
+	 * Supported parameters:
+	 * - Parameters::kStereoBMBlockSize()
+	 * - Parameters::kStereoBMMinDisparity()
+	 * - Parameters::kStereoBMNumDisparities()
+	 * - Parameters::kStereoBMPreFilterSize()
+	 * - Parameters::kStereoBMPreFilterCap()
+	 * - Parameters::kStereoBMUniquenessRatio()
+	 * - Parameters::kStereoBMTextureThreshold()
+	 * - Parameters::kStereoBMSpeckleWindowSize()
+	 * - Parameters::kStereoBMSpeckleRange()
+	 * - Parameters::kStereoBMDisp12MaxDiff()
+	 * 
+	 * @param parameters Parameters map containing configuration values
+	 */
 	virtual void parseParameters(const ParametersMap & parameters);
+	
+	/**
+	 * @brief Compute disparity map from stereo image pair
+	 * 
+	 * Computes a disparity map using the Block Matching algorithm. The images
+	 * must have the same size and be either grayscale (CV_8UC1) or color (CV_8UC3).
+	 * Color images are automatically converted to grayscale.
+	 * 
+	 * @param leftImage Left stereo image (CV_8UC1 or CV_8UC3)
+	 * @param rightImage Right stereo image (CV_8UC1 or CV_8UC3), must have same size as leftImage
+	 * @return Disparity map as a 16-bit signed integer image (CV_16SC1)
+	 * @note The disparity values are stored as fixed-point numbers with 4 fractional bits.
+	 *       To get the actual disparity, divide by 16.
+	 */
 	virtual cv::Mat computeDisparity(
 			const cv::Mat & leftImage,
 			const cv::Mat & rightImage) const;
 
 private:
-	int blockSize_;         //15
-	int minDisparity_;      //0
-	int numDisparities_;    //64
-	int preFilterSize_;     //9
-	int preFilterCap_;      //31
-	int uniquenessRatio_;   //15
-	int textureThreshold_;  //10
-	int speckleWindowSize_; //100
-	int speckleRange_;      //4
-	int disp12MaxDiff_;     //-1
+	int blockSize_;         ///< Size of the block window for matching (default: 15, must be odd)
+	int minDisparity_;      ///< Minimum disparity value to search (default: 0)
+	int numDisparities_;    ///< Number of disparity levels to search (default: 64, must be divisible by 16)
+	int preFilterSize_;     ///< Size of the prefiltering window (default: 9, must be odd)
+	int preFilterCap_;      ///< Prefiltering cap value (default: 31)
+	int uniquenessRatio_;   ///< Uniqueness ratio for matching (default: 15)
+	int textureThreshold_;  ///< Texture threshold for filtering (default: 10)
+	int speckleWindowSize_; ///< Maximum size of smooth disparity regions to consider as speckles (default: 100)
+	int speckleRange_;      ///< Maximum disparity variation within each connected component (default: 4)
+	int disp12MaxDiff_;     ///< Maximum allowed difference in left-right disparity check (default: -1, disabled)
 };
 
 } /* namespace rtabmap */

corelib/include/rtabmap/core/stereo/StereoSGBM.h

@@ -34,28 +34,86 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 namespace rtabmap {
 
+/**
+ * @class StereoSGBM
+ * @brief Semi-Global Block Matching algorithm for dense stereo matching
+ * 
+ * This class implements the Semi-Global Block Matching (SGBM) algorithm for
+ * computing disparity maps from stereo image pairs. 
+ * 
+ * SGBM generally produces more accurate results than Block Matching, especially
+ * in textureless regions and areas with repetitive patterns, but is computationally
+ * more expensive.
+ * 
+ * @note This class wraps OpenCV's cv::StereoSGBM implementation.
+ * @see StereoBM for a faster but less accurate alternative
+ */
 class RTABMAP_CORE_EXPORT StereoSGBM : public StereoDense {
 public:
+	/**
+	 * @brief Constructor with parameters map
+	 * 
+	 * Creates a StereoSGBM instance and initializes it from the provided parameters map.
+	 * 
+	 * @param parameters Parameters map containing configuration values
+	 */
 	StereoSGBM(const ParametersMap & parameters = ParametersMap());
+	
+	/**
+	 * @brief Virtual destructor
+	 */
 	virtual ~StereoSGBM() {}
 
+	/**
+	 * @brief Parse parameters from a parameters map
+	 * 
+	 * Updates the algorithm's configuration based on the provided parameters map.
+	 * Supported parameters:
+	 * - Parameters::kStereoSGBMBlockSize()
+	 * - Parameters::kStereoSGBMMinDisparity()
+	 * - Parameters::kStereoSGBMNumDisparities()
+	 * - Parameters::kStereoSGBMPreFilterCap()
+	 * - Parameters::kStereoSGBMUniquenessRatio()
+	 * - Parameters::kStereoSGBMSpeckleWindowSize()
+	 * - Parameters::kStereoSGBMSpeckleRange()
+	 * - Parameters::kStereoSGBMP1()
+	 * - Parameters::kStereoSGBMP2()
+	 * - Parameters::kStereoSGBMDisp12MaxDiff()
+	 * - Parameters::kStereoSGBMMode()
+	 * 
+	 * @param parameters Parameters map containing configuration values
+	 */
 	virtual void parseParameters(const ParametersMap & parameters);
+	
+	/**
+	 * @brief Compute disparity map from stereo image pair
+	 * 
+	 * Computes a disparity map using the Semi-Global Block Matching algorithm.
+	 * The images must have the same size and be either grayscale (CV_8UC1) or
+	 * color (CV_8UC3). Color images are automatically converted to grayscale.
+	 * 
+	 * @param leftImage Left stereo image (CV_8UC1 or CV_8UC3)
+	 * @param rightImage Right stereo image (CV_8UC1 or CV_8UC3), must have same size as leftImage
+	 * @return Disparity map as a 16-bit signed integer image (CV_16SC1)
+	 * @note The disparity values are stored as fixed-point numbers with 4 fractional bits.
+	 *       To get the actual disparity, divide by 16.
+	 */
 	virtual cv::Mat computeDisparity(
 			const cv::Mat & leftImage,
 			const cv::Mat & rightImage) const;
 
 private:
-	int blockSize_;         //15
-	int minDisparity_;      //0
-	int numDisparities_;    //64
-	int preFilterCap_;      //31
-	int uniquenessRatio_;   //15
-	int speckleWindowSize_; //100
-	int speckleRange_;      //4
-	int P1_;                //0
-	int P2_;                //0
-	int disp12MaxDiff_;     //0
-	int mode_;              //0=cv::StereoSGBM::MODE_SGBM;
+	int blockSize_;         ///< Size of the block window for matching (default: 15, must be odd)
+	int minDisparity_;      ///< Minimum disparity value to search (default: 0)
+	int numDisparities_;    ///< Number of disparity levels to search (default: 64, must be divisible by 16)
+	int preFilterCap_;      ///< Prefiltering cap value (default: 31)
+	int uniquenessRatio_;   ///< Uniqueness ratio for matching (default: 15)
+	int speckleWindowSize_; ///< Maximum size of smooth disparity regions to consider as speckles (default: 100)
+	int speckleRange_;      ///< Maximum disparity variation within each connected component (default: 4)
+	int P1_;                ///< Penalty parameter for disparity changes of 1 pixel (default: 0, typically 8*blockSize*blockSize)
+	int P2_;                ///< Penalty parameter for disparity changes of more than 1 pixel (default: 0, typically 32*blockSize*blockSize)
+	int disp12MaxDiff_;     ///< Maximum allowed difference in left-right disparity check (default: 0)
+	int mode_;              ///< Algorithm mode: 0=cv::StereoSGBM::MODE_SGBM, 1=cv::StereoSGBM::MODE_HH (default: 0)
 };
 
 } /* namespace rtabmap */