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|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.

Final Result