### Navigation

- index
- next |
- previous |
- OpenCV 3.0.0-dev documentation »
- OpenCV Tutorials »
- core module. The Core Functionality »

# Intel® IPP Asynchronous C/C++ library in OpenCV

## Goal

The tutorial demonstrates the Intel® IPP Asynchronous C/C++ library usage with OpenCV. The code example below illustrates implementation of the Sobel operation, accelerated with Intel® IPP Asynchronous C/C++ functions. In this code example, hpp::getMat and hpp::getHpp functions are used for data conversion between hppiMatrix and `Mat` matrices.

## Code

You may also find the source code in the `samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp` file of the OpenCV source library or `download it from here`.

      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    #include <stdio.h>

    #include "opencv2/core/utility.hpp"
    #include "opencv2/imgproc.hpp"
    #include "opencv2/highgui.hpp"
    #include "cvconfig.h"

    using namespace std;
    using namespace cv;

    #ifdef HAVE_IPP_A
    #include "opencv2/core/ippasync.hpp"

    #define CHECK_STATUS(STATUS, NAME)\
        if(STATUS!=HPP_STATUS_NO_ERROR){ printf("%s error %d\n", NAME, STATUS);\
        if (virtMatrix) {hppStatus delSts = hppiDeleteVirtualMatrices(accel, virtMatrix); CHECK_DEL_STATUS(delSts,"hppiDeleteVirtualMatrices");}\
        if (accel)      {hppStatus delSts = hppDeleteInstance(accel); CHECK_DEL_STATUS(delSts, "hppDeleteInstance");}\
        return -1;}

    #define CHECK_DEL_STATUS(STATUS, NAME)\
        if(STATUS!=HPP_STATUS_NO_ERROR){ printf("%s error %d\n", NAME, STATUS); return -1;}

    #endif

    static void help()
    {
     printf("\nThis program shows how to use the conversion for IPP Async.\n"
    "This example uses the Sobel filter.\n"
    "You can use cv::Sobel or hppiSobel.\n"
    "Usage: \n"
    "./ipp_async_sobel [--camera]=<use camera,if this key is present>, \n"
    "                  [--file_name]=<path to movie or image file>\n"
    "                  [--accel]=<accelerator type: auto (default), cpu, gpu>\n\n");
    }

    const char* keys =
    {
        "{c  camera   |           | use camera or not}"
        "{fn file_name|../data/baboon.jpg | image file       }"
        "{a accel     |auto       | accelerator type: auto (default), cpu, gpu}"
    };

    //this is a sample for hppiSobel functions
    int main(int argc, const char** argv)
    {
        help();

        VideoCapture cap;
        CommandLineParser parser(argc, argv, keys);
        Mat image, gray, result;

    #ifdef HAVE_IPP_A

        hppiMatrix* src,* dst;
        hppAccel accel = 0;
        hppAccelType accelType;
        hppStatus sts;
        hppiVirtualMatrix * virtMatrix;

        bool useCamera = parser.has("camera");
        string file = parser.get<string>("file_name");
        string sAccel = parser.get<string>("accel");

        parser.printMessage();

        if( useCamera )
        {
            printf("used camera\n");
            cap.open(0);
        }
        else
        {
            printf("used image %s\n", file.c_str());
            cap.open(file.c_str());
        }

        if( !cap.isOpened() )
        {
            printf("can not open camera or video file\n");
            return -1;
        }

        accelType = sAccel == "cpu" ? HPP_ACCEL_TYPE_CPU:
                    sAccel == "gpu" ? HPP_ACCEL_TYPE_GPU:
                                      HPP_ACCEL_TYPE_ANY;

        //Create accelerator instance
        sts = hppCreateInstance(accelType, 0, &accel);
        CHECK_STATUS(sts, "hppCreateInstance");

        accelType = hppQueryAccelType(accel);

        sAccel = accelType == HPP_ACCEL_TYPE_CPU ? "cpu":
                 accelType == HPP_ACCEL_TYPE_GPU ? "gpu":
                 accelType == HPP_ACCEL_TYPE_GPU_VIA_DX9 ? "gpu dx9": "?";

        printf("accelType %s\n", sAccel.c_str());

        virtMatrix = hppiCreateVirtualMatrices(accel, 1);

        for(;;)
        {
            cap >> image;
            if(image.empty())
                break;

            cvtColor( image, gray, COLOR_BGR2GRAY );

            result.create( image.rows, image.cols, CV_8U);

            double execTime = (double)getTickCount();

            //convert Mat to hppiMatrix
            src = hpp::getHpp(gray,accel);
            dst = hpp::getHpp(result,accel);

            sts = hppiSobel(accel,src, HPP_MASK_SIZE_3X3,HPP_NORM_L1,virtMatrix[0]);
            CHECK_STATUS(sts,"hppiSobel");

            sts = hppiConvert(accel, virtMatrix[0], 0, HPP_RND_MODE_NEAR, dst, HPP_DATA_TYPE_8U);
            CHECK_STATUS(sts,"hppiConvert");

            // Wait for tasks to complete
            sts = hppWait(accel, HPP_TIME_OUT_INFINITE);
            CHECK_STATUS(sts, "hppWait");

            execTime = ((double)getTickCount() - execTime)*1000./getTickFrequency();

            printf("Time : %0.3fms\n", execTime);

            imshow("image", image);
            imshow("rez", result);

            waitKey(15);

            sts =  hppiFreeMatrix(src);
            CHECK_DEL_STATUS(sts,"hppiFreeMatrix");

            sts =  hppiFreeMatrix(dst);
            CHECK_DEL_STATUS(sts,"hppiFreeMatrix");

        }

        if (!useCamera)
            waitKey(0);

        if (virtMatrix)
        {
            sts = hppiDeleteVirtualMatrices(accel, virtMatrix);
            CHECK_DEL_STATUS(sts,"hppiDeleteVirtualMatrices");
        }

        if (accel)
        {
            sts = hppDeleteInstance(accel);
            CHECK_DEL_STATUS(sts, "hppDeleteInstance");
        }

        printf("SUCCESS\n");

    #else

        printf("IPP Async not supported\n");

    #endif

        return 0;
    }

## Explanation

1. Create parameters for OpenCV:

       VideoCapture cap;
       Mat image, gray, result;

   and IPP Async:

       hppiMatrix* src,* dst;
       hppAccel accel = 0;
       hppAccelType accelType;
       hppStatus sts;
       hppiVirtualMatrix * virtMatrix;

2. Load input image or video. How to open and read video stream you can see in the Video Input with OpenCV and similarity measurement tutorial.

       if( useCamera )
       {
          printf("used camera\n");
          cap.open(0);
       }
       else
       {
          printf("used image %s\n", file.c_str());
          cap.open(file.c_str());
       }

       if( !cap.isOpened() )
       {
          printf("can not open camera or video file\n");
          return -1;
       }

3. Create accelerator instance using hppCreateInstance:

       accelType = sAccel == "cpu" ? HPP_ACCEL_TYPE_CPU:
                   sAccel == "gpu" ? HPP_ACCEL_TYPE_GPU:
                                     HPP_ACCEL_TYPE_ANY;

       //Create accelerator instance
       sts = hppCreateInstance(accelType, 0, &accel);
       CHECK_STATUS(sts, "hppCreateInstance");

4. Create an array of virtual matrices using hppiCreateVirtualMatrices function.

       virtMatrix = hppiCreateVirtualMatrices(accel, 1);

5. Prepare a matrix for input and output data:

       cap >> image;
       if(image.empty())
          break;

       cvtColor( image, gray, COLOR_BGR2GRAY );

       result.create( image.rows, image.cols, CV_8U);

6. Convert `Mat` to hppiMatrix using getHpp and call hppiSobel function.

       //convert Mat to hppiMatrix
       src = getHpp(gray, accel);
       dst = getHpp(result, accel);

       sts = hppiSobel(accel,src, HPP_MASK_SIZE_3X3,HPP_NORM_L1,virtMatrix[0]);
       CHECK_STATUS(sts,"hppiSobel");

       sts = hppiConvert(accel, virtMatrix[0], 0, HPP_RND_MODE_NEAR, dst, HPP_DATA_TYPE_8U);
       CHECK_STATUS(sts,"hppiConvert");

       // Wait for tasks to complete
       sts = hppWait(accel, HPP_TIME_OUT_INFINITE);
       CHECK_STATUS(sts, "hppWait");

   We use hppiConvert because hppiSobel returns destination matrix with `HPP_DATA_TYPE_16S` data type for source matrix with `HPP_DATA_TYPE_8U` type. You should check `hppStatus` after each call IPP Async function.

7. Create windows and show the images, the usual way.

       imshow("image", image);
       imshow("rez", result);

       waitKey(15);

8. Delete hpp matrices.

       sts =  hppiFreeMatrix(src);
       CHECK_DEL_STATUS(sts,"hppiFreeMatrix");

       sts =  hppiFreeMatrix(dst);
       CHECK_DEL_STATUS(sts,"hppiFreeMatrix");

9. Delete virtual matrices and accelerator instance.

       if (virtMatrix)
       {
          sts = hppiDeleteVirtualMatrices(accel, virtMatrix);
          CHECK_DEL_STATUS(sts,"hppiDeleteVirtualMatrices");
       }

       if (accel)
       {
          sts = hppDeleteInstance(accel);
          CHECK_DEL_STATUS(sts, "hppDeleteInstance");
       }

## Result

After compiling the code above we can execute it giving an image or video path and accelerator type as an argument. For this tutorial we use baboon.png image as input. The result is below.

## Help and Feedback

You did not find what you were looking for?

- Ask a question on the Q&A forum.
- If you think something is missing or wrong in the documentation, please file a bug report.

### Navigation

- index
- next |
- previous |
- OpenCV 3.0.0-dev documentation »
- OpenCV Tutorials »
- core module. The Core Functionality »