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
isSeparable() const245 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
normalizeAnchor(Point anchor,Size ksize)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