AR# 75727


Using Vitis Vision Libraries with OpenCV in Vitis HLS


This article describes the process for setting up and using the Vitis Vision Libraries in a standalone Vitis HLS IP flow for Windows and Linux environments and using OpenCV for verification in the testbench.



The Vitis Vision Libraries are an accelerated library of OpenCV and Vision functions for implementation in the Vitis environment.

These libraries provide a L1 directory which contains Vitis HLS kernels as well as example designs that highlight the kernel behavior. The example designs use OpenCV for the testbench functionality, and as such, require an existing OpenCV installation. In order to accomadate a wide variety of user environments, Xilinx no longer provides a pre-installed version of OpenCV with the tools as of the 2020.1 release.

While OpenCV is not required for Vitis implementation of the Vision libraries, it is required to run the example designs, and may be desirable to use in user testbench verification. 

This Answer Record describes the process for creating a standalone Vitis HLS Tcl project file and augments the information found in the Getting Started with HLS section of the Vision documentation which is located here:


This Answer Record describes the process to create a HLS Tcl script with runs the resize example in the L1 Vision directory in Windows/ This utilizes a user installed OpenCV librarary. 

To utilize the examples designs, or reference the OpenCV libraries in a user testbench, the following steps must be taken:
  • Install the OpenCV tools version 3.x 
  • Set up the environment to reference the OpenCV installation 
  • Create a Tcl script for Vitis HLS execution which references the OpenCV libraries

Install OpenCV:

The installation of OpenCV and setting of the environment is beyond the scope of this article. OpenCV is an open-source distribution located at the following location:

Note: The 2020.1 Vitis Vision library was verified using version 3.3 of the OpenCV library. Any version more recent than that will work, however, version 4.x might have library function changes relative to the 3.x version, and as such might require the example design testbenches to be modified. For this reason, it is recommended that example designs be run using OpenCV version 3.x.

Important: The OpenCV libraries only provide testbench functionality. They are not required and do not affect the implementation of the Vision kernels in any way. 

Environment Setup:

The environment setup requirements for the acceleration platform makefile flow are described in the L1 Kernel github page located at the following location:

This Answer Record describes a process outside of the acceleration platform makefile flow which will use the environment settings similar to the makefile flow process for consistency. 

Note: The LD_LIBRARY_PATH environment variable and OpenCV PATH information must be properly set in the User's environment for this script and the Vitis Vision example designs to work properly.

Vitis HLS TCL Script:

A Tcl script to run the L1 resize example design outside of the makefile flow is provided with this Answer Record.

This script is based on the Windows environment and the following environment settings:

  • OpenCV version 3.4.11
  • OpenCV inclulde directory : C:/Data/OpenCV/build_win64/install/include
  • OpenCV library directory : C:/Data/OpenCV/build_win64/install/x64/mingw/lib
  • Vitis Vision Directory : C:/Data/Vitis_Libraries/Vitis_Libraries-master/vision/

To run the Vitis HLS script, perform the following actions:

1) Place the script in the <path>/vision/L1/example/resize directory.
2) Open the Vitis HLS command line shell and navigate to the <path>/vision/L1/example/resize directory
3) Run the following command: 

vitis_hls -f run_hls_standalone.tcl

The Tcl script file contains the following sections

  • Variable declarations representing the OpenCV and project environment
  • Project creation commands
  • Design file addition with Vitis Vision library include paths
  • Testbench file addition with OpenCV and Vitis Vision library include paths
  • C simulation with OpenCV linker references
  • Vitis HLS IP Synthesis
  • RTL CoSimulation with OpenCV linker references
  • Export of the IP

Variable Declarations:

The first part of the variable declaration section declares variables which replicate the environment variables of the makefile flow and the settings.tcl file that flow produces.

These variables point to the Vitis Vision Includes, the OpenCV header files, and the OpenCV pre-compiled libraries. These locations can vary based on the install paths of the user's system.

set XF_PROJ_ROOT "C:/Data/Vitis_Libraries/Vitis_Libraries-master/vision"   # Vitis Vision Libary include directory
set OPENCV_INCLUDE "C:/Data/OpenCV/build_win64/install/include"            # OpenCV header file directory
set OPENCV_LIB "C:/Data/OpenCV/build_win64/install/x64/mingw/lib"          # OpenCV compiled library directory

The next variable declaration section assists in creating the Vitis HLS project and helps to make the script portable:

set PROJ_DIR "$XF_PROJ_ROOT/L1/examples/resize"
set PROJ_NAME "hls_example"
set PROJ_TOP "resize_accel"
set SOLUTION_NAME "sol1"
set SOLUTION_PART "xcvu11p-flgb2104-1-e"

Finally, the last section declares variables that represent the include and simulation flags required by HLS to reference and use the libraries.

Using variables instead of direct code helps in understanding how these options are used. 

set VISION_INC_FLAGS "-I$XF_PROJ_ROOT/L1/include -std=c++0x"    # Vitis Vision Include path, and C++ 11 settings
set OPENCV_INC_FLAGS "-I$OPENCV_INCLUDE"                        # OpenCV include directory reference
set OPENCV_LIB_FLAGS "-L $OPENCV_LIB"                           # OpenCV libary reference

Note: In Windows, the library references must include the version number. This example uses a OpenCV 3.4.11 installation.

The precise include format will depend on the user's installation and might be different than listed below. 

set OPENCV_LIB_REF "-lopencv_imgcodecs3411 -lopencv_imgproc3411 -lopencv_core3411 -lopencv_highgui3411 -lopencv_flann3411 -lopencv_features2d3411"

The equivalent Linux include statement does not require the version number and is given as follows:

set OPENCV_LIB_REF "-lopencv_imgcodecs -lopencv_imgproc -lopencv_core -lopencv_highgui -lopencv_flann -lopencv_features2d"

Note: The exact library references required will depend on the OpenCV functions used in the testbench. Please reference the OpenCV documentation to determine the required libraries for inclusion.

Project Creation Part I:

The project creation section is straightforward and creates a new project directory and project file

open_project -reset $PROJ_NAME

Design File Include:

The design files are added to the design in this section. This command:

- references the individual HLS kernel file : add_files "${PROJ_DIR}/xf_resize_accel.cpp"
- references the vision libraries and project specific include directories for synthesis: -cflags "${VISION_INC_FLAGS} -I${PROJ_DIR}/build
- references the vision libraries and project specific include directories for C Simulation:  -csimflags "${VISION_INC_FLAGS} -I${PROJ_DIR}/build"

add_files "${PROJ_DIR}/xf_resize_accel.cpp" -cflags "${VISION_INC_FLAGS} -I${PROJ_DIR}/build" -csimflags "${VISION_INC_FLAGS} -I${PROJ_DIR}/build"

Testbench File Include:

The testbench files are added to the design in this section. The command:

- references the testbench file: add_files -tb "${PROJ_DIR}/xf_resize_tb.cpp"
- references the vision libraries and project specific include directories: -cflags "${OPENCV_INC_FLAGS} ${VISION_INC_FLAGS} -I${PROJ_DIR}/build"
- references the vision libraries and project specific include directories for C Simulation:  -csimflags "${OPENCV_INC_FLAGS} ${VISION_INC_FLAGS} -I${PROJ_DIR}/build"

Note the addition of the ${VISION_INC_FLAGS} variable in the testbench flags versus the design file flags. This setting references the OpenCV include files. 

add_files -tb "${PROJ_DIR}/xf_resize_tb.cpp" -cflags "${OPENCV_INC_FLAGS} ${VISION_INC_FLAGS} -I${PROJ_DIR}/build" -csimflags "${OPENCV_INC_FLAGS} ${VISION_INC_FLAGS} -I${PROJ_DIR}/build"

Project Creation Part II:

Now that the C source files have been added, the final step of project creation is executed. These commands set the top level function of the HLS IP, and open the desired project solution. 

set_top $PROJ_TOP                        # set top level file of HLS IP
open_solution -reset $SOLUTION_NAME      # create the project solution
set_part $SOLUTION_PART                  # set the solution part
create_clock -period $SOLUTION_CLKP      # set the project target clock period

C Simulation:

This section executes the C simulation stage of the HLS flow by sending the HLS IP and Testbench designs to the compiler for compilation and execution.

This command is used to set the compiler linker flags and testbench files and:

- References the OpenCV include and pre-compiled library directory : -ldflags "-L ${OPENCV_LIB} ${OPENCV_LIB_REF}"
- Includes an image for the verification testbench: -argv "${XF_PROJ_ROOT}/data/128x128.png"

csim_design -ldflags "-L ${OPENCV_LIB} ${OPENCV_LIB_REF}" -argv "${XF_PROJ_ROOT}/data/128x128.png"

C to RTL Synthesis:

This section executes the Vitis HLS C to RTL synthesis stage. No flags or options are required for this stage. 


RTL CoSimulation:

This section executes the RTL CoSimulation of the Vitis HLS IP after synthesis. The command is similar to the C Simulation command and is used to set the compiler linker flags and testbench files and:

- References the OpenCV include and pre-compiled library directory : -ldflags "-L ${OPENCV_LIB} ${OPENCV_LIB_REF}"
- Includes an image for the verification testbench: -argv "${XF_PROJ_ROOT}/data/128x128.png"

cosim_design -ldflags "-L ${OPENCV_LIB} ${OPENCV_LIB_REF}" -argv "${XF_PROJ_ROOT}/data/128x128.png"

Design Export: 

The final stage of the Vitis HLS flow is the export of the design. There are several options for this stage which are described in the HLS User's Guide.

This example exports the design for RTL and runs Vivado Synthesis to obtain accurate resource utilization and estimated timing results.

export_design -flow syn -rtl verilog


Associated Attachments

Name File Size File Type
run_hls_standalone.tcl 3 KB TCL
AR# 75727
Date 11/24/2020
Status Active
Type General Article
People Also Viewed