From 69b670bdaa29f5a86957bf5f47d1104916e9b431 Mon Sep 17 00:00:00 2001 From: Alexey Spizhevoy Date: Thu, 19 Jan 2012 09:43:13 +0000 Subject: [PATCH] Updated the stitching module docs --- modules/stitching/doc/autocalib.rst | 33 ++++++ modules/stitching/doc/blenders.rst | 86 ++++++++++++++ .../stitching/doc/exposure_compensation.rst | 84 ++++++++++++++ modules/stitching/doc/references.rst | 14 +++ modules/stitching/doc/seam_estimation.rst | 108 ++++++++++++++++++ modules/stitching/doc/stitching.rst | 8 +- modules/stitching/doc/warpers.rst | 94 +++++++++++++++ .../opencv2/stitching/detail/warpers.hpp | 1 - 8 files changed, 426 insertions(+), 2 deletions(-) create mode 100644 modules/stitching/doc/autocalib.rst create mode 100644 modules/stitching/doc/blenders.rst create mode 100644 modules/stitching/doc/exposure_compensation.rst create mode 100644 modules/stitching/doc/references.rst create mode 100644 modules/stitching/doc/seam_estimation.rst create mode 100644 modules/stitching/doc/warpers.rst diff --git a/modules/stitching/doc/autocalib.rst b/modules/stitching/doc/autocalib.rst new file mode 100644 index 0000000000..b918323720 --- /dev/null +++ b/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 &features, const std::vector &pairwise_matches, std::vector &focals) + + :param features: Features of images. + + :param pairwise_matches: Matches between all images pairs. + + :param focals: Estimated focal lengths for each camera. + diff --git a/modules/stitching/doc/blenders.rst b/modules/stitching/doc/blenders.rst new file mode 100644 index 0000000000..e7da934ccd --- /dev/null +++ b/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 createDefault(int type, bool try_gpu = false); + + void prepare(const std::vector &corners, const std::vector &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 &masks, const std::vector &corners, + std::vector &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 dst_pyr_laplace_; + std::vector dst_band_weights_; + Rect dst_roi_final_; + bool can_use_gpu_; + }; + +.. seealso:: :ocv:class:`detail::Blender` diff --git a/modules/stitching/doc/exposure_compensation.rst b/modules/stitching/doc/exposure_compensation.rst new file mode 100644 index 0000000000..b4fb4b7a12 --- /dev/null +++ b/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 createDefault(int type); + + void feed(const std::vector &corners, const std::vector &images, + const std::vector &masks); + virtual void feed(const std::vector &corners, const std::vector &images, + const std::vector > &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 &/*corners*/, const std::vector &/*images*/, + const std::vector > &/*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 &corners, const std::vector &images, + const std::vector > &masks); + void apply(int index, Point corner, Mat &image, const Mat &mask); + std::vector gains() const; + + private: + Mat_ 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 &corners, const std::vector &images, + const std::vector > &masks); + void apply(int index, Point corner, Mat &image, const Mat &mask); + + private: + int bl_width_, bl_height_; + std::vector > gain_maps_; + }; + +.. seealso:: :ocv:class:`detail::ExposureCompensation` + diff --git a/modules/stitching/doc/references.rst b/modules/stitching/doc/references.rst new file mode 100644 index 0000000000..33b9828223 --- /dev/null +++ b/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. diff --git a/modules/stitching/doc/seam_estimation.rst b/modules/stitching/doc/seam_estimation.rst new file mode 100644 index 0000000000..3beeafe2ef --- /dev/null +++ b/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 &src, const std::vector &corners, + std::vector &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&, const std::vector&, std::vector&) {} + }; + +.. 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 &src, const std::vector &corners, + std::vector &masks); + + protected: + void run(); + virtual void findInPair(size_t first, size_t second, Rect roi) = 0; + + std::vector images_; + std::vector sizes_; + std::vector corners_; + std::vector 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, const std::vector &corners, + std::vector &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 &src, const std::vector &corners, + std::vector &masks); + + private: + /* hidden */ + }; + +.. seealso:: + :ocv:class:`detail::GraphCutSeamFinderBase`, + :ocv:class:`detail::SeamFinder` diff --git a/modules/stitching/doc/stitching.rst b/modules/stitching/doc/stitching.rst index 0c91a8e9cd..2f7de2949e 100644 --- a/modules/stitching/doc/stitching.rst +++ b/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 diff --git a/modules/stitching/doc/warpers.rst b/modules/stitching/doc/warpers.rst new file mode 100644 index 0000000000..401e0f529c --- /dev/null +++ b/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 + { + 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 + { + 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 + { + public: + CylindricalWarper(float scale) { projector_.scale = scale; } + + protected: + void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br) + { + RotationWarperBase::detectResultRoiByBorder(src_size, dst_tl, dst_br); + } + }; + +.. seealso:: :ocv:class:`detail::RotationWarper` + diff --git a/modules/stitching/include/opencv2/stitching/detail/warpers.hpp b/modules/stitching/include/opencv2/stitching/detail/warpers.hpp index 9c64f5dd58..abb99fb67e 100644 --- a/modules/stitching/include/opencv2/stitching/detail/warpers.hpp +++ b/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 { public: