Merge pull request #63 from 23pointsNorth/ccalib_module

Added Custom Calibration Pattern Module.

modules/ccalib/CMakeLists.txt

+set(the_description "Custom Calibration Pattern")
+ocv_define_module(ccalib opencv_core opencv_imgproc opencv_calib3d opencv_features2d)

modules/ccalib/doc/customPattern.rst

+Custom Calibration Pattern
+==========================
+
+.. highlight:: cpp
+
+CustomPattern
+-------------
+A custom pattern class that can be used to calibrate a camera and to further track the translation and rotation of the pattern. Defaultly it uses an ``ORB`` feature detector and a ``BruteForce-Hamming(2)`` descriptor matcher to find the location of the pattern feature points that will subsequently be used for calibration.
+
+.. ocv:class:: CustomPattern : public Algorithm
+
+
+CustomPattern::CustomPattern
+----------------------------
+CustomPattern constructor.
+
+.. ocv:function:: CustomPattern()
+
+
+CustomPattern::create
+---------------------
+A method that initializes the class and generates the necessary detectors, extractors and matchers.
+
+.. ocv:function:: bool create(InputArray pattern, const Size2f boardSize, OutputArray output = noArray())
+
+    :param pattern: The image, which will be used as a pattern. If the desired pattern is part of a bigger image, you can crop it out using image(roi).
+
+    :param boardSize: The size of the pattern in physical dimensions. These will be used to scale the points when the calibration occurs.
+
+    :param output: A matrix that is the same as the input pattern image, but has all the feature points drawn on it.
+
+    :return Returns whether the initialization was successful or not. Possible reason for failure may be that no feature points were detected.
+
+.. seealso::
+
+    :ocv:func:`getFeatureDetector`,
+    :ocv:func:`getDescriptorExtractor`,
+    :ocv:func:`getDescriptorMatcher`
+
+.. note::
+
+   * Determine the number of detected feature points can be done through :ocv:func:`getPatternPoints` method.
+
+   * The feature detector, extractor and matcher cannot be changed after initialization.
+
+
+
+CustomPattern::findPattern
+--------------------------
+Finds the pattern in the input image
+
+.. ocv:function:: bool findPattern(InputArray image, OutputArray matched_features, OutputArray pattern_points, const double ratio = 0.7, const double proj_error = 8.0, const bool refine_position = false, OutputArray out = noArray(), OutputArray H = noArray(), OutputArray pattern_corners = noArray());
+
+    :param image: The input image where the pattern is searched for.
+
+    :param matched_features: A ``vector<Point2f>`` of the projections of calibration pattern points, matched in the image. The points correspond to the ``pattern_points``.``matched_features`` and ``pattern_points`` have the same size.
+
+    :param pattern_points: A ``vector<Point3f>`` of calibration pattern points in the calibration pattern coordinate space.
+
+    :param ratio: A ratio used to threshold matches based on D. Lowe's point ratio test.
+
+    :param proj_error: The maximum projection error that is allowed when the found points are back projected. A lower projection error will be beneficial for eliminating mismatches. Higher values are recommended when the camera lens has greater distortions.
+
+    :param refine_position: Whether to refine the position of the feature points with :ocv:func:`cornerSubPix`.
+
+    :param out: An image showing the matched feature points and a contour around the estimated pattern.
+
+    :param H: The homography transformation matrix between the pattern and the current image.
+
+    :param pattern_corners: A ``vector<Point2f>`` containing the 4 corners of the found pattern.
+
+    :return The method return whether the pattern was found or not.
+
+
+CustomPattern::isInitialized
+----------------------------
+
+.. ocv:function:: bool isInitialized()
+
+    :return If the class is initialized or not.
+
+
+CustomPattern::getPatternPoints
+-------------------------------
+
+.. ocv:function:: void getPatternPoints(OutputArray original_points)
+
+    :param original_points: Fills the vector with the points found in the pattern.
+
+
+CustomPattern::getPixelSize
+---------------------------
+.. ocv:function:: double getPixelSize()
+
+    :return Get the physical pixel size as initialized by the pattern.
+
+
+CustomPattern::setFeatureDetector
+---------------------------------
+ .. ocv:function:: bool setFeatureDetector(Ptr<FeatureDetector> featureDetector)
+
+    :param featureDetector: Set a new FeatureDetector.
+
+    :return Is it successfully set? Will fail if the object is already initialized by :ocv:func:`create`.
+
+.. note::
+
+    * It is left to user discretion to select matching feature detector, extractor and matchers. Please consult the documentation for each to confirm coherence.
+
+
+CustomPattern::setDescriptorExtractor
+-------------------------------------
+.. ocv:function:: bool setDescriptorExtractor(Ptr<DescriptorExtractor> extractor)
+
+    :param extractor: Set a new DescriptorExtractor.
+
+    :return Is it successfully set? Will fail if the object is already initialized by :ocv:func:`create`.
+
+
+CustomPattern::setDescriptorMatcher
+-----------------------------------
+.. ocv:function:: bool setDescriptorMatcher(Ptr<DescriptorMatcher> matcher)
+
+    :param matcher: Set a new DescriptorMatcher.
+
+    :return Is it successfully set? Will fail if the object is already initialized by :ocv:func:`create`.
+
+
+CustomPattern::getFeatureDetector
+---------------------------------
+.. ocv:function:: Ptr<FeatureDetector> getFeatureDetector()
+
+    :return The used FeatureDetector.
+
+
+CustomPattern::getDescriptorExtractor
+-------------------------------------
+.. ocv:function:: Ptr<DescriptorExtractor> getDescriptorExtractor()
+
+    :return The used DescriptorExtractor.
+
+
+CustomPattern::getDescriptorMatcher
+-----------------------------------
+.. ocv:function:: Ptr<DescriptorMatcher> getDescriptorMatcher()
+
+    :return The used DescriptorMatcher.
+
+
+CustomPattern::calibrate
+------------------------
+Calibrates the camera.
+
+.. ocv:function:: double calibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags = 0, TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 30, DBL_EPSILON))
+
+    See :ocv:func:`calibrateCamera` for parameter information.
+
+
+CustomPattern::findRt
+---------------------
+Finds the rotation and translation vectors of the pattern.
+
+.. ocv:function:: bool findRt(InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int flags = ITERATIVE)
+.. ocv:function:: bool findRt(InputArray image, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int flags = ITERATIVE)
+
+    :param image: The image, in which the rotation and translation of the pattern will be found.
+
+    See :ocv:func:`solvePnP` for parameter information.
+
+
+CustomPattern::findRtRANSAC
+---------------------------
+Finds the rotation and translation vectors of the pattern using RANSAC.
+
+.. ocv:function:: bool findRtRANSAC(InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int iterationsCount = 100, float reprojectionError = 8.0, int minInliersCount = 100, OutputArray inliers = noArray(), int flags = ITERATIVE)
+.. ocv:function:: bool findRtRANSAC(InputArray image, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int iterationsCount = 100, float reprojectionError = 8.0, int minInliersCount = 100, OutputArray inliers = noArray(), int flags = ITERATIVE)
+
+    :param image: The image, in which the rotation and translation of the pattern will be found.
+
+    See :ocv:func:`solvePnPRANSAC` for parameter information.
+
+
+CustomPattern::drawOrientation
+------------------------------
+Draws the ``(x,y,z)`` axis on the image, in the center of the pattern, showing the orientation of the pattern.
+
+.. ocv:function:: void drawOrientation(InputOutputArray image, InputArray tvec, InputArray rvec, InputArray cameraMatrix, InputArray distCoeffs, double axis_length = 3, int axis_width = 2)
+
+    :param image: The image, based on which the rotation and translation was calculated. The axis will be drawn in color - ``x`` - in red, ``y`` - in green, ``z`` - in blue.
+
+    :param tvec: Translation vector.
+
+    :param rvec: Rotation vector.
+
+    :param cameraMatrix: The camera matrix.
+
+    :param distCoeffs: The distortion coefficients.
+
+    :param axis_length: The length of the axis symbol.
+
+    :param axis_width: The width of the axis symbol.
+

modules/ccalib/include/opencv2/ccalib.hpp

+/*M///////////////////////////////////////////////////////////////////////////////////////
+ //
+ //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+ //
+ //  By downloading, copying, installing or using the software you agree to this license.
+ //  If you do not agree to this license, do not download, install,
+ //  copy or use the software.
+ //
+ //
+ //                           License Agreement
+ //                For Open Source Computer Vision Library
+ //
+ // Copyright (C) 2014, OpenCV Foundation, all rights reserved.
+ // Third party copyrights are property of their respective owners.
+ //
+ // Redistribution and use in source and binary forms, with or without modification,
+ // are permitted provided that the following conditions are met:
+ //
+ //   * Redistribution's of source code must retain the above copyright notice,
+ //     this list of conditions and the following disclaimer.
+ //
+ //   * Redistribution's in binary form must reproduce the above copyright notice,
+ //     this list of conditions and the following disclaimer in the documentation
+ //     and/or other materials provided with the distribution.
+ //
+ //   * The name of the copyright holders may not be used to endorse or promote products
+ //     derived from this software without specific prior written permission.
+ //
+ // This software is provided by the copyright holders and contributors "as is" and
+ // any express or implied warranties, including, but not limited to, the implied
+ // warranties of merchantability and fitness for a particular purpose are disclaimed.
+ // In no event shall the Intel Corporation or contributors be liable for any direct,
+ // indirect, incidental, special, exemplary, or consequential damages
+ // (including, but not limited to, procurement of substitute goods or services;
+ // loss of use, data, or profits; or business interruption) however caused
+ // and on any theory of liability, whether in contract, strict liability,
+ // or tort (including negligence or otherwise) arising in any way out of
+ // the use of this software, even if advised of the possibility of such damage.
+ //
+ //M*/
+
+#ifndef __OPENCV_CCALIB_HPP__
+#define __OPENCV_CCALIB_HPP__
+
+#include <opencv2/core.hpp>
+#include <opencv2/features2d.hpp>
+#include <opencv2/imgproc.hpp>
+#include <opencv2/calib3d.hpp>
+
+#include <vector>
+
+namespace cv{ namespace ccalib{
+
+class CV_EXPORTS CustomPattern : public Algorithm
+{
+public:
+	CustomPattern();
+	virtual ~CustomPattern();
+
+	bool create(InputArray pattern, const Size2f boardSize, OutputArray output = noArray());
+
+	bool findPattern(InputArray image, OutputArray matched_features, OutputArray pattern_points, const double ratio = 0.7,
+					 const double proj_error = 8.0, const bool refine_position = false, OutputArray out = noArray(),
+					 OutputArray H = noArray(), OutputArray pattern_corners = noArray());
+
+	bool isInitialized();
+
+	void getPatternPoints(OutputArray original_points);
+	/*
+		Returns a vector<Point> of the original points.
+	*/
+	double getPixelSize();
+	/*
+		Get the pixel size of the pattern
+	*/
+
+	bool setFeatureDetector(Ptr<FeatureDetector> featureDetector);
+	bool setDescriptorExtractor(Ptr<DescriptorExtractor> extractor);
+	bool setDescriptorMatcher(Ptr<DescriptorMatcher> matcher);
+
+	Ptr<FeatureDetector> getFeatureDetector();
+	Ptr<DescriptorExtractor> getDescriptorExtractor();
+	Ptr<DescriptorMatcher> getDescriptorMatcher();
+
+	double calibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints,
+				Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs,
+				OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags = 0,
+				TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 30, DBL_EPSILON));
+	/*
+		Calls the calirateCamera function with the same inputs.
+	*/
+
+	bool findRt(InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs,
+                OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int flags = SOLVEPNP_ITERATIVE);
+	bool findRt(InputArray image, InputArray cameraMatrix, InputArray distCoeffs,
+                OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int flags = SOLVEPNP_ITERATIVE);
+	/*
+		Uses solvePnP to find the rotation and translation of the pattern
+		with respect to the camera frame.
+	*/
+
+	bool findRtRANSAC(InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs,
+				OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int iterationsCount = 100,
+				float reprojectionError = 8.0, int minInliersCount = 100, OutputArray inliers = noArray(), int flags = SOLVEPNP_ITERATIVE);
+	bool findRtRANSAC(InputArray image, InputArray cameraMatrix, InputArray distCoeffs,
+				OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess = false, int iterationsCount = 100,
+				float reprojectionError = 8.0, int minInliersCount = 100, OutputArray inliers = noArray(), int flags = SOLVEPNP_ITERATIVE);
+        /*
+		Uses solvePnPRansac()
+	*/
+
+	void drawOrientation(InputOutputArray image, InputArray tvec, InputArray rvec, InputArray cameraMatrix,
+						 InputArray distCoeffs, double axis_length = 3, int axis_width = 2);
+	/*
+		pattern_corners -> projected over the image position of the edges of the pattern.
+	*/
+
+private:
+
+	Mat img_roi;
+	std::vector<Point2f> obj_corners;
+	double pxSize;
+
+	bool initialized;
+
+	Ptr<FeatureDetector> detector;
+	Ptr<DescriptorExtractor> descriptorExtractor;
+	Ptr<DescriptorMatcher> descriptorMatcher;
+
+	std::vector<KeyPoint> keypoints;
+	std::vector<Point3f> points3d;
+	Mat descriptor;
+
+	bool init(Mat& image, const float pixel_size, OutputArray output = noArray());
+	bool findPatternPass(const Mat& image, std::vector<Point2f>& matched_features, std::vector<Point3f>& pattern_points,
+						 Mat& H, std::vector<Point2f>& scene_corners, const double pratio, const double proj_error,
+						 const bool refine_position = false, const Mat& mask = Mat(), OutputArray output = noArray());
+	void scaleFoundPoints(const double squareSize, const std::vector<KeyPoint>& corners, std::vector<Point3f>& pts3d);
+	void check_matches(std::vector<Point2f>& matched, const std::vector<Point2f>& pattern, std::vector<DMatch>& good, std::vector<Point3f>& pattern_3d, const Mat& H);
+
+	void keypoints2points(const std::vector<KeyPoint>& in, std::vector<Point2f>& out);
+	void updateKeypointsPos(std::vector<KeyPoint>& in, const std::vector<Point2f>& new_pos);
+	void refinePointsPos(const Mat& img, std::vector<Point2f>& p);
+	void refineKeypointsPos(const Mat& img, std::vector<KeyPoint>& kp);
+};
+
+}} // namespace ccalib, cv
+
+#endif

modules/ccalib/src/precomp.hpp

+/*M///////////////////////////////////////////////////////////////////////////////////////
+ //
+ //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+ //
+ //  By downloading, copying, installing or using the software you agree to this license.
+ //  If you do not agree to this license, do not download, install,
+ //  copy or use the software.
+ //
+ //
+ //                           License Agreement
+ //                For Open Source Computer Vision Library
+ //
+ // Copyright (C) 2014, OpenCV Foundation, all rights reserved.
+ // Third party copyrights are property of their respective owners.
+ //
+ // Redistribution and use in source and binary forms, with or without modification,
+ // are permitted provided that the following conditions are met:
+ //
+ //   * Redistribution's of source code must retain the above copyright notice,
+ //     this list of conditions and the following disclaimer.
+ //
+ //   * Redistribution's in binary form must reproduce the above copyright notice,
+ //     this list of conditions and the following disclaimer in the documentation
+ //     and/or other materials provided with the distribution.
+ //
+ //   * The name of the copyright holders may not be used to endorse or promote products
+ //     derived from this software without specific prior written permission.
+ //
+ // This software is provided by the copyright holders and contributors "as is" and
+ // any express or implied warranties, including, but not limited to, the implied
+ // warranties of merchantability and fitness for a particular purpose are disclaimed.
+ // In no event shall the Intel Corporation or contributors be liable for any direct,
+ // indirect, incidental, special, exemplary, or consequential damages
+ // (including, but not limited to, procurement of substitute goods or services;
+ // loss of use, data, or profits; or business interruption) however caused
+ // and on any theory of liability, whether in contract, strict liability,
+ // or tort (including negligence or otherwise) arising in any way out of
+ // the use of this software, even if advised of the possibility of such damage.
+ //
+ //M*/
+
+#ifndef __OPENCV_CCALIB_PRECOMP__
+#define __OPENCV_CCALIB_PRECOMP__
+
+#include <opencv2/core.hpp>
+#include <opencv2/calib3d.hpp>
+#include <opencv2/features2d.hpp>
+
+#include <vector>
+
+#endif