modules/ocl/doc/operations_on_matrices.rst

   1 Operations on Matrics
   2 =============================
   3
   4 .. highlight:: cpp
   5
   6 ocl::oclMat::convertTo
   7 ----------------------
   8 Returns void
   9
  10 .. ocv:function:: void ocl::oclMat::convertTo( oclMat &m, int rtype, double alpha = 1, double beta = 0 ) const
  11
  12     :param m: The destination matrix. If it does not have a proper size or type before the operation, it will be reallocated
  13
  14     :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.
  15
  16     :param alpha: must be default now
  17
  18     :param beta: must be default now
  19
  20 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.
  21
  22 ocl::oclMat::copyTo
  23 -------------------
  24 Returns void
  25
  26 .. ocv:function:: void ocl::oclMat::copyTo( oclMat &m, const oclMat &mask ) const
  27
  28     :param m: The destination matrix. If it does not have a proper size or type before the operation, it will be reallocated
  29
  30     :param mask(optional): The operation mask. Its non-zero elements indicate, which matrix elements need to be copied
  31
  32 Copies the matrix to another one. Supports CV_8UC1, CV_8UC4, CV_32SC1, CV_32SC4, CV_32FC1, CV_32FC4
  33
  34 ocl::oclMat::setTo
  35 ------------------
  36 Returns oclMat
  37
  38 .. ocv:function:: oclMat& ocl::oclMat::setTo(const Scalar &s, const oclMat &mask = oclMat())
  39
  40     :param s: Assigned scalar, which is converted to the actual array type
  41
  42     :param mask: The operation mask of the same size as ``*this``
  43
  44 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.
  45
  46 ocl::absdiff
  47 ------------------
  48 Returns void
  49
  50 .. ocv:function:: void ocl::absdiff( const oclMat& a, const oclMat& b, oclMat& c )
  51
  52 .. ocv:function:: void ocl::absdiff( const oclMat& a, const Scalar& s, oclMat& c )
  53
  54
  55     :param a: The first input array
  56
  57     :param b: The second input array, must be the same size and same type as a
  58
  59     :param s: Scalar, the second input parameter
  60
  61     :param c: The destination array, it will have the same size and same type as a
  62
  63 Computes per-element absolute difference between two arrays or between array and a scalar. Supports all data types except CV_8S.
  64
  65 ocl::add
  66 ------------------
  67 Returns void
  68
  69 .. ocv:function:: void ocl::add( const oclMat & a, const oclMat & b, oclMat & c )
  70
  71 .. ocv:function:: void ocl::add( const oclMat & a, const oclMat & b, oclMat & c, const oclMat & mask )
  72
  73 .. ocv:function:: void ocl::add( const oclMat & a, const Scalar & sc, oclMat & c, const oclMat & mask=oclMat() )
  74
  75     :param a: The first input array
  76
  77     :param b: The second input array, must be the same size and same type as src1
  78
  79     :param sc: Scalar, the second input parameter
  80
  81     :param c: The destination array, it will have the same size and same type as src1
  82
  83     :param mask: he optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
  84
  85 Computes per-element additon between two arrays or between array and a scalar. Supports all data types except CV_8S.
  86
  87 ocl::subtract
  88 ------------------
  89 Returns void
  90
  91 .. ocv:function:: void ocl::subtract( const oclMat& a, const oclMat& b, oclMat& c )
  92
  93 .. ocv:function:: void ocl::subtract( const oclMat& a, const oclMat& b, oclMat& c, const oclMat& mask )
  94
  95 .. ocv:function:: void ocl::subtract( const oclMat& a, const Scalar& sc, oclMat& c, const oclMat& mask=oclMat() )
  96
  97 .. ocv:function:: void ocl::subtract( const Scalar& sc, const oclMat& a, oclMat& c, const oclMat& mask=oclMat() )
  98
  99
 100     :param a: The first input array
 101
 102     :param b: The second input array, must be the same size and same type as src1
 103
 104     :param sc: Scalar, the second input parameter
 105
 106     :param c: The destination array, it will have the same size and same type as src1
 107
 108     :param mask: he optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
 109
 110 Computes per-element subtract between two arrays or between array and a scalar. Supports all data types except CV_8S.
 111
 112 ocl::multiply
 113 ------------------
 114 Returns void
 115
 116 .. ocv:function:: void ocl::multiply( const oclMat& a, const oclMat& b, oclMat& c, double scale=1 )
 117
 118     :param a: The first input array
 119
 120     :param b: The second input array, must be the same size and same type as src1
 121
 122     :param c: The destination array, it will have the same size and same type as src1
 123
 124     :param scale: must be 1 now
 125
 126 Computes per-element multiply between two arrays or between array and a scalar. Supports all data types except CV_8S.
 127
 128 ocl::divide
 129 ------------------
 130 Returns void
 131
 132 .. ocv:function:: void ocl::divide( const oclMat& a, const oclMat& b, oclMat& c, double scale=1 )
 133
 134 .. ocv:function:: void ocl::divide( double scale, const oclMat& b, oclMat& c )
 135
 136     :param a: The first input array
 137
 138     :param b: The second input array, must be the same size and same type as src1
 139
 140     :param c: The destination array, it will have the same size and same type as src1
 141
 142     :param scale: must be 1 now
 143
 144 Computes per-element divide between two arrays or between array and a scalar. Supports all data types except CV_8S.
 145
 146 ocl::bitwise_and
 147 ------------------
 148 Returns void
 149
 150 .. ocv:function:: void ocl::bitwise_and( const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask=oclMat() )
 151
 152 .. ocv:function:: void ocl::bitwise_and( const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask=oclMat() )
 153
 154     :param src1: The first input array
 155
 156     :param src2: The second input array, must be the same size and same type as src1
 157
 158     :param s: Scalar, the second input parameter
 159
 160     :param dst: The destination array, it will have the same size and same type as src1
 161
 162     :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
 163
 164 Computes per-element bitwise_and between two arrays or between array and a scalar. Supports all data types except CV_8S.
 165
 166 ocl::bitwise_or
 167 ------------------
 168 Returns void
 169
 170 .. ocv:function:: void ocl::bitwise_or( const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask=oclMat() )
 171
 172 .. ocv:function:: void ocl::bitwise_or( const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask=oclMat() )
 173
 174     :param src1: The first input array
 175
 176     :param src2: The second input array, must be the same size and same type as src1
 177
 178     :param s: Scalar, the second input parameter
 179
 180     :param dst: The destination array, it will have the same size and same type as src1
 181
 182     :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
 183
 184 Computes per-element bitwise_or between two arrays or between array and a scalar. Supports all data types except CV_8S.
 185
 186 ocl::bitwise_xor
 187 ------------------
 188 Returns void
 189
 190 .. ocv:function:: void ocl::bitwise_xor( const oclMat& src1, const oclMat& src2, oclMat& dst, const oclMat& mask=oclMat() )
 191
 192 .. ocv:function:: void ocl::bitwise_xor( const oclMat& src1, const Scalar& s, oclMat& dst, const oclMat& mask=oclMat() )
 193
 194     :param src1: The first input array
 195
 196     :param src2: The second input array, must be the same size and same type as src1
 197
 198     :param sc: Scalar, the second input parameter
 199
 200     :param dst: The destination array, it will have the same size and same type as src1
 201
 202     :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
 203
 204 Computes per-element bitwise_xor between two arrays or between array and a scalar. Supports all data types except CV_8S.
 205
 206 ocl::bitwise_not
 207 ------------------
 208 Returns void
 209
 210 .. ocv:function:: void ocl::bitwise_not(const oclMat &src, oclMat &dst)
 211
 212     :param src: The input array
 213
 214     :param dst: The destination array, it will have the same size and same type as src1
 215
 216 The functions bitwise not compute per-element bit-wise inversion of the source array:. Supports all data types except CV_8S.
 217
 218 ocl::cartToPolar
 219 ------------------
 220 Returns void
 221
 222 .. ocv:function:: void ocl::cartToPolar(const oclMat &x, const oclMat &y, oclMat &magnitude, oclMat &angle, bool angleInDegrees = false)
 223
 224     :param x: The array of x-coordinates; must be single-precision or double-precision floating-point array
 225
 226     :param y: The array of y-coordinates; it must have the same size and same type as x
 227
 228     :param magnitude: The destination array of magnitudes of the same size and same type as x
 229
 230     :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).
 231
 232     :param angleInDegrees: The flag indicating whether the angles are measured in radians, which is default mode, or in degrees
 233
 234 Calculates the magnitude and angle of 2d vectors. Supports only CV_32F and CV_64F data types.
 235
 236 ocl::polarToCart
 237 ------------------
 238 Returns void
 239
 240 .. ocv:function:: void ocl::polarToCart(const oclMat &magnitude, const oclMat &angle, oclMat &x, oclMat &y, bool angleInDegrees = false)
 241
 242     :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
 243
 244     :param angle: The source floating-point array of angles of the 2D vectors
 245
 246     :param x: The destination array of x-coordinates of 2D vectors; will have the same size and the same type as angle
 247
 248     :param y: The destination array of y-coordinates of 2D vectors; will have the same size and the same type as angle
 249
 250     :param angleInDegrees: The flag indicating whether the angles are measured in radians, which is default mode, or in degrees
 251
 252 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.
 253
 254 ocl::compare
 255 ------------------
 256 Returns void
 257
 258 .. ocv:function:: void ocl::compare(const oclMat &a, const oclMat &b, oclMat &c, int cmpop)
 259
 260     :param a: The first source array
 261
 262     :param b: The second source array; must have the same size and same type as a
 263
 264     :param c: The destination array; will have the same size as a
 265
 266     :param cmpop: The flag specifying the relation between the elements to be checked
 267
 268 Performs per-element comparison of two arrays or an array and scalar value. Supports all the 1 channel data types except CV_8S.
 269
 270 ocl::exp
 271 ------------------
 272 Returns void
 273
 274 .. ocv:function:: void ocl::exp(const oclMat &a, oclMat &b)
 275
 276     :param a: The first source array
 277
 278     :param b: The dst array; must have the same size and same type as a
 279
 280 The function exp calculates the exponent of every element of the input array. Supports only CV_32FC1 data type.
 281
 282 ocl::log
 283 ------------------
 284 Returns void
 285
 286 .. ocv:function:: void ocl::log(const oclMat &a, oclMat &b)
 287
 288     :param a: The first source array
 289
 290     :param b: The dst array; must have the same size and same type as a
 291
 292 The function log calculates the log of every element of the input array. Supports only CV_32FC1 data type.
 293
 294 ocl::LUT
 295 ------------------
 296 Returns void
 297
 298 .. ocv:function:: void ocl::LUT(const oclMat &src, const oclMat &lut, oclMat &dst)
 299
 300     :param src: Source array of 8-bit elements
 301
 302     :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
 303
 304     :param dst: Destination array; will have the same size and the same number of channels as src, and the same depth as lut
 305
 306 Performs a look-up table transform of an array. Supports only CV_8UC1 and CV_8UC4 data type.
 307
 308 ocl::magnitude
 309 ------------------
 310 Returns void
 311
 312 .. ocv:function:: void ocl::magnitude(const oclMat &x, const oclMat &y, oclMat &magnitude)
 313
 314     :param x: The floating-point array of x-coordinates of the vectors
 315
 316     :param y: he floating-point array of y-coordinates of the vectors; must have the same size as x
 317
 318     :param magnitude: The destination array; will have the same size and same type as x
 319
 320 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.
 321
 322 ocl::flip
 323 ------------------
 324 Returns void
 325
 326 .. ocv:function:: void ocl::flip( const oclMat& a, oclMat& b, int flipCode )
 327
 328     :param a: Source image.
 329
 330     :param b: Destination image
 331
 332     :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.
 333
 334 The function flip flips the array in one of three different ways (row and column indices are 0-based). Supports all data types.
 335
 336 ocl::meanStdDev
 337 ------------------
 338 Returns void
 339
 340 .. ocv:function:: void ocl::meanStdDev(const oclMat &mtx, Scalar &mean, Scalar &stddev)
 341
 342     :param mtx: Source image.
 343
 344     :param mean: The output parameter: computed mean value
 345
 346     :param stddev: The output parameter: computed standard deviation
 347
 348 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
 349
 350 ocl::merge
 351 ------------------
 352 Returns void
 353
 354 .. ocv:function:: void ocl::merge(const vector<oclMat> &src, oclMat &dst)
 355
 356     :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
 357
 358     :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
 359
 360 Composes a multi-channel array from several single-channel arrays. Supports all data types.
 361
 362 ocl::split
 363 ------------------
 364 Returns void
 365
 366 .. ocv:function:: void ocl::split(const oclMat &src, vector<oclMat> &dst)
 367
 368     :param src: The source multi-channel array
 369
 370     :param dst: The destination array or vector of arrays; The number of arrays must match src.channels(). The arrays themselves will be reallocated if needed
 371
 372 The functions split split multi-channel array into separate single-channel arrays. Supports all data types.
 373
 374 ocl::norm
 375 ------------------
 376 Returns the calculated norm
 377
 378 .. ocv:function:: double ocl::norm(const oclMat &src1, int normType = NORM_L2)
 379
 380 .. ocv:function:: double ocl::norm(const oclMat &src1, const oclMat &src2, int normType = NORM_L2)
 381
 382     :param src1: The first source array
 383
 384     :param src2: The second source array of the same size and the same type as src1
 385
 386     :param normType: Type of the norm
 387
 388 Calculates absolute array norm, absolute difference norm, or relative difference norm. Supports only CV_8UC1 data type.
 389
 390 ocl::phase
 391 ------------------
 392 Returns void
 393
 394 .. ocv:function:: void ocl::phase(const oclMat &x, const oclMat &y, oclMat &angle, bool angleInDegrees = false)
 395
 396     :param x: The source floating-point array of x-coordinates of 2D vectors
 397
 398     :param y: The source array of y-coordinates of 2D vectors; must have the same size and the same type as x
 399
 400     :param angle: The destination array of vector angles; it will have the same size and same type as x
 401
 402     :param angleInDegrees: When it is true, the function will compute angle in degrees, otherwise they will be measured in radians
 403
 404 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.
 405
 406 ocl::pow
 407 ------------------
 408 Returns void
 409
 410 .. ocv:function:: void ocl::pow(const oclMat &x, double p, oclMat &y)
 411
 412     :param x: The source array
 413
 414     :param power: The exponent of power;The source floating-point array of angles of the 2D vectors
 415
 416     :param y: The destination array, should be the same type as the source
 417
 418 The function pow raises every element of the input array to p. Supports only CV_32FC1 and CV_64FC1 data type.
 419
 420 ocl::transpose
 421 ------------------
 422 Returns void
 423
 424 .. ocv:function:: void ocl::transpose(const oclMat &src, oclMat &dst)
 425
 426     :param src: The source array
 427
 428     :param dst: The destination array of the same type as src
 429
 430 Transposes a matrix. Supports 8UC1, 8UC4, 8SC4, 16UC2, 16SC2, 32SC1 and 32FC1 data types.
 431
 432
 433 ocl::dft
 434 ------------
 435 Performs a forward or inverse discrete Fourier transform (1D or 2D) of the floating point matrix.
 436
 437 .. ocv:function:: void ocl::dft( const oclMat& src, oclMat& dst, Size dft_size=Size(0, 0), int flags=0 )
 438
 439     :param src: Source matrix (real or complex).
 440
 441     :param dst: Destination matrix (real or complex).
 442
 443     :param dft_size: Size of original input, which is used for transformation from complex to real.
 444
 445     :param flags: Optional flags:
 446
 447         * **DFT_ROWS** transforms each individual row of the source matrix.
 448
 449         * **DFT_COMPLEX_OUTPUT** performs a forward transformation of 1D or 2D real array. The result, though being a complex array, has complex-conjugate symmetry (*CCS*, see the function description below for details). Such an array can be packed into a real array of the same size as input, which is the fastest option and which is what the function does by default. However, you may wish to get a full complex array (for simpler spectrum analysis, and so on). Pass the flag to enable the function to produce a full-size complex output array.
 450
 451         * **DFT_INVERSE** inverts DFT. Use for complex-complex cases (real-complex and complex-real cases are always forward and inverse, respectively).
 452
 453         * **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.
 454
 455 Use to handle real matrices ( ``CV32FC1`` ) and complex matrices in the interleaved format ( ``CV32FC2`` ).
 456
 457 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
 458
 459 .. seealso:: :ocv:func:`dft`
 460
 461 ocl::gemm
 462 ------------------
 463 Performs generalized matrix multiplication.
 464
 465 .. ocv:function:: void ocl::gemm(const oclMat& src1, const oclMat& src2, double alpha, const oclMat& src3, double beta, oclMat& dst, int flags = 0)
 466
 467     :param src1: First multiplied input matrix that should be ``CV_32FC1`` type.
 468
 469     :param src2: Second multiplied input matrix of the same type as  ``src1`` .
 470
 471     :param alpha: Weight of the matrix product.
 472
 473     :param src3: Third optional delta matrix added to the matrix product. It should have the same type as  ``src1``  and  ``src2`` .
 474
 475     :param beta: Weight of  ``src3`` .
 476
 477     :param dst: Destination matrix. It has the proper size and the same type as input matrices.
 478
 479     :param flags: Operation flags:
 480
 481             * **GEMM_1_T** transpose  ``src1``
 482             * **GEMM_2_T** transpose  ``src2``
 483
 484 .. seealso:: :ocv:func:`gemm`
 485
 486 ocl::sortByKey
 487 ------------------
 488 Returns void
 489
 490 .. ocv:function:: void ocl::sortByKey(oclMat& keys, oclMat& values, int method, bool isGreaterThan = false)
 491
 492     :param keys:   The keys to be used as sorting indices.
 493
 494     :param values: The array of values.
 495
 496     :param isGreaterThan: Determine sorting order.
 497
 498     :param method: supported sorting methods:
 499             * **SORT_BITONIC**   bitonic sort, only support power-of-2 buffer size
 500             * **SORT_SELECTION** selection sort, currently cannot sort duplicate keys
 501             * **SORT_MERGE**     merge sort
 502             * **SORT_RADIX**     radix sort, only support signed int/float keys(``CV_32S``/``CV_32F``)
 503
 504 Returns the sorted result of all the elements in values based on equivalent keys.
 505
 506 The element unit in the values to be sorted is determined from the data type,
 507 i.e., a ``CV_32FC2`` input ``{a1a2, b1b2}`` will be considered as two elements, regardless its matrix dimension.
 508
 509 Both keys and values will be sorted inplace.
 510
 511 Keys needs to be a **single** channel `oclMat`.
 512
 513 Example::
 514     input -
 515     keys   = {2,    3,   1}   (CV_8UC1)
 516     values = {10,5, 4,3, 6,2} (CV_8UC2)
 517     sortByKey(keys, values, SORT_SELECTION, false);
 518     output -
 519     keys   = {1,    2,   3}   (CV_8UC1)
 520     values = {6,2, 10,5, 4,3} (CV_8UC2)