OpenCV AM57 Test Instructions

Testing TI Implementation of OpenCV

OpenCV (open source computer vision) is an open source collection of C++ (with some C) functions and utilities for image processing. A good tutorial for OpenCV can be found at http://docs.opencv.org/2.4/doc/tutorials/tutorials.html

OpenCV implementation is available for the following TI devices:

• AM335X
• AM437X
• AM57X
• K2E
• K2H
• K2L

To meet the requirements of real-time processing of images and video OpenCV functions were optimized.

More-ever, TI’s OpenCV implementation of hybrid ARM-DSP devices (AM57X, K2E, K2H, K2L) provides very efficient implementation of OpenCV function where signal-processing-rich algorithms are processed by DSP while the ARM processes all other algorithms, controls and manages the DSP.

TI implementation of OpenCV contains implementation of OpenCV functions as well as a set of unit tests to verify the performances and the accuracy of the implementation.

OpenCV Modules Supported By TI

Table 1 lists the modules of OpenCV that are supported under Processor SDK.

Module Name	K2H (Hawking Support)	AM57x Support	Comments
calib3d	Yes	Yes
Core	Yes	Yes
features2d	Yes	Yes
flann	Yes	Yes
imgcodecs	Yes	Yes
imgproc	Yes	Yes
ml	Yes	Yes
objdetect	Yes	Yes
photo	Yes	Yes
shape	Yes	Yes
stiching	Yes	Yes
superres	Yes	Yes
video	Yes	Yes
videoio	Yes	Yes
cudaarithm	No	No	No cuda support
cudabgsegm	No	No	No cuda support
cudacodec	No	No	No cuda support
cudafeatures2d	No	No	No cuda support
cudafilters	No	No	No cuda support
cudaimgproc	No	No	No cuda support
cudalegacy	No	No	No cuda support
cudaobjdetect	No	No	No cuda support

OpenCL offload

OpenCV 3.1 provides a transparent API that allows seamless offloads of OpenCL kernels when a supported hardware accelerator is available. OpenCV 3.1 available with Processor SDK allows these OpenCL kernels to be offloaded to the C66x DSP.

OpenCV 3.1 supports approximately 200 OpenCL kernels that optimize key functionalities in the different modules. The OpenCL kernel offload through the transparent API is enabled by the UMat data structure that replaces the legacy Mat data structure. UMat uses the OpenCL memory allocation procedure whenever possible, but maintains backward compatibility with Mat data structure.

Within the context of Processor SDK, to enable the offload of OpenCL kernels in OpenCV 3.1, the environment variable OPENCV_OPENCL_DEVICE should be defined as follows:

For K2H (Hawking) Platforms export OPENCV_OPENCL_DEVICE='TI KeyStone II:ACCELERATOR:TI Multicore C66 DSP'

For AM57x Platforms export OPENCV_OPENCL_DEVICE='TI AM57:ACCELERATOR:TI Multicore C66 DSP'

If this environment variable is not defined properly then OpenCV will not initialize OpenCL and the OpenCL support is disabled. Further, the library user can enable/disable OpenCL at runtime using ocl::setUseOpenCL(true) or ocl::setUseOpenCL(false) routines.

Figure 1 shows the decision tree the transparent API executes to determine if the computations will be offloaded to the accelerator through OpenCL. The boxes that are shaded gray are specific to TI’s implementation of OpenCV. The prohibited list allows us to prevent certain OpenCL kernels from executing on the DSP. The kernels are prevented to execute on the DSP if they did not pass the accuracy tests.

Unit Tests

Each function inthe OpenCV implementation has a unit test associate with the function.
The following instructions show how to load and run unit tests of TI’s OpenCV implementation.
The screen shots and device dependent instructions in this document are from AM57X build and run and can be used as a reference for build and run OpenCV test for any other TI devices from the above list

Unit Tests Pre-requisites

1. AM572 EVM (or other AM57X based system) with connection to the network. See http://www.ti.com/tool/TMDXEVM5728 for information on AM57X EVM
2. Processor runs TI Processor SDK Linux prospective LINUX operating system. URL to download Processor SDK Linux prospective is given below
3. File system either on a SD card (for devices with SD card interface), or mount to external server. If the file system resides on SD card, the card size should be at least 32GB.
   

* Note The following screen shots were taken from Tera Term terminal that is connected to the mother board of AM57X EVM

Loading standard test data

Processor SDK is available from the following locations

• For AM335X -> http://www.ti.com/tool/PROCESSOR-SDK-AM335X
• For AM437X -> http://www.ti.com/tool/PROCESSOR-SDK-AM437X
• For AM57X -> http://www.ti.com/tool/PROCESSOR-SDK-AM57X
• For K2E -> http://www.ti.com/tool/PROCESSOR-SDK-K2E
• For K2H -> http://www.ti.com/tool/PROCESSOR-SDK-K2H
• For K2L -> http://www.ti.com/tool/PROCESSOR-SDK-K2L

It is recommended to build the OpenCV test in a separate directory. After booting the EVM and login as a root the user can make a new directory. The standard test code data opencv_extra-master.zip can be downloaded from here [[1]]

There are multiple ways to download the data into the EVM

• If the EVM has display and keyboard the user can downloaded the data compressed file directly to the EVM and then unzip it
• Otherwise download the data compressed file to a PC on the network and use SCP or tftp or USB memory stick to move the data compressed file into the EVM. Then unzip it

The following screen shot shows how to download the standard data compressed file into the EVM and unzip it. It assumes that there is a TFTP master server for example Solarwinds or similar, and that the file opencv_extra-master.zip was downloaded from https://github.com/Itseez/opencv_extra/archive/master.zip and resides in the root directory of the TFTP server.

From the EVM terminal do the following: mkdir OpenCV create an new directory cd OpenCV Move to the directory tftp -l master.zip -r opencv_extra-master.zip -g 158.21r.zip -g xxx.xxx.xxx.xxx tftp and get the file opencv_extra-master.zip from remote terminal at IP address xxx.xxx.xxx.xxx and give it local name master.zip. Note in the screen shots here the server IP address is 158.218.109.189. The process takes few minutes because the file is very large. (More than 600MB)

• Next unzip the master.zip file unzip master.zip . After the unzip process ends, delete the master.zip file.

Notes: An alternative way to TFTP is using SCP to push the compressed data file. The following screen shot shows how to push the compressed data file using SCP from an Ubuntu machine. The address 158.218.109.244 is the IP address of the EVM

Loading TI Test Code

TI test code needs to be loaded from a git server.

In the OpenCV directory of the EVM clone the tiopencv directory.  git clone git://git.ti.com/opencv/tiopencv.git  

Next update the version that is used for testing, change directory to the new clone directory tiopencv cd tiopencv and do git checkout tiopencvdev (see note 1 below)

• Note 1 – This document was written before the public release. The git branch that is checkout will be included in the main branch and the git checkout tiopencvdev may not be necessary.
• Note 2 – The directory tiopencv has the following elements

Setup Environment Variables and Run the Test Script

Three environment variables are needed. OPENCV_BUILDDIR specifies where the executable bin files are located. In TI file system export OPENCV_BUILDDIR=/usr/share/OpenCV/samples

The OPENCV_TEST_DATA_PATH specifies where the test data files are located. Following the instructions from above export OPENCV_TEST_DATA_PATH=~/OpenCV/tiopencv/testdata 

The OPENCV_OPENCL_DEVICE specifies what architecture is used for OpenCL. OpenCL is used only with hybrid ARM-DSP devices like AM57X, K2H, K2E and K2L. TI’s implementation of OpenCV uses OpenCL to distribute execution between ARM processor and one or more DSP cores. Thus OPENCV_OPENCL_DEVICE tells the system what processors are available. For AM57 export OPENCV_OPENCL_DEVICE = ‘TI AM57:ACCELERATOR:TI Multicore C66 DSP’ For K2H, K2L and K2E export OPENCV_OPENCL_DEVICE = ‘TI KEYSTONE II:ACCELERATOR:TI Multicore C66 DSP’

In the following screen shot a source file environment.sh was built with the variables for AM57 and was execute

The runtests script runs all the OpenCV tests. It is located in directory titestsuite that is subdirectory of tiopencv. The following screen shot show how to start the runtests script

The script runs for a long time. The results are built in the file opencv_test_log.out during the execution of the script. Here is a screen shot from the start of the run:

Problem and Issues (BusyBox v1.23.1 (2016-03-02 23:57:12 EST) , tiopencv and test data were loaded on 3/11/16)

1. Photo module OpenCL tests are stuck, had to do control C to continue, The error message in the log file is in the following screen shot:

2. Other issues TBD