Building your first application

This tutorial provides step-by-step procedures for building an application that demonstrates VPI programming concepts. With this tutorial a simple grayscale image blurring command line application that runs on CUDA is created.

Requirements

Creating the application requires:

• c++ compiler (g++ or clang++ works, testing was performed with version g++-7 and clang++-7)
• cmake >= 3.8, to build the project
• OpenCV >= 3.0, for image Input/Output

On Ubuntu 18.04, install these packages:

apt-get install g++ cmake libopencv-dev

Creating a CMake Project

Create the cmake project to build the application as follows.

cmake_minimum_required(VERSION 3.5)
 
project(vpi_blur)
 
# This instructs cmake to look for the most recent
# vpi instance installed on the system.
find_package(vpi REQUIRED)
find_package(OpenCV REQUIRED)
 
# Creates the blur executable target
add_executable(vpi_blur main.cpp)
 
# It uses vpi and opencv. CMake will automatically
# set up the correct header and library directories,
# and make hello_work link to these libraries.
target_link_libraries(vpi_blur vpi opencv_core)
 
# OpenCV < 3 uses a different library for image i/o
if(OpenCV_VERSION VERSION_LESS 3)
    target_link_libraries(vpi_blur opencv_highgui)
else()
    target_link_libraries(vpi_blur opencv_imgcodecs)
endif()

Note that cmake automatically sets up the VPI header and library paths for the executable. It is not necessary to manually define them.

Writing an Image Blurring Application

Write the C++ code that gets one image file from command line, blurs it, and writes the results back to disk.

Copy the provided code to a file named main.cpp. For simplicity, error checking is purposely left out. Consult the 2D convolution sample for a complete application with proper error handling.

/*
* Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*  * Redistributions of source code must retain the above copyright
*    notice, this list of conditions and the following disclaimer.
*  * Redistributions in binary form must reproduce the above copyright
*    notice, this list of conditions and the following disclaimer in the
*    documentation and/or other materials provided with the distribution.
*  * Neither the name of NVIDIA CORPORATION nor the names of its
*    contributors may be used to endorse or promote products derived
*    from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
 
// For image I/O
#include <opencv2/core/version.hpp>
#if CV_MAJOR_VERSION >= 3
#    include <opencv2/imgcodecs.hpp>
#else
#    include <opencv2/highgui/highgui.hpp>
#endif
 
#include <iostream>
 
// All vpi headers are under directory vpi/
#include <vpi/Image.h>
#include <vpi/Stream.h>
 
// Algorithm we'll need. Blurring will be performed by a box filter.
#include <vpi/algo/BoxFilter.h>
 
int main(int argc, char *argv[])
{
    if (argc != 2)
    {
        std::cerr << "Must pass an input image to be blurred" << std::endl;
        return 1;
    }
 
    // Phase 1: Initialization ---------------------------------
 
    // First load the input image
    cv::Mat cvImage = cv::imread(argv[1], cv::IMREAD_GRAYSCALE);
    if (cvImage.data == NULL)
    {
        std::cerr << "Can't open input image" << std::endl;
        return 2;
    }
 
    // Now create the stream. Passing 0 allows algorithms submitted to it to run
    // in any available backend.
    VPIStream stream;
    vpiStreamCreate(0, &stream);
 
    // Now wrap the loaded image into a VPIImage object to be used by VPI.
 
    // First fill VPIImageData with all image parameters.
    VPIImageData imgData;
 
    // OpenCV guarantees that cvImage has just one plane (hence
    // grayscale), with 8 bits per pixel, unsigned.
    imgData.numPlanes = 1;
    imgData.type      = VPI_IMAGE_FORMAT_U8;
 
    // Define the image dimensions, the length in bytes of each row (pitchBytes)
    // and finally a pointer to the actual image data.
    imgData.planes[0].width      = cvImage.cols;
    imgData.planes[0].height     = cvImage.rows;
    imgData.planes[0].pitchBytes = cvImage.step[0];
    imgData.planes[0].data       = cvImage.data;
    // pixel format will be inferred from image type
    imgData.planes[0].pixelFormat = VPI_PIXEL_FORMAT_DEFAULT;
 
    // Wrap it into a VPIImage. VPI won't make a copy of it, so the original
    // image must be in scope at all times. The parameters are:
    // 1. the imgData structure we've filled above.
    // 2. Image flags. Passing 0 tells vpi to make the image available to all
    //    backends. One could restrict the backends this image can work with so
    //    that possibly less memory is used in some scenarios.
    // 3. The variable that will receive a handle to the created image.
    VPIImage image;
    vpiImageCreateHostMemWrapper(&imgData, 0, &image);
 
    // Now create the output images, single unsigned 8-bit channel. The image lifetime is
    // managed by VPI.
    VPIImage blurred;
    vpiImageCreate(cvImage.cols, cvImage.rows, VPI_IMAGE_FORMAT_U8, 0, &blurred);
 
    // Phase 2: main processing --------------------------------------
 
    // Submit the algorithm task for processing along with inputs and outputs
    // Parameters are:
    // 1. the stream on which the algorithm will run
    // 2. Which hardware backend will execute it. Here CUDA is specified, but it could be CPU or
    //    PVA (on Jetson Xavier devices). No further changes to the program are needed to have it executed
    //    on a different hardware.
    // 3. input image to be blurred.
    // 4. output image with the result.
    // 5 and 6. box filter size, in this case, 5x5
    // 7. Boundary condition for when the algorithm tries to sample pixels outside the image boundary.
    //    VPI_BOUNDARY_COND_ZERO will consider all such pixels as being 0.
    vpiSubmitBoxFilter(stream, VPI_BACKEND_CUDA, image, blurred, 5, 5, VPI_BOUNDARY_COND_ZERO);
 
    // Block the current thread until until the stream finishes all tasks submitted to it up till now.
    vpiStreamSync(stream);
 
    // Finally retrieve the output image contents and output it to disk
 
    // Lock output image to retrieve its data from cpu memory
    VPIImageData outData;
    vpiImageLock(blurred, VPI_LOCK_READ, &outData);
 
    // Construct an cv::Mat out of the retrieved data.
    cv::Mat cvOut(outData.planes[0].height, outData.planes[0].width, CV_8UC1, outData.planes[0].data,
                  outData.planes[0].pitchBytes);
    // Just write it to disk
    imwrite("tutorial_blurred.png", cvOut);
 
    // Done handling output image, don't forget to unlock it.
    vpiImageUnlock(blurred);
 
    // Stage 3: clean up --------------------------------------
 
    // Destroy all created objects.
    vpiStreamDestroy(stream);
    vpiImageDestroy(image);
    vpiImageDestroy(blurred);
 
    return 0;
}

Building and Testing the Application

With everything set in place, execute:

cmake .
make

The executable vpi_blur is created in the same directory.

To run the application, execute:

./vpi_blur <image file name>

substituting <image file name> by some image on disk.

A sample input image and the resulting blurred image is displayed. Note that although the input in in color, OpenCV converts the to grayscale prior passing it to VPI which results in grayscale output.

Input image	Output image, blurred