doc/tutorials/core/how_to_use_ippa_conversion/how_to_use_ippa_conversion.rst

   1 .. _howToUseIPPAconversion:
   2
   3 Intel® IPP Asynchronous C/C++ library in OpenCV
   4 ***********************************************
   5
   6 Goal
   7 ====
   8
   9 .. _hppiSobel: http://software.intel.com/en-us/node/474701
  10 .. _hppiMatrix: http://software.intel.com/en-us/node/501660
  11
  12 The tutorial demonstrates the `Intel® IPP Asynchronous C/C++ <http://software.intel.com/en-us/intel-ipp-preview>`_ library usage with OpenCV.
  13 The code example below illustrates implementation of the Sobel operation, accelerated with Intel® IPP Asynchronous C/C++ functions.
  14 In this code example, :ippa_convert:`hpp::getMat <>` and :ippa_convert:`hpp::getHpp <>` functions are used for data conversion between hppiMatrix_ and ``Mat`` matrices.
  15
  16 Code
  17 ====
  18
  19 You may also find the source code in the :file:`samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp`
  20 file of the OpenCV source library or :download:`download it from here
  21 <../../../../samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp>`.
  22
  23 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp
  24    :language: cpp
  25    :linenos:
  26    :tab-width: 4
  27
  28 Explanation
  29 ===========
  30
  31 #. Create parameters for OpenCV:
  32
  33    .. code-block:: cpp
  34
  35       VideoCapture cap;
  36       Mat image, gray, result;
  37
  38    and IPP Async:
  39
  40    .. code-block:: cpp
  41
  42       hppiMatrix* src,* dst;
  43       hppAccel accel = 0;
  44       hppAccelType accelType;
  45       hppStatus sts;
  46       hppiVirtualMatrix * virtMatrix;
  47
  48 #. Load input image or video. How to open and read video stream you can see in the :ref:`videoInputPSNRMSSIM` tutorial.
  49
  50    .. code-block:: cpp
  51
  52       if( useCamera )
  53       {
  54          printf("used camera\n");
  55          cap.open(0);
  56       }
  57       else
  58       {
  59          printf("used image %s\n", file.c_str());
  60          cap.open(file.c_str());
  61       }
  62
  63       if( !cap.isOpened() )
  64       {
  65          printf("can not open camera or video file\n");
  66          return -1;
  67       }
  68
  69 #. Create accelerator instance using `hppCreateInstance <http://software.intel.com/en-us/node/501686>`_:
  70
  71    .. code-block:: cpp
  72
  73       accelType = sAccel == "cpu" ? HPP_ACCEL_TYPE_CPU:
  74                   sAccel == "gpu" ? HPP_ACCEL_TYPE_GPU:
  75                                     HPP_ACCEL_TYPE_ANY;
  76
  77       //Create accelerator instance
  78       sts = hppCreateInstance(accelType, 0, &accel);
  79       CHECK_STATUS(sts, "hppCreateInstance");
  80
  81 #. Create an array of virtual matrices using `hppiCreateVirtualMatrices <http://software.intel.com/en-us/node/501700>`_ function.
  82
  83    .. code-block:: cpp
  84
  85       virtMatrix = hppiCreateVirtualMatrices(accel, 1);
  86
  87 #. Prepare a matrix for input and output data:
  88
  89    .. code-block:: cpp
  90
  91       cap >> image;
  92       if(image.empty())
  93          break;
  94
  95       cvtColor( image, gray, COLOR_BGR2GRAY );
  96
  97       result.create( image.rows, image.cols, CV_8U);
  98
  99 #. Convert ``Mat`` to hppiMatrix_ using :ippa_convert:`getHpp <>` and call hppiSobel_ function.
 100
 101    .. code-block:: cpp
 102
 103       //convert Mat to hppiMatrix
 104       src = getHpp(gray, accel);
 105       dst = getHpp(result, accel);
 106
 107       sts = hppiSobel(accel,src, HPP_MASK_SIZE_3X3,HPP_NORM_L1,virtMatrix[0]);
 108       CHECK_STATUS(sts,"hppiSobel");
 109
 110       sts = hppiConvert(accel, virtMatrix[0], 0, HPP_RND_MODE_NEAR, dst, HPP_DATA_TYPE_8U);
 111       CHECK_STATUS(sts,"hppiConvert");
 112
 113       // Wait for tasks to complete
 114       sts = hppWait(accel, HPP_TIME_OUT_INFINITE);
 115       CHECK_STATUS(sts, "hppWait");
 116
 117    We use `hppiConvert <http://software.intel.com/en-us/node/501746>`_ because hppiSobel_ returns destination
 118    matrix with ``HPP_DATA_TYPE_16S`` data type for source matrix with ``HPP_DATA_TYPE_8U`` type.
 119    You should check ``hppStatus`` after each call IPP Async function.
 120
 121 #. Create windows and show the images, the usual way.
 122
 123    .. code-block:: cpp
 124
 125       imshow("image", image);
 126       imshow("rez", result);
 127
 128       waitKey(15);
 129
 130 #. Delete hpp matrices.
 131
 132    .. code-block:: cpp
 133
 134       sts =  hppiFreeMatrix(src);
 135       CHECK_DEL_STATUS(sts,"hppiFreeMatrix");
 136
 137       sts =  hppiFreeMatrix(dst);
 138       CHECK_DEL_STATUS(sts,"hppiFreeMatrix");
 139
 140 #. Delete virtual matrices and accelerator instance.
 141
 142    .. code-block:: cpp
 143
 144       if (virtMatrix)
 145       {
 146          sts = hppiDeleteVirtualMatrices(accel, virtMatrix);
 147          CHECK_DEL_STATUS(sts,"hppiDeleteVirtualMatrices");
 148       }
 149
 150       if (accel)
 151       {
 152          sts = hppDeleteInstance(accel);
 153          CHECK_DEL_STATUS(sts, "hppDeleteInstance");
 154       }
 155
 156 Result
 157 =======
 158
 159 After compiling the code above we can execute it giving an image or video path and accelerator type as an argument.
 160 For this tutorial we use baboon.png image as input. The result is below.
 161
 162   .. image:: images/How_To_Use_IPPA_Result.jpg
 163     :alt: Final Result
 164     :align: center