OpenVINO™ and Intel® System Studio 2019: Get Started

This guide is for developers who are interested in using the Intel® System Studio Eclipse*-based Integrated Development Environment (IDE) with the OpenVINO™ toolkit to develop Computer Vision and Deep Learning optimized applications.

Definitions

  • Host system: The local system on which you’ve installed your development tools. It has a graphical interface for access.
  • Target system: The system on which you run an application during development and test.
  • A target system can be the same as your host system (local) or a separate system that can be accessed on the network by the host system (remote).

Process Overview

The sections of this guide step you through each part of the process – from installing prerequisites to running or debugging a project.

Prerequisites
Check the system requirements and install Intel System Studio on your host system.
Launch Intel System Studio.
Create a custom Docker* image that will enable you to build OpenVINO applications in Intel System Studio.

Create and Build a New Project in Intel System Studio
Create and build a project based on one of the OpenVINO samples.

Prepare Your OpenVINO Target System
Install OpenVINO on your target system and create a connection to the target system.

Run and debug the sample applications:

Troubleshooting

Related Information

To learn more about the OpenVINO toolkit and Intel System Studio, see:

Prerequisites

System Requirements

Host system: Intel System Studio supports Windows*, macOS*, or Linux* as development systems. In this guide, the instructions are for a Linux system.

Target system: Linux. The instructions in this guide were tested using an Ubuntu* 16.04 target system. We show file and folder paths for a Linux system in the instructions.

NOTE: To use a Windows system, modify the file and folder paths to reflect the installed location of Intel System Studio and OpenVINO toolkit.

Install Intel System Studio on Your Host System

Before you continue, you must install Intel System Studio (2019 Update 1 or later) on your host system.

  • You will need to register the product, create an account, and sign in before choosing your install package.
  • To follow the instructions in this guide, choose Linux* as the host and Linux as the target.
  • Click here to get started.

To launch Intel System Studio:

  1. Run this script:
    /opt/intel/system_studio_2019/iss_ide_eclipse-launcher.sh
  2. If you discover problems with the install, check the Intel System Studio community forum or the Online Service Center.

Create a Custom Docker* Image

Before you can run or debug OpenVINO sample applications in the Intel System Studio Eclipse*-based IDE, you need to create a custom Docker* image (also referred to as a “platform”). If you have already done this (following the instructions in this section), skip to Create and Build a New Project in Intel® System Studio below.

Step 1. Download the customized Docker file

We’ve provided a Docker file that you can use to create the custom Docker image.

  1. Download the Docker file from: https://software.intel.com/en-us/download/intel-system-studio-and-openvino-docker-file-for-r5.
  2. Extract the Docker file from the archive to a location on your host system. 

Step 2. Add a custom Docker image

Use the Platform Support Manager to add a new custom Docker image to Intel System Studio.

  1. From the IDE toolbar, choose Project > Manage installed development platforms to open the Platform Support Manager.

  2. Click the New button, which is located below the list of platforms, to open the Add Custom Docker Image dialog.

  3. Enter information, as follows:
    • Custom Image Name: Type a name for the custom image. For example, Ubuntu OpenVINO R5.
    • Select Base Image: Select Ubuntu Linux 16.04 64 bit (GCC) v14 or a later version, if available.
    • Docker ID: Type an identifier. It must be all lowercase and cannot contain spaces. For example, iss-ubuntu-16.04-openvino-r5. Make sure the ID does not end with a dash. This will cause an error.
    • Description: Type a description. This field cannot be left empty.
    • Dockerfile: Click Browse and select the custom Docker file you downloaded in Step 1 above.
  4. Click Finish.

    The new custom Docker image is now listed under Custom Linux Platform. The Status column shows Not Installed.

Step 3. Build the new custom Docker image

  1. Still on the Platform Support Manager dialog, under Custom Linux Platform, select the checkbox next to the custom Docker image you just added.
  2. Click Start.
  3. When a message saying that the installation may take more than 15 minutes appears, click Yes to continue.

    The time to complete the process varies and there will be periods where the progress bar and status messages in the console remain static.

  4. Wait until the following messages appear in the console to indicate that the process is complete:
    Successfully built 123xyz
    Successfully tagged iss-ubuntu-16.04-some-id:latest
  5. Click Close.

Create and Build a New Project in Intel® System Studio

In this section, we step you through creating and building a new project based on the OpenVINO™ sample projects available in the Intel® System Studio Eclipse*-based IDE.

Follow these steps:

  1. You need a custom Docker* image in order to use the OpenVINO samples. Follow the instructions in Create a Custom Docker* Image to download our sample Docker file and create the custom image. If you have already done this, skip this step. 
  2. Choose File > New > Project from the menu to start the new project wizard.
  3. Expand Intel Application Development and select C++ Project. Click Next.

    https://software.intel.com/sites/default/files/did_feeds_images/48044872-CE6C-4426-BAFC-0E6A442ECA40/48044872-CE6C-4426-BAFC-0E6A442ECA40-imageId=A23DF855-8AA9-42AC-8208-8021F0162E16.png

    The Create a New CPP Project screen opens.

  4. Click to open the Tool Samples tab.
  5. Expand OpenVINO™ Toolkit and select a sample; for example, Security Barrier Camera.

    The sample project name appears in the New Project Name field. If you wish to change it, type over the displayed name.

  6. For Builder and Build Options, leave CMake and Docker selected.

  7. Click Next.
  8. Select the custom Docker image you created in the Create a Custom Docker Image section.
  9. Click Finish to start the build process.

    CMake creates the necessary make files for the project, and then starts a build. View the build progress in the CMakeconsole and CDT buildconsole at the bottom of the workspace.

    TIP: To switch between the consoles, click the down arrow next to Display Selected Console and select a console from the drop-down list.

Prepare Your OpenVINO Target System

In this section, we step you through preparing to run or debug on a target system. There are two possible scenarios:

Local Development: Your host and target systems are the same -- Intel System Studio and OpenVINO are installed on the same machine.

Remote Development: You run and debug on a separate target system -- Intel System Studio is installed on your host system and OpenVINO is installed on your target system. Note that the target system must be accessible on the network from your host system.

Step 1. Install OpenVINO™ on your target system

Before you continue, you must install OpenVINO™ on your target system. Doing so will install the required OpenVINO shared libraries.

  • You will need to register the product, create an account, and sign in before choosing your install package.
  • To follow the instructions in this guide, choose Linux* as the host and Linux as the target.
  • Click here to get started.

Step 2. Create a connection to the target system

CAUTION: When you connect to your target using the Eclipse* Target Communication Framework (TCF), Intel® System Studio copies a TCF agent to your target, which is listening for connections from any computer on your local network. Even though the IDE asks for authentication credentials, the agent does NOT have any authentication. Therefore, any user can connect to it and can use the agent to run arbitrary code on your target device.

Follow these steps:

  1. Make sure your target device is functioning properly and can be reached on the network by your host system.
  2. On the main toolbar, click the arrow next to the New Connection box, and then select New Connection.
  3. Select Connection for container based C/C++ applications or Java* applications, and then click Next.
  4. Type a name in the Connection Name field.
  5. Enter the board name or IP address in the Address field, and then click Finish.
  6. When prompted, provide the appropriate credentials to access your device, and then click OK.

Step 3. Set Up Credentials

Set up credentials to access the target device. You can use either of the following authentication methods:

Public key login

If the application accesses hardware sensors, LEDs, or requires elevated privileges, use public key based authentication for a higher level of security. Follow the steps in SSH Connection: Password-less Access to a Remote Linux* Target Device.

Login with password

If the application does not require elevated privileges, you can use login with password.

NOTE: For local development (your target system is the same as your host system), you can enter the system's IP or 'localhost' in the address field of the new connection dialog.

Security Barrier Camera Sample

This sample showcases Vehicle Detection, followed by Vehicle Attributes and License Plate Recognition applied on top of Vehicle Detection.

In the following sections, we step you through running and debugging the sample.

Create and Build

See the instructions in previous sections to create and build the project.

Run and Debug

Step 1. Update the launch configuration

  1. On the main toolbar, click the down arrow next to the Run button, and then select Run Configurations.

  2. Click to open C/C++ Application built in a container and running on Linux.
  3. Select Security_Barrier_Camera.
  4. On the Main tab, under C/C++ Application, click Search Project.

  5. Select security_barrier_camera_demo.

Step 2. [Optional] Verify that the ROOT_DIR variable is set

  1. Still on the Main tab, click the Variables button.
  2. Click Edit Variables.

  3. Verify that ROOT_DIR is set to /opt/intel/computer_vision_sdk/deployment tools.

  4. Click Cancel twice to close the dialogs.

Step 3. [Optional] Verify that commands are set properly

  1. Still on the Main tab, review the Commands to execute before application to make sure the paths are set properly for your target system, as follows.

    NOTE: The following assumes that OpenVINO is installed on the default location for a user with root privileges. If you’ve installed OpenVINO in a different folder, modify the first line below accordingly.

    export INTEL_CVSDK_DIR=/opt/intel/computer_vision_sdk_2018.4.420; export INFENG=$INTEL_CVSDK_DIR/deployment_tools/inference_engine; export IE_PLUGINS_PATH=$INFENG/lib/ubuntu_16.04/intel64; [ ! -d /tmp/OpenVINO ] && mkdir /tmp/OpenVINO; cp $INFENG/lib/ubuntu_16.04/intel64/libcpu_extension_sse4.so /tmp/OpenVINO/libcpu_extension.so; export LD_LIBRARY_PATH=/tmp/OpenVINO:$INTEL_CVSDK_DIR/opencv/lib:/opt/intel/opencl:$INFENG/external/gna/lib:$INFENG/external/mkltiny_lnx/lib:$INFENG/external/omp/lib:$INFENG/lib/ubuntu_16.04/intel64:$LD_LIBRARY_PATH

    TIP: If your system has a processor that supports the AVX instructions, you can use a more optimized version of the libcpu_extension. To do this, change this part of the above command:

    From this:
    cp $INFENG/lib/ubuntu_16.04/intel64/libcpu_extension_sse4.so /tmp/OpenVINO/libcpu_extension.so;

    To this:
    cp $INFENG/lib/ubuntu_16.04/intel64/libcpu_extension_avx2.so /tmp/OpenVINO/libcpu_extension.so;

Step 4. Verify that arguments are set properly

  1. Select the Arguments tab.
  2. Verify that the Program arguments are set properly. Change them as needed.

  3. [Optional] Run with video instead of a single image. To use the car-detection.mp4 video:
    • Find the video in GitHub*. Click intel-iot-devkit/sample-videos.
    • Download the video to a folder on your target system.
    • Provide the path to the video file in the arguments in step 3 above.
  4. To close the Run Configuration window, click Apply and then click Close.

Step 5. Run or debug

Run

Click the   Run button.

Debug

Click the     Debug button.

Results

The application goes through several steps and then starts inference. It will try to open a window on the target system’s display to show the output image.

Open a graphical display for the application

In the results, you might see the error: Gtk-WARNING**:cannot open display.

The recommended way to resolve this problem is to connect a monitor to your target system and do the following:

  1. Open a terminal on your host system.
  2. To see how DISPLAY is defined:
    • Type ssh username@IP_address
    • Type echo $DISPLAY

    It will show something similar to this: :0

  3. Make a note of this and keep this terminal open.
  4. In Commands to execute before application, add: export DISPLAY=:0; where :0 is the result you just saw in the terminal. Separate all commands with a semi-colon (;).

NOTE: You must complete these steps even if your target system is the same as your host system. In this case you don’t need to ‘ssh’ to a remote system, just open a terminal and type echo $DISPLAY as indicated in step 2 above.

Interactive Face Detection Demo

This demo showcases the Object Detection task applied to face recognition using a sequence of neural networks.

Async API can improve the overall frame-rate of the application. Rather than waiting for inference to complete, the application can continue operating on the host while accelerator is busy.

This demo maintains four parallel infer requests for the Age/Gender Recognition, Head Pose Estimation, Emotions Recognition, and Facial Landmarks Estimation that run simultaneously.

Most of the steps for this demo is are the same as the steps for the Security Barrier Camera sample described in the preceding section of this guide.

StepsInstructions
Create and BuildFollow the steps in the Security Barrier Camera sample exactly.
Run and Debug

Follow the steps in the Security Barrier Camera sample with one modification: Select interactive_face_detection_demo instead of security_barrier_camera_demo.

Image Classification Sample

This sample application performs inference using image classification networks, like AlexNet* and GoogLeNet*. The sample application reads command line parameters and loads a network and an image to the Inference Engine plugin. When inference is complete, the application creates an output image and outputs data to the standard output stream.

In this section, we show you how to prepare and run an image classification application.

Provide an Appropriate Trained Model

To use this sample you must provide an appropriate trained model. Many image classification trained models exist. For this sample, we use the SqueezeNet v1.1 model.

NOTE: If OpenVINO™ is installed on your target system, perform this step on the target system. If not, perform this step on the host system and then copy the output files to a folder on your target system.

When you run this sample it runs the model to classify the image and prints the five top matching labels (of Imagenet 1000) and their corresponding probabilities. You can look up the text descriptions of the labels here: https://gist.github.com/maraoz/388eddec39d60c6d52d4

  1. Download the following files from the squeezenet model:
    deploy.prototxt
    (make sure to download the raw prototxt file, not an html version!)
    squeezenet_v1.1.caffemodel
  2. Run the OpenVINO Model Optimizer to prepare the model for the Inference Engine:
    python3 'path_to_OpenVINO/deployment_tools/model_optimizer/mo.py' --input_model 'path_to_downloaded_squeezenet/squeezenet/1.1/caffe/squeezenet1.1.caffemodel' --input_proto 'path_to_squeezenet/squeezenet/1.1/caffe/deploy.prototxt' -o <path to an optimized model output folder>
    where optimized model output folder is a folder you choose on your system

Create and Build

See the instructions in the previous sections to create and build the project.

Run and Debug

Step 1. Copy shared library to target

When an OpenVINO™ sample is built, in addition to the executable it generates a couple of shared libraries that might be needed to run the sample. These libraries are created inside the Docker* container and must be copied to the target system.

  1. To list the containers running on your host system, type 'docker ps' in a terminal.
  2. In the list, locate the container that corresponds to the custom image you created in Create a Custom Docker* Image.
  3. Make a note of the first few letters of the container id.

    TIP: If you don't see a Docker container that contains the custom image:

    • In the IDE, click the Build icon to start another project build.
    • Locate the command in CDT Build console. It will look something like this: 'docker exec -i xyz_id /bin/bash ...'.
  4. Copy the container id into the command.
  5. Create this folder on your host system: /tmp/OpenVINO
  6. Enter the following commands in a terminal:
    docker cp xyz_id:/workspace/image_classification/build/Release/intel64/Release/lib/libformat_reader.so /tmp/OpenVINO

    NOTE: Replace xyz_id with the ID of the container that is running and use the actual project name in the path above.

  7. If you are remotely running or debugging a project, enter the following command to copy the file from the local folder (see step 6 above) to a folder on your target system:
    scp /tmp/OpenVINO/libformat_reader.so user@targetip:/tmp/OpenVINO

Step 2. Update the launch configuration

  1. On the main toolbar, click the down arrow next to the  Run button, and then select Run Configurations.

  2. Click to open C/C++ Application built in a container and running on Linux.
  3. Select classification_sample.
  4. On the Main tab, under C/C++ Application, click Search Project.

Step 3. [Optional] Verify that the ROOT_DIR variable is set

  1. Still on the Main tab, click the Variables button.
  2. Click Edit Variables.
  3. Verify that ROOT_DIR is set to /opt/intel/computer_vision_sdk/deployment tools.

  4. Click Cancel twice to close the dialogs.

Step 4. [Optional] Verify that the commands are set properly

  1. Still on the Main tab, review the Commands to execute before application to make sure the paths are set properly for your target system, as follows.

    NOTE: The following assumes that OpenVINO is installed on the default location for a user with root privileges. If you’ve installed OpenVINO in a different folder, modify the first line below accordingly.

    export INTEL_CVSDK_DIR=/opt/intel/computer_vision_sdk_2018.4.420; export INFENG=$INTEL_CVSDK_DIR/deployment_tools/inference_engine; export IE_PLUGINS_PATH=$INFENG/lib/ubuntu_16.04/intel64; [ ! -d /tmp/OpenVINO ] && mkdir /tmp/OpenVINO; cp $INFENG/lib/ubuntu_16.04/intel64/libcpu_extension_sse4.so /tmp/OpenVINO/libcpu_extension.so; export LD_LIBRARY_PATH=/tmp/OpenVINO:$INTEL_CVSDK_DIR/opencv/lib:/opt/intel/opencl:$INFENG/external/gna/lib:$INFENG/external/mkltiny_lnx/lib:$INFENG/external/omp/lib:$INFENG/lib/ubuntu_16.04/intel64:$LD_LIBRARY_PATH

Step 5 Verify that arguments are set properly

  1. Select the Arguments tab.
  2. Verify that the Arguments are set properly. The following example assumes you have an image named horse.jpg.
    -d CPU -i /home/ubuntu/OpenVINO/horse.jpg -m /home/ubuntu/OpenVINO/Squeezenet/output/squeezenet_v1.1.xml -nt 5
  3. Change the arguments as needed.
  4. To close the Run Configuration window, click Apply and then click Close.

Step 6. Run or debug

Run

Click the    Run button.

Debug

Click the     Debug button.

Results

The sample runs the model to classify the image and prints the top five matching labels (of Imagenet* 1000) and their corresponding probabilities. For text descriptions of the labels, click here.

Hello Infer Sample

In this section, we show you how to use the new Infer Request API of the Inference Engine in applications. For details, see How to Integrate the Inference Engine in Your Application. This sample application is a simplified version of the Image Classification sample described in the preceding section of this guide. As noted below, most of the steps are identical to the steps for Image Classification sample.

StepsInstructions

Provide an Appropriate Trained Model

Create and Build

Follow the steps in the Image Classification sample exactly.
Run and DebugFollow the steps in the Image Classification sample with one modification: Select hello_infer instead of classification_sample

Other Samples

Additional OpenVINO sample details and a full list of the program arguments and their descriptions can be found here: https://software.intel.com/en-us/articles/OpenVINO-IE-Samples

Troubleshooting

ProblemSolution
The application terminates soon after you start running or debugging.

This might be due to missing required shared libraries but it is difficult to identify because terminal data is overwritten.

To work around this problem, select Debug instead of Run so you can view the problem in the terminal.

You are trying to remote debug and see the message cannot run gdbserver on the terminal.Open the Launch Config, and check the ‘commands to execute before the application’. There might be an error in the commands list that prevented the application from running.

When you run the project, you see a message such as, “Illegal instruction.”

This indicates that the host and target system processors have different features.

For example, one supports Streaming SIMD Extensions (SSE) or Advanced Vector Extensions (AVX) but the other does not.

  1. Right-click on your project and open the Properties window.
  2. Navigate to C/C++ Build -> CMake and select the Symbols tab.
  3. Add a symbol named ENABLE_SSE42 of type STRING and with the value ON to build the samples for targets based on Celeron®, Pentium®, or Intel® Atom® targets.

Explicitly setting SSE42 value to ON will disable the AVX2 and AVX512 extensions, causing the illegal instruction.

For further instructions about how to toggle SSE and AVX support during OpenVINO sample builds, see the CMakeLists.txt file located here: /opt/intel/computer_vision_sdk/inference_engine/src/extension/.

When you run the project, you see the message "GTK-WARNING**: cannot open display" and no output is shown.

In order for the graphic output of the application to be shown, a DISPLAY environment variable needs to be defined and appropriately set. Follow these steps:

  1. Connect a monitor or VNC client to the target system to watch the output.
  2. Open a terminal on your target system and type echo $DISPLAY. It will show something similar to :0. Make a note of this.
  3. On your host system, go to Run –> Run Configurations and select the run configuration for your sample.
  4. Under the Main tab, append the following to Commands to execute before application:
    export DISPLAY=:0; export
    XAUTHORITY=/home/your_actual_username/.Xauthority;
  5. Make sure the number you add after DISPLAY=: is the same number you read when you typed echo $DISPLAY in the terminal (step 2 above).

Alternatively, for most samples you can turn off the output with the -no_show program argument.

For additional help for sample arguments, see https://software.intel.com/en-us/articles/OpenVINO-IE-Samples

The application builds correctly but you see several indexer errors in the Intel System Studio IDE editor window.

Change the project properties as follows:

  1. Select Project > Properties > C/C++ Build > Settings.
  2. Expand GCC C++ compiler and select Dialect.
  3. From the Language standard drop-down list, select Language Standard > ISO C++ 11.
  4. Click Apply.
  5. Select Includes and thenclick the Add buttonin the Include paths area.
  6. For Directory, enter /opt/intel/computer_vision_sdk/inference_engine/include and click OK.
  7. Click OK and then click Apply and Close.

Legal Information

Intel, the Intel logo, OpenVINO, Celeron, Pentium, and Intel Atom are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

Copyright 2015-2019 Intel Corporation

This software and the related documents are Intel copyrighted materials, and your use of them is governed by the express license under which they were provided to you (License). Unless the License provides otherwise, you may not use, modify, copy, publish, distribute, disclose or transmit this software or the related documents without Intel's prior written permission.

This software and the related documents are provided as is, with no express or implied warranties, other than those that are expressly stated in the License.

For more complete information about compiler optimizations, see our Optimization Notice.