Updated the stitching module docs

modules/stitching/doc/autocalib.rst

@@ -0,0 +1,33 @@
+Autocalibration
+===============
+
+.. highlight:: cpp
+
+detail::focalsFromHomography
+----------------------------
+Tries to estimate focal lengths from the given homography under the assumption that the camera undergoes rotations around its centre only.
+
+.. ocv:function:: void focalsFromHomography(const Mat &H, double &f0, double &f1, bool &f0_ok, bool &f1_ok)
+
+    :param H: Homography.
+
+    :param f0: Estimated focal length along X axis.
+
+    :param f1: Estimated focal length along Y axis. 
+
+    :param f0_ok: True, if f0 was estimated successfully, false otherwise.
+
+    :param f1_ok: True, if f1 was estimated successfully, false otherwise.
+
+detail::estimateFocal
+---------------------
+Estimates focal lengths for each given camera.
+
+.. ocv:function:: void estimateFocal(const std::vector<ImageFeatures> &features, const std::vector<MatchesInfo> &pairwise_matches, std::vector<double> &focals)
+
+    :param features: Features of images.
+
+    :param pairwise_matches: Matches between all images pairs.
+
+    :param focals: Estimated focal lengths for each camera.
+

modules/stitching/doc/blenders.rst

@@ -0,0 +1,86 @@
+Image Blenders
+==============
+
+.. highlight:: cpp
+
+detail::Blender
+---------------
+.. ocv:class:: detail::Blender
+
+Base class for all blenders. ::
+   
+    class CV_EXPORTS Blender
+    {
+    public:
+        virtual ~Blender() {}
+
+        enum { NO, FEATHER, MULTI_BAND };
+        static Ptr<Blender> createDefault(int type, bool try_gpu = false);
+
+        void prepare(const std::vector<Point> &corners, const std::vector<Size> &sizes);    
+        virtual void prepare(Rect dst_roi);
+        virtual void feed(const Mat &img, const Mat &mask, Point tl);
+        virtual void blend(Mat &dst, Mat &dst_mask);
+
+    protected:
+        Mat dst_, dst_mask_;
+        Rect dst_roi_;
+    };
+
+detail::FeatherBlender
+----------------------
+.. ocv:class:: detail::FeatherBlender
+
+Simple blender which mixes images at its borders. ::
+
+    class CV_EXPORTS FeatherBlender : public Blender
+    {
+    public:
+        FeatherBlender(float sharpness = 0.02f) { setSharpness(sharpness); }
+
+        float sharpness() const { return sharpness_; }
+        void setSharpness(float val) { sharpness_ = val; }
+
+        void prepare(Rect dst_roi);
+        void feed(const Mat &img, const Mat &mask, Point tl);
+        void blend(Mat &dst, Mat &dst_mask);
+
+        // Creates weight maps for fixed set of source images by their masks and top-left corners.
+        // Final image can be obtained by simple weighting of the source images.
+        Rect createWeightMaps(const std::vector<Mat> &masks, const std::vector<Point> &corners,
+                              std::vector<Mat> &weight_maps);
+
+    private:
+        float sharpness_;
+        Mat weight_map_;
+        Mat dst_weight_map_;
+    };
+
+.. seealso:: :ocv:class:`detail::Blender`
+
+detail::MultiBandBlender
+------------------------
+.. ocv:class:: detail::MultiBandBlender
+
+Blender which uses multi-band blending algorithm (see [BA83]_). ::
+
+    class CV_EXPORTS MultiBandBlender : public Blender
+    {
+    public:
+        MultiBandBlender(int try_gpu = false, int num_bands = 5);
+        int numBands() const { return actual_num_bands_; }
+        void setNumBands(int val) { actual_num_bands_ = val; }
+
+        void prepare(Rect dst_roi);
+        void feed(const Mat &img, const Mat &mask, Point tl);
+        void blend(Mat &dst, Mat &dst_mask);
+
+    private:
+        int actual_num_bands_, num_bands_;
+        std::vector<Mat> dst_pyr_laplace_;
+        std::vector<Mat> dst_band_weights_;
+        Rect dst_roi_final_;
+        bool can_use_gpu_;
+    };
+
+.. seealso:: :ocv:class:`detail::Blender`

modules/stitching/doc/exposure_compensation.rst

@@ -0,0 +1,84 @@
+Exposure Compensation
+=====================
+
+.. highlight:: cpp
+
+detail::ExposureCompensation
+----------------------------
+.. ocv:class:: detail::ExposureCompensation
+
+Base class for all exposure compensators. ::
+
+    class CV_EXPORTS ExposureCompensator
+    {
+    public:
+        virtual ~ExposureCompensator() {}
+
+        enum { NO, GAIN, GAIN_BLOCKS };
+        static Ptr<ExposureCompensator> createDefault(int type);
+
+        void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
+                  const std::vector<Mat> &masks);
+        virtual void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
+                          const std::vector<std::pair<Mat,uchar> > &masks) = 0;
+        virtual void apply(int index, Point corner, Mat &image, const Mat &mask) = 0;
+    };
+
+detail::NoExposureCompensator
+-----------------------------
+.. ocv:class:: detail::NoExposureCompensator
+
+Stub exposure compensator which does nothing. ::
+
+    class CV_EXPORTS NoExposureCompensator : public ExposureCompensator
+    {
+    public:
+        void feed(const std::vector<Point> &/*corners*/, const std::vector<Mat> &/*images*/,
+                  const std::vector<std::pair<Mat,uchar> > &/*masks*/) {};
+        void apply(int /*index*/, Point /*corner*/, Mat &/*image*/, const Mat &/*mask*/) {};
+    };
+
+.. seealso:: :ocv:class:`detail::ExposureCompensation`
+
+detail::GainCompensator
+-----------------------
+.. ocv:class:: detail::GainCompensator
+
+Exposure compensator which tries to remove exposure related artifacts by adjusting image intensities. ::
+
+    class CV_EXPORTS GainCompensator : public ExposureCompensator
+    {
+    public:
+        void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
+                  const std::vector<std::pair<Mat,uchar> > &masks);
+        void apply(int index, Point corner, Mat &image, const Mat &mask);
+        std::vector<double> gains() const;
+
+    private:
+        Mat_<double> gains_;
+    };
+
+.. seealso:: :ocv:class:`detail::ExposureCompensation`
+
+detail::BlocksGainCompensator
+-----------------------------
+.. ocv:class:: detail::BlocksGainCompensator
+
+Exposure compensator which tries to remove exposure related artifacts by adjusting image block intensities. ::
+
+    class CV_EXPORTS BlocksGainCompensator : public ExposureCompensator
+    {
+    public:
+        BlocksGainCompensator(int bl_width = 32, int bl_height = 32) 
+                : bl_width_(bl_width), bl_height_(bl_height) {}
+        void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
+                  const std::vector<std::pair<Mat,uchar> > &masks);
+        void apply(int index, Point corner, Mat &image, const Mat &mask);
+
+    private:
+        int bl_width_, bl_height_;
+        std::vector<Mat_<float> > gain_maps_;
+    };
+
+.. seealso:: :ocv:class:`detail::ExposureCompensation`
+

modules/stitching/doc/references.rst

@@ -0,0 +1,14 @@
+References
+==========
+
+.. [BL07] M. Brown and D. Lowe. Automatic Panoramic Image Stitching using Invariant Features. International Journal of Computer Vision, 74(1), pages 59-73, 2007.
+
+.. [RS10] Richard Szeliski. Computer Vision: Algorithms and Applications. Springer, New York, 2010.
+
+.. [RS04] Richard Szeliski. Image alignment and stitching: A tutorial. Technical Report MSR-TR-2004-92, Microsoft Research, December 2004.
+
+.. [SS00] Heung-Yeung Shum and Richard Szeliski. Construction of panoramic mosaics with global and local alignment. International Journal of Computer Vision, 36(2):101-130, February 2000. Erratum published July 2002, 48(2):151-152.
+
+.. [V03] Vivek Kwatra, Arno Schödl, Irfan Essa, Greg Turk and Aaron Bobick. Graphcut Textures: Image and Video Synthesis Using Graph Cuts. To appear in Proc. ACM Transactions on Graphics, SIGGRAPH 2003.
+
+.. [BA83] Burt, P., and Adelson, E. H., A Multiresolution Spline with Application to Image Mosaics. ACM Transactions on Graphics, 2(4):217-236, 1983.

modules/stitching/doc/seam_estimation.rst

@@ -0,0 +1,108 @@
+Seam Estimation
+===============
+
+.. highlight:: cpp
+
+detail::SeamFinder
+------------------
+.. ocv:class:: detail::SeamFinder
+
+Base class for seam estimators. ::
+
+    class CV_EXPORTS SeamFinder
+    {
+    public:
+        virtual ~SeamFinder() {}
+        virtual void find(const std::vector<Mat> &src, const std::vector<Point> &corners,
+                          std::vector<Mat> &masks) = 0;
+    };
+
+detail::NoSeamFinder
+--------------------
+.. ocv:class:: detail::NoSeamFinder
+
+Stub seam estimator which does nothing. ::
+
+    class CV_EXPORTS NoSeamFinder : public SeamFinder
+    {
+    public:
+        void find(const std::vector<Mat>&, const std::vector<Point>&, std::vector<Mat>&) {}
+    };
+
+.. seealso:: :ocv:class:`detail::SeamFinder`
+
+detail::PairwiseSeamFinder
+--------------------------
+.. ocv:class:: detail::PairwiseSeamFinder
+
+Base class for all pairwise seam estimators. ::
+
+    class CV_EXPORTS PairwiseSeamFinder : public SeamFinder
+    {
+    public:
+        virtual void find(const std::vector<Mat> &src, const std::vector<Point> &corners,
+                          std::vector<Mat> &masks);
+
+    protected:
+        void run();
+        virtual void findInPair(size_t first, size_t second, Rect roi) = 0;
+
+        std::vector<Mat> images_;
+        std::vector<Size> sizes_;
+        std::vector<Point> corners_;
+        std::vector<Mat> masks_;
+    };
+
+.. seealso:: :ocv:class:`detail::SeamFinder`
+
+detail::VoronoiSeamFinder
+-------------------------
+.. ocv:class:: detail::VoronoiSeamFinder
+
+Voronoi diagram-based seam estimator. ::
+
+    class CV_EXPORTS VoronoiSeamFinder : public PairwiseSeamFinder
+    {
+    public:
+        virtual void find(const std::vector<Size> &size, const std::vector<Point> &corners,
+                          std::vector<Mat> &masks);
+    private:
+        void findInPair(size_t first, size_t second, Rect roi);
+    };
+
+.. seealso:: :ocv:class:`detail::PairwiseSeamFinder`
+
+detail::GraphCutSeamFinderBase
+------------------------------
+.. ocv:class:: detail::GraphCutSeamFinderBase
+
+Base class for all minimum graph cut-based seam estimators. ::
+
+    class CV_EXPORTS GraphCutSeamFinderBase
+    {
+    public:
+        enum { COST_COLOR, COST_COLOR_GRAD };
+    };
+
+detail::GraphCutSeamFinder
+--------------------------
+.. ocv:class:: detail::GraphCutSeamFinder
+
+Minimum graph cut-based seam estimator. ::
+
+    class CV_EXPORTS GraphCutSeamFinder : public GraphCutSeamFinderBase, public SeamFinder
+    {
+    public:
+        GraphCutSeamFinder(int cost_type = COST_COLOR_GRAD, float terminal_cost = 10000.f,
+                           float bad_region_penalty = 1000.f);
+
+        void find(const std::vector<Mat> &src, const std::vector<Point> &corners,
+                  std::vector<Mat> &masks);
+
+    private:
+        /* hidden */
+    };
+
+.. seealso:: 
+    :ocv:class:`detail::GraphCutSeamFinderBase`,
+    :ocv:class:`detail::SeamFinder`

modules/stitching/doc/stitching.rst

@@ -4,9 +4,15 @@ stitching. Images stitching
 
 .. toctree::
     :maxdepth: 2
-
+    
     high_level
     matching
     motion_estimation
+    autocalib
+    warpers
+    seam_estimation
+    exposure_compensation
+    blenders
+    references
 
 

modules/stitching/doc/warpers.rst

@@ -0,0 +1,94 @@
+Images Warping
+==============
+
+.. highlight:: cpp
+
+detail::RotationWarper
+----------------------
+.. ocv:class:: detail::RotationWarper
+
+Rotation-only model image warpers interface. ::
+
+    class CV_EXPORTS RotationWarper
+    {
+    public:
+        virtual ~RotationWarper() {}
+
+        virtual Point2f warpPoint(const Point2f &pt, const Mat &K, const Mat &R) = 0;
+
+        virtual Rect buildMaps(Size src_size, const Mat &K, const Mat &R, Mat &xmap, Mat &ymap) = 0;
+
+        virtual Point warp(const Mat &src, const Mat &K, const Mat &R, int interp_mode, int border_mode,
+                           Mat &dst) = 0;
+       
+        virtual void warpBackward(const Mat &src, const Mat &K, const Mat &R, int interp_mode, int border_mode,
+                                  Size dst_size, Mat &dst) = 0;
+
+        virtual Rect warpRoi(Size src_size, const Mat &K, const Mat &R) = 0;
+    };
+
+detail::PlaneWarper
+-------------------
+.. ocv:class:: detail::PlaneWarper
+
+Warper that maps an image onto the z = 1 plane. ::
+
+    class CV_EXPORTS PlaneWarper : public RotationWarperBase<PlaneProjector>
+    {
+    public:
+        PlaneWarper(float scale = 1.f) { projector_.scale = scale; }
+
+        void setScale(float scale) { projector_.scale = scale; }
+
+        Point2f warpPoint(const Point2f &pt, const Mat &K, const Mat &R, const Mat &T);
+
+        Rect buildMaps(Size src_size, const Mat &K, const Mat &R, const Mat &T, Mat &xmap, Mat &ymap);
+
+        Point warp(const Mat &src, const Mat &K, const Mat &R, const Mat &T, int interp_mode, int border_mode,
+                   Mat &dst);
+
+        Rect warpRoi(Size src_size, const Mat &K, const Mat &R, const Mat &T);
+
+    protected:
+        void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
+    };
+
+.. seealso:: :ocv:class:`detail::RotationWarper`
+
+detail::SphericalWarper
+-----------------------
+.. ocv:class:: detail::SphericalWarper
+
+Warper that maps an image onto the unit sphere located at the origin. ::
+
+    class CV_EXPORTS SphericalWarper : public RotationWarperBase<SphericalProjector>
+    {
+    public:
+        SphericalWarper(float scale) { projector_.scale = scale; }
+
+    protected:
+        void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
+    };
+
+.. seealso:: :ocv:class:`detail::RotationWarper`
+   
+detail::CylindricalWarper
+-------------------------
+.. ocv:class:: detail::CylindricalWarper
+
+Warper that maps an image onto the x*x + z*z = 1 cylinder. ::
+    
+    class CV_EXPORTS CylindricalWarper : public RotationWarperBase<CylindricalProjector>
+    {
+    public:
+        CylindricalWarper(float scale) { projector_.scale = scale; }
+
+    protected:
+        void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br)
+        { 
+            RotationWarperBase<CylindricalProjector>::detectResultRoiByBorder(src_size, dst_tl, dst_br); 
+        }
+    };
+
+.. seealso:: :ocv:class:`detail::RotationWarper`
+

modules/stitching/include/opencv2/stitching/detail/warpers.hpp

@@ -123,7 +123,6 @@ struct CV_EXPORTS PlaneProjector : ProjectorBase
 };
 
 
-// Projects image onto z = plane_dist plane
 class CV_EXPORTS PlaneWarper : public RotationWarperBase<PlaneProjector>
 {
 public: