From f5af3ab851195b337aef03451080d9182f867c7a Mon Sep 17 00:00:00 2001 From: Ilya Lavrenov Date: Wed, 25 Sep 2013 16:18:04 +0400 Subject: [PATCH] changes in OpenCL matrix operations docs --- modules/ocl/doc/operations_on_matrices.rst | 333 ++++++++++++++--------------- modules/ocl/include/opencv2/ocl/ocl.hpp | 121 +++++------ modules/ocl/src/matrix_operations.cpp | 13 +- 3 files changed, 225 insertions(+), 242 deletions(-) diff --git a/modules/ocl/doc/operations_on_matrices.rst b/modules/ocl/doc/operations_on_matrices.rst index e47e720..39888e2 100644 --- a/modules/ocl/doc/operations_on_matrices.rst +++ b/modules/ocl/doc/operations_on_matrices.rst @@ -7,29 +7,29 @@ ocl::oclMat::convertTo ---------------------- Returns void -.. ocv:function:: void ocl::oclMat::convertTo( oclMat &m, int rtype, double alpha = 1, double beta = 0 ) const +.. ocv:function:: void ocl::oclMat::convertTo(oclMat &m, int rtype, double alpha = 1, double beta = 0) const - :param m: The destination matrix. If it does not have a proper size or type before the operation, it will be reallocated + :param m: the destination matrix. If it does not have a proper size or type before the operation, it will be reallocated. - :param rtype: The desired destination matrix type, or rather, the depth(since the number of channels will be the same with the source one). If rtype is negative, the destination matrix will have the same type as the source. + :param rtype: the desired destination matrix type, or rather, the depth (since the number of channels will be the same with the source one). If rtype is negative, the destination matrix will have the same type as the source. - :param alpha: must be default now + :param alpha: optional scale factor. - :param beta: must be default now + :param beta: optional delta added to the scaled values. -The method converts source pixel values to the target datatype. saturate cast is applied in the end to avoid possible overflows. Supports CV_8UC1, CV_8UC4, CV_32SC1, CV_32SC4, CV_32FC1, CV_32FC4. +The method converts source pixel values to the target datatype. Saturate cast is applied in the end to avoid possible overflows. Supports all data types. ocl::oclMat::copyTo ------------------- Returns void -.. ocv:function:: void ocl::oclMat::copyTo( oclMat &m, const oclMat &mask ) const +.. ocv:function:: void ocl::oclMat::copyTo(oclMat &m, const oclMat &mask = oclMat()) const - :param m: The destination matrix. If it does not have a proper size or type before the operation, it will be reallocated + :param m: The destination matrix. If it does not have a proper size or type before the operation, it will be reallocated. - :param mask(optional): The operation mask. Its non-zero elements indicate, which matrix elements need to be copied + :param mask: The operation mask. Its non-zero elements indicate, which matrix elements need to be copied. -Copies the matrix to another one. Supports CV_8UC1, CV_8UC4, CV_32SC1, CV_32SC4, CV_32FC1, CV_32FC4 +Copies the matrix to another one. Supports all data types. ocl::oclMat::setTo ------------------ @@ -37,171 +37,163 @@ Returns oclMat .. ocv:function:: oclMat& ocl::oclMat::setTo(const Scalar &s, const oclMat &mask = oclMat()) - :param s: Assigned scalar, which is converted to the actual array type + :param s: Assigned scalar, which is converted to the actual array type. - :param mask: The operation mask of the same size as ``*this`` + :param mask: The operation mask of the same size as ``*this`` and type ``CV_8UC1``. -Sets all or some of the array elements to the specified value. This is the advanced variant of Mat::operator=(const Scalar s) operator. Supports CV_8UC1, CV_8UC4, CV_32SC1, CV_32SC4, CV_32FC1, CV_32FC4. +Sets all or some of the array elements to the specified value. This is the advanced variant of Mat::operator=(const Scalar s) operator. Supports all data types. ocl::absdiff ------------------ Returns void -.. ocv:function:: void ocl::absdiff( const oclMat& a, const oclMat& b, oclMat& c ) +.. ocv:function:: void ocl::absdiff(const oclMat& src1, const oclMat& src2, oclMat& dst) -.. ocv:function:: void ocl::absdiff( const oclMat& a, const Scalar& s, oclMat& c ) +.. ocv:function:: void ocl::absdiff(const oclMat& src1, const Scalar& s, oclMat& dst) + :param src1: the first input array. - :param a: The first input array + :param src2: the second input array, must be the same size and same type as ``src1``. - :param b: The second input array, must be the same size and same type as a + :param s: scalar, the second input parameter. - :param s: Scalar, the second input parameter + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param c: The destination array, it will have the same size and same type as a - -Computes per-element absolute difference between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element absolute difference between two arrays or between array and a scalar. Supports all data types. ocl::add ------------------ Returns void -.. ocv:function:: void ocl::add( const oclMat & a, const oclMat & b, oclMat & c ) - -.. ocv:function:: void ocl::add( const oclMat & a, const oclMat & b, oclMat & c, const oclMat & mask ) +.. ocv:function:: void ocl::add(const oclMat & src1, const oclMat & src2, oclMat & dst, const oclMat & mask = oclMat()) -.. ocv:function:: void ocl::add( const oclMat & a, const Scalar & sc, oclMat & c, const oclMat & mask=oclMat() ) +.. ocv:function:: void ocl::add(const oclMat & src1, const Scalar & s, oclMat & dst, const oclMat & mask = oclMat()) - :param a: The first input array + :param src1: the first input array. - :param b: The second input array, must be the same size and same type as src1 + :param src2: the second input array, must be the same size and same type as ``src1``. - :param sc: Scalar, the second input parameter + :param s: scalar, the second input parameter - :param c: The destination array, it will have the same size and same type as src1 + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param mask: he optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed + :param mask: the optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed. -Computes per-element additon between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element additon between two arrays or between array and a scalar. Supports all data types. ocl::subtract ------------------ Returns void -.. ocv:function:: void ocl::subtract( const oclMat& a, const oclMat& b, oclMat& c ) - -.. ocv:function:: void ocl::subtract( const oclMat& a, const oclMat& b, oclMat& c, const oclMat& mask ) - -.. ocv:function:: void ocl::subtract( const oclMat& a, const Scalar& sc, oclMat& c, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::subtract(const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask = oclMat()) -.. ocv:function:: void ocl::subtract( const Scalar& sc, const oclMat& a, oclMat& c, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::subtract(const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask = oclMat()) + :param src1: the first input array. - :param a: The first input array + :param src2: the second input array, must be the same size and same type as ``src1``. - :param b: The second input array, must be the same size and same type as src1 + :param s: scalar, the second input parameter. - :param sc: Scalar, the second input parameter + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param c: The destination array, it will have the same size and same type as src1 + :param mask: the optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed. - :param mask: he optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed - -Computes per-element subtract between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element subtract between two arrays or between array and a scalar. Supports all data types. ocl::multiply ------------------ Returns void -.. ocv:function:: void ocl::multiply( const oclMat& a, const oclMat& b, oclMat& c, double scale=1 ) +.. ocv:function:: void ocl::multiply(const oclMat& src1, const oclMat& src2, oclMat& dst, double scale = 1) - :param a: The first input array + :param src1: the first input array. - :param b: The second input array, must be the same size and same type as src1 + :param src2: the second input array, must be the same size and same type as ``src1``. - :param c: The destination array, it will have the same size and same type as src1 + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param scale: must be 1 now + :param scale: optional scale factor. -Computes per-element multiply between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element multiply between two arrays or between array and a scalar. Supports all data types. ocl::divide ------------------ Returns void -.. ocv:function:: void ocl::divide( const oclMat& a, const oclMat& b, oclMat& c, double scale=1 ) +.. ocv:function:: void ocl::divide(const oclMat& src1, const oclMat& src2, oclMat& dst, double scale = 1) -.. ocv:function:: void ocl::divide( double scale, const oclMat& b, oclMat& c ) +.. ocv:function:: void ocl::divide(double scale, const oclMat& src1, oclMat& dst) - :param a: The first input array + :param src1: the first input array. - :param b: The second input array, must be the same size and same type as src1 + :param src2: the second input array, must be the same size and same type as ``src1``. - :param c: The destination array, it will have the same size and same type as src1 + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param scale: must be 1 now + :param scale: scalar factor. -Computes per-element divide between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element divide between two arrays or between array and a scalar. Supports all data types. ocl::bitwise_and ------------------ Returns void -.. ocv:function:: void ocl::bitwise_and( const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::bitwise_and(const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask = oclMat()) -.. ocv:function:: void ocl::bitwise_and( const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::bitwise_and(const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask = oclMat()) - :param src1: The first input array + :param src1: the first input array. - :param src2: The second input array, must be the same size and same type as src1 + :param src2: the second input array, must be the same size and same type as ``src1``. - :param s: Scalar, the second input parameter + :param s: scalar, the second input parameter. - :param dst: The destination array, it will have the same size and same type as src1 + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed + :param mask: the optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed. -Computes per-element bitwise_and between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element bitwise_and between two arrays or between array and a scalar. Supports all data types. ocl::bitwise_or ------------------ Returns void -.. ocv:function:: void ocl::bitwise_or( const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::bitwise_or(const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask = oclMat()) -.. ocv:function:: void ocl::bitwise_or( const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::bitwise_or(const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask = oclMat()) - :param src1: The first input array + :param src1: the first input array. - :param src2: The second input array, must be the same size and same type as src1 + :param src2: the second input array, must be the same size and same type as ``src1``. - :param s: Scalar, the second input parameter + :param s: scalar, the second input parameter. - :param dst: The destination array, it will have the same size and same type as src1 + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed + :param mask: the optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed. -Computes per-element bitwise_or between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element bitwise_or between two arrays or between array and a scalar. Supports all data types. ocl::bitwise_xor ------------------ Returns void -.. ocv:function:: void ocl::bitwise_xor( const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::bitwise_xor(const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask = oclMat()) -.. ocv:function:: void ocl::bitwise_xor( const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask=oclMat() ) +.. ocv:function:: void ocl::bitwise_xor(const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask = oclMat()) - :param src1: The first input array + :param src1: the first input array. - :param src2: The second input array, must be the same size and same type as src1 + :param src2: the second input array, must be the same size and same type as ``src1``. - :param sc: Scalar, the second input parameter + :param sc: scalar, the second input parameter. - :param dst: The destination array, it will have the same size and same type as src1 + :param dst: the destination array, it will have the same size and same type as ``src1``. - :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed + :param mask: the optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed. -Computes per-element bitwise_xor between two arrays or between array and a scalar. Supports all data types except CV_8S. +Computes per-element bitwise_xor between two arrays or between array and a scalar. Supports all data types. ocl::bitwise_not ------------------ @@ -209,11 +201,11 @@ Returns void .. ocv:function:: void ocl::bitwise_not(const oclMat &src, oclMat &dst) - :param src: The input array + :param src: the input array. - :param dst: The destination array, it will have the same size and same type as src1 + :param dst: the destination array, it will have the same size and same type as ``src``. -The functions bitwise not compute per-element bit-wise inversion of the source array:. Supports all data types except CV_8S. +The functions bitwise not compute per-element bit-wise inversion of the source array. Supports all data types. ocl::cartToPolar ------------------ @@ -221,17 +213,17 @@ Returns void .. ocv:function:: void ocl::cartToPolar(const oclMat &x, const oclMat &y, oclMat &magnitude, oclMat &angle, bool angleInDegrees = false) - :param x: The array of x-coordinates; must be single-precision or double-precision floating-point array + :param x: the array of x-coordinates; must be single-precision or double-precision floating-point array. - :param y: The array of y-coordinates; it must have the same size and same type as x + :param y: the array of y-coordinates; it must have the same size and same type as ``x``. - :param magnitude: The destination array of magnitudes of the same size and same type as x + :param magnitude: the destination array of magnitudes of the same size and same type as ``x``. - :param angle: The destination array of angles of the same size and same type as x. The angles are measured in radians (0 to 2pi ) or in degrees (0 to 360 degrees). + :param angle: the destination array of angles of the same size and same type as ``x``. The angles are measured in radians (0 to 2pi) or in degrees (0 to 360 degrees). - :param angleInDegrees: The flag indicating whether the angles are measured in radians, which is default mode, or in degrees + :param angleInDegrees: the flag indicating whether the angles are measured in radians, which is default mode, or in degrees. -Calculates the magnitude and angle of 2d vectors. Supports only CV_32F and CV_64F data types. +Calculates the magnitude and angle of 2D vectors. Supports only ``CV_32F`` and ``CV_64F`` data types. ocl::polarToCart ------------------ @@ -239,57 +231,57 @@ Returns void .. ocv:function:: void ocl::polarToCart(const oclMat &magnitude, const oclMat &angle, oclMat &x, oclMat &y, bool angleInDegrees = false) - :param magnitude: The source floating-point array of magnitudes of 2D vectors. It can be an empty matrix (=Mat()) - in this case the function assumes that all the magnitudes are =1. If it's not empty, it must have the same size and same type as angle + :param magnitude: the source floating-point array of magnitudes of 2D vectors. It can be an empty matrix (=Mat()) - in this case the function assumes that all the magnitudes are = 1. If it's not empty, it must have the same size and same type as ``angle``. - :param angle: The source floating-point array of angles of the 2D vectors + :param angle: the source floating-point array of angles of the 2D vectors. - :param x: The destination array of x-coordinates of 2D vectors; will have the same size and the same type as angle + :param x: the destination array of x-coordinates of 2D vectors; will have the same size and the same type as ``angle``. - :param y: The destination array of y-coordinates of 2D vectors; will have the same size and the same type as angle + :param y: the destination array of y-coordinates of 2D vectors; will have the same size and the same type as ``angle``. - :param angleInDegrees: The flag indicating whether the angles are measured in radians, which is default mode, or in degrees + :param angleInDegrees: the flag indicating whether the angles are measured in radians, which is default mode, or in degrees. -The function polarToCart computes the cartesian coordinates of each 2D vector represented by the corresponding elements of magnitude and angle. Supports only CV_32F and CV_64F data types. +The function polarToCart computes the cartesian coordinates of each 2D vector represented by the corresponding elements of magnitude and angle. Supports only ``CV_32F`` and ``CV_64F`` data types. ocl::compare ------------------ Returns void -.. ocv:function:: void ocl::compare(const oclMat &a, const oclMat &b, oclMat &c, int cmpop) +.. ocv:function:: void ocl::compare(const oclMat &src1, const oclMat &src2, oclMat &dst, int cmpop) - :param a: The first source array + :param src1: the first source array. - :param b: The second source array; must have the same size and same type as a + :param src2: the second source array; must have the same size and same type as ``src1``. - :param c: The destination array; will have the same size as a + :param dst: the destination array; will have the same size as ``src1`` and type ``CV_8UC1``. - :param cmpop: The flag specifying the relation between the elements to be checked + :param cmpop: the flag specifying the relation between the elements to be checked. -Performs per-element comparison of two arrays or an array and scalar value. Supports all the 1 channel data types except CV_8S. +Performs per-element comparison of two arrays or an array and scalar value. Supports all data types. ocl::exp ------------------ Returns void -.. ocv:function:: void ocl::exp(const oclMat &a, oclMat &b) +.. ocv:function:: void ocl::exp(const oclMat &src, oclMat &dst) - :param a: The first source array + :param src: the first source array. - :param b: The dst array; must have the same size and same type as a + :param dst: the dst array; must have the same size and same type as ``src``. -The function exp calculates the exponent of every element of the input array. Supports only CV_32FC1 data type. +The function exp calculates the exponent of every element of the input array. Supports only ``CV_32FC1`` and ``CV_64F`` data types. ocl::log ------------------ Returns void -.. ocv:function:: void ocl::log(const oclMat &a, oclMat &b) +.. ocv:function:: void ocl::log(const oclMat &src, oclMat &dst) - :param a: The first source array + :param src: the first source array. - :param b: The dst array; must have the same size and same type as a + :param dst: the dst array; must have the same size and same type as ``src``. -The function log calculates the log of every element of the input array. Supports only CV_32FC1 data type. +The function log calculates the log of every element of the input array. Supports only ``CV_32FC1`` and ``CV_64F`` data types. ocl::LUT ------------------ @@ -297,13 +289,13 @@ Returns void .. ocv:function:: void ocl::LUT(const oclMat &src, const oclMat &lut, oclMat &dst) - :param src: Source array of 8-bit elements + :param src: source array of 8-bit elements. - :param lut: Look-up table of 256 elements. In the case of multi-channel source array, the table should either have a single channel (in this case the same table is used for all channels) or the same number of channels as in the source array + :param lut: look-up table of 256 elements. In the case of multi-channel source array, the table should either have a single channel (in this case the same table is used for all channels) or the same number of channels as in the source array. - :param dst: Destination array; will have the same size and the same number of channels as src, and the same depth as lut + :param dst: destination array; will have the same size and the same number of channels as ``src``, and the same depth as ``lut``. -Performs a look-up table transform of an array. Supports only CV_8UC1 and CV_8UC4 data type. +Performs a look-up table transform of an array. ocl::magnitude ------------------ @@ -311,25 +303,25 @@ Returns void .. ocv:function:: void ocl::magnitude(const oclMat &x, const oclMat &y, oclMat &magnitude) - :param x: The floating-point array of x-coordinates of the vectors + :param x: the floating-point array of x-coordinates of the vectors. - :param y: he floating-point array of y-coordinates of the vectors; must have the same size as x + :param y: the floating-point array of y-coordinates of the vectors; must have the same size as ``x``. - :param magnitude: The destination array; will have the same size and same type as x + :param magnitude: the destination array; will have the same size and same type as ``x``. -The function magnitude calculates magnitude of 2D vectors formed from the corresponding elements of x and y arrays. Supports only CV_32F and CV_64F data type. +The function magnitude calculates magnitude of 2D vectors formed from the corresponding elements of ``x`` and ``y`` arrays. Supports only ``CV_32F`` and ``CV_64F`` data types. ocl::flip ------------------ Returns void -.. ocv:function:: void ocl::flip( const oclMat& a, oclMat& b, int flipCode ) +.. ocv:function:: void ocl::flip(const oclMat& src, oclMat& dst, int flipCode) - :param a: Source image. + :param src: source image. - :param b: Destination image + :param dst: destination image. - :param flipCode: Specifies how to flip the array: 0 means flipping around the x-axis, positive (e.g., 1) means flipping around y-axis, and negative (e.g., -1) means flipping around both axes. + :param flipCode: specifies how to flip the array: 0 means flipping around the x-axis, positive (e.g., 1) means flipping around y-axis, and negative (e.g., -1) means flipping around both axes. The function flip flips the array in one of three different ways (row and column indices are 0-based). Supports all data types. @@ -339,13 +331,13 @@ Returns void .. ocv:function:: void ocl::meanStdDev(const oclMat &mtx, Scalar &mean, Scalar &stddev) - :param mtx: Source image. + :param mtx: source image. - :param mean: The output parameter: computed mean value + :param mean: the output parameter: computed mean value. - :param stddev: The output parameter: computed standard deviation + :param stddev: the output parameter: computed standard deviation. -The functions meanStdDev compute the mean and the standard deviation M of array elements, independently for each channel, and return it via the output parameters. Supports all data types except CV_32F,CV_64F +The functions meanStdDev compute the mean and the standard deviation M of array elements, independently for each channel, and return it via the output parameters. Supports all data types except ``CV_32F``, ``CV_64F``. ocl::merge ------------------ @@ -353,9 +345,9 @@ Returns void .. ocv:function:: void ocl::merge(const vector &src, oclMat &dst) - :param src: The source array or vector of the single-channel matrices to be merged. All the matrices in src must have the same size and the same type + :param src: The source array or vector of the single-channel matrices to be merged. All the matrices in src must have the same size and the same type. - :param dst: The destination array; will have the same size and the same depth as src, the number of channels will match the number of source matrices + :param dst: The destination array; will have the same size and the same depth as src, the number of channels will match the number of source matrices. Composes a multi-channel array from several single-channel arrays. Supports all data types. @@ -379,13 +371,13 @@ Returns the calculated norm .. ocv:function:: double ocl::norm(const oclMat &src1, const oclMat &src2, int normType = NORM_L2) - :param src1: The first source array + :param src1: the first source array. - :param src2: The second source array of the same size and the same type as src1 + :param src2: the second source array of the same size and the same type as ``src1``. - :param normType: Type of the norm + :param normType: type of the norm. -Calculates absolute array norm, absolute difference norm, or relative difference norm. Supports only CV_8UC1 data type. +Calculates absolute array norm, absolute difference norm, or relative difference norm. Supports only ``CV_8UC1`` data type. ocl::phase ------------------ @@ -393,15 +385,15 @@ Returns void .. ocv:function:: void ocl::phase(const oclMat &x, const oclMat &y, oclMat &angle, bool angleInDegrees = false) - :param x: The source floating-point array of x-coordinates of 2D vectors + :param x: the source floating-point array of x-coordinates of 2D vectors - :param y: The source array of y-coordinates of 2D vectors; must have the same size and the same type as x + :param y: the source array of y-coordinates of 2D vectors; must have the same size and the same type as ``x``. - :param angle: The destination array of vector angles; it will have the same size and same type as x + :param angle: the destination array of vector angles; it will have the same size and same type as ``x``. - :param angleInDegrees: When it is true, the function will compute angle in degrees, otherwise they will be measured in radians + :param angleInDegrees: when it is true, the function will compute angle in degrees, otherwise they will be measured in radians. -The function phase computes the rotation angle of each 2D vector that is formed from the corresponding elements of x and y. Supports only CV_32FC1 and CV_64FC1 data type. +The function phase computes the rotation angle of each 2D vector that is formed from the corresponding elements of ``x`` and ``y``. Supports only ``CV_32FC1`` and ``CV_64FC1`` data type. ocl::pow ------------------ @@ -409,13 +401,13 @@ Returns void .. ocv:function:: void ocl::pow(const oclMat &x, double p, oclMat &y) - :param x: The source array + :param x: the source array. - :param power: The exponent of power;The source floating-point array of angles of the 2D vectors + :param p: the exponent of power; the source floating-point array of angles of the 2D vectors. - :param y: The destination array, should be the same type as the source + :param y: the destination array, should be the same type as the source. -The function pow raises every element of the input array to p. Supports only CV_32FC1 and CV_64FC1 data type. +The function pow raises every element of the input array to ``p``. Supports only ``CV_32FC1`` and ``CV_64FC1`` data types. ocl::transpose ------------------ @@ -423,26 +415,26 @@ Returns void .. ocv:function:: void ocl::transpose(const oclMat &src, oclMat &dst) - :param src: The source array + :param src: the source array. - :param dst: The destination array of the same type as src + :param dst: the destination array of the same type as ``src``. -Transposes a matrix. Supports 8UC1, 8UC4, 8SC4, 16UC2, 16SC2, 32SC1 and 32FC1 data types. +Transposes a matrix (in case when ``src`` == ``dst`` and matrix is square the operation are performed inplace) ocl::dft ------------ Performs a forward or inverse discrete Fourier transform (1D or 2D) of the floating point matrix. -.. ocv:function:: void ocl::dft( const oclMat& src, oclMat& dst, Size dft_size=Size(0, 0), int flags=0 ) +.. ocv:function:: void ocl::dft(const oclMat& src, oclMat& dst, Size dft_size = Size(), int flags = 0) - :param src: Source matrix (real or complex). + :param src: source matrix (real or complex). - :param dst: Destination matrix (real or complex). + :param dst: destination matrix (real or complex). - :param dft_size: Size of original input, which is used for transformation from complex to real. + :param dft_size: size of original input, which is used for transformation from complex to real. - :param flags: Optional flags: + :param flags: optional flags: * **DFT_ROWS** transforms each individual row of the source matrix. @@ -452,9 +444,9 @@ Performs a forward or inverse discrete Fourier transform (1D or 2D) of the float * **DFT_REAL_OUTPUT** specifies the output as real. The source matrix is the result of real-complex transform, so the destination matrix must be real. -Use to handle real matrices ( ``CV32FC1`` ) and complex matrices in the interleaved format ( ``CV32FC2`` ). +Use to handle real matrices (``CV_32FC1``) and complex matrices in the interleaved format (``CV_32FC2``). -The dft_size must be powers of 2, 3 and 5. Real to complex dft output is not the same with cpu version. real to complex and complex to real does not support DFT_ROWS +The ``dft_size`` must be powers of ``2``, ``3`` and ``5``. Real to complex dft output is not the same with cpu version. Real to complex and complex to real does not support ``DFT_ROWS``. .. seealso:: :ocv:func:`dft` @@ -464,22 +456,22 @@ Performs generalized matrix multiplication. .. ocv:function:: void ocl::gemm(const oclMat& src1, const oclMat& src2, double alpha, const oclMat& src3, double beta, oclMat& dst, int flags = 0) - :param src1: First multiplied input matrix that should be ``CV_32FC1`` type. + :param src1: first multiplied input matrix that should be ``CV_32FC1`` type. - :param src2: Second multiplied input matrix of the same type as ``src1`` . + :param src2: second multiplied input matrix of the same type as ``src1``. - :param alpha: Weight of the matrix product. + :param alpha: weight of the matrix product. - :param src3: Third optional delta matrix added to the matrix product. It should have the same type as ``src1`` and ``src2`` . + :param src3: third optional delta matrix added to the matrix product. It should have the same type as ``src1`` and ``src2``. - :param beta: Weight of ``src3`` . + :param beta: weight of ``src3``. - :param dst: Destination matrix. It has the proper size and the same type as input matrices. + :param dst: destination matrix. It has the proper size and the same type as input matrices. - :param flags: Operation flags: + :param flags: operation flags: - * **GEMM_1_T** transpose ``src1`` - * **GEMM_2_T** transpose ``src2`` + * **GEMM_1_T** transpose ``src1``. + * **GEMM_2_T** transpose ``src2``. .. seealso:: :ocv:func:`gemm` @@ -489,28 +481,29 @@ Returns void .. ocv:function:: void ocl::sortByKey(oclMat& keys, oclMat& values, int method, bool isGreaterThan = false) - :param keys: The keys to be used as sorting indices. + :param keys: the keys to be used as sorting indices. - :param values: The array of values. + :param values: the array of values. - :param isGreaterThan: Determine sorting order. + :param isGreaterThan: determine sorting order. :param method: supported sorting methods: - * **SORT_BITONIC** bitonic sort, only support power-of-2 buffer size - * **SORT_SELECTION** selection sort, currently cannot sort duplicate keys - * **SORT_MERGE** merge sort - * **SORT_RADIX** radix sort, only support signed int/float keys(``CV_32S``/``CV_32F``) + + * **SORT_BITONIC** bitonic sort, only support power-of-2 buffer size. + * **SORT_SELECTION** selection sort, currently cannot sort duplicate keys. + * **SORT_MERGE** merge sort. + * **SORT_RADIX** radix sort, only support signed int/float keys(``CV_32S``/``CV_32F``). Returns the sorted result of all the elements in values based on equivalent keys. -The element unit in the values to be sorted is determined from the data type, -i.e., a ``CV_32FC2`` input ``{a1a2, b1b2}`` will be considered as two elements, regardless its matrix dimension. +The element unit in the values to be sorted is determined from the data type, i.e., a ``CV_32FC2`` input ``{a1a2, b1b2}`` will be considered as two elements, regardless its matrix dimension. Both keys and values will be sorted inplace. -Keys needs to be a **single** channel `oclMat`. +Keys needs to be a **single** channel ``oclMat``. Example:: + input - keys = {2, 3, 1} (CV_8UC1) values = {10,5, 4,3, 6,2} (CV_8UC2) diff --git a/modules/ocl/include/opencv2/ocl/ocl.hpp b/modules/ocl/include/opencv2/ocl/ocl.hpp index d46ad50..d3dbded 100644 --- a/modules/ocl/include/opencv2/ocl/ocl.hpp +++ b/modules/ocl/include/opencv2/ocl/ocl.hpp @@ -268,13 +268,12 @@ namespace cv //! returns deep copy of the oclMatrix, i.e. the data is copied oclMat clone() const; - //! copies the oclMatrix content to "m". + + //! copies those oclMatrix elements to "m" that are marked with non-zero mask elements. // It calls m.create(this->size(), this->type()). // It supports any data type - void copyTo( oclMat &m ) const; - //! copies those oclMatrix elements to "m" that are marked with non-zero mask elements. - //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4 - void copyTo( oclMat &m, const oclMat &mask ) const; + void copyTo( oclMat &m, const oclMat &mask = oclMat()) const; + //! converts oclMatrix to another datatype with optional scalng. See cvConvertScale. //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4 void convertTo( oclMat &m, int rtype, double alpha = 1, double beta = 0 ) const; @@ -410,57 +409,51 @@ namespace cv ////////////////////////////// Arithmetics /////////////////////////////////// - //#if defined DOUBLE_SUPPORT - //typedef double F; - //#else - //typedef float F; - //#endif - - // CV_EXPORTS void addWeighted(const oclMat& a,F alpha, const oclMat& b,F beta,F gama, oclMat& c); - CV_EXPORTS void addWeighted(const oclMat &a, double alpha, const oclMat &b, double beta, double gama, oclMat &c); - - //! adds one matrix to another (c = a + b) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void add(const oclMat &a, const oclMat &b, oclMat &c, const oclMat &mask = oclMat()); - //! adds scalar to a matrix (c = a + s) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void add(const oclMat &a, const Scalar &sc, oclMat &c, const oclMat &mask = oclMat()); - - //! subtracts one matrix from another (c = a - b) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void subtract(const oclMat &a, const oclMat &b, oclMat &c, const oclMat &mask = oclMat()); - //! subtracts scalar from a matrix (c = a - s) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void subtract(const oclMat &a, const Scalar &sc, oclMat &c, const oclMat &mask = oclMat()); - - //! computes element-wise product of the two arrays (c = a * b) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void multiply(const oclMat &a, const oclMat &b, oclMat &c, double scale = 1); + //! adds one matrix to another with scale (dst = src1 * alpha + src2 * beta + gama) + CV_EXPORTS void addWeighted(const oclMat &src1, double alpha, const oclMat &src2, double beta, double gama, oclMat &dst); + + //! adds one matrix to another (dst = src1 + src2) + // supports all data types + CV_EXPORTS void add(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat &mask = oclMat()); + //! adds scalar to a matrix (dst = src1 + s) + // supports all data types + CV_EXPORTS void add(const oclMat &src1, const Scalar &s, oclMat &dst, const oclMat &mask = oclMat()); + + //! subtracts one matrix from another (dst = src1 - src2) + // supports all data types + CV_EXPORTS void subtract(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat &mask = oclMat()); + //! subtracts scalar from a matrix (dst = src1 - s) + // supports all data types + CV_EXPORTS void subtract(const oclMat &src1, const Scalar &s, oclMat &dst, const oclMat &mask = oclMat()); + + //! computes element-wise product of the two arrays (dst = src1 * scale * src2) + // supports all data types + CV_EXPORTS void multiply(const oclMat &src1, const oclMat &src2, oclMat &dst, double scale = 1); //! multiplies matrix to a number (dst = scalar * src) - // supports CV_32FC1 only + // supports all data types CV_EXPORTS void multiply(double scalar, const oclMat &src, oclMat &dst); - //! computes element-wise quotient of the two arrays (c = a / b) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void divide(const oclMat &a, const oclMat &b, oclMat &c, double scale = 1); - //! computes element-wise quotient of the two arrays (c = a / b) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void divide(double scale, const oclMat &b, oclMat &c); + //! computes element-wise quotient of the two arrays (dst = src1 * scale / src2) + // supports all data types + CV_EXPORTS void divide(const oclMat &src1, const oclMat &src2, oclMat &dst, double scale = 1); + //! computes element-wise quotient of the two arrays (dst = scale / src) + // supports all data types + CV_EXPORTS void divide(double scale, const oclMat &src1, oclMat &dst); - //! compares elements of two arrays (c = a b) - // supports except CV_8SC1,CV_8SC2,CV8SC3,CV_8SC4 types - CV_EXPORTS void compare(const oclMat &a, const oclMat &b, oclMat &c, int cmpop); + //! compares elements of two arrays (dst = src1 src2) + // supports all data types + CV_EXPORTS void compare(const oclMat &src1, const oclMat &src2, oclMat &dst, int cmpop); //! transposes the matrix - // supports CV_8UC1, 8UC4, 8SC4, 16UC2, 16SC2, 32SC1 and 32FC1.(the same as cuda) + // supports all data types CV_EXPORTS void transpose(const oclMat &src, oclMat &dst); - //! computes element-wise absolute difference of two arrays (c = abs(a - b)) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void absdiff(const oclMat &a, const oclMat &b, oclMat &c); - //! computes element-wise absolute difference of array and scalar (c = abs(a - s)) - // supports all types except CV_8SC1,CV_8SC2,CV8SC3 and CV_8SC4 - CV_EXPORTS void absdiff(const oclMat &a, const Scalar &s, oclMat &c); + //! computes element-wise absolute difference of two arrays (dst = abs(src1 - src2)) + // supports all data types + CV_EXPORTS void absdiff(const oclMat &src1, const oclMat &src2, oclMat &dst); + //! computes element-wise absolute difference of array and scalar (dst = abs(src1 - s)) + // supports all data types + CV_EXPORTS void absdiff(const oclMat &src1, const Scalar &s, oclMat &dst); //! computes mean value and standard deviation of all or selected array elements // supports except CV_32F,CV_64F @@ -478,7 +471,7 @@ namespace cv //! reverses the order of the rows, columns or both in a matrix // supports all types - CV_EXPORTS void flip(const oclMat &a, oclMat &b, int flipCode); + CV_EXPORTS void flip(const oclMat &src, oclMat &dst, int flipCode); //! computes sum of array elements // disabled until fix crash @@ -489,13 +482,11 @@ namespace cv //! finds global minimum and maximum array elements and returns their values // support all C1 types - CV_EXPORTS void minMax(const oclMat &src, double *minVal, double *maxVal = 0, const oclMat &mask = oclMat()); CV_EXPORTS void minMax_buf(const oclMat &src, double *minVal, double *maxVal, const oclMat &mask, oclMat& buf); //! finds global minimum and maximum array elements and returns their values with locations // support all C1 types - CV_EXPORTS void minMaxLoc(const oclMat &src, double *minVal, double *maxVal = 0, Point *minLoc = 0, Point *maxLoc = 0, const oclMat &mask = oclMat()); @@ -524,27 +515,27 @@ namespace cv // This is not truly a bilateral filter. Instead of using user provided fixed parameters, // the function calculates a constant at each window based on local standard deviation, // and use this constant to do filtering. - // supports 8UC1 8UC3 + // supports 8UC1, 8UC3 CV_EXPORTS void adaptiveBilateralFilter(const oclMat& src, oclMat& dst, Size ksize, double sigmaSpace, Point anchor = Point(-1, -1), int borderType=BORDER_DEFAULT); - //! computes exponent of each matrix element (b = e**a) - // supports only CV_32FC1 type - CV_EXPORTS void exp(const oclMat &a, oclMat &b); + //! computes exponent of each matrix element (dst = e**src) + // supports only CV_32FC1, CV_64FC1 type + CV_EXPORTS void exp(const oclMat &src, oclMat &dst); - //! computes natural logarithm of absolute value of each matrix element: b = log(abs(a)) - // supports only CV_32FC1 type - CV_EXPORTS void log(const oclMat &a, oclMat &b); + //! computes natural logarithm of absolute value of each matrix element: dst = log(abs(src)) + // supports only CV_32FC1, CV_64FC1 type + CV_EXPORTS void log(const oclMat &src, oclMat &dst); //! computes magnitude of each (x(i), y(i)) vector - // supports only CV_32F CV_64F type + // supports only CV_32F, CV_64F type CV_EXPORTS void magnitude(const oclMat &x, const oclMat &y, oclMat &magnitude); //! computes angle (angle(i)) of each (x(i), y(i)) vector - // supports only CV_32F CV_64F type + // supports only CV_32F, CV_64F type CV_EXPORTS void phase(const oclMat &x, const oclMat &y, oclMat &angle, bool angleInDegrees = false); //! the function raises every element of tne input array to p - //! support only CV_32F CV_64F type + // support only CV_32F, CV_64F type CV_EXPORTS void pow(const oclMat &x, double p, oclMat &y); //! converts Cartesian coordinates to polar @@ -558,14 +549,17 @@ namespace cv //! perfroms per-elements bit-wise inversion // supports all types CV_EXPORTS void bitwise_not(const oclMat &src, oclMat &dst); + //! calculates per-element bit-wise disjunction of two arrays // supports all types CV_EXPORTS void bitwise_or(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat &mask = oclMat()); CV_EXPORTS void bitwise_or(const oclMat &src1, const Scalar &s, oclMat &dst, const oclMat &mask = oclMat()); + //! calculates per-element bit-wise conjunction of two arrays // supports all types CV_EXPORTS void bitwise_and(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat &mask = oclMat()); CV_EXPORTS void bitwise_and(const oclMat &src1, const Scalar &s, oclMat &dst, const oclMat &mask = oclMat()); + //! calculates per-element bit-wise "exclusive or" operation // supports all types CV_EXPORTS void bitwise_xor(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat &mask = oclMat()); @@ -585,12 +579,13 @@ namespace cv CV_EXPORTS oclMatExpr operator / (const oclMat &src1, const oclMat &src2); //! computes convolution of two images - //! support only CV_32FC1 type + // support only CV_32FC1 type CV_EXPORTS void convolve(const oclMat &image, const oclMat &temp1, oclMat &result); CV_EXPORTS void cvtColor(const oclMat &src, oclMat &dst, int code , int dcn = 0); CV_EXPORTS void setIdentity(oclMat& src, double val); + //////////////////////////////// Filter Engine //////////////////////////////// /*! @@ -982,7 +977,7 @@ namespace cv // real to complex dft requires at least v1.8 clAmdFft // real to complex dft output is not the same with cpu version // real to complex and complex to real does not support DFT_ROWS - CV_EXPORTS void dft(const oclMat &src, oclMat &dst, Size dft_size = Size(0, 0), int flags = 0); + CV_EXPORTS void dft(const oclMat &src, oclMat &dst, Size dft_size = Size(), int flags = 0); //! implements generalized matrix product algorithm GEMM from BLAS // The functionality requires clAmdBlas library diff --git a/modules/ocl/src/matrix_operations.cpp b/modules/ocl/src/matrix_operations.cpp index ff52b8a..78d1cd4 100644 --- a/modules/ocl/src/matrix_operations.cpp +++ b/modules/ocl/src/matrix_operations.cpp @@ -347,19 +347,14 @@ static void copy_to_with_mask(const oclMat &src, oclMat &dst, const oclMat &mask localThreads, args, -1, -1, compile_option); } -void cv::ocl::oclMat::copyTo( oclMat &m ) const -{ - CV_DbgAssert(!this->empty()); - m.create(size(), type()); - openCLCopyBuffer2D(clCxt, m.data, m.step, m.offset, - data, step, cols * elemSize(), rows, offset); -} - void cv::ocl::oclMat::copyTo( oclMat &mat, const oclMat &mask) const { if (mask.empty()) { - copyTo(mat); + CV_DbgAssert(!this->empty()); + mat.create(size(), type()); + openCLCopyBuffer2D(clCxt, mat.data, mat.step, mat.offset, + data, step, cols * elemSize(), rows, offset); } else { -- 2.7.4