===============
Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images (represented as
-:func:`Mat` 's), that is, for each pixel location
-:math:`(x,y)` in the source image some its (normally rectangular) neighborhood is considered and used to compute the response. In case of a linear filter it is a weighted sum of pixel values, in case of morphological operations it is the minimum or maximum etc. The computed response is stored to the destination image at the same location
-:math:`(x,y)` . It means, that the output image will be of the same size as the input image. Normally, the functions supports multi-channel arrays, in which case every channel is processed independently, therefore the output image will also have the same number of channels as the input one.
+:func:`Mat`'s). It means that for each pixel location
+:math:`(x,y)` in the source image (normally, rectangular), its neighborhood is considered and used to compute the response. In case of a linear filter, it is a weighted sum of pixel values. In case of morphological operations, it is the minimum or maximum values, and so on. The computed response is stored in the destination image at the same location
+:math:`(x,y)` . It means that the output image will be of the same size as the input image. Normally, the functions support multi-channel arrays, in which case every channel is processed independently. Therefore, the output image will also have the same number of channels as the input one.
-Another common feature of the functions and classes described in this section is that, unlike simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For example, if we want to smooth an image using a Gaussian
-:math:`3 \times 3` filter, then during the processing of the left-most pixels in each row we need pixels to the left of them, i.e. outside of the image. We can let those pixels be the same as the left-most image pixels (i.e. use "replicated border" extrapolation method), or assume that all the non-existing pixels are zeros ("contant border" extrapolation method) etc.
-OpenCV let the user to specify the extrapolation method; see the function :func:`borderInterpolate` and discussion of ``borderType`` parameter in various functions below.
+Another common feature of the functions and classes described in this section is that, unlike simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For example, if you want to smooth an image using a Gaussian
+:math:`3 \times 3` filter, then, when processing the left-most pixels in each row, you need pixels to the left of them, that is, outside of the image. You can let these pixels be the same as the left-most image pixels ("replicated border" extrapolation method), or assume that all the non-existing pixels are zeros ("contant border" extrapolation method), and so on.
+OpenCV enables you to specify the extrapolation method. For details, see the function :func:`borderInterpolate` and discussion of the ``borderType`` parameter in various functions below.
.. index:: BaseColumnFilter
// To be overriden by the user.
//
- // runs filtering operation on the set of rows,
+ // runs a filtering operation on the set of rows,
// "dstcount + ksize - 1" rows on input,
// "dstcount" rows on output,
// each input and output row has "width" elements
};
-The class ``BaseColumnFilter`` is the base class for filtering data using single-column kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
+The class ``BaseColumnFilter`` is a base class for filtering data using single-column kernels. Filtering does not have to be a linear operation. In general, it could be written as follows:
.. math::
\texttt{dst} (x,y) = F( \texttt{src} [y](x), \; \texttt{src} [y+1](x), \; ..., \; \texttt{src} [y+ \texttt{ksize} -1](x)
where
-:math:`F` is the filtering function, but, as it is represented as a class, it can produce any side effects, memorize previously processed data etc. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to
-:func:`FilterEngine` constructor. While the filtering operation interface uses ``uchar`` type, a particular implementation is not limited to 8-bit data.
+:math:`F` is a filtering function but, as it is represented as a class, it can produce any side effects, memorize previously processed data, and so on. The class only defines an interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to the
+:func:`FilterEngine` constructor. While the filtering operation interface uses the ``uchar`` type, a particular implementation is not limited to 8-bit data.
+
+See Also:
+:func:`BaseRowFilter`,
+:func:`BaseFilter`,
+:func:`FilterEngine`,
+:func:`getColumnSumFilter`,
+:func:`getLinearColumnFilter`,
+:func:`getMorphologyColumnFilter`
-See also:
-:func:`BaseRowFilter`,:func:`BaseFilter`,:func:`FilterEngine`,
-:func:`getColumnSumFilter`,:func:`getLinearColumnFilter`,:func:`getMorphologyColumnFilter`
.. index:: BaseFilter
.. _BaseFilter:
// To be overriden by the user.
//
- // runs filtering operation on the set of rows,
+ // runs a filtering operation on the set of rows,
// "dstcount + ksize.height - 1" rows on input,
// "dstcount" rows on output,
// each input row has "(width + ksize.width-1)*cn" elements
};
-The class ``BaseFilter`` is the base class for filtering data using 2D kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
+The class ``BaseFilter`` is a base class for filtering data using 2D kernels. Filtering does not have to be a linear operation. In general, it could be written as follows:
.. math::
\end{array}
where
-:math:`F` is the filtering function. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to
-:func:`FilterEngine` constructor. While the filtering operation interface uses ``uchar`` type, a particular implementation is not limited to 8-bit data.
+:math:`F` is a filtering function. The class only defines an interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to the
+:func:`FilterEngine` constructor. While the filtering operation interface uses the ``uchar`` type, a particular implementation is not limited to 8-bit data.
+
+See Also:
+:func:`BaseColumnFilter`,
+:func:`BaseRowFilter`,
+:func:`FilterEngine`,
+:func:`getLinearFilter`,
+:func:`getMorphologyFilter`
-See also:
-:func:`BaseColumnFilter`,:func:`BaseRowFilter`,:func:`FilterEngine`,
-:func:`getLinearFilter`,:func:`getMorphologyFilter`
.. index:: BaseRowFilter
.. _BaseRowFilter:
};
-The class ``BaseRowFilter`` is the base class for filtering data using single-row kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
+The class ``BaseRowFilter`` is a base class for filtering data using single-row kernels. Filtering does not have to be a linear operation. In general, it could be written as follows:
.. math::
\texttt{dst} (x,y) = F( \texttt{src} [y](x), \; \texttt{src} [y](x+1), \; ..., \; \texttt{src} [y](x+ \texttt{ksize.width} -1))
where
-:math:`F` is the filtering function. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to
-:func:`FilterEngine` constructor. While the filtering operation interface uses ``uchar`` type, a particular implementation is not limited to 8-bit data.
+:math:`F` is a filtering function. The class only defines an interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to the
+:func:`FilterEngine` constructor. While the filtering operation interface uses the ``uchar`` type, a particular implementation is not limited to 8-bit data.
+
+See Also:
+:func:`BaseColumnFilter`,
+:func:`Filter`,
+:func:`FilterEngine`,
+:func:`getLinearRowFilter`,
+:func:`getMorphologyRowFilter`,
+:func:`getRowSumFilter`
-See also:
-:func:`BaseColumnFilter`,:func:`Filter`,:func:`FilterEngine`,
-:func:`getLinearRowFilter`,:func:`getMorphologyRowFilter`,:func:`getRowSumFilter`
.. index:: FilterEngine
.. _FilterEngine:
// alternative form of start that takes the image
// itself instead of "wholeSize". Set isolated to true to pretend that
// there are no real pixels outside of the ROI
- // (so that the pixels will be extrapolated using the specified border modes)
+ // (so that the pixels are extrapolated using the specified border modes)
virtual int start(const Mat& src, const Rect& srcRoi=Rect(0,0,-1,-1),
bool isolated=false, int maxBufRows=-1);
// processes the next portion of the source image,
// "srcCount" rows starting from "src" and
- // stores the results to "dst".
+ // stores the results in "dst".
// returns the number of produced rows
virtual int proceed(const uchar* src, int srcStep, int srcCount,
uchar* dst, int dstStep);
The class ``FilterEngine`` can be used to apply an arbitrary filtering operation to an image.
-It contains all the necessary intermediate buffers, it computes extrapolated values
-of the "virtual" pixels outside of the image etc. Pointers to the initialized ``FilterEngine`` instances
-are returned by various ``create*Filter`` functions, see below, and they are used inside high-level functions such as
-:func:`filter2D`,:func:`erode`,:func:`dilate` etc, that is, the class is the workhorse in many of OpenCV filtering functions.
-
-This class makes it easier (though, maybe not very easy yet) to combine filtering operations with other operations, such as color space conversions, thresholding, arithmetic operations, etc. By combining several operations together you can get much better performance because your data will stay in cache. For example, below is the implementation of Laplace operator for a floating-point images, which is a simplified implementation of
+It contains all the necessary intermediate buffers, computes extrapolated values
+of the "virtual" pixels outside of the image, and so on. Pointers to the initialized ``FilterEngine`` instances
+are returned by various ``create*Filter`` functions (see below) and they are used inside high-level functions such as
+:func:`filter2D`,
+:func:`erode`,
+:func:`dilate`, and others. Thus, the class plays a key role in many of OpenCV filtering functions.
+
+This class makes it easier to combine filtering operations with other operations, such as color space conversions, thresholding, arithmetic operations, and others. By combining several operations together you can get much better performance because your data will stay in cache. For example, see below the implementation of the Laplace operator for floating-point images, which is a simplified implementation of
:func:`Laplacian` : ::
void laplace_f(const Mat& src, Mat& dst)
dst.create(src.size(), src.type());
// get the derivative and smooth kernels for d2I/dx2.
- // for d2I/dy2 we could use the same kernels, just swapped
+ // for d2I/dy2 consider using the same kernels, just swapped
Mat kd, ks;
getSobelKernels( kd, ks, 2, 0, ksize, false, ktype );
- // let's process 10 source rows at once
+ // process 10 source rows at once
int DELTA = std::min(10, src.rows);
Ptr<FilterEngine> Fxx = createSeparableLinearFilter(src.type(),
dst.type(), kd, ks, Point(-1,-1), 0, borderType, borderType, Scalar() );
Mat Ixx( DELTA + kd.rows - 1, src.cols, dst.type() );
Mat Iyy( DELTA + kd.rows - 1, src.cols, dst.type() );
- // inside the loop we always pass DELTA rows to the filter
+ // inside the loop always pass DELTA rows to the filter
// (note that the "proceed" method takes care of possibe overflow, since
// it was given the actual image height in the "start" method)
- // on output we can get:
- // * < DELTA rows (the initial buffer accumulation stage)
+ // on output you can get:
+ // * < DELTA rows (initial buffer accumulation stage)
// * = DELTA rows (settled state in the middle)
- // * > DELTA rows (then the input image is over, but we generate
+ // * > DELTA rows (when the input image is over, generate
// "virtual" rows using the border mode and filter them)
// this variable number of output rows is dy.
// dsty is the current output row.
if( _srcRoi == Rect(0,0,-1,-1) )
_srcRoi = Rect(0,0,src.cols,src.rows);
- // check if the destination ROI is inside the dst.
+ // check if the destination ROI is inside dst.
// and FilterEngine::start will check if the source ROI is inside src.
CV_Assert( dstOfs.x >= 0 && dstOfs.y >= 0 &&
dstOfs.x + _srcRoi.width <= dst.cols &&
}
-Unlike the earlier versions of OpenCV, now the filtering operations fully support the notion of image ROI, that is, pixels outside of the ROI but inside the image can be used in the filtering operations. For example, you can take a ROI of a single pixel and filter it - that will be a filter response at that particular pixel (however, it's possible to emulate the old behavior by passing ``isolated=false`` to ``FilterEngine::start`` or ``FilterEngine::apply`` ). You can pass the ROI explicitly to ``FilterEngine::apply`` , or construct a new matrix headers: ::
+Unlike the earlier versions of OpenCV, now the filtering operations fully support the notion of image ROI, that is, pixels outside of the ROI but inside the image can be used in the filtering operations. For example, you can take a ROI of a single pixel and filter it. This will be a filter response at that particular pixel. However, it is possible to emulate the old behavior by passing ``isolated=false`` to ``FilterEngine::start`` or ``FilterEngine::apply`` . You can pass the ROI explicitly to ``FilterEngine::apply`` or construct a new matrix headers: ::
// compute dI/dx derivative at src(x,y)
printf("method1 =
-Note on the data types. As it was mentioned in
+Explore the data types. As it was mentioned in the
:func:`BaseFilter` description, the specific filters can process data of any type, despite that ``Base*Filter::operator()`` only takes ``uchar`` pointers and no information about the actual types. To make it all work, the following rules are used:
*
- in case of separable filtering ``FilterEngine::rowFilter`` applied first. It transforms the input image data (of type ``srcType`` ) to the intermediate results stored in the internal buffers (of type ``bufType`` ). Then these intermediate results are processed
- *as single-channel data*
- with ``FilterEngine::columnFilter`` and stored in the output image (of type ``dstType`` ). Thus, the input type for ``rowFilter`` is ``srcType`` and the output type is ``bufType`` ; the input type for ``columnFilter`` is ``CV_MAT_DEPTH(bufType)`` and the output type is ``CV_MAT_DEPTH(dstType)`` .
+ In case of separable filtering, ``FilterEngine::rowFilter`` is applied first. It transforms the input image data (of type ``srcType`` ) to the intermediate results stored in the internal buffers (of type ``bufType`` ). Then, these intermediate results are processed as
+ *single-channel data*
+ with ``FilterEngine::columnFilter`` and stored in the output image (of type ``dstType`` ). Thus, the input type for ``rowFilter`` is ``srcType`` and the output type is ``bufType`` . The input type for ``columnFilter`` is ``CV_MAT_DEPTH(bufType)`` and the output type is ``CV_MAT_DEPTH(dstType)`` .
*
- in case of non-separable filtering ``bufType`` must be the same as ``srcType`` . The source data is copied to the temporary buffer if needed and then just passed to ``FilterEngine::filter2D`` . That is, the input type for ``filter2D`` is ``srcType`` (= ``bufType`` ) and the output type is ``dstType`` .
+ In case of non-separable filtering, ``bufType`` must be the same as ``srcType`` . The source data is copied to the temporary buffer, if needed, and then just passed to ``FilterEngine::filter2D`` . That is, the input type for ``filter2D`` is ``srcType`` (= ``bufType`` ) and the output type is ``dstType`` .
+
+See Also:
+:func:`BaseColumnFilter`,
+:func:`BaseFilter`,
+:func:`BaseRowFilter`,
+:func:`createBoxFilter`,
+:func:`createDerivFilter`,
+:func:`createGaussianFilter`,
+:func:`createLinearFilter`,
+:func:`createMorphologyFilter`,
+:func:`createSeparableLinearFilter`
-See also:
-:func:`BaseColumnFilter`,:func:`BaseFilter`,:func:`BaseRowFilter`,:func:`createBoxFilter`,:func:`createDerivFilter`,:func:`createGaussianFilter`,:func:`createLinearFilter`,:func:`createMorphologyFilter`,:func:`createSeparableLinearFilter`
.. index:: bilateralFilter
bilateralFilter
-------------------
.. c:function:: void bilateralFilter( const Mat\& src, Mat\& dst, int d, double sigmaColor, double sigmaSpace, int borderType=BORDER_DEFAULT )
- Applies bilateral filter to the image
+ Applies the bilateral filter to an image.
- :param src: The source 8-bit or floating-point, 1-channel or 3-channel image
+ :param src: Source 8-bit or floating-point, 1-channel or 3-channel image.
- :param dst: The destination image; will have the same size and the same type as ``src``
+ :param dst: Destination image of the same size and type as ``src`` .
- :param d: The diameter of each pixel neighborhood, that is used during filtering. If it is non-positive, it's computed from ``sigmaSpace``
+ :param d: Diameter of each pixel neighborhood that is used during filtering. If it is non-positive, it is computed from ``sigmaSpace`` .
- :param sigmaColor: Filter sigma in the color space. Larger value of the parameter means that farther colors within the pixel neighborhood (see ``sigmaSpace`` ) will be mixed together, resulting in larger areas of semi-equal color
+ :param sigmaColor: Filter sigma in the color space. A larger value of the parameter means that farther colors within the pixel neighborhood (see ``sigmaSpace`` ) will be mixed together, resulting in larger areas of semi-equal color.
- :param sigmaSpace: Filter sigma in the coordinate space. Larger value of the parameter means that farther pixels will influence each other (as long as their colors are close enough; see ``sigmaColor`` ). Then ``d>0`` , it specifies the neighborhood size regardless of ``sigmaSpace`` , otherwise ``d`` is proportional to ``sigmaSpace``
+ :param sigmaSpace: Filter sigma in the coordinate space. A larger value of the parameter means that farther pixels will influence each other as long as their colors are close enough (see ``sigmaColor`` ). When ``d>0`` , it specifies the neighborhood size regardless of ``sigmaSpace`` . Otherwise, ``d`` is proportional to ``sigmaSpace`` .
The function applies bilateral filtering to the input image, as described in
http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/MANDUCHI1/Bilateral\_Filtering.html
--------
.. c:function:: void blur( const Mat\& src, Mat\& dst, Size ksize, Point anchor=Point(-1,-1), int borderType=BORDER_DEFAULT )
- Smoothes image using normalized box filter
+ Smoothes an image using the normalized box filter.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image; will have the same size and the same type as ``src``
+ :param dst: Destination image of the same size and type as ``src`` .
- :param ksize: The smoothing kernel size
+ :param ksize: Smoothing kernel size.
- :param anchor: The anchor point. The default value ``Point(-1,-1)`` means that the anchor is at the kernel center
+ :param anchor: Anchor point. The default value ``Point(-1,-1)`` means that the anchor is at the kernel center.
- :param borderType: The border mode used to extrapolate pixels outside of the image
+ :param borderType: Border mode used to extrapolate pixels outside of the image.
-The function smoothes the image using the kernel:
+The function smoothes an image using the kernel:
.. math::
The call ``blur(src, dst, ksize, anchor, borderType)`` is equivalent to ``boxFilter(src, dst, src.type(), anchor, true, borderType)`` .
-See also:
-:func:`boxFilter`,:func:`bilateralFilter`,:func:`GaussianBlur`,:func:`medianBlur` .
+See Also:
+:func:`boxFilter`,
+:func:`bilateralFilter`,
+:func:`GaussianBlur`,
+:func:`medianBlur`
.. index:: borderInterpolate
---------------------
.. c:function:: int borderInterpolate( int p, int len, int borderType )
- Computes source location of extrapolated pixel
+ Computes the source location of an extrapolated pixel.
- :param p: 0-based coordinate of the extrapolated pixel along one of the axes, likely <0 or >= ``len``
+ :param p: 0-based coordinate of the extrapolated pixel along one of the axes, likely <0 or >= ``len`` .
- :param len: length of the array along the corresponding axis
+ :param len: Length of the array along the corresponding axis.
- :param borderType: the border type, one of the ``BORDER_*`` , except for ``BORDER_TRANSPARENT`` and ``BORDER_ISOLATED`` . When ``borderType==BORDER_CONSTANT`` the function always returns -1, regardless of ``p`` and ``len``
+ :param borderType: Border type, one of the ``BORDER_*`` , except for ``BORDER_TRANSPARENT`` and ``BORDER_ISOLATED`` . When ``borderType==BORDER_CONSTANT`` , the function always returns -1, regardless of ``p`` and ``len`` .
The function computes and returns the coordinate of the donor pixel, corresponding to the specified extrapolated pixel when using the specified extrapolation border mode. For example, if we use ``BORDER_WRAP`` mode in the horizontal direction, ``BORDER_REFLECT_101`` in the vertical direction and want to compute value of the "virtual" pixel ``Point(-5, 100)`` in a floating-point image ``img`` , it will be ::
borderInterpolate(-5, img.cols, BORDER_WRAP));
-Normally, the function is not called directly; it is used inside
+Normally, the function is not called directly. It is used inside
:func:`FilterEngine` and
:func:`copyMakeBorder` to compute tables for quick extrapolation.
-See also:
-:func:`FilterEngine`,:func:`copyMakeBorder`
+See Also:
+:func:`FilterEngine`,
+:func:`copyMakeBorder`
.. index:: boxFilter
-------------
.. c:function:: void boxFilter( const Mat\& src, Mat\& dst, int ddepth, Size ksize, Point anchor=Point(-1,-1), bool normalize=true, int borderType=BORDER_DEFAULT )
- Smoothes image using box filter
+ Smoothes an image using the box filter.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image; will have the same size and the same type as ``src``
+ :param dst: Destination image of the same size and type as ``src`` .
- :param ksize: The smoothing kernel size
+ :param ksize: Smoothing kernel size.
- :param anchor: The anchor point. The default value ``Point(-1,-1)`` means that the anchor is at the kernel center
+ :param anchor: Anchor point. The default value ``Point(-1,-1)`` means that the anchor is at the kernel center.
- :param normalize: Indicates, whether the kernel is normalized by its area or not
+ :param normalize: Flag specifying whether the kernel is normalized by its area or not.
- :param borderType: The border mode used to extrapolate pixels outside of the image
+ :param borderType: Border mode used to extrapolate pixels outside of the image.
-The function smoothes the image using the kernel:
+The function smoothes an image using the kernel:
.. math::
\alpha = \fork{\frac{1}{\texttt{ksize.width*ksize.height}}}{when \texttt{normalize=true}}{1}{otherwise}
-Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariation matrices of image derivatives (used in dense optical flow algorithms,
-etc.). If you need to compute pixel sums over variable-size windows, use
+Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariance matrices of image derivatives (used in dense optical flow algorithms,
+and so on). If you need to compute pixel sums over variable-size windows, use
:func:`integral` .
-See also:
-:func:`boxFilter`,:func:`bilateralFilter`,:func:`GaussianBlur`,:func:`medianBlur`,:func:`integral` .
+See Also:
+:func:`boxFilter`,
+:func:`bilateralFilter`,
+:func:`GaussianBlur`,
+:func:`medianBlur`,
+:func:`integral`
.. index:: buildPyramid
----------------
.. c:function:: void buildPyramid( const Mat\& src, vector<Mat>\& dst, int maxlevel )
- Constructs Gaussian pyramid for an image
+ Constructs the Gaussian pyramid for an image.
- :param src: The source image; check :func:`pyrDown` for the list of supported types
+ :param src: Source image. Check :func:`pyrDown` for the list of supported types.
- :param dst: The destination vector of ``maxlevel+1`` images of the same type as ``src`` ; ``dst[0]`` will be the same as ``src`` , ``dst[1]`` is the next pyramid layer,
- a smoothed and down-sized ``src`` etc.
+ :param dst: Destination vector of ``maxlevel+1`` images of the same type as ``src`` . ``dst[0]`` will be the same as ``src`` . ``dst[1]`` is the next pyramid layer,
+ a smoothed and down-sized ``src`` , and so on.
- :param maxlevel: The 0-based index of the last (i.e. the smallest) pyramid layer; it must be non-negative
+ :param maxlevel: 0-based index of the last (the smallest) pyramid layer. It must be non-negative.
-The function constructs a vector of images and builds the gaussian pyramid by recursively applying
+The function constructs a vector of images and builds the Gaussian pyramid by recursively applying
:func:`pyrDown` to the previously built pyramid layers, starting from ``dst[0]==src`` .
.. index:: copyMakeBorder
------------------
.. c:function:: void copyMakeBorder( const Mat\& src, Mat\& dst, int top, int bottom, int left, int right, int borderType, const Scalar\& value=Scalar() )
- Forms a border around the image
+ Forms a border around an image.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image; will have the same type as ``src`` and the size ``Size(src.cols+left+right, src.rows+top+bottom)``
+ :param dst: Destination image of the same type as ``src`` and the size ``Size(src.cols+left+right, src.rows+top+bottom)`` .
- :param top, bottom, left, right: Specify how much pixels in each direction from the source image rectangle one needs to extrapolate, e.g. ``top=1, bottom=1, left=1, right=1`` mean that 1 pixel-wide border needs to be built
+ :param top, bottom, left, right: Parameter specifying how many pixels in each direction from the source image rectangle to extrapolate. For example, ``top=1, bottom=1, left=1, right=1`` mean that 1 pixel-wide border needs to be built.
- :param borderType: The border type; see :func:`borderInterpolate`
+ :param borderType: Border type. See :func:`borderInterpolate` for details.
- :param value: The border value if ``borderType==BORDER_CONSTANT``
+ :param value: Border value if ``borderType==BORDER_CONSTANT`` .
The function copies the source image into the middle of the destination image. The areas to the left, to the right, above and below the copied source image will be filled with extrapolated pixels. This is not what
-:func:`FilterEngine` or based on it filtering functions do (they extrapolate pixels on-fly), but what other more complex functions, including your own, may do to simplify image boundary handling.
+:func:`FilterEngine` or filtering functions based on it do (they extrapolate pixels on-fly), but what other more complex functions, including your own, may do to simplify image boundary handling.
-The function supports the mode when ``src`` is already in the middle of ``dst`` . In this case the function does not copy ``src`` itself, but simply constructs the border, e.g.: ::
+The function supports the mode when ``src`` is already in the middle of ``dst`` . In this case, the function does not copy ``src`` itself but simply constructs the border, for example: ::
// let border be the same in all directions
int border=2;
...
-See also:
+See Also:
:func:`borderInterpolate`
.. index:: createBoxFilter
.. c:function:: Ptr<BaseColumnFilter> getColumnSumFilter(int sumType, int dstType, int ksize, int anchor=-1, double scale=1)
- Returns box filter engine
+ Returns a box filter engine.
- :param srcType: The source image type
+ :param srcType: Source image type.
- :param sumType: The intermediate horizontal sum type; must have as many channels as ``srcType``
+ :param sumType: Intermediate horizontal sum type that must have as many channels as ``srcType`` .
- :param dstType: The destination image type; must have as many channels as ``srcType``
+ :param dstType: Destination image type that must have as many channels as ``srcType`` .
- :param ksize: The aperture size
+ :param ksize: Aperture size.
- :param anchor: The anchor position with the kernel; negative values mean that the anchor is at the kernel center
+ :param anchor: Anchor position with the kernel. Negative values mean that the anchor is at the kernel center.
- :param normalize: Whether the sums are normalized or not; see :func:`boxFilter`
+ :param normalize: Flag specifying whether the sums are normalized or not. See :func:`boxFilter` for details.
- :param scale: Another way to specify normalization in lower-level ``getColumnSumFilter``
+ :param scale: Another way to specify normalization in lower-level ``getColumnSumFilter`` .
- :param borderType: Which border type to use; see :func:`borderInterpolate`
+ :param borderType: Border type to use. See :func:`borderInterpolate` .
-The function is a convenience function that retrieves horizontal sum primitive filter with
+The function is a convenience function that retrieves the horizontal sum primitive filter with
:func:`getRowSumFilter` , vertical sum filter with
:func:`getColumnSumFilter` , constructs new
-:func:`FilterEngine` and passes both of the primitive filters there. The constructed filter engine can be used for image filtering with normalized or unnormalized box filter.
+:func:`FilterEngine` , and passes both of the primitive filters there. The constructed filter engine can be used for image filtering with normalized or unnormalized box filter.
The function itself is used by
:func:`blur` and
:func:`boxFilter` .
-See also:
-:func:`FilterEngine`,:func:`blur`,:func:`boxFilter` .
+See Also:
+:func:`FilterEngine`,
+:func:`blur`,
+:func:`boxFilter`
.. index:: createDerivFilter
---------------------
.. c:function:: Ptr<FilterEngine> createDerivFilter( int srcType, int dstType, int dx, int dy, int ksize, int borderType=BORDER_DEFAULT )
- Returns engine for computing image derivatives
+ Returns an engine for computing image derivatives.
- :param srcType: The source image type
+ :param srcType: Source image type.
- :param dstType: The destination image type; must have as many channels as ``srcType``
+ :param dstType: Destination image type that must have as many channels as ``srcType`` .
- :param dx: The derivative order in respect with x
+ :param dx: Derivative order in respect of x.
- :param dy: The derivative order in respect with y
+ :param dy: Derivative order in respect of y.
- :param ksize: The aperture size; see :func:`getDerivKernels`
+ :param ksize: Aperture size See :func:`getDerivKernels` .
- :param borderType: Which border type to use; see :func:`borderInterpolate`
+ :param borderType: Border type to use. See :func:`borderInterpolate` .
The function :func:`createDerivFilter` is a small convenience function that retrieves linear filter coefficients for computing image derivatives using
:func:`getDerivKernels` and then creates a separable linear filter with
:func:`Sobel` and
:func:`Scharr` .
-See also:
-:func:`createSeparableLinearFilter`,:func:`getDerivKernels`,:func:`Scharr`,:func:`Sobel` .
+See Also:
+:func:`createSeparableLinearFilter`,
+:func:`getDerivKernels`,
+:func:`Scharr`,
+:func:`Sobel`
.. index:: createGaussianFilter
------------------------
.. c:function:: Ptr<FilterEngine> createGaussianFilter( int type, Size ksize, double sigmaX, double sigmaY=0, int borderType=BORDER_DEFAULT)
- Returns engine for smoothing images with a Gaussian filter
+ Returns an engine for smoothing images with the Gaussian filter.
- :param type: The source and the destination image type
+ :param type: Source and destination image type.
- :param ksize: The aperture size; see :func:`getGaussianKernel`
+ :param ksize: Aperture size. See :func:`getGaussianKernel` .
- :param sigmaX: The Gaussian sigma in the horizontal direction; see :func:`getGaussianKernel`
+ :param sigmaX: Gaussian sigma in the horizontal direction. See :func:`getGaussianKernel` .
- :param sigmaY: The Gaussian sigma in the vertical direction; if 0, then :math:`\texttt{sigmaY}\leftarrow\texttt{sigmaX}`
+ :param sigmaY: Gaussian sigma in the vertical direction. If 0, then :math:`\texttt{sigmaY}\leftarrow\texttt{sigmaX}` .
- :param borderType: Which border type to use; see :func:`borderInterpolate`
+ :param borderType: Border type to use. See :func:`borderInterpolate` .
-The function :func:`createGaussianFilter` computes Gaussian kernel coefficients and then returns separable linear filter for that kernel. The function is used by
-:func:`GaussianBlur` . Note that while the function takes just one data type, both for input and output, you can pass by this limitation by calling
+The function :func:`createGaussianFilter` computes Gaussian kernel coefficients and then returns a separable linear filter for that kernel. The function is used by
+:func:`GaussianBlur` . Note that while the function takes just one data type, both for input and output, you can pass this limitation by calling
:func:`getGaussianKernel` and then
:func:`createSeparableFilter` directly.
-See also:
-:func:`createSeparableLinearFilter`,:func:`getGaussianKernel`,:func:`GaussianBlur` .
+See Also:
+:func:`createSeparableLinearFilter`,
+:func:`getGaussianKernel`,
+:func:`GaussianBlur`
.. index:: createLinearFilter
.. c:function:: Ptr<BaseFilter> getLinearFilter(int srcType, int dstType, const Mat\& kernel, Point anchor=Point(-1,-1), double delta=0, int bits=0)
- Creates non-separable linear filter engine
+ Creates a non-separable linear filter engine.
- :param srcType: The source image type
+ :param srcType: Source image type.
- :param dstType: The destination image type; must have as many channels as ``srcType``
+ :param dstType: Destination image type that must have as many channels as ``srcType`` .
- :param kernel: The 2D array of filter coefficients
+ :param kernel: 2D array of filter coefficients.
- :param anchor: The anchor point within the kernel; special value ``Point(-1,-1)`` means that the anchor is at the kernel center
+ :param anchor: Anchor point within the kernel. Special value ``Point(-1,-1)`` means that the anchor is at the kernel center.
- :param delta: The value added to the filtered results before storing them
+ :param delta: Value added to the filtered results before storing them.
- :param bits: When the kernel is an integer matrix representing fixed-point filter coefficients,
- the parameter specifies the number of the fractional bits
+ :param bits: Number of the fractional bits. the parameter is used when the kernel is an integer matrix representing fixed-point filter coefficients.
- :param rowBorderType, columnBorderType: The pixel extrapolation methods in the horizontal and the vertical directions; see :func:`borderInterpolate`
+ :param rowBorderType, columnBorderType: Pixel extrapolation methods in the horizontal and vertical directions. See :func:`borderInterpolate` for details.
- :param borderValue: Used in case of constant border
+ :param borderValue: Border vaule used in case of a constant border.
-The function returns pointer to 2D linear filter for the specified kernel, the source array type and the destination array type. The function is a higher-level function that calls ``getLinearFilter`` and passes the retrieved 2D filter to
+The function returns a pointer to a 2D linear filter for the specified kernel, the source array type, and the destination array type. The function is a higher-level function that calls ``getLinearFilter`` and passes the retrieved 2D filter to the
:func:`FilterEngine` constructor.
-See also:
-:func:`createSeparableLinearFilter`,:func:`FilterEngine`,:func:`filter2D`
+See Also:
+:func:`createSeparableLinearFilter`,
+:func:`FilterEngine`,
+:func:`filter2D`
.. index:: createMorphologyFilter
createMorphologyFilter
.. c:function:: static inline Scalar morphologyDefaultBorderValue(){ return Scalar::all(DBL_MAX) }
- Creates engine for non-separable morphological operations
+ Creates an engine for non-separable morphological operations.
- :param op: The morphology operation id, ``MORPH_ERODE`` or ``MORPH_DILATE``
+ :param op: Morphology operation id, ``MORPH_ERODE`` or ``MORPH_DILATE`` .
- :param type: The input/output image type
+ :param type: Input/output image type.
- :param element: The 2D 8-bit structuring element for the morphological operation. Non-zero elements indicate the pixels that belong to the element
+ :param element: 2D 8-bit structuring element for a morphological operation. Non-zero elements indicate the pixels that belong to the element.
- :param esize: The horizontal or vertical structuring element size for separable morphological operations
+ :param esize: Horizontal or vertical structuring element size for separable morphological operations.
- :param anchor: The anchor position within the structuring element; negative values mean that the anchor is at the center
+ :param anchor: Anchor position within the structuring element. Negative values mean that the anchor is at the kernel center.
- :param rowBorderType, columnBorderType: The pixel extrapolation methods in the horizontal and the vertical directions; see :func:`borderInterpolate`
+ :param rowBorderType, columnBorderType: Pixel extrapolation methods in the horizontal and vertical directions. See :func:`borderInterpolate` for details.
- :param borderValue: The border value in case of a constant border. The default value, \ ``morphologyDefaultBorderValue`` , has the special meaning. It is transformed :math:`+\inf` for the erosion and to :math:`-\inf` for the dilation, which means that the minimum (maximum) is effectively computed only over the pixels that are inside the image.
+ :param borderValue: Border value in case of a constant border. The default value, \ ``morphologyDefaultBorderValue`` , has a special meaning. It is transformed :math:`+\inf` for the erosion and to :math:`-\inf` for the dilation, which means that the minimum (maximum) is effectively computed only over the pixels that are inside the image.
-The functions construct primitive morphological filtering operations or a filter engine based on them. Normally it's enough to use
+The functions construct primitive morphological filtering operations or a filter engine based on them. Normally it is enough to use
:func:`createMorphologyFilter` or even higher-level
-:func:`erode`,:func:`dilate` or
-:func:`morphologyEx` , Note, that
-:func:`createMorphologyFilter` analyses the structuring element shape and builds a separable morphological filter engine when the structuring element is square.
-
-See also:
-:func:`erode`,:func:`dilate`,:func:`morphologyEx`,:func:`FilterEngine`
+:func:`erode`,
+:func:`dilate` , or
+:func:`morphologyEx` .
+Note that
+:func:`createMorphologyFilter` analyzes the structuring element shape and builds a separable morphological filter engine when the structuring element is square.
+
+See Also:
+:func:`erode`,
+:func:`dilate`,
+:func:`morphologyEx`,
+:func:`FilterEngine`
.. index:: createSeparableLinearFilter
createSeparableLinearFilter
.. c:function:: Ptr<BaseRowFilter> getLinearRowFilter(int srcType, int bufType, const Mat\& rowKernel, int anchor, int symmetryType)
- Creates engine for separable linear filter
+ Creates an engine for a separable linear filter.
- :param srcType: The source array type
+ :param srcType: Source array type.
- :param dstType: The destination image type; must have as many channels as ``srcType``
+ :param dstType: Destination image type that must have as many channels as ``srcType`` .
- :param bufType: The inermediate buffer type; must have as many channels as ``srcType``
+ :param bufType: Intermediate buffer type that must have as many channels as ``srcType`` .
- :param rowKernel: The coefficients for filtering each row
+ :param rowKernel: Coefficients for filtering each row.
- :param columnKernel: The coefficients for filtering each column
+ :param columnKernel: Coefficients for filtering each column.
- :param anchor: The anchor position within the kernel; negative values mean that anchor is positioned at the aperture center
+ :param anchor: Anchor position within the kernel. Negative values mean that anchor is positioned at the aperture center.
- :param delta: The value added to the filtered results before storing them
+ :param delta: Value added to the filtered results before storing them.
- :param bits: When the kernel is an integer matrix representing fixed-point filter coefficients,
- the parameter specifies the number of the fractional bits
+ :param bits: Number of the fractional bits. The parameter is used when the kernel is an integer matrix representing fixed-point filter coefficients.
- :param rowBorderType, columnBorderType: The pixel extrapolation methods in the horizontal and the vertical directions; see :func:`borderInterpolate`
+ :param rowBorderType, columnBorderType: Pixel extrapolation methods in the horizontal and vertical directions. See :func:`borderInterpolate` for details.
- :param borderValue: Used in case of a constant border
+ :param borderValue: Border value used in case of a constant border.
- :param symmetryType: The type of each of the row and column kernel; see :func:`getKernelType` .
+ :param symmetryType: Type of each row and column kernel. See :func:`getKernelType` .
-The functions construct primitive separable linear filtering operations or a filter engine based on them. Normally it's enough to use
+The functions construct primitive separable linear filtering operations or a filter engine based on them. Normally it is enough to use
:func:`createSeparableLinearFilter` or even higher-level
:func:`sepFilter2D` . The function
-:func:`createMorphologyFilter` is smart enough to figure out the ``symmetryType`` for each of the two kernels, the intermediate ``bufType`` , and, if the filtering can be done in integer arithmetics, the number of ``bits`` to encode the filter coefficients. If it does not work for you, it's possible to call ``getLinearColumnFilter``,``getLinearRowFilter`` directly and then pass them to
+:func:`createMorphologyFilter` is smart enough to figure out the ``symmetryType`` for each of the two kernels, the intermediate ``bufType`` and, if filtering can be done in integer arithmetics, the number of ``bits`` to encode the filter coefficients. If it does not work for you, it is possible to call ``getLinearColumnFilter``,``getLinearRowFilter`` directly and then pass them to the
:func:`FilterEngine` constructor.
-See also:
-:func:`sepFilter2D`,:func:`createLinearFilter`,:func:`FilterEngine`,:func:`getKernelType`
+See Also:
+:func:`sepFilter2D`,
+:func:`createLinearFilter`,
+:func:`FilterEngine`,
+:func:`getKernelType`
.. index:: dilate
dilate
Dilates an image by using a specific structuring element.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image. It will have the same size and the same type as ``src``
+ :param dst: Destination image of the same size and type as ``src`` .
- :param element: The structuring element used for dilation. If ``element=Mat()`` , a :math:`3\times 3` rectangular structuring element is used
+ :param element: Structuring element used for dilation. If ``element=Mat()`` , a :math:`3\times 3` rectangular structuring element is used.
- :param anchor: Position of the anchor within the element. The default value :math:`(-1, -1)` means that the anchor is at the element center
+ :param anchor: Position of the anchor within the element. The default value :math:`(-1, -1)` means that the anchor is at the element center.
- :param iterations: The number of times dilation is applied
+ :param iterations: Number of times dilation is applied.
- :param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
- :param borderValue: The border value in case of a constant border. The default value has a special meaning, see :func:`createMorphologyFilter`
+ :param borderValue: Border value in case of a constant border. The default value has a special meaning. See :func:`createMorphologyFilter` for details.
The function dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken:
\texttt{dst} (x,y) = \max _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')
-The function supports the in-place mode. Dilation can be applied several ( ``iterations`` ) times. In the case of multi-channel images each channel is processed independently.
+The function supports the in-place mode. Dilation can be applied several ( ``iterations`` ) times. In case of multi-channel images, each channel is processed independently.
-See also:
-:func:`erode`,:func:`morphologyEx`,:func:`createMorphologyFilter`
+See Also:
+:func:`erode`,
+:func:`morphologyEx`,
+:func:`createMorphologyFilter`
.. index:: erode
erode
Erodes an image by using a specific structuring element.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image. It will have the same size and the same type as ``src``
+ :param dst: Destination image of the same size and type as ``src`` .
- :param element: The structuring element used for dilation. If ``element=Mat()`` , a :math:`3\times 3` rectangular structuring element is used
+ :param element: Structuring element used for dilation. If ``element=Mat()`` , a :math:`3\times 3` rectangular structuring element is used.
- :param anchor: Position of the anchor within the element. The default value :math:`(-1, -1)` means that the anchor is at the element center
+ :param anchor: Position of the anchor within the element. The default value :math:`(-1, -1)` means that the anchor is at the element center.
- :param iterations: The number of times erosion is applied
+ :param iterations: Number of times erosion is applied.
- :param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
- :param borderValue: The border value in case of a constant border. The default value has a special meaning, see :func:`createMorphoogyFilter`
+ :param borderValue: Border value in case of a constant border. The default value has a special meaning. See :func:`createMorphoogyFilter` for details.
The function erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:
\texttt{dst} (x,y) = \min _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')
-The function supports the in-place mode. Erosion can be applied several ( ``iterations`` ) times. In the case of multi-channel images each channel is processed independently.
+The function supports the in-place mode. Erosion can be applied several ( ``iterations`` ) times. In case of multi-channel images, each channel is processed independently.
-See also:
-:func:`dilate`,:func:`morphologyEx`,:func:`createMorphologyFilter`
+See Also:
+:func:`dilate`,
+:func:`morphologyEx`,
+:func:`createMorphologyFilter`
.. index:: filter2D
------------
.. c:function:: void filter2D( const Mat\& src, Mat\& dst, int ddepth, const Mat\& kernel, Point anchor=Point(-1,-1), double delta=0, int borderType=BORDER_DEFAULT )
- Convolves an image with the kernel
+ Convolves an image with the kernel.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image. It will have the same size and the same number of channels as ``src``
+ :param dst: Destination image of the same size and the same number of channels as ``src`` .
- :param ddepth: The desired depth of the destination image. If it is negative, it will be the same as ``src.depth()``
+ :param ddepth: Desired depth of the destination image. If it is negative, it will be the same as ``src.depth()`` .
- :param kernel: Convolution kernel (or rather a correlation kernel), a single-channel floating point matrix. If you want to apply different kernels to different channels, split the image into separate color planes using :func:`split` and process them individually
+ :param kernel: Convolution kernel (or rather a correlation kernel), a single-channel floating point matrix. If you want to apply different kernels to different channels, split the image into separate color planes using :func:`split` and process them individually.
- :param anchor: The anchor of the kernel that indicates the relative position of a filtered point within the kernel. The anchor should lie within the kernel. The special default value (-1,-1) means that the anchor is at the kernel center
+ :param anchor: Anchor of the kernel that indicates the relative position of a filtered point within the kernel. The anchor should lie within the kernel. The special default value (-1,-1) means that the anchor is at the kernel center.
- :param delta: The optional value added to the filtered pixels before storing them in ``dst``
+ :param delta: Optional value added to the filtered pixels before storing them in ``dst`` .
- :param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
-The function applies an arbitrary linear filter to the image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values according to the specified border mode.
+The function applies an arbitrary linear filter to an image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values according to the specified border mode.
-The function does actually computes correlation, not the convolution:
+The function does actually compute correlation, not the convolution:
.. math::
That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip the kernel using
:func:`flip` and set the new anchor to ``(kernel.cols - anchor.x - 1, kernel.rows - anchor.y - 1)`` .
-The function uses
--based algorithm in case of sufficiently large kernels (~
+The function uses the
+??-based algorithm in case of sufficiently large kernels (~
:math:`11\times11` ) and the direct algorithm (that uses the engine retrieved by
:func:`createLinearFilter` ) for small kernels.
-See also:
-:func:`sepFilter2D`,:func:`createLinearFilter`,:func:`dft`,:func:`matchTemplate`
+See Also:
+:func:`sepFilter2D`,
+:func:`createLinearFilter`,
+:func:`dft`,
+:func:`matchTemplate`
.. index:: GaussianBlur
----------------
.. c:function:: void GaussianBlur( const Mat\& src, Mat\& dst, Size ksize, double sigmaX, double sigmaY=0, int borderType=BORDER_DEFAULT )
- Smoothes image using a Gaussian filter
+ Smoothes an image using a Gaussian filter.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image; will have the same size and the same type as ``src``
+ :param dst: Destination image of the same size and type as ``src`` .
- :param ksize: The Gaussian kernel size; ``ksize.width`` and ``ksize.height`` can differ, but they both must be positive and odd. Or, they can be zero's, then they are computed from ``sigma*``
+ :param ksize: Gaussian kernel size. ``ksize.width`` and ``ksize.height`` can differ but they both must be positive and odd. Or, they can be zero's and then they are computed from ``sigma*`` .
- :param sigmaX, sigmaY: The Gaussian kernel standard deviations in X and Y direction. If ``sigmaY`` is zero, it is set to be equal to ``sigmaX`` . If they are both zeros, they are computed from ``ksize.width`` and ``ksize.height`` , respectively, see :func:`getGaussianKernel` . To fully control the result regardless of possible future modification of all this semantics, it is recommended to specify all of ``ksize`` , ``sigmaX`` and ``sigmaY``
+ :param sigmaX, sigmaY: Gaussian kernel standard deviations in X and Y direction. If ``sigmaY`` is zero, it is set to be equal to ``sigmaX`` . If they are both zeros, they are computed from ``ksize.width`` and ``ksize.height`` , respectively. See :func:`getGaussianKernel` for details. To fully control the result regardless of possible future modifications of all this semantics, it is recommended to specify all of ``ksize`` , ``sigmaX`` , and ``sigmaY`` .
- :param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
The function convolves the source image with the specified Gaussian kernel. In-place filtering is supported.
-See also:
-:func:`sepFilter2D`,:func:`filter2D`,:func:`blur`,:func:`boxFilter`,:func:`bilateralFilter`,:func:`medianBlur`
+See Also:
+:func:`sepFilter2D`,
+:func:`filter2D`,
+:func:`blur`,
+:func:`boxFilter`,
+:func:`bilateralFilter`,
+:func:`medianBlur`
.. index:: getDerivKernels
getDerivKernels
-------------------
.. c:function:: void getDerivKernels( Mat\& kx, Mat\& ky, int dx, int dy, int ksize, bool normalize=false, int ktype=CV_32F )
- Returns filter coefficients for computing spatial image derivatives
+ Returns filter coefficients for computing spatial image derivatives.
- :param kx: The output matrix of row filter coefficients; will have type ``ktype``
+ :param kx: Output matrix of row filter coefficients. It has the type ``ktype`` .
- :param ky: The output matrix of column filter coefficients; will have type ``ktype``
+ :param ky: Output matrix of column filter coefficients. It has the type ``ktype`` .
- :param dx: The derivative order in respect with x
+ :param dx: Derivative order in respect of x.
- :param dy: The derivative order in respect with y
+ :param dy: Derivative order in respect of y.
- :param ksize: The aperture size. It can be ``CV_SCHARR`` , 1, 3, 5 or 7
+ :param ksize: Aperture size. It can be ``CV_SCHARR`` , 1, 3, 5, or 7.
- :param normalize: Indicates, whether to normalize (scale down) the filter coefficients or not. In theory the coefficients should have the denominator :math:`=2^{ksize*2-dx-dy-2}` . If you are going to filter floating-point images, you will likely want to use the normalized kernels. But if you compute derivatives of a 8-bit image, store the results in 16-bit image and wish to preserve all the fractional bits, you may want to set ``normalize=false`` .
+ :param normalize: Flag indicating whether to normalize (scale down) the filter coefficients or not. Theoretically, the coefficients should have the denominator :math:`=2^{ksize*2-dx-dy-2}` . If you are going to filter floating-point images, you are likely to use the normalized kernels. But if you compute derivatives of an 8-bit image, store the results in a 16-bit image, and wish to preserve all the fractional bits, you may want to set ``normalize=false`` .
- :param ktype: The type of filter coefficients. It can be ``CV_32f`` or ``CV_64F``
+ :param ktype: Type of filter coefficients. It can be ``CV_32f`` or ``CV_64F`` .
The function computes and returns the filter coefficients for spatial image derivatives. When ``ksize=CV_SCHARR`` , the Scharr
-:math:`3 \times 3` kernels are generated, see
-:func:`Scharr` . Otherwise, Sobel kernels are generated, see
-:func:`Sobel` . The filters are normally passed to
+:math:`3 \times 3` kernels are generated (see
+:func:`Scharr` ). Otherwise, Sobel kernels are generated (see
+:func:`Sobel` ). The filters are normally passed to
:func:`sepFilter2D` or to
:func:`createSeparableLinearFilter` .
---------------------
.. c:function:: Mat getGaussianKernel( int ksize, double sigma, int ktype=CV_64F )
- Returns Gaussian filter coefficients
+ Returns Gaussian filter coefficients.
- :param ksize: The aperture size. It should be odd ( :math:`\texttt{ksize} \mod 2 = 1` ) and positive.
+ :param ksize: Aperture size. It should be odd ( :math:`\texttt{ksize} \mod 2 = 1` ) and positive.
- :param sigma: The Gaussian standard deviation. If it is non-positive, it is computed from ``ksize`` as \ ``sigma = 0.3*(ksize/2 - 1) + 0.8``
- :param ktype: The type of filter coefficients. It can be ``CV_32f`` or ``CV_64F``
+ :param sigma: Gaussian standard deviation. If it is non-positive, it is computed from ``ksize`` as \ ``sigma = 0.3*(ksize/2 - 1) + 0.8`` .
+ :param ktype: Type of filter coefficients. It can be ``CV_32f`` or ``CV_64F`` .
The function computes and returns the
:math:`\texttt{ksize} \times 1` matrix of Gaussian filter coefficients:
where
:math:`i=0..\texttt{ksize}-1` and
:math:`\alpha` is the scale factor chosen so that
-:math:`\sum_i G_i=1` Two of such generated kernels can be passed to
+:math:`\sum_i G_i=1` . Two of such generated kernels can be passed to
:func:`sepFilter2D` or to
-:func:`createSeparableLinearFilter` that will automatically detect that these are smoothing kernels and handle them accordingly. Also you may use the higher-level
+:func:`createSeparableLinearFilter` . These functions?? automatically recognize smoothing kernels and handle them accordingly. You may also use the higher-level
:func:`GaussianBlur` .
-See also:
-:func:`sepFilter2D`,:func:`createSeparableLinearFilter`,:func:`getDerivKernels`,:func:`getStructuringElement`,:func:`GaussianBlur` .
+See Also:
+:func:`sepFilter2D`,
+:func:`createSeparableLinearFilter`,
+:func:`getDerivKernels`,
+:func:`getStructuringElement`,
+:func:`GaussianBlur`
.. index:: getKernelType
-----------------
.. c:function:: int getKernelType(const Mat\& kernel, Point anchor)
- Returns the kernel type
+ Returns the kernel type.
- :param kernel: 1D array of the kernel coefficients to analyze
+ :param kernel: 1D array of the kernel coefficients to analyze.
- :param anchor: The anchor position within the kernel
+ :param anchor: Anchor position within the kernel.
The function analyzes the kernel coefficients and returns the corresponding kernel type:
- * **KERNEL_GENERAL** Generic kernel - when there is no any type of symmetry or other properties
+ * **KERNEL_GENERAL** The kernel is generic. It is used when there is no any type of symmetry or other properties.
- * **KERNEL_SYMMETRICAL** The kernel is symmetrical: :math:`\texttt{kernel}_i == \texttt{kernel}_{ksize-i-1}` and the anchor is at the center
+ * **KERNEL_SYMMETRICAL** The kernel is symmetrical: :math:`\texttt{kernel}_i == \texttt{kernel}_{ksize-i-1}` , and the anchor is at the center.
- * **KERNEL_ASYMMETRICAL** The kernel is asymmetrical: :math:`\texttt{kernel}_i == -\texttt{kernel}_{ksize-i-1}` and the anchor is at the center
+ * **KERNEL_ASYMMETRICAL** The kernel is asymmetrical: :math:`\texttt{kernel}_i == -\texttt{kernel}_{ksize-i-1}` , and the anchor is at the center.
- * **KERNEL_SMOOTH** All the kernel elements are non-negative and sum to 1. E.g. the Gaussian kernel is both smooth kernel and symmetrical, so the function will return ``KERNEL_SMOOTH | KERNEL_SYMMETRICAL``
- * **KERNEL_INTEGER** Al the kernel coefficients are integer numbers. This flag can be combined with ``KERNEL_SYMMETRICAL`` or ``KERNEL_ASYMMETRICAL``
+ * **KERNEL_SMOOTH** All the kernel elements are non-negative and summed to 1. For example, the Gaussian kernel is both smooth kernel and symmetrical, so the function returns ``KERNEL_SMOOTH | KERNEL_SYMMETRICAL`` .
+ * **KERNEL_INTEGER** All the kernel coefficients are integer numbers. This flag can be combined with ``KERNEL_SYMMETRICAL`` or ``KERNEL_ASYMMETRICAL`` .
.. index:: getStructuringElement
-------------------------
.. c:function:: Mat getStructuringElement(int shape, Size esize, Point anchor=Point(-1,-1))
- Returns the structuring element of the specified size and shape for morphological operations
+ Returns a structuring element of the specified size and shape for morphological operations.
- :param shape: The element shape, one of:
+ :param shape: Element shape that could be one of the following:
- * ``MORPH_RECT`` - rectangular structuring element
+ * ``MORPH_RECT`` - a rectangular structuring element:
.. math::
E_{ij}=1
- * ``MORPH_ELLIPSE`` - elliptic structuring element, i.e. a filled ellipse inscribed into the rectangle ``Rect(0, 0, esize.width, 0.esize.height)``
+ * ``MORPH_ELLIPSE`` - an elliptic structuring element, that is, a filled ellipse inscribed into the rectangle ``Rect(0, 0, esize.width, 0.esize.height)``
- * ``MORPH_CROSS`` - cross-shaped structuring element:
+ * ``MORPH_CROSS`` - a cross-shaped structuring element:
.. math::
E_{ij} = \fork{1}{if i=\texttt{anchor.y} or j=\texttt{anchor.x}}{0}{otherwise}
- :param esize: Size of the structuring element
+ :param esize: Size of the structuring element.
- :param anchor: The anchor position within the element. The default value :math:`(-1, -1)` means that the anchor is at the center. Note that only the cross-shaped element's shape depends on the anchor position; in other cases the anchor just regulates by how much the result of the morphological operation is shifted
+ :param anchor: Anchor position within the element. The default value :math:`(-1, -1)` means that the anchor is at the center. Note that only the shape of a cross-shaped element depends on the anchor position. In other cases the anchor just regulates how much the result of the morphological operation is shifted.
The function constructs and returns the structuring element that can be then passed to
-:func:`createMorphologyFilter`,:func:`erode`,:func:`dilate` or
-:func:`morphologyEx` . But also you can construct an arbitrary binary mask yourself and use it as the structuring element.
+:func:`createMorphologyFilter`,
+:func:`erode`,
+:func:`dilate` or
+:func:`morphologyEx` . But you can also construct an arbitrary binary mask yourself and use it as the structuring element.
.. index:: medianBlur
--------------
.. c:function:: void medianBlur( const Mat\& src, Mat\& dst, int ksize )
- Smoothes image using median filter
+ Smoothes an image using the median filter.
- :param src: The source 1-, 3- or 4-channel image. When ``ksize`` is 3 or 5, the image depth should be ``CV_8U`` , ``CV_16U`` or ``CV_32F`` . For larger aperture sizes it can only be ``CV_8U``
+ :param src: Source 1-, 3-, or 4-channel image. When ``ksize`` is 3 or 5, the image depth should be ``CV_8U`` , ``CV_16U`` , or ``CV_32F`` . For larger aperture sizes, it can only be ``CV_8U`` .
- :param dst: The destination array; will have the same size and the same type as ``src``
+ :param dst: Destination array of the same size and type as ``src`` .
- :param ksize: The aperture linear size. It must be odd and more than 1, i.e. 3, 5, 7 ...
+ :param ksize: Aperture linear size. It must be odd and greater than 1, for example: 3, 5, 7 ...
-The function smoothes image using the median filter with
+The function smoothes an image using the median filter with the
:math:`\texttt{ksize} \times \texttt{ksize}` aperture. Each channel of a multi-channel image is processed independently. In-place operation is supported.
-See also:
-:func:`bilateralFilter`,:func:`blur`,:func:`boxFilter`,:func:`GaussianBlur`
+See Also:
+:func:`bilateralFilter`,
+:func:`blur`,
+:func:`boxFilter`,
+:func:`GaussianBlur`
.. index:: morphologyEx
morphologyEx
----------------
.. c:function:: void morphologyEx( const Mat\& src, Mat\& dst, int op, const Mat\& element, Point anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar\& borderValue=morphologyDefaultBorderValue() )
- Performs advanced morphological transformations
+ Performs advanced morphological transformations.
- :param src: Source image
+ :param src: Source image.
- :param dst: Destination image. It will have the same size and the same type as ``src``
+ :param dst: Destination image of the same size and type as ``src`` .
- :param element: Structuring element
+ :param element: Structuring element.
- :param op: Type of morphological operation, one of the following:
+ :param op: Type of a morphological operation that can be one of the following:
- * **MORPH_OPEN** opening
+ * **MORPH_OPEN** - an opening operation
- * **MORPH_CLOSE** closing
+ * **MORPH_CLOSE** - a closing operation
- * **MORPH_GRADIENT** morphological gradient
+ * **MORPH_GRADIENT** - a morphological gradient
- * **MORPH_TOPHAT** "top hat"
+ * **MORPH_TOPHAT** - "top hat"
- * **MORPH_BLACKHAT** "black hat"
+ * **MORPH_BLACKHAT** - "black hat"
- :param iterations: Number of times erosion and dilation are applied
+ :param iterations: Number of times erosion and dilation are applied.
- :param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
- :param borderValue: The border value in case of a constant border. The default value has a special meaning, see :func:`createMorphoogyFilter`
+ :param borderValue: Border value in case of a constant border. The default value has a special meaning. See :func:`createMorphoogyFilter` for details.
-The function can perform advanced morphological transformations using erosion and dilation as basic operations.
+The function can perform advanced morphological transformations using an erosion and dilation as basic operations.
-Opening:
+Opening operation:
.. math::
\texttt{dst} = \mathrm{open} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \mathrm{erode} ( \texttt{src} , \texttt{element} ))
-Closing:
+Closing operation:
.. math::
Any of the operations can be done in-place.
-See also:
-:func:`dilate`,:func:`erode`,:func:`createMorphologyFilter`
+See Also:
+:func:`dilate`,
+:func:`erode`,
+:func:`createMorphologyFilter`
.. index:: Laplacian
Laplacian
-------------
.. c:function:: void Laplacian( const Mat\& src, Mat\& dst, int ddepth, int ksize=1, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
- Calculates the Laplacian of an image
+ Calculates the Laplacian of an image.
- :param src: Source image
+ :param src: Source image.
- :param dst: Destination image; will have the same size and the same number of channels as ``src``
+ :param dst: Destination image of the same size and the same number of channels as ``src`` .
- :param ddepth: The desired depth of the destination image
+ :param ddepth: Desired depth of the destination image.
- :param ksize: The aperture size used to compute the second-derivative filters, see :func:`getDerivKernels` . It must be positive and odd
+ :param ksize: Aperture size used to compute the second-derivative filters. See :func:`getDerivKernels` for details. The size must be positive and odd.
- :param scale: The optional scale factor for the computed Laplacian values (by default, no scaling is applied, see :func:`getDerivKernels` )
+ :param scale: Optional scale factor for the computed Laplacian values. By default, no scaling is applied. See :func:`getDerivKernels` for details.
- :param delta: The optional delta value, added to the results prior to storing them in ``dst``
+ :param delta: Optional delta value that is added to the results prior to storing them in ``dst`` .
- :param borderType: The pixel extrapolation method, see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator:
\vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0}
-See also:
-:func:`Sobel`,:func:`Scharr`
+See Also:
+:func:`Sobel`,
+:func:`Scharr`
.. index:: pyrDown
pyrDown
Smoothes an image and downsamples it.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image. It will have the specified size and the same type as ``src``
+ :param dst: Destination image. It has the specified size and the same type as ``src`` .
- :param dstsize: Size of the destination image. By default it is computed as ``Size((src.cols+1)/2, (src.rows+1)/2)`` . But in any case the following conditions should be satisfied:
+ :param dstsize: Size of the destination image. By default, it is computed as ``Size((src.cols+1)/2, (src.rows+1)/2)`` . But in any case, the following conditions should be satisfied:
.. math::
\begin{array}{l}
| \texttt{dstsize.width} *2-src.cols| \leq 2 \\ | \texttt{dstsize.height} *2-src.rows| \leq 2 \end{array}
-The function performs the downsampling step of the Gaussian pyramid construction. First it convolves the source image with the kernel:
+The function performs the downsampling step of the Gaussian pyramid construction. First, it convolves the source image with the kernel:
.. math::
\frac{1}{16} \begin{bmatrix} 1 & 4 & 6 & 4 & 1 \\ 4 & 16 & 24 & 16 & 4 \\ 6 & 24 & 36 & 24 & 6 \\ 4 & 16 & 24 & 16 & 4 \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}
-and then downsamples the image by rejecting even rows and columns.
+Then, it downsamples the image by rejecting even rows and columns.
.. index:: pyrUp
---------
.. c:function:: void pyrUp( const Mat\& src, Mat\& dst, const Size\& dstsize=Size())
- Upsamples an image and then smoothes it
+ Upsamples an image and then smoothes it.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image. It will have the specified size and the same type as ``src``
+ :param dst: Destination image. It has the specified size and the same type as ``src`` .
- :param dstsize: Size of the destination image. By default it is computed as ``Size(src.cols*2, (src.rows*2)`` . But in any case the following conditions should be satisfied:
+ :param dstsize: Size of the destination image. By default, it is computed as ``Size(src.cols*2, (src.rows*2)`` . But in any case, the following conditions should be satisfied:
.. math::
\begin{array}{l}
| \texttt{dstsize.width} -src.cols*2| \leq ( \texttt{dstsize.width} \mod 2) \\ | \texttt{dstsize.height} -src.rows*2| \leq ( \texttt{dstsize.height} \mod 2) \end{array}
-The function performs the upsampling step of the Gaussian pyramid construction (it can actually be used to construct the Laplacian pyramid). First it upsamples the source image by injecting even zero rows and columns and then convolves the result with the same kernel as in
-:func:`pyrDown` , multiplied by 4.
+The function performs the upsampling step of the Gaussian pyramid construction though it can actually be used to construct the Laplacian pyramid. First, it upsamples the source image by injecting even zero rows and columns and then convolves the result with the same kernel as in
+:func:`pyrDown` multiplied by 4.
.. index:: sepFilter2D
---------------
.. c:function:: void sepFilter2D( const Mat\& src, Mat\& dst, int ddepth, const Mat\& rowKernel, const Mat\& columnKernel, Point anchor=Point(-1,-1), double delta=0, int borderType=BORDER_DEFAULT )
- Applies separable linear filter to an image
+ Applies a separable linear filter to an image.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image; will have the same size and the same number of channels as ``src``
+ :param dst: Destination image of the same size and the same number of channels as ``src`` .
- :param ddepth: The destination image depth
+ :param ddepth: Destination image depth.
- :param rowKernel: The coefficients for filtering each row
+ :param rowKernel: Coefficients for filtering each row.
- :param columnKernel: The coefficients for filtering each column
+ :param columnKernel: Coefficients for filtering each column.
- :param anchor: The anchor position within the kernel; The default value :math:`(-1, 1)` means that the anchor is at the kernel center
+ :param anchor: Anchor position within the kernel. The default value :math:`(-1, 1)` means that the anchor is at the kernel center.
- :param delta: The value added to the filtered results before storing them
+ :param delta: Value added to the filtered results before storing them.
- :param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
-The function applies a separable linear filter to the image. That is, first, every row of ``src`` is filtered with 1D kernel ``rowKernel`` . Then, every column of the result is filtered with 1D kernel ``columnKernel`` and the final result shifted by ``delta`` is stored in ``dst`` .
+The function applies a separable linear filter to the image. That is, first, every row of ``src`` is filtered with the 1D kernel ``rowKernel`` . Then, every column of the result is filtered with the 1D kernel ``columnKernel`` . The final result shifted by ``delta`` is stored in ``dst`` .
-See also:
-:func:`createSeparableLinearFilter`,:func:`filter2D`,:func:`Sobel`,:func:`GaussianBlur`,:func:`boxFilter`,:func:`blur` .
+See Also:
+:func:`createSeparableLinearFilter`,
+:func:`filter2D`,
+:func:`Sobel`,
+:func:`GaussianBlur`,
+:func:`boxFilter`,
+:func:`blur`
.. index:: Sobel
---------
.. c:function:: void Sobel( const Mat\& src, Mat\& dst, int ddepth, int xorder, int yorder, int ksize=3, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
- Calculates the first, second, third or mixed image derivatives using an extended Sobel operator
+ Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image; will have the same size and the same number of channels as ``src``
+ :param dst: Destination image of the same size and the same number of channels as ``src`` .
- :param ddepth: The destination image depth
+ :param ddepth: Destination image depth.
- :param xorder: Order of the derivative x
+ :param xorder: Order of the derivative x.
- :param yorder: Order of the derivative y
+ :param yorder: Order of the derivative y.
- :param ksize: Size of the extended Sobel kernel, must be 1, 3, 5 or 7
+ :param ksize: Size of the extended Sobel kernel. It must be 1, 3, 5, or 7.
- :param scale: The optional scale factor for the computed derivative values (by default, no scaling is applied, see :func:`getDerivKernels` )
+ :param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. See :func:`getDerivKernels` for details.
- :param delta: The optional delta value, added to the results prior to storing them in ``dst``
+ :param delta: Optional delta value that is added to the results prior to storing them in ``dst`` .
- :param borderType: The pixel extrapolation method, see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
-In all cases except 1, an
+In all cases except one, the
:math:`\texttt{ksize} \times
-\texttt{ksize}` separable kernel will be used to calculate the
+\texttt{ksize}` separable kernel is used to calculate the
derivative. When
-:math:`\texttt{ksize = 1}` , a
+:math:`\texttt{ksize = 1}` , the
:math:`3 \times 1` or
-:math:`1 \times 3` kernel will be used (i.e. no Gaussian smoothing is done). ``ksize = 1`` can only be used for the first or the second x- or y- derivatives.
+:math:`1 \times 3` kernel is used (that is, no Gaussian smoothing is done). ``ksize = 1`` can only be used for the first or the second x- or y- derivatives.
-There is also the special value ``ksize = CV_SCHARR`` (-1) that corresponds to a
+There is also the special value ``ksize = CV_SCHARR`` (-1) that corresponds to the
:math:`3\times3` Scharr
-filter that may give more accurate results than a
-:math:`3\times3` Sobel. The Scharr
-aperture is
+filter that may give more accurate results than the
+:math:`3\times3` Sobel. The Scharr aperture is
.. math::
\vecthreethree{-3}{0}{3}{-10}{0}{10}{-3}{0}{3}
-for the x-derivative or transposed for the y-derivative.
+for the x-derivative, or transposed for the y-derivative.
-The function calculates the image derivative by convolving the image with the appropriate kernel:
+The function calculates an image derivative by convolving the image with the appropriate kernel:
.. math::
\vecthreethree{-1}{0}{1}{-2}{0}{2}{-1}{0}{1}
-and the second one corresponds to a kernel of:
+The second case corresponds to a kernel of:
.. math::
\vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}
-See also:
-:func:`Scharr`,:func:`Lapacian`,:func:`sepFilter2D`,:func:`filter2D`,:func:`GaussianBlur`
+See Also:
+:func:`Scharr`,
+:func:`Lapacian`,
+:func:`sepFilter2D`,
+:func:`filter2D`,
+:func:`GaussianBlur`
.. index:: Scharr
Scharr
----------
.. c:function:: void Scharr( const Mat\& src, Mat\& dst, int ddepth, int xorder, int yorder, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
- Calculates the first x- or y- image derivative using Scharr operator
+ Calculates the first x- or y- image derivative using Scharr operator.
- :param src: The source image
+ :param src: Source image.
- :param dst: The destination image; will have the same size and the same number of channels as ``src``
+ :param dst: Destination image of the same size and the same number of channels as ``src`` .
- :param ddepth: The destination image depth
+ :param ddepth: Destination image depth.
- :param xorder: Order of the derivative x
+ :param xorder: Order of the derivative x.
- :param yorder: Order of the derivative y
+ :param yorder: Order of the derivative y.
- :param scale: The optional scale factor for the computed derivative values (by default, no scaling is applied, see :func:`getDerivKernels` )
+ :param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. See :func:`getDerivKernels` for details.
- :param delta: The optional delta value, added to the results prior to storing them in ``dst``
+ :param delta: Optional delta value that is added to the results prior to storing them in ``dst`` .
- :param borderType: The pixel extrapolation method, see :func:`borderInterpolate`
+ :param borderType: Pixel extrapolation method. See :func:`borderInterpolate` for details.
-The function computes the first x- or y- spatial image derivative using Scharr operator. The call
+The function computes the first x- or y- spatial image derivative using the Scharr operator. The call
.. math::
Geometric Image Transformations
===============================
-The functions in this section perform various geometrical transformations of 2D images. That is, they do not change the image content, but deform the pixel grid, and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from destination to the source. That is, for each pixel
-:math:`(x, y)` of the destination image, the functions compute coordinates of the corresponding "donor" pixel in the source image and copy the pixel value, that is:
+The functions in this section perform various geometrical transformations of 2D images. They do not change the image content but deform the pixel grid, and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from destination to the source. That is, for each pixel
+:math:`(x, y)` of the destination image, the functions compute coordinates of the corresponding "donor" pixel in the source image and copy the pixel value:
.. math::
\texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y))
-In the case when the user specifies the forward mapping:
-:math:`\left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst}` , the OpenCV functions first compute the corresponding inverse mapping:
+In case when you specify the forward mapping
+:math:`\left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst}` , the OpenCV functions first compute the corresponding inverse mapping
:math:`\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}` and then use the above formula.
The actual implementations of the geometrical transformations, from the most generic
:ref:`Remap` and to the simplest and the fastest
-:ref:`Resize` , need to solve the 2 main problems with the above formula:
+:ref:`Resize` , need to solve two main problems with the above formula:
-#.
- extrapolation of non-existing pixels. Similarly to the filtering functions, described in the previous section, for some
- :math:`(x,y)` one of
- :math:`f_x(x,y)` or
- :math:`f_y(x,y)` , or they both, may fall outside of the image, in which case some extrapolation method needs to be used. OpenCV provides the same selection of the extrapolation methods as in the filtering functions, but also an additional method ``BORDER_TRANSPARENT`` , which means that the corresponding pixels in the destination image will not be modified at all.
+*
+ Extrapolation of non-existing pixels. Similarly to the filtering functions described in the previous section, for some
+ :math:`(x,y)` , either one of
+ :math:`f_x(x,y)` , or
+ :math:`f_y(x,y)` , or both of them may fall outside of the image. In this case, an extrapolation method needs to be used. OpenCV provides the same selection of extrapolation methods as in the filtering functions. In addition, it provides the method ``BORDER_TRANSPARENT`` . This means that the corresponding pixels in the destination image will not be modified at all.
-#.
- interpolation of pixel values. Usually
+*
+ Interpolation of pixel values. Usually
:math:`f_x(x,y)` and
- :math:`f_y(x,y)` are floating-point numbers (i.e.
- :math:`\left<f_x, f_y\right>` can be an affine or perspective transformation, or radial lens distortion correction etc.), so a pixel values at fractional coordinates needs to be retrieved. In the simplest case the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel used, which is called nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated `interpolation methods <http://en.wikipedia.org/wiki/Multivariate_interpolation>`_
+ :math:`f_y(x,y)` are floating-point numbers. This means that
+ :math:`\left<f_x, f_y\right>` can be either an affine or perspective transformation, or radial lens distortion correction, and so on. So, a pixel value at fractional coordinates needs to be retrieved. In the simplest case, the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel can be used. This is called a nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated `interpolation methods <http://en.wikipedia.org/wiki/Multivariate_interpolation>`_
, where a polynomial function is fit into some neighborhood of the computed pixel
- :math:`(f_x(x,y), f_y(x,y))` and then the value of the polynomial at
- :math:`(f_x(x,y), f_y(x,y))` is taken as the interpolated pixel value. In OpenCV you can choose between several interpolation methods, see
- :ref:`Resize` .
+ :math:`(f_x(x,y), f_y(x,y))` , and then the value of the polynomial at
+ :math:`(f_x(x,y), f_y(x,y))` is taken as the interpolated pixel value. In OpenCV, you can choose between several interpolation methods. See
+ :ref:`Resize` for details.
.. index:: convertMaps
.. c:function:: void convertMaps( const Mat& map1, const Mat& map2, Mat& dstmap1, Mat& dstmap2, int dstmap1type, bool nninterpolation=false )
- Converts image transformation maps from one representation to another
+ Converts image transformation maps from one representation to another.
- :param map1: The first input map of type ``CV_16SC2`` or ``CV_32FC1`` or ``CV_32FC2``
+ :param map1: The first input map of type ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` .
- :param map2: The second input map of type ``CV_16UC1`` or ``CV_32FC1`` or none (empty matrix), respectively
+ :param map2: The second input map of type ``CV_16UC1`` , ``CV_32FC1`` , or none (empty matrix), respectively.
- :param dstmap1: The first output map; will have type ``dstmap1type`` and the same size as ``src``
+ :param dstmap1: The first output map that has the type ``dstmap1type`` and the same size as ``src`` .
- :param dstmap2: The second output map
+ :param dstmap2: The second output map.
- :param dstmap1type: The type of the first output map; should be ``CV_16SC2`` , ``CV_32FC1`` or ``CV_32FC2``
+ :param dstmap1type: Type of the first output map that should be ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` .
- :param nninterpolation: Indicates whether the fixed-point maps will be used for nearest-neighbor or for more complex interpolation
+ :param nninterpolation: Flag indicatingwhether the fixed-point maps are used for the nearest-neighbor or for a more complex interpolation.
The function converts a pair of maps for
:func:`remap` from one representation to another. The following options ( ``(map1.type(), map2.type())`` :math:`\rightarrow` ``(dstmap1.type(), dstmap2.type())`` ) are supported:
-#.
+*
:math:`\texttt{(CV\_32FC1, CV\_32FC1)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . This is the most frequently used conversion operation, in which the original floating-point maps (see
- :func:`remap` ) are converted to more compact and much faster fixed-point representation. The first output array will contain the rounded coordinates and the second array (created only when ``nninterpolation=false`` ) will contain indices in the interpolation tables.
+ :func:`remap` ) are converted to a more compact and much faster fixed-point representation. The first output array contains the rounded coordinates and the second array (created only when ``nninterpolation=false`` ) contains indices in the interpolation tables.
-#.
- :math:`\texttt{(CV\_32FC2)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . The same as above, but the original maps are stored in one 2-channel matrix.
+*
+ :math:`\texttt{(CV\_32FC2)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . The same as above but the original maps are stored in one 2-channel matrix.
-#.
- the reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals.
+*
+ Reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals.
-See also:
-:func:`remap`,:func:`undisort`,:func:`initUndistortRectifyMap`
+See Also:
+:func:`remap`,
+:func:`undisort`,
+:func:`initUndistortRectifyMap`
.. index:: getAffineTransform
----------------------
.. c:function:: Mat getAffineTransform( const Point2f src[], const Point2f dst[] )
- Calculates the affine transform from 3 pairs of the corresponding points
+ Calculates the affine transform from three pairs of the corresponding points.
- :param src: Coordinates of a triangle vertices in the source image
+ :param src: Coordinates of triangle vertices in the source image.
- :param dst: Coordinates of the corresponding triangle vertices in the destination image
+ :param dst: Coordinates of the corresponding triangle vertices in the destination image.
-The function calculates the :math:`2 \times 3` matrix of an affine transform such that:
+The function calculates the :math:`2 \times 3` matrix of an affine transform so that:
.. math::
src(i)=(x_i, y_i),
i=0,1,2
-See also:
-:func:`warpAffine`,:func:`transform`
+See Also:
+:func:`warpAffine`,
+:func:`transform`
.. index:: getPerspectiveTransform
---------------------------
.. c:function:: Mat getPerspectiveTransform( const Point2f src[], const Point2f dst[] )
- Calculates the perspective transform from 4 pairs of the corresponding points
+ Calculates the perspective transform from four pairs of the corresponding points.
- :param src: Coordinates of a quadrange vertices in the source image
+ :param src: Coordinates of quadrangle vertices in the source image.
- :param dst: Coordinates of the corresponding quadrangle vertices in the destination image
+ :param dst: Coordinates of the corresponding quadrangle vertices in the destination image.
-The function calculates the :math:`3 \times 3` matrix of a perspective transform such that:
+The function calculates the :math:`3 \times 3` matrix of a perspective transform so that:
.. math::
src(i)=(x_i, y_i),
i=0,1,2
-See also:
-:func:`findHomography`,:func:`warpPerspective`,:func:`perspectiveTransform`
+See Also:
+:func:`findHomography`,
+:func:`warpPerspective`,
+:func:`perspectiveTransform`
.. index:: getRectSubPix
-----------------
.. c:function:: void getRectSubPix( const Mat& image, Size patchSize, Point2f center, Mat& dst, int patchType=-1 )
- Retrieves the pixel rectangle from an image with sub-pixel accuracy
+ Retrieves the pixel rectangle from an image with sub-pixel accuracy.
- :param src: Source image
+ :param src: Source image.
- :param patchSize: Size of the extracted patch
+ :param patchSize: Size of the extracted patch.
- :param center: Floating point coordinates of the extracted rectangle center within the source image. The center must be inside the image
+ :param center: Floating point coordinates of the center of the extracted rectangle within the source image. The center must be inside the image.
- :param dst: The extracted patch; will have the size ``patchSize`` and the same number of channels as ``src``
+ :param dst: Extracted patch that has the size ``patchSize`` and the same number of channels as ``src`` .
- :param patchType: The depth of the extracted pixels. By default they will have the same depth as ``src``
+ :param patchType: Depth of the extracted pixels. By default, they have the same depth as ``src`` .
The function ``getRectSubPix`` extracts pixels from ``src`` :
dst(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)
where the values of the pixels at non-integer coordinates are retrieved
-using bilinear interpolation. Every channel of multiple-channel
-images is processed independently. While the rectangle center
+using bilinear interpolation. Every channel of multi-channel
+images is processed independently. While the center of the rectangle
must be inside the image, parts of the rectangle may be
outside. In this case, the replication border mode (see
:func:`borderInterpolate` ) is used to extrapolate
the pixel values outside of the image.
-See also:
-:func:`warpAffine`,:func:`warpPerspective`
+See Also:
+:func:`warpAffine`,
+:func:`warpPerspective`
.. index:: getRotationMatrix2D
-----------------------
.. c:function:: Mat getRotationMatrix2D( Point2f center, double angle, double scale )
- Calculates the affine matrix of 2d rotation.
+ Calculates an affine matrix of 2D rotation.
- :param center: Center of the rotation in the source image
+ :param center: Center of the rotation in the source image.
- :param angle: The rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner)
+ :param angle: Rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner).
- :param scale: Isotropic scale factor
+ :param scale: Isotropic scale factor.
The function calculates the following matrix:
\begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}
-The transformation maps the rotation center to itself. If this is not the purpose, the shift should be adjusted.
+The transformation maps the rotation center to itself. If this is not the target, adjust the shift.
-See also:
-:func:`getAffineTransform`,:func:`warpAffine`,:func:`transform`
+See Also:
+:func:`getAffineTransform`,
+:func:`warpAffine`,
+:func:`transform`
.. index:: invertAffineTransform
-------------------------
.. c:function:: void invertAffineTransform(const Mat& M, Mat& iM)
- Inverts an affine transformation
+ Inverts an affine transformation.
- :param M: The original affine transformation
+ :param M: Original affine transformation.
- :param iM: The output reverse affine transformation
+ :param iM: Output reverse affine transformation.
-The function computes inverse affine transformation represented by
+The function computes an inverse affine transformation represented by
:math:`2 \times 3` matrix ``M`` :
.. math::
\begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}
-The result will also be a
+The result is also a
:math:`2 \times 3` matrix of the same type as ``M`` .
.. index:: remap
Applies a generic geometrical transformation to an image.
- :param src: Source image
+ :param src: Source image.
- :param dst: Destination image. It will have the same size as ``map1`` and the same type as ``src``
- :param map1: The first map of either ``(x,y)`` points or just ``x`` values having type ``CV_16SC2`` , ``CV_32FC1`` or ``CV_32FC2`` . See :func:`convertMaps` for converting floating point representation to fixed-point for speed.
+ :param dst: Destination image. It has the same size as ``map1`` and the same type as ``src`` .
+ :param map1: The first map of either ``(x,y)`` points or just ``x`` values having the type ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` . See :func:`convertMaps` for details on converting a floating point representation to fixed-point for speed.
- :param map2: The second map of ``y`` values having type ``CV_16UC1`` , ``CV_32FC1`` or none (empty map if map1 is ``(x,y)`` points), respectively
+ :param map2: The second map of ``y`` values having the type ``CV_16UC1`` , ``CV_32FC1`` , or none (empty map if ``map1`` is ``(x,y)`` points), respectively.
- :param interpolation: The interpolation method, see :func:`resize` . The method ``INTER_AREA`` is not supported by this function
+ :param interpolation: Interpolation method (see :func:`resize` ). The method ``INTER_AREA`` is not supported by this function.
- :param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
+ :param borderMode: Pixel extrapolation method (see :func:`borderInterpolate` ). When \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function.
- :param borderValue: A value used in the case of a constant border. By default it is 0
+ :param borderValue: Value used in case of a constant border. By default, it is 0.
The function ``remap`` transforms the source image using the specified map:
\texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))
-Where values of pixels with non-integer coordinates are computed using one of the available interpolation methods.
+where values of pixels with non-integer coordinates are computed using one of available interpolation methods.
:math:`map_x` and
:math:`map_y` can be encoded as separate floating-point maps in
:math:`map_1` and
:math:`map_2` respectively, or interleaved floating-point maps of
:math:`(x,y)` in
:math:`map_1` , or
-fixed-point maps made by using
+fixed-point maps created by using
:func:`convertMaps` . The reason you might want to convert from floating to fixed-point
representations of a map is that they can yield much faster (~2x) remapping operations. In the converted case,
:math:`map_1` contains pairs ``(cvFloor(x), cvFloor(y))`` and
:math:`map_2` contains indices in a table of interpolation coefficients.
-This function can not operate in-place.
+This function cannot operate in-place.
.. index:: resize
.. c:function:: void resize( const Mat& src, Mat& dst, Size dsize, double fx=0, double fy=0, int interpolation=INTER_LINEAR )
- Resizes an image
+ Resizes an image.
- :param src: Source image
+ :param src: Source image.
- :param dst: Destination image. It will have size ``dsize`` (when it is non-zero) or the size computed from ``src.size()`` and ``fx`` and ``fy`` . The type of ``dst`` will be the same as of ``src`` .
+ :param dst: Destination image. It has size ``dsize`` (when it is non-zero) or the size computed from ``src.size()`` , ``fx`` , and ``fy`` . The type of ``dst`` is the same as of ``src`` .
- :param dsize: The destination image size. If it is zero, then it is computed as:
+ :param dsize: Destination image size. If it is zero, it is computed as:
.. math::
\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}
- .
- Either ``dsize`` or both ``fx`` or ``fy`` must be non-zero.
+
+ Either ``dsize`` or both ``fx`` and ``fy`` must be non-zero.
- :param fx: The scale factor along the horizontal axis. When 0, it is computed as
+ :param fx: Scale factor along the horizontal axis. When it is 0, it is computed as
.. math::
\texttt{(double)dsize.width/src.cols}
- :param fy: The scale factor along the vertical axis. When 0, it is computed as
+ :param fy: Scale factor along the vertical axis. When it is 0, it is computed as
.. math::
\texttt{(double)dsize.height/src.rows}
- :param interpolation: The interpolation method:
+ :param interpolation: Interpolation method:
- * **INTER_NEAREST** nearest-neighbor interpolation
+ * **INTER_NEAREST** - a nearest-neighbor interpolation
- * **INTER_LINEAR** bilinear interpolation (used by default)
+ * **INTER_LINEAR** - a bilinear interpolation (used by default)
- * **INTER_AREA** resampling using pixel area relation. It may be the preferred method for image decimation, as it gives moire-free results. But when the image is zoomed, it is similar to the ``INTER_NEAREST`` method
+ * **INTER_AREA** - resampling using pixel area relation. It may be a preferred method for image decimation, as it gives freer?? results. But when the image is zoomed, it is similar to the ``INTER_NEAREST`` method.
- * **INTER_CUBIC** bicubic interpolation over 4x4 pixel neighborhood
+ * **INTER_CUBIC** - a bicubic interpolation over 4x4 pixel neighborhood
- * **INTER_LANCZOS4** Lanczos interpolation over 8x8 pixel neighborhood
+ * **INTER_LANCZOS4** - a Lanczos interpolation over 8x8 pixel neighborhood
-The function ``resize`` resizes an image ``src`` down to or up to the specified size.
-Note that the initial ``dst`` type or size are not taken into account. Instead the size and type are derived from the ``src``,``dsize``,``fx`` and ``fy`` . If you want to resize ``src`` so that it fits the pre-created ``dst`` , you may call the function as: ::
+The function ``resize`` resizes the image ``src`` down to or up to the specified size.
+Note that the initial ``dst`` type or size are not taken into account. Instead, the size and type are derived from the ``src``,``dsize``,``fx`` , and ``fy`` . If you want to resize ``src`` so that it fits the pre-created ``dst`` , you may call the function as follows: ::
// explicitly specify dsize=dst.size(); fx and fy will be computed from that.
resize(src, dst, dst.size(), 0, 0, interpolation);
If you want to decimate the image by factor of 2 in each direction, you can call the function this way: ::
- // specify fx and fy and let the function to compute the destination image size.
+ // specify fx and fy and let the function compute the destination image size.
resize(src, dst, Size(), 0.5, 0.5, interpolation);
-See also:
-:func:`warpAffine`,:func:`warpPerspective`,:func:`remap` .
+See Also:
+:func:`warpAffine`,
+:func:`warpPerspective`,
+:func:`remap`
.. index:: warpAffine
Applies an affine transformation to an image.
- :param src: Source image
+ :param src: Source image.
- :param dst: Destination image; will have size ``dsize`` and the same type as ``src``
+ :param dst: Destination image that has the size ``dsize`` and the same type as ``src`` .
- :param M: :math:`2\times 3` transformation matrix
+ :param M: :math:`2\times 3` transformation matrix.
- :param dsize: Size of the destination image
+ :param dsize: Size of the destination image.
- :param flags: A combination of interpolation methods, see :func:`resize` , and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` )
+ :param flags: Combination of interpolation methods (see :func:`resize` ) and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` ).
- :param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
+ :param borderMode: Pixel extrapolation method (see :func:`borderInterpolate` ). When \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image corresponding to the "outliers" in the source image are not modified by the function.
- :param borderValue: A value used in case of a constant border. By default it is 0
+ :param borderValue: Value used in case of a constant border. By default, it is 0.
The function ``warpAffine`` transforms the source image using the specified matrix:
when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
:func:`invertAffineTransform` and then put in the formula above instead of ``M`` .
-The function can not operate in-place.
+The function cannot operate in-place.
-See also:
-:func:`warpPerspective`,:func:`resize`,:func:`remap`,:func:`getRectSubPix`,:func:`transform`
+See Also:
+:func:`warpPerspective`,
+:func:`resize`,
+:func:`remap`,
+:func:`getRectSubPix`,
+:func:`transform`
.. index:: warpPerspective
Applies a perspective transformation to an image.
- :param src: Source image
+ :param src: Source image.
- :param dst: Destination image; will have size ``dsize`` and the same type as ``src``
- :param M: :math:`3\times 3` transformation matrix
+ :param dst: Destination image that has the size ``dsize`` and the same type as ``src`` .
+
+ :param M: :math:`3\times 3` transformation matrix.
- :param dsize: Size of the destination image
+ :param dsize: Size of the destination image.
- :param flags: A combination of interpolation methods, see :func:`resize` , and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` )
+ :param flags: Combination of interpolation methods (see :func:`resize` ) and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` ).
- :param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
+ :param borderMode: Pixel extrapolation method (see :func:`borderInterpolate` ). When \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function.
- :param borderValue: A value used in case of a constant border. By default it is 0
+ :param borderValue: Value used in case of a constant border. By default, it is 0.
The function ``warpPerspective`` transforms the source image using the specified matrix:
when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
:func:`invert` and then put in the formula above instead of ``M`` .
-The function can not operate in-place.
-
-See also:
-:func:`warpAffine`,:func:`resize`,:func:`remap`,:func:`getRectSubPix`,:func:`perspectiveTransform`
+The function cannot operate in-place.
+
+See Also:
+:func:`warpAffine`,
+:func:`resize`,
+:func:`remap`,
+:func:`getRectSubPix`,
+:func:`perspectiveTransform`
\ No newline at end of file
projects / platform / upstream / opencv.git / commitdiff