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       Ptr<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);
 105       dst = getHpp(result);
 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 virtual matrices and accelerator instance.
 131
 132    .. code-block:: cpp
 133
 134       if (virtMatrix)
 135       {
 136          sts = hppiDeleteVirtualMatrices(accel, virtMatrix);
 137          CHECK_DEL_STATUS(sts,"hppiDeleteVirtualMatrices");
 138       }
 139
 140       if (accel)
 141       {
 142          sts = hppDeleteInstance(accel);
 143          CHECK_DEL_STATUS(sts, "hppDeleteInstance");
 144       }
 145
 146    We shouldn't delete hppiMatrix_ because we use :ptr:`Ptr <>` and so `hppiFreeMatrix <http://software.intel.com/en-us/node/501699>`_ will be called implicitly.
 147
 148 Result
 149 =======
 150
 151 After compiling the code above we can execute it giving an image or video path and accelerator type as an argument.
 152 For this tutorial we use baboon.png image as input. The result is below.
 153
 154   .. image:: images/How_To_Use_IPPA_Result.jpg
 155     :alt: Final Result
 156     :align: center