stitching.hpp

00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                          License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Third party copyrights are property of their respective owners.
00016 //
00017 // Redistribution and use in source and binary forms, with or without modification,
00018 // are permitted provided that the following conditions are met:
00019 //
00020 //   * Redistribution's of source code must retain the above copyright notice,
00021 //     this list of conditions and the following disclaimer.
00022 //
00023 //   * Redistribution's in binary form must reproduce the above copyright notice,
00024 //     this list of conditions and the following disclaimer in the documentation
00025 //     and/or other materials provided with the distribution.
00026 //
00027 //   * The name of the copyright holders may not be used to endorse or promote products
00028 //     derived from this software without specific prior written permission.
00029 //
00030 // This software is provided by the copyright holders and contributors "as is" and
00031 // any express or implied warranties, including, but not limited to, the implied
00032 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00033 // In no event shall the Intel Corporation or contributors be liable for any direct,
00034 // indirect, incidental, special, exemplary, or consequential damages
00035 // (including, but not limited to, procurement of substitute goods or services;
00036 // loss of use, data, or profits; or business interruption) however caused
00037 // and on any theory of liability, whether in contract, strict liability,
00038 // or tort (including negligence or otherwise) arising in any way out of
00039 // the use of this software, even if advised of the possibility of such damage.
00040 //
00041 //M*/
00042 
00043 #ifndef __OPENCV_STITCHING_STITCHER_HPP__
00044 #define __OPENCV_STITCHING_STITCHER_HPP__
00045 
00046 #include "opencv2/core.hpp"
00047 #include "opencv2/features2d.hpp"
00048 #include "opencv2/stitching/warpers.hpp"
00049 #include "opencv2/stitching/detail/matchers.hpp"
00050 #include "opencv2/stitching/detail/motion_estimators.hpp"
00051 #include "opencv2/stitching/detail/exposure_compensate.hpp"
00052 #include "opencv2/stitching/detail/seam_finders.hpp"
00053 #include "opencv2/stitching/detail/blenders.hpp"
00054 #include "opencv2/stitching/detail/camera.hpp"
00055 
00056 /**
00057 @defgroup stitching Images stitching
00058 
00059 This figure illustrates the stitching module pipeline implemented in the Stitcher class. Using that
00060 class it's possible to configure/remove some steps, i.e. adjust the stitching pipeline according to
00061 the particular needs. All building blocks from the pipeline are available in the detail namespace,
00062 one can combine and use them separately.
00063 
00064 The implemented stitching pipeline is very similar to the one proposed in @cite BL07 .
00065 
00066 ![image](StitchingPipeline.jpg)
00067 
00068 @{
00069     @defgroup stitching_match Features Finding and Images Matching
00070     @defgroup stitching_rotation Rotation Estimation
00071     @defgroup stitching_autocalib Autocalibration
00072     @defgroup stitching_warp Images Warping
00073     @defgroup stitching_seam Seam Estimation
00074     @defgroup stitching_exposure Exposure Compensation
00075     @defgroup stitching_blend Image Blenders
00076 @}
00077   */
00078 
00079 namespace cv {
00080 
00081 //! @addtogroup stitching
00082 //! @{
00083 
00084 /** @brief High level image stitcher.
00085 
00086 It's possible to use this class without being aware of the entire stitching pipeline. However, to
00087 be able to achieve higher stitching stability and quality of the final images at least being
00088 familiar with the theory is recommended.
00089 
00090 @note
00091    -   A basic example on image stitching can be found at
00092         opencv_source_code/samples/cpp/stitching.cpp
00093     -   A detailed example on image stitching can be found at
00094         opencv_source_code/samples/cpp/stitching_detailed.cpp
00095  */
00096 class CV_EXPORTS_W Stitcher
00097 {
00098 public:
00099     enum { ORIG_RESOL = -1 };
00100     enum Status
00101     {
00102         OK = 0,
00103         ERR_NEED_MORE_IMGS = 1,
00104         ERR_HOMOGRAPHY_EST_FAIL = 2,
00105         ERR_CAMERA_PARAMS_ADJUST_FAIL = 3
00106     };
00107 
00108    // Stitcher() {}
00109     /** @brief Creates a stitcher with the default parameters.
00110 
00111     @param try_use_gpu Flag indicating whether GPU should be used whenever it's possible.
00112     @return Stitcher class instance.
00113      */
00114     static Stitcher createDefault(bool try_use_gpu = false);
00115 
00116     CV_WRAP double registrationResol() const { return registr_resol_; }
00117     CV_WRAP void setRegistrationResol(double resol_mpx) { registr_resol_ = resol_mpx; }
00118 
00119     CV_WRAP double seamEstimationResol() const { return seam_est_resol_; }
00120     CV_WRAP void setSeamEstimationResol(double resol_mpx) { seam_est_resol_ = resol_mpx; }
00121 
00122     CV_WRAP double compositingResol() const { return compose_resol_; }
00123     CV_WRAP void setCompositingResol(double resol_mpx) { compose_resol_ = resol_mpx; }
00124 
00125     CV_WRAP double panoConfidenceThresh() const { return conf_thresh_; }
00126     CV_WRAP void setPanoConfidenceThresh(double conf_thresh) { conf_thresh_ = conf_thresh; }
00127 
00128     CV_WRAP bool waveCorrection() const { return do_wave_correct_; }
00129     CV_WRAP void setWaveCorrection(bool flag) { do_wave_correct_ = flag; }
00130 
00131     detail::WaveCorrectKind waveCorrectKind() const { return wave_correct_kind_; }
00132     void setWaveCorrectKind(detail::WaveCorrectKind kind) { wave_correct_kind_ = kind; }
00133 
00134     Ptr<detail::FeaturesFinder>  featuresFinder() { return features_finder_; }
00135     const Ptr<detail::FeaturesFinder>  featuresFinder() const { return features_finder_; }
00136     void setFeaturesFinder(Ptr<detail::FeaturesFinder>  features_finder)
00137         { features_finder_ = features_finder; }
00138 
00139     Ptr<detail::FeaturesMatcher>  featuresMatcher() { return features_matcher_; }
00140     const Ptr<detail::FeaturesMatcher>  featuresMatcher() const { return features_matcher_; }
00141     void setFeaturesMatcher(Ptr<detail::FeaturesMatcher>  features_matcher)
00142         { features_matcher_ = features_matcher; }
00143 
00144     const cv::UMat & matchingMask() const { return matching_mask_; }
00145     void setMatchingMask(const cv::UMat  &mask)
00146     {
00147         CV_Assert(mask.type() == CV_8U && mask.cols == mask.rows);
00148         matching_mask_ = mask.clone();
00149     }
00150 
00151     Ptr<detail::BundleAdjusterBase>  bundleAdjuster() { return bundle_adjuster_; }
00152     const Ptr<detail::BundleAdjusterBase>  bundleAdjuster() const { return bundle_adjuster_; }
00153     void setBundleAdjuster(Ptr<detail::BundleAdjusterBase>  bundle_adjuster)
00154         { bundle_adjuster_ = bundle_adjuster; }
00155 
00156     Ptr<WarperCreator>  warper() { return warper_; }
00157     const Ptr<WarperCreator>  warper() const { return warper_; }
00158     void setWarper(Ptr<WarperCreator>  creator) { warper_ = creator; }
00159 
00160     Ptr<detail::ExposureCompensator>  exposureCompensator() { return exposure_comp_; }
00161     const Ptr<detail::ExposureCompensator>  exposureCompensator() const { return exposure_comp_; }
00162     void setExposureCompensator(Ptr<detail::ExposureCompensator>  exposure_comp)
00163         { exposure_comp_ = exposure_comp; }
00164 
00165     Ptr<detail::SeamFinder>  seamFinder() { return seam_finder_; }
00166     const Ptr<detail::SeamFinder>  seamFinder() const { return seam_finder_; }
00167     void setSeamFinder(Ptr<detail::SeamFinder>  seam_finder) { seam_finder_ = seam_finder; }
00168 
00169     Ptr<detail::Blender>  blender() { return blender_; }
00170     const Ptr<detail::Blender>  blender() const { return blender_; }
00171     void setBlender(Ptr<detail::Blender>  b) { blender_ = b; }
00172 
00173     /** @overload */
00174     CV_WRAP Status estimateTransform(InputArrayOfArrays images);
00175     /** @brief These functions try to match the given images and to estimate rotations of each camera.
00176 
00177     @note Use the functions only if you're aware of the stitching pipeline, otherwise use
00178     Stitcher::stitch.
00179 
00180     @param images Input images.
00181     @param rois Region of interest rectangles.
00182     @return Status code.
00183      */
00184     Status estimateTransform(InputArrayOfArrays images, const std::vector<std::vector<Rect> > &rois);
00185 
00186     /** @overload */
00187     CV_WRAP Status composePanorama(OutputArray pano);
00188     /** @brief These functions try to compose the given images (or images stored internally from the other function
00189     calls) into the final pano under the assumption that the image transformations were estimated
00190     before.
00191 
00192     @note Use the functions only if you're aware of the stitching pipeline, otherwise use
00193     Stitcher::stitch.
00194 
00195     @param images Input images.
00196     @param pano Final pano.
00197     @return Status code.
00198      */
00199     Status composePanorama(InputArrayOfArrays images, OutputArray pano);
00200 
00201     /** @overload */
00202     CV_WRAP Status stitch(InputArrayOfArrays images, OutputArray pano);
00203     /** @brief These functions try to stitch the given images.
00204 
00205     @param images Input images.
00206     @param rois Region of interest rectangles.
00207     @param pano Final pano.
00208     @return Status code.
00209      */
00210     Status stitch(InputArrayOfArrays images, const std::vector<std::vector<Rect> > &rois, OutputArray pano);
00211 
00212     std::vector<int> component() const { return indices_; }
00213     std::vector<detail::CameraParams> cameras() const { return cameras_; }
00214     CV_WRAP double workScale() const { return work_scale_; }
00215 
00216 private:
00217     //Stitcher() {}
00218 
00219     Status matchImages();
00220     Status estimateCameraParams();
00221 
00222     double registr_resol_;
00223     double seam_est_resol_;
00224     double compose_resol_;
00225     double conf_thresh_;
00226     Ptr<detail::FeaturesFinder>  features_finder_;
00227     Ptr<detail::FeaturesMatcher>  features_matcher_;
00228     cv::UMat  matching_mask_;
00229     Ptr<detail::BundleAdjusterBase>  bundle_adjuster_;
00230     bool do_wave_correct_;
00231     detail::WaveCorrectKind wave_correct_kind_;
00232     Ptr<WarperCreator>  warper_;
00233     Ptr<detail::ExposureCompensator>  exposure_comp_;
00234     Ptr<detail::SeamFinder>  seam_finder_;
00235     Ptr<detail::Blender>  blender_;
00236 
00237     std::vector<cv::UMat> imgs_;
00238     std::vector<std::vector<cv::Rect> > rois_;
00239     std::vector<cv::Size> full_img_sizes_;
00240     std::vector<detail::ImageFeatures> features_;
00241     std::vector<detail::MatchesInfo> pairwise_matches_;
00242     std::vector<cv::UMat> seam_est_imgs_;
00243     std::vector<int> indices_;
00244     std::vector<detail::CameraParams> cameras_;
00245     double work_scale_;
00246     double seam_scale_;
00247     double seam_work_aspect_;
00248     double warped_image_scale_;
00249 };
00250 
00251 CV_EXPORTS_W Ptr<Stitcher> createStitcher(bool try_use_gpu = false);
00252 
00253 //! @} stitching
00254 
00255 } // namespace cv
00256 
00257 #endif // __OPENCV_STITCHING_STITCHER_HPP__
00258