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. We'll be using gaussian blur and since it's
// a separable filter, we can leverage VPI's box filter to do it
// efficiently.
#include <vpi/algo/BoxImageFilter.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 that uses the CUDA backend. To make it work with
// other backends, pass VPI_DEVICE_TYPE_CPU or VPI_DEVICE_TYPE_PVA. No
// other changes to the code would be needed.
VPIStream stream;
vpiStreamCreate(VPI_DEVICE_TYPE_CUDA, &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_TYPE_U8;
// Define the image dimensions, the length in bytes of each row (rowStride)
// and finally a pointer to the actual image data.
// pixel type will be inferred from image type
// 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. The image type. This represents how pixels are to be interpreted. The
// loaded image is unsigned grayscale, with 8 bits per pixel, hence the VPI
// type is U8. For signed, it would have been S8.
// 3. Flags. 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.
// 4. The VPIImage variable that will receive the created image handle.
VPIImage image;
vpiImageWrapHostMem(&imgData, 0, &image);
// Now create the output images, single unsigned 8-bit channel.
VPIImage blurred;
vpiImageCreate(cvImage.cols, cvImage.rows, VPI_IMAGE_TYPE_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. input image
// 3. output image
// 4 and 5. box filter size, in this case, 5x5
// 6. 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.
vpiSubmitBoxImageFilter(stream, image, blurred, 5, 5, VPI_BOUNDARY_COND_ZERO);
// Wait until the algorithm finishes processing by synchronizing to the stream.
// It'll blockuntil the given 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.
// 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 --------------------------------------
vpiImageDestroy(image);
vpiImageDestroy(blurred);
vpiStreamDestroy(stream);
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 |
|---|---|
 |  |