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 #if defined(Status)
00058 #  warning Detected X11 'Status' macro definition, it can cause build conflicts. Please, include this header before any X11 headers.
00059 #endif
00060 
00061 
00062 /**
00063 @defgroup stitching Images stitching
00064 
00065 This figure illustrates the stitching module pipeline implemented in the Stitcher class. Using that
00066 class it's possible to configure/remove some steps, i.e. adjust the stitching pipeline according to
00067 the particular needs. All building blocks from the pipeline are available in the detail namespace,
00068 one can combine and use them separately.
00069 
00070 The implemented stitching pipeline is very similar to the one proposed in @cite BL07 .
00071 
00072 ![stitching pipeline](StitchingPipeline.jpg)
00073 
00074 Camera models
00075 -------------
00076 
00077 There are currently 2 camera models implemented in stitching pipeline.
00078 
00079 - _Homography model_ expecting perspective transformations between images
00080   implemented in @ref cv::detail::BestOf2NearestMatcher cv::detail::HomographyBasedEstimator
00081   cv::detail::BundleAdjusterReproj cv::detail::BundleAdjusterRay
00082 - _Affine model_ expecting affine transformation with 6 DOF or 4 DOF implemented in
00083   @ref cv::detail::AffineBestOf2NearestMatcher cv::detail::AffineBasedEstimator
00084   cv::detail::BundleAdjusterAffine cv::detail::BundleAdjusterAffinePartial cv::AffineWarper
00085 
00086 Homography model is useful for creating photo panoramas captured by camera,
00087 while affine-based model can be used to stitch scans and object captured by
00088 specialized devices. Use @ref cv::Stitcher::create to get preconfigured pipeline for one
00089 of those models.
00090 
00091 @note
00092 Certain detailed settings of @ref cv::Stitcher might not make sense. Especially
00093 you should not mix classes implementing affine model and classes implementing
00094 Homography model, as they work with different transformations.
00095 
00096 @{
00097     @defgroup stitching_match Features Finding and Images Matching
00098     @defgroup stitching_rotation Rotation Estimation
00099     @defgroup stitching_autocalib Autocalibration
00100     @defgroup stitching_warp Images Warping
00101     @defgroup stitching_seam Seam Estimation
00102     @defgroup stitching_exposure Exposure Compensation
00103     @defgroup stitching_blend Image Blenders
00104 @}
00105   */
00106 
00107 namespace cv {
00108 
00109 //! @addtogroup stitching
00110 //! @{
00111 
00112 /** @brief High level image stitcher.
00113 
00114 It's possible to use this class without being aware of the entire stitching pipeline. However, to
00115 be able to achieve higher stitching stability and quality of the final images at least being
00116 familiar with the theory is recommended.
00117 
00118 @note
00119    -   A basic example on image stitching can be found at
00120         opencv_source_code/samples/cpp/stitching.cpp
00121     -   A detailed example on image stitching can be found at
00122         opencv_source_code/samples/cpp/stitching_detailed.cpp
00123  */
00124 class CV_EXPORTS_W Stitcher
00125 {
00126 public:
00127     enum { ORIG_RESOL = -1 };
00128     enum Status
00129     {
00130         OK = 0,
00131         ERR_NEED_MORE_IMGS = 1,
00132         ERR_HOMOGRAPHY_EST_FAIL = 2,
00133         ERR_CAMERA_PARAMS_ADJUST_FAIL = 3
00134     };
00135     enum Mode 
00136     {
00137         /** Mode for creating photo panoramas. Expects images under perspective
00138         transformation and projects resulting pano to sphere.
00139 
00140         @sa detail::BestOf2NearestMatcher SphericalWarper
00141         */
00142         PANORAMA = 0,
00143         /** Mode for composing scans. Expects images under affine transformation does
00144         not compensate exposure by default.
00145 
00146         @sa detail::AffineBestOf2NearestMatcher AffineWarper
00147         */
00148         SCANS = 1,
00149 
00150     };
00151 
00152    // Stitcher() {}
00153     /** @brief Creates a stitcher with the default parameters.
00154 
00155     @param try_use_gpu Flag indicating whether GPU should be used whenever it's possible.
00156     @return Stitcher class instance.
00157      */
00158     static Stitcher createDefault(bool try_use_gpu = false);
00159     /** @brief Creates a Stitcher configured in one of the stitching modes.
00160 
00161     @param mode Scenario for stitcher operation. This is usually determined by source of images
00162     to stitch and their transformation. Default parameters will be chosen for operation in given
00163     scenario.
00164     @param try_use_gpu Flag indicating whether GPU should be used whenever it's possible.
00165     @return Stitcher class instance.
00166      */
00167     static Ptr<Stitcher> create(Mode mode = PANORAMA, bool try_use_gpu = false);
00168 
00169     CV_WRAP double registrationResol() const { return registr_resol_; }
00170     CV_WRAP void setRegistrationResol(double resol_mpx) { registr_resol_ = resol_mpx; }
00171 
00172     CV_WRAP double seamEstimationResol() const { return seam_est_resol_; }
00173     CV_WRAP void setSeamEstimationResol(double resol_mpx) { seam_est_resol_ = resol_mpx; }
00174 
00175     CV_WRAP double compositingResol() const { return compose_resol_; }
00176     CV_WRAP void setCompositingResol(double resol_mpx) { compose_resol_ = resol_mpx; }
00177 
00178     CV_WRAP double panoConfidenceThresh() const { return conf_thresh_; }
00179     CV_WRAP void setPanoConfidenceThresh(double conf_thresh) { conf_thresh_ = conf_thresh; }
00180 
00181     CV_WRAP bool waveCorrection() const { return do_wave_correct_; }
00182     CV_WRAP void setWaveCorrection(bool flag) { do_wave_correct_ = flag; }
00183 
00184     detail::WaveCorrectKind waveCorrectKind() const { return wave_correct_kind_; }
00185     void setWaveCorrectKind(detail::WaveCorrectKind kind) { wave_correct_kind_ = kind; }
00186 
00187     Ptr<detail::FeaturesFinder> featuresFinder() { return features_finder_; }
00188     const Ptr<detail::FeaturesFinder> featuresFinder() const { return features_finder_; }
00189     void setFeaturesFinder(Ptr<detail::FeaturesFinder> features_finder)
00190         { features_finder_ = features_finder; }
00191 
00192     Ptr<detail::FeaturesMatcher> featuresMatcher() { return features_matcher_; }
00193     const Ptr<detail::FeaturesMatcher> featuresMatcher() const { return features_matcher_; }
00194     void setFeaturesMatcher(Ptr<detail::FeaturesMatcher> features_matcher)
00195         { features_matcher_ = features_matcher; }
00196 
00197     const cv::UMat & matchingMask() const { return matching_mask_; }
00198     void setMatchingMask(const cv::UMat  &mask)
00199     {
00200         CV_Assert(mask.type() == CV_8U && mask.cols == mask.rows);
00201         matching_mask_ = mask.clone();
00202     }
00203 
00204     Ptr<detail::BundleAdjusterBase> bundleAdjuster() { return bundle_adjuster_; }
00205     const Ptr<detail::BundleAdjusterBase> bundleAdjuster() const { return bundle_adjuster_; }
00206     void setBundleAdjuster(Ptr<detail::BundleAdjusterBase> bundle_adjuster)
00207         { bundle_adjuster_ = bundle_adjuster; }
00208 
00209     /* TODO OpenCV ABI 4.x
00210     Ptr<detail::Estimator> estimator() { return estimator_; }
00211     const Ptr<detail::Estimator> estimator() const { return estimator_; }
00212     void setEstimator(Ptr<detail::Estimator> estimator)
00213         { estimator_ = estimator; }
00214     */
00215 
00216     Ptr<WarperCreator> warper() { return warper_; }
00217     const Ptr<WarperCreator> warper() const { return warper_; }
00218     void setWarper(Ptr<WarperCreator> creator) { warper_ = creator; }
00219 
00220     Ptr<detail::ExposureCompensator> exposureCompensator() { return exposure_comp_; }
00221     const Ptr<detail::ExposureCompensator> exposureCompensator() const { return exposure_comp_; }
00222     void setExposureCompensator(Ptr<detail::ExposureCompensator> exposure_comp)
00223         { exposure_comp_ = exposure_comp; }
00224 
00225     Ptr<detail::SeamFinder> seamFinder() { return seam_finder_; }
00226     const Ptr<detail::SeamFinder> seamFinder() const { return seam_finder_; }
00227     void setSeamFinder(Ptr<detail::SeamFinder> seam_finder) { seam_finder_ = seam_finder; }
00228 
00229     Ptr<detail::Blender> blender() { return blender_; }
00230     const Ptr<detail::Blender> blender() const { return blender_; }
00231     void setBlender(Ptr<detail::Blender> b) { blender_ = b; }
00232 
00233     /** @overload */
00234     CV_WRAP Status estimateTransform(InputArrayOfArrays images);
00235     /** @brief These functions try to match the given images and to estimate rotations of each camera.
00236 
00237     @note Use the functions only if you're aware of the stitching pipeline, otherwise use
00238     Stitcher::stitch.
00239 
00240     @param images Input images.
00241     @param rois Region of interest rectangles.
00242     @return Status code.
00243      */
00244     Status estimateTransform(InputArrayOfArrays images, const std::vector<std::vector<Rect> > &rois);
00245 
00246     /** @overload */
00247     CV_WRAP Status composePanorama(OutputArray pano);
00248     /** @brief These functions try to compose the given images (or images stored internally from the other function
00249     calls) into the final pano under the assumption that the image transformations were estimated
00250     before.
00251 
00252     @note Use the functions only if you're aware of the stitching pipeline, otherwise use
00253     Stitcher::stitch.
00254 
00255     @param images Input images.
00256     @param pano Final pano.
00257     @return Status code.
00258      */
00259     Status composePanorama(InputArrayOfArrays images, OutputArray pano);
00260 
00261     /** @overload */
00262     CV_WRAP Status stitch(InputArrayOfArrays images, OutputArray pano);
00263     /** @brief These functions try to stitch the given images.
00264 
00265     @param images Input images.
00266     @param rois Region of interest rectangles.
00267     @param pano Final pano.
00268     @return Status code.
00269      */
00270     Status stitch(InputArrayOfArrays images, const std::vector<std::vector<Rect> > &rois, OutputArray pano);
00271 
00272     std::vector<int> component() const { return indices_; }
00273     std::vector<detail::CameraParams> cameras() const { return cameras_; }
00274     CV_WRAP double workScale() const { return work_scale_; }
00275 
00276 private:
00277     //Stitcher() {}
00278 
00279     Status matchImages();
00280     Status estimateCameraParams();
00281 
00282     double registr_resol_;
00283     double seam_est_resol_;
00284     double compose_resol_;
00285     double conf_thresh_;
00286     Ptr<detail::FeaturesFinder> features_finder_;
00287     Ptr<detail::FeaturesMatcher> features_matcher_;
00288     cv::UMat  matching_mask_;
00289     Ptr<detail::BundleAdjusterBase> bundle_adjuster_;
00290     /* TODO OpenCV ABI 4.x
00291     Ptr<detail::Estimator> estimator_;
00292     */
00293     bool do_wave_correct_;
00294     detail::WaveCorrectKind wave_correct_kind_;
00295     Ptr<WarperCreator> warper_;
00296     Ptr<detail::ExposureCompensator> exposure_comp_;
00297     Ptr<detail::SeamFinder> seam_finder_;
00298     Ptr<detail::Blender> blender_;
00299 
00300     std::vector<cv::UMat> imgs_;
00301     std::vector<std::vector<cv::Rect> > rois_;
00302     std::vector<cv::Size> full_img_sizes_;
00303     std::vector<detail::ImageFeatures> features_;
00304     std::vector<detail::MatchesInfo> pairwise_matches_;
00305     std::vector<cv::UMat> seam_est_imgs_;
00306     std::vector<int> indices_;
00307     std::vector<detail::CameraParams> cameras_;
00308     double work_scale_;
00309     double seam_scale_;
00310     double seam_work_aspect_;
00311     double warped_image_scale_;
00312 };
00313 
00314 CV_EXPORTS_W Ptr<Stitcher> createStitcher(bool try_use_gpu = false);
00315 
00316 //! @} stitching
00317 
00318 } // namespace cv
00319 
00320 #endif // OPENCV_STITCHING_STITCHER_HPP