1 /* 2 By downloading, copying, installing or using the software you agree to this license. 3 If you do not agree to this license, do not download, install, 4 copy or use the software. 5 6 7 License Agreement 8 For Open Source Computer Vision Library 9 (3-clause BSD License) 10 11 Redistribution and use in source and binary forms, with or without modification, 12 are permitted provided that the following conditions are met: 13 14 * Redistributions of source code must retain the above copyright notice, 15 this list of conditions and the following disclaimer. 16 17 * Redistributions in binary form must reproduce the above copyright notice, 18 this list of conditions and the following disclaimer in the documentation 19 and/or other materials provided with the distribution. 20 21 * Neither the names of the copyright holders nor the names of the contributors 22 may be used to endorse or promote products derived from this software 23 without specific prior written permission. 24 25 This software is provided by the copyright holders and contributors "as is" and 26 any express or implied warranties, including, but not limited to, the implied 27 warranties of merchantability and fitness for a particular purpose are disclaimed. 28 In no event shall copyright holders or contributors be liable for any direct, 29 indirect, incidental, special, exemplary, or consequential damages 30 (including, but not limited to, procurement of substitute goods or services; 31 loss of use, data, or profits; or business interruption) however caused 32 and on any theory of liability, whether in contract, strict liability, 33 or tort (including negligence or otherwise) arising in any way out of 34 the use of this software, even if advised of the possibility of such damage. 35 */ 36 37 #ifndef __OPENCV_IMGPROC_FILTERENGINE_HPP__ 38 #define __OPENCV_IMGPROC_FILTERENGINE_HPP__ 39 40 namespace cv 41 { 42 43 //! type of the kernel 44 enum 45 { 46 KERNEL_GENERAL = 0, // the kernel is generic. No any type of symmetry or other properties. 47 KERNEL_SYMMETRICAL = 1, // kernel[i] == kernel[ksize-i-1] , and the anchor is at the center 48 KERNEL_ASYMMETRICAL = 2, // kernel[i] == -kernel[ksize-i-1] , and the anchor is at the center 49 KERNEL_SMOOTH = 4, // all the kernel elements are non-negative and summed to 1 50 KERNEL_INTEGER = 8 // all the kernel coefficients are integer numbers 51 }; 52 53 /*! 54 The Base Class for 1D or Row-wise Filters 55 56 This is the base class for linear or non-linear filters that process 1D data. 57 In particular, such filters are used for the "horizontal" filtering parts in separable filters. 58 59 Several functions in OpenCV return Ptr<BaseRowFilter> for the specific types of filters, 60 and those pointers can be used directly or within cv::FilterEngine. 61 */ 62 class BaseRowFilter 63 { 64 public: 65 //! the default constructor 66 BaseRowFilter(); 67 //! the destructor 68 virtual ~BaseRowFilter(); 69 //! the filtering operator. Must be overridden in the derived classes. The horizontal border interpolation is done outside of the class. 70 virtual void operator()(const uchar* src, uchar* dst, int width, int cn) = 0; 71 72 int ksize; 73 int anchor; 74 }; 75 76 77 /*! 78 The Base Class for Column-wise Filters 79 80 This is the base class for linear or non-linear filters that process columns of 2D arrays. 81 Such filters are used for the "vertical" filtering parts in separable filters. 82 83 Several functions in OpenCV return Ptr<BaseColumnFilter> for the specific types of filters, 84 and those pointers can be used directly or within cv::FilterEngine. 85 86 Unlike cv::BaseRowFilter, cv::BaseColumnFilter may have some context information, 87 i.e. box filter keeps the sliding sum of elements. To reset the state BaseColumnFilter::reset() 88 must be called (e.g. the method is called by cv::FilterEngine) 89 */ 90 class BaseColumnFilter 91 { 92 public: 93 //! the default constructor 94 BaseColumnFilter(); 95 //! the destructor 96 virtual ~BaseColumnFilter(); 97 //! the filtering operator. Must be overridden in the derived classes. The vertical border interpolation is done outside of the class. 98 virtual void operator()(const uchar** src, uchar* dst, int dststep, int dstcount, int width) = 0; 99 //! resets the internal buffers, if any 100 virtual void reset(); 101 102 int ksize; 103 int anchor; 104 }; 105 106 107 /*! 108 The Base Class for Non-Separable 2D Filters. 109 110 This is the base class for linear or non-linear 2D filters. 111 112 Several functions in OpenCV return Ptr<BaseFilter> for the specific types of filters, 113 and those pointers can be used directly or within cv::FilterEngine. 114 115 Similar to cv::BaseColumnFilter, the class may have some context information, 116 that should be reset using BaseFilter::reset() method before processing the new array. 117 */ 118 class BaseFilter 119 { 120 public: 121 //! the default constructor 122 BaseFilter(); 123 //! the destructor 124 virtual ~BaseFilter(); 125 //! the filtering operator. The horizontal and the vertical border interpolation is done outside of the class. 126 virtual void operator()(const uchar** src, uchar* dst, int dststep, int dstcount, int width, int cn) = 0; 127 //! resets the internal buffers, if any 128 virtual void reset(); 129 130 Size ksize; 131 Point anchor; 132 }; 133 134 135 /*! 136 The Main Class for Image Filtering. 137 138 The class can be used to apply an arbitrary filtering operation to an image. 139 It contains all the necessary intermediate buffers, it computes extrapolated values 140 of the "virtual" pixels outside of the image etc. 141 Pointers to the initialized cv::FilterEngine instances 142 are returned by various OpenCV functions, such as cv::createSeparableLinearFilter(), 143 cv::createLinearFilter(), cv::createGaussianFilter(), cv::createDerivFilter(), 144 cv::createBoxFilter() and cv::createMorphologyFilter(). 145 146 Using the class you can process large images by parts and build complex pipelines 147 that include filtering as some of the stages. If all you need is to apply some pre-defined 148 filtering operation, you may use cv::filter2D(), cv::erode(), cv::dilate() etc. 149 functions that create FilterEngine internally. 150 151 Here is the example on how to use the class to implement Laplacian operator, which is the sum of 152 second-order derivatives. More complex variant for different types is implemented in cv::Laplacian(). 153 154 \code 155 void laplace_f(const Mat& src, Mat& dst) 156 { 157 CV_Assert( src.type() == CV_32F ); 158 // make sure the destination array has the proper size and type 159 dst.create(src.size(), src.type()); 160 161 // get the derivative and smooth kernels for d2I/dx2. 162 // for d2I/dy2 we could use the same kernels, just swapped 163 Mat kd, ks; 164 getSobelKernels( kd, ks, 2, 0, ksize, false, ktype ); 165 166 // let's process 10 source rows at once 167 int DELTA = std::min(10, src.rows); 168 Ptr<FilterEngine> Fxx = createSeparableLinearFilter(src.type(), 169 dst.type(), kd, ks, Point(-1,-1), 0, borderType, borderType, Scalar() ); 170 Ptr<FilterEngine> Fyy = createSeparableLinearFilter(src.type(), 171 dst.type(), ks, kd, Point(-1,-1), 0, borderType, borderType, Scalar() ); 172 173 int y = Fxx->start(src), dsty = 0, dy = 0; 174 Fyy->start(src); 175 const uchar* sptr = src.data + y*src.step; 176 177 // allocate the buffers for the spatial image derivatives; 178 // the buffers need to have more than DELTA rows, because at the 179 // last iteration the output may take max(kd.rows-1,ks.rows-1) 180 // rows more than the input. 181 Mat Ixx( DELTA + kd.rows - 1, src.cols, dst.type() ); 182 Mat Iyy( DELTA + kd.rows - 1, src.cols, dst.type() ); 183 184 // inside the loop we always pass DELTA rows to the filter 185 // (note that the "proceed" method takes care of possibe overflow, since 186 // it was given the actual image height in the "start" method) 187 // on output we can get: 188 // * < DELTA rows (the initial buffer accumulation stage) 189 // * = DELTA rows (settled state in the middle) 190 // * > DELTA rows (then the input image is over, but we generate 191 // "virtual" rows using the border mode and filter them) 192 // this variable number of output rows is dy. 193 // dsty is the current output row. 194 // sptr is the pointer to the first input row in the portion to process 195 for( ; dsty < dst.rows; sptr += DELTA*src.step, dsty += dy ) 196 { 197 Fxx->proceed( sptr, (int)src.step, DELTA, Ixx.data, (int)Ixx.step ); 198 dy = Fyy->proceed( sptr, (int)src.step, DELTA, d2y.data, (int)Iyy.step ); 199 if( dy > 0 ) 200 { 201 Mat dstripe = dst.rowRange(dsty, dsty + dy); 202 add(Ixx.rowRange(0, dy), Iyy.rowRange(0, dy), dstripe); 203 } 204 } 205 } 206 \endcode 207 */ 208 class FilterEngine 209 { 210 public: 211 //! the default constructor 212 FilterEngine(); 213 //! the full constructor. Either _filter2D or both _rowFilter and _columnFilter must be non-empty. 214 FilterEngine(const Ptr<BaseFilter>& _filter2D, 215 const Ptr<BaseRowFilter>& _rowFilter, 216 const Ptr<BaseColumnFilter>& _columnFilter, 217 int srcType, int dstType, int bufType, 218 int _rowBorderType = BORDER_REPLICATE, 219 int _columnBorderType = -1, 220 const Scalar& _borderValue = Scalar()); 221 //! the destructor 222 virtual ~FilterEngine(); 223 //! reinitializes the engine. The previously assigned filters are released. 224 void init(const Ptr<BaseFilter>& _filter2D, 225 const Ptr<BaseRowFilter>& _rowFilter, 226 const Ptr<BaseColumnFilter>& _columnFilter, 227 int srcType, int dstType, int bufType, 228 int _rowBorderType = BORDER_REPLICATE, 229 int _columnBorderType = -1, 230 const Scalar& _borderValue = Scalar()); 231 //! starts filtering of the specified ROI of an image of size wholeSize. 232 virtual int start(Size wholeSize, Rect roi, int maxBufRows = -1); 233 //! starts filtering of the specified ROI of the specified image. 234 virtual int start(const Mat& src, const Rect& srcRoi = Rect(0,0,-1,-1), 235 bool isolated = false, int maxBufRows = -1); 236 //! processes the next srcCount rows of the image. 237 virtual int proceed(const uchar* src, int srcStep, int srcCount, 238 uchar* dst, int dstStep); 239 //! applies filter to the specified ROI of the image. if srcRoi=(0,0,-1,-1), the whole image is filtered. 240 virtual void apply( const Mat& src, Mat& dst, 241 const Rect& srcRoi = Rect(0,0,-1,-1), 242 Point dstOfs = Point(0,0), 243 bool isolated = false); 244 //! returns true if the filter is separable 245 bool isSeparable() const { return !filter2D; } 246 //! returns the number 247 int remainingInputRows() const; 248 int remainingOutputRows() const; 249 250 int srcType; 251 int dstType; 252 int bufType; 253 Size ksize; 254 Point anchor; 255 int maxWidth; 256 Size wholeSize; 257 Rect roi; 258 int dx1; 259 int dx2; 260 int rowBorderType; 261 int columnBorderType; 262 std::vector<int> borderTab; 263 int borderElemSize; 264 std::vector<uchar> ringBuf; 265 std::vector<uchar> srcRow; 266 std::vector<uchar> constBorderValue; 267 std::vector<uchar> constBorderRow; 268 int bufStep; 269 int startY; 270 int startY0; 271 int endY; 272 int rowCount; 273 int dstY; 274 std::vector<uchar*> rows; 275 276 Ptr<BaseFilter> filter2D; 277 Ptr<BaseRowFilter> rowFilter; 278 Ptr<BaseColumnFilter> columnFilter; 279 }; 280 281 282 //! returns type (one of KERNEL_*) of 1D or 2D kernel specified by its coefficients. 283 int getKernelType(InputArray kernel, Point anchor); 284 285 //! returns the primitive row filter with the specified kernel 286 Ptr<BaseRowFilter> getLinearRowFilter(int srcType, int bufType, 287 InputArray kernel, int anchor, 288 int symmetryType); 289 290 //! returns the primitive column filter with the specified kernel 291 Ptr<BaseColumnFilter> getLinearColumnFilter(int bufType, int dstType, 292 InputArray kernel, int anchor, 293 int symmetryType, double delta = 0, 294 int bits = 0); 295 296 //! returns 2D filter with the specified kernel 297 Ptr<BaseFilter> getLinearFilter(int srcType, int dstType, 298 InputArray kernel, 299 Point anchor = Point(-1,-1), 300 double delta = 0, int bits = 0); 301 302 //! returns the separable linear filter engine 303 Ptr<FilterEngine> createSeparableLinearFilter(int srcType, int dstType, 304 InputArray rowKernel, InputArray columnKernel, 305 Point anchor = Point(-1,-1), double delta = 0, 306 int rowBorderType = BORDER_DEFAULT, 307 int columnBorderType = -1, 308 const Scalar& borderValue = Scalar()); 309 310 //! returns the non-separable linear filter engine 311 Ptr<FilterEngine> createLinearFilter(int srcType, int dstType, 312 InputArray kernel, Point _anchor = Point(-1,-1), 313 double delta = 0, int rowBorderType = BORDER_DEFAULT, 314 int columnBorderType = -1, const Scalar& borderValue = Scalar()); 315 316 //! returns the Gaussian filter engine 317 Ptr<FilterEngine> createGaussianFilter( int type, Size ksize, 318 double sigma1, double sigma2 = 0, 319 int borderType = BORDER_DEFAULT); 320 321 //! returns filter engine for the generalized Sobel operator 322 Ptr<FilterEngine> createDerivFilter( int srcType, int dstType, 323 int dx, int dy, int ksize, 324 int borderType = BORDER_DEFAULT ); 325 326 //! returns horizontal 1D box filter 327 Ptr<BaseRowFilter> getRowSumFilter(int srcType, int sumType, 328 int ksize, int anchor = -1); 329 330 //! returns vertical 1D box filter 331 Ptr<BaseColumnFilter> getColumnSumFilter( int sumType, int dstType, 332 int ksize, int anchor = -1, 333 double scale = 1); 334 //! returns box filter engine 335 Ptr<FilterEngine> createBoxFilter( int srcType, int dstType, Size ksize, 336 Point anchor = Point(-1,-1), 337 bool normalize = true, 338 int borderType = BORDER_DEFAULT); 339 340 341 //! returns horizontal 1D morphological filter 342 Ptr<BaseRowFilter> getMorphologyRowFilter(int op, int type, int ksize, int anchor = -1); 343 344 //! returns vertical 1D morphological filter 345 Ptr<BaseColumnFilter> getMorphologyColumnFilter(int op, int type, int ksize, int anchor = -1); 346 347 //! returns 2D morphological filter 348 Ptr<BaseFilter> getMorphologyFilter(int op, int type, InputArray kernel, 349 Point anchor = Point(-1,-1)); 350 351 //! returns morphological filter engine. Only MORPH_ERODE and MORPH_DILATE are supported. 352 CV_EXPORTS Ptr<FilterEngine> createMorphologyFilter(int op, int type, InputArray kernel, 353 Point anchor = Point(-1,-1), int rowBorderType = BORDER_CONSTANT, 354 int columnBorderType = -1, 355 const Scalar& borderValue = morphologyDefaultBorderValue()); 356 357 static inline Point normalizeAnchor( Point anchor, Size ksize ) 358 { 359 if( anchor.x == -1 ) 360 anchor.x = ksize.width/2; 361 if( anchor.y == -1 ) 362 anchor.y = ksize.height/2; 363 CV_Assert( anchor.inside(Rect(0, 0, ksize.width, ksize.height)) ); 364 return anchor; 365 } 366 367 void preprocess2DKernel( const Mat& kernel, std::vector<Point>& coords, std::vector<uchar>& coeffs ); 368 void crossCorr( const Mat& src, const Mat& templ, Mat& dst, 369 Size corrsize, int ctype, 370 Point anchor=Point(0,0), double delta=0, 371 int borderType=BORDER_REFLECT_101 ); 372 373 } 374 375 #endif 376
