warpers.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_WARPERS_HPP
00044 #define OPENCV_STITCHING_WARPERS_HPP
00045 
00046 #include "opencv2/core.hpp"
00047 #include "opencv2/core/cuda.hpp"
00048 #include "opencv2/imgproc.hpp"
00049 #include "opencv2/opencv_modules.hpp"
00050 
00051 namespace cv {
00052 namespace detail {
00053 
00054 //! @addtogroup stitching_warp
00055 //! @{
00056 
00057 /** @brief Rotation-only model image warper interface.
00058  */
00059 class CV_EXPORTS RotationWarper
00060 {
00061 public:
00062     virtual ~RotationWarper() {}
00063 
00064     /** @brief Projects the image point.
00065 
00066     @param pt Source point
00067     @param K Camera intrinsic parameters
00068     @param R Camera rotation matrix
00069     @return Projected point
00070      */
00071     virtual Point2f  warpPoint(const Point2f  &pt, InputArray K, InputArray R) = 0;
00072 
00073     /** @brief Builds the projection maps according to the given camera data.
00074 
00075     @param src_size Source image size
00076     @param K Camera intrinsic parameters
00077     @param R Camera rotation matrix
00078     @param xmap Projection map for the x axis
00079     @param ymap Projection map for the y axis
00080     @return Projected image minimum bounding box
00081      */
00082     virtual Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap) = 0;
00083 
00084     /** @brief Projects the image.
00085 
00086     @param src Source image
00087     @param K Camera intrinsic parameters
00088     @param R Camera rotation matrix
00089     @param interp_mode Interpolation mode
00090     @param border_mode Border extrapolation mode
00091     @param dst Projected image
00092     @return Project image top-left corner
00093      */
00094     virtual Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
00095                        OutputArray dst) = 0;
00096 
00097     /** @brief Projects the image backward.
00098 
00099     @param src Projected image
00100     @param K Camera intrinsic parameters
00101     @param R Camera rotation matrix
00102     @param interp_mode Interpolation mode
00103     @param border_mode Border extrapolation mode
00104     @param dst_size Backward-projected image size
00105     @param dst Backward-projected image
00106      */
00107     virtual void warpBackward(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
00108                               Size dst_size, OutputArray dst) = 0;
00109 
00110     /**
00111     @param src_size Source image bounding box
00112     @param K Camera intrinsic parameters
00113     @param R Camera rotation matrix
00114     @return Projected image minimum bounding box
00115      */
00116     virtual Rect warpRoi(Size src_size, InputArray K, InputArray R) = 0;
00117 
00118     virtual float getScale() const { return 1.f; }
00119     virtual void setScale(float) {}
00120 };
00121 
00122 /** @brief Base class for warping logic implementation.
00123  */
00124 struct CV_EXPORTS ProjectorBase
00125 {
00126     void setCameraParams(InputArray K = Mat::eye(3, 3, CV_32F),
00127                          InputArray R = Mat::eye(3, 3, CV_32F),
00128                          InputArray T = Mat::zeros(3, 1, CV_32F));
00129 
00130     float scale;
00131     float k[9];
00132     float rinv[9];
00133     float r_kinv[9];
00134     float k_rinv[9];
00135     float t[3];
00136 };
00137 
00138 /** @brief Base class for rotation-based warper using a detail::ProjectorBase_ derived class.
00139  */
00140 template <class P>
00141 class CV_EXPORTS RotationWarperBase : public RotationWarper
00142 {
00143 public:
00144     Point2f  warpPoint(const Point2f  &pt, InputArray K, InputArray R);
00145 
00146     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap);
00147 
00148     Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
00149                OutputArray dst);
00150 
00151     void warpBackward(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
00152                       Size dst_size, OutputArray dst);
00153 
00154     Rect warpRoi(Size src_size, InputArray K, InputArray R);
00155 
00156     float getScale() const { return projector_.scale; }
00157     void setScale(float val) { projector_.scale = val; }
00158 
00159 protected:
00160 
00161     // Detects ROI of the destination image. It's correct for any projection.
00162     virtual void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
00163 
00164     // Detects ROI of the destination image by walking over image border.
00165     // Correctness for any projection isn't guaranteed.
00166     void detectResultRoiByBorder(Size src_size, Point &dst_tl, Point &dst_br);
00167 
00168     P projector_;
00169 };
00170 
00171 
00172 struct CV_EXPORTS PlaneProjector : ProjectorBase
00173 {
00174     void mapForward(float x, float y, float &u, float &v);
00175     void mapBackward(float u, float v, float &x, float &y);
00176 };
00177 
00178 /** @brief Warper that maps an image onto the z = 1 plane.
00179  */
00180 class CV_EXPORTS PlaneWarper : public RotationWarperBase<PlaneProjector>
00181 {
00182 public:
00183     /** @brief Construct an instance of the plane warper class.
00184 
00185     @param scale Projected image scale multiplier
00186      */
00187     PlaneWarper(float scale = 1.f) { projector_.scale = scale; }
00188 
00189     Point2f  warpPoint(const Point2f  &pt, InputArray K, InputArray R);
00190     Point2f  warpPoint(const Point2f  &pt, InputArray K, InputArray R, InputArray T);
00191 
00192     virtual Rect buildMaps(Size src_size, InputArray K, InputArray R, InputArray T, OutputArray xmap, OutputArray ymap);
00193     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap);
00194 
00195     Point warp(InputArray src, InputArray K, InputArray R,
00196                int interp_mode, int border_mode, OutputArray dst);
00197     virtual Point warp(InputArray src, InputArray K, InputArray R, InputArray T, int interp_mode, int border_mode,
00198                OutputArray dst);
00199 
00200     Rect warpRoi(Size src_size, InputArray K, InputArray R);
00201     Rect warpRoi(Size src_size, InputArray K, InputArray R, InputArray T);
00202 
00203 protected:
00204     void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
00205 };
00206 
00207 
00208 /** @brief Affine warper that uses rotations and translations
00209 
00210  Uses affine transformation in homogeneous coordinates to represent both rotation and
00211  translation in camera rotation matrix.
00212  */
00213 class CV_EXPORTS AffineWarper : public PlaneWarper
00214 {
00215 public:
00216     /** @brief Construct an instance of the affine warper class.
00217 
00218     @param scale Projected image scale multiplier
00219      */
00220     AffineWarper(float scale = 1.f) : PlaneWarper(scale) {}
00221 
00222     Point2f  warpPoint(const Point2f  &pt, InputArray K, InputArray R);
00223     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap);
00224     Point warp(InputArray src, InputArray K, InputArray R,
00225                int interp_mode, int border_mode, OutputArray dst);
00226     Rect warpRoi(Size src_size, InputArray K, InputArray R);
00227 
00228 protected:
00229     /** @brief Extracts rotation and translation matrices from matrix H representing
00230         affine transformation in homogeneous coordinates
00231      */
00232     void getRTfromHomogeneous(InputArray H, Mat &R, Mat &T);
00233 };
00234 
00235 
00236 struct CV_EXPORTS SphericalProjector : ProjectorBase
00237 {
00238     void mapForward(float x, float y, float &u, float &v);
00239     void mapBackward(float u, float v, float &x, float &y);
00240 };
00241 
00242 
00243 /** @brief Warper that maps an image onto the unit sphere located at the origin.
00244 
00245  Projects image onto unit sphere with origin at (0, 0, 0) and radius scale, measured in pixels.
00246  A 360° panorama would therefore have a resulting width of 2 * scale * PI pixels.
00247  Poles are located at (0, -1, 0) and (0, 1, 0) points.
00248 */
00249 class CV_EXPORTS SphericalWarper : public RotationWarperBase<SphericalProjector>
00250 {
00251 public:
00252     /** @brief Construct an instance of the spherical warper class.
00253 
00254     @param scale Radius of the projected sphere, in pixels. An image spanning the
00255                  whole sphere will have a width of 2 * scale * PI pixels.
00256      */
00257     SphericalWarper(float scale) { projector_.scale = scale; }
00258 
00259     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap);
00260     Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode, OutputArray dst);
00261 protected:
00262     void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
00263 };
00264 
00265 
00266 struct CV_EXPORTS CylindricalProjector : ProjectorBase
00267 {
00268     void mapForward(float x, float y, float &u, float &v);
00269     void mapBackward(float u, float v, float &x, float &y);
00270 };
00271 
00272 
00273 /** @brief Warper that maps an image onto the x\*x + z\*z = 1 cylinder.
00274  */
00275 class CV_EXPORTS CylindricalWarper : public RotationWarperBase<CylindricalProjector>
00276 {
00277 public:
00278     /** @brief Construct an instance of the cylindrical warper class.
00279 
00280     @param scale Projected image scale multiplier
00281      */
00282     CylindricalWarper(float scale) { projector_.scale = scale; }
00283 
00284     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap);
00285     Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode, OutputArray dst);
00286 protected:
00287     void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br)
00288     {
00289         RotationWarperBase<CylindricalProjector>::detectResultRoiByBorder(src_size, dst_tl, dst_br);
00290     }
00291 };
00292 
00293 
00294 struct CV_EXPORTS FisheyeProjector : ProjectorBase
00295 {
00296     void mapForward(float x, float y, float &u, float &v);
00297     void mapBackward(float u, float v, float &x, float &y);
00298 };
00299 
00300 
00301 class CV_EXPORTS FisheyeWarper : public RotationWarperBase<FisheyeProjector>
00302 {
00303 public:
00304     FisheyeWarper(float scale) { projector_.scale = scale; }
00305 };
00306 
00307 
00308 struct CV_EXPORTS StereographicProjector : ProjectorBase
00309 {
00310     void mapForward(float x, float y, float &u, float &v);
00311     void mapBackward(float u, float v, float &x, float &y);
00312 };
00313 
00314 
00315 class CV_EXPORTS StereographicWarper : public RotationWarperBase<StereographicProjector>
00316 {
00317 public:
00318     StereographicWarper(float scale) { projector_.scale = scale; }
00319 };
00320 
00321 
00322 struct CV_EXPORTS CompressedRectilinearProjector : ProjectorBase
00323 {
00324     float a, b;
00325 
00326     void mapForward(float x, float y, float &u, float &v);
00327     void mapBackward(float u, float v, float &x, float &y);
00328 };
00329 
00330 
00331 class CV_EXPORTS CompressedRectilinearWarper : public RotationWarperBase<CompressedRectilinearProjector>
00332 {
00333 public:
00334     CompressedRectilinearWarper(float scale, float A = 1, float B = 1)
00335     {
00336         projector_.a = A;
00337         projector_.b = B;
00338         projector_.scale = scale;
00339     }
00340 };
00341 
00342 
00343 struct CV_EXPORTS CompressedRectilinearPortraitProjector : ProjectorBase
00344 {
00345     float a, b;
00346 
00347     void mapForward(float x, float y, float &u, float &v);
00348     void mapBackward(float u, float v, float &x, float &y);
00349 };
00350 
00351 
00352 class CV_EXPORTS CompressedRectilinearPortraitWarper : public RotationWarperBase<CompressedRectilinearPortraitProjector>
00353 {
00354 public:
00355    CompressedRectilinearPortraitWarper(float scale, float A = 1, float B = 1)
00356    {
00357        projector_.a = A;
00358        projector_.b = B;
00359        projector_.scale = scale;
00360    }
00361 };
00362 
00363 
00364 struct CV_EXPORTS PaniniProjector : ProjectorBase
00365 {
00366     float a, b;
00367 
00368     void mapForward(float x, float y, float &u, float &v);
00369     void mapBackward(float u, float v, float &x, float &y);
00370 };
00371 
00372 
00373 class CV_EXPORTS PaniniWarper : public RotationWarperBase<PaniniProjector>
00374 {
00375 public:
00376    PaniniWarper(float scale, float A = 1, float B = 1)
00377    {
00378        projector_.a = A;
00379        projector_.b = B;
00380        projector_.scale = scale;
00381    }
00382 };
00383 
00384 
00385 struct CV_EXPORTS PaniniPortraitProjector : ProjectorBase
00386 {
00387     float a, b;
00388 
00389     void mapForward(float x, float y, float &u, float &v);
00390     void mapBackward(float u, float v, float &x, float &y);
00391 };
00392 
00393 
00394 class CV_EXPORTS PaniniPortraitWarper : public RotationWarperBase<PaniniPortraitProjector>
00395 {
00396 public:
00397    PaniniPortraitWarper(float scale, float A = 1, float B = 1)
00398    {
00399        projector_.a = A;
00400        projector_.b = B;
00401        projector_.scale = scale;
00402    }
00403 
00404 };
00405 
00406 
00407 struct CV_EXPORTS MercatorProjector : ProjectorBase
00408 {
00409     void mapForward(float x, float y, float &u, float &v);
00410     void mapBackward(float u, float v, float &x, float &y);
00411 };
00412 
00413 
00414 class CV_EXPORTS MercatorWarper : public RotationWarperBase<MercatorProjector>
00415 {
00416 public:
00417     MercatorWarper(float scale) { projector_.scale = scale; }
00418 };
00419 
00420 
00421 struct CV_EXPORTS TransverseMercatorProjector : ProjectorBase
00422 {
00423     void mapForward(float x, float y, float &u, float &v);
00424     void mapBackward(float u, float v, float &x, float &y);
00425 };
00426 
00427 
00428 class CV_EXPORTS TransverseMercatorWarper : public RotationWarperBase<TransverseMercatorProjector>
00429 {
00430 public:
00431     TransverseMercatorWarper(float scale) { projector_.scale = scale; }
00432 };
00433 
00434 
00435 class CV_EXPORTS PlaneWarperGpu : public PlaneWarper
00436 {
00437 public:
00438     PlaneWarperGpu(float scale = 1.f) : PlaneWarper(scale) {}
00439 
00440     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap)
00441     {
00442         Rect result = buildMaps(src_size, K, R, d_xmap_, d_ymap_);
00443         d_xmap_.download(xmap);
00444         d_ymap_.download(ymap);
00445         return result;
00446     }
00447 
00448     Rect buildMaps(Size src_size, InputArray K, InputArray R, InputArray T, OutputArray xmap, OutputArray ymap)
00449     {
00450         Rect result = buildMaps(src_size, K, R, T, d_xmap_, d_ymap_);
00451         d_xmap_.download(xmap);
00452         d_ymap_.download(ymap);
00453         return result;
00454     }
00455 
00456     Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
00457                OutputArray dst)
00458     {
00459         d_src_.upload(src);
00460         Point result = warp(d_src_, K, R, interp_mode, border_mode, d_dst_);
00461         d_dst_.download(dst);
00462         return result;
00463     }
00464 
00465     Point warp(InputArray src, InputArray K, InputArray R, InputArray T, int interp_mode, int border_mode,
00466                OutputArray dst)
00467     {
00468         d_src_.upload(src);
00469         Point result = warp(d_src_, K, R, T, interp_mode, border_mode, d_dst_);
00470         d_dst_.download(dst);
00471         return result;
00472     }
00473 
00474     Rect buildMaps(Size src_size, InputArray K, InputArray R, cuda::GpuMat & xmap, cuda::GpuMat & ymap);
00475 
00476     Rect buildMaps(Size src_size, InputArray K, InputArray R, InputArray T, cuda::GpuMat & xmap, cuda::GpuMat & ymap);
00477 
00478     Point warp(const cuda::GpuMat & src, InputArray K, InputArray R, int interp_mode, int border_mode,
00479                cuda::GpuMat & dst);
00480 
00481     Point warp(const cuda::GpuMat & src, InputArray K, InputArray R, InputArray T, int interp_mode, int border_mode,
00482                cuda::GpuMat & dst);
00483 
00484 private:
00485     cuda::GpuMat d_xmap_, d_ymap_, d_src_, d_dst_;
00486 };
00487 
00488 
00489 class CV_EXPORTS SphericalWarperGpu : public SphericalWarper
00490 {
00491 public:
00492     SphericalWarperGpu(float scale) : SphericalWarper(scale) {}
00493 
00494     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap)
00495     {
00496         Rect result = buildMaps(src_size, K, R, d_xmap_, d_ymap_);
00497         d_xmap_.download(xmap);
00498         d_ymap_.download(ymap);
00499         return result;
00500     }
00501 
00502     Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
00503                OutputArray dst)
00504     {
00505         d_src_.upload(src);
00506         Point result = warp(d_src_, K, R, interp_mode, border_mode, d_dst_);
00507         d_dst_.download(dst);
00508         return result;
00509     }
00510 
00511     Rect buildMaps(Size src_size, InputArray K, InputArray R, cuda::GpuMat & xmap, cuda::GpuMat & ymap);
00512 
00513     Point warp(const cuda::GpuMat & src, InputArray K, InputArray R, int interp_mode, int border_mode,
00514                cuda::GpuMat & dst);
00515 
00516 private:
00517     cuda::GpuMat d_xmap_, d_ymap_, d_src_, d_dst_;
00518 };
00519 
00520 
00521 class CV_EXPORTS CylindricalWarperGpu : public CylindricalWarper
00522 {
00523 public:
00524     CylindricalWarperGpu(float scale) : CylindricalWarper(scale) {}
00525 
00526     Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap)
00527     {
00528         Rect result = buildMaps(src_size, K, R, d_xmap_, d_ymap_);
00529         d_xmap_.download(xmap);
00530         d_ymap_.download(ymap);
00531         return result;
00532     }
00533 
00534     Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
00535                OutputArray dst)
00536     {
00537         d_src_.upload(src);
00538         Point result = warp(d_src_, K, R, interp_mode, border_mode, d_dst_);
00539         d_dst_.download(dst);
00540         return result;
00541     }
00542 
00543     Rect buildMaps(Size src_size, InputArray K, InputArray R, cuda::GpuMat & xmap, cuda::GpuMat & ymap);
00544 
00545     Point warp(const cuda::GpuMat & src, InputArray K, InputArray R, int interp_mode, int border_mode,
00546                cuda::GpuMat & dst);
00547 
00548 private:
00549     cuda::GpuMat d_xmap_, d_ymap_, d_src_, d_dst_;
00550 };
00551 
00552 
00553 struct SphericalPortraitProjector : ProjectorBase
00554 {
00555     void mapForward(float x, float y, float &u, float &v);
00556     void mapBackward(float u, float v, float &x, float &y);
00557 };
00558 
00559 
00560 // Projects image onto unit sphere with origin at (0, 0, 0).
00561 // Poles are located NOT at (0, -1, 0) and (0, 1, 0) points, BUT at (1, 0, 0) and (-1, 0, 0) points.
00562 class CV_EXPORTS SphericalPortraitWarper : public RotationWarperBase<SphericalPortraitProjector>
00563 {
00564 public:
00565     SphericalPortraitWarper(float scale) { projector_.scale = scale; }
00566 
00567 protected:
00568     void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
00569 };
00570 
00571 struct CylindricalPortraitProjector : ProjectorBase
00572 {
00573     void mapForward(float x, float y, float &u, float &v);
00574     void mapBackward(float u, float v, float &x, float &y);
00575 };
00576 
00577 
00578 class CV_EXPORTS CylindricalPortraitWarper : public RotationWarperBase<CylindricalPortraitProjector>
00579 {
00580 public:
00581     CylindricalPortraitWarper(float scale) { projector_.scale = scale; }
00582 
00583 protected:
00584     void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br)
00585     {
00586         RotationWarperBase<CylindricalPortraitProjector>::detectResultRoiByBorder(src_size, dst_tl, dst_br);
00587     }
00588 };
00589 
00590 struct PlanePortraitProjector : ProjectorBase
00591 {
00592     void mapForward(float x, float y, float &u, float &v);
00593     void mapBackward(float u, float v, float &x, float &y);
00594 };
00595 
00596 
00597 class CV_EXPORTS PlanePortraitWarper : public RotationWarperBase<PlanePortraitProjector>
00598 {
00599 public:
00600     PlanePortraitWarper(float scale) { projector_.scale = scale; }
00601 
00602 protected:
00603     void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br)
00604     {
00605         RotationWarperBase<PlanePortraitProjector>::detectResultRoiByBorder(src_size, dst_tl, dst_br);
00606     }
00607 };
00608 
00609 //! @} stitching_warp
00610 
00611 } // namespace detail
00612 } // namespace cv
00613 
00614 #include "warpers_inl.hpp"
00615 
00616 #endif // OPENCV_STITCHING_WARPERS_HPP