Use the Intel® Distribution of OpenVINO™ Toolkit to Create Python* Projects for Intel® System Studio

Publicado:07/01/2019   Última actualización:07/01/2019

Introduction

This guide is for developers interested in creating computer vision, AI, IoT, and cloud-based applications using the Intel® Distribution for OpenVINO™ toolkit with Intel® System Studio and the Intel® Distribution for Python*.

 Feature Highlights

  • Start projects from existing samples and templates.
  • Includes all expected editor integration options, including syntax highlighting, GUI package management, and debugging.
  • Seamless integration with the Intel Distribution for OpenVINO toolkit, Eclipse* IoT projects, and other open source projects.
  • Interactive console for quick interaction with existing scripts.
  • Easy to work with ML training frameworks, benchmarks, containers, and more.

The following illustration shows the major software components.

What You Will Learn

After following the steps in this guide, you will have a working installation of Intel Distribution for Python and will know how to use it to run a sample project.

This demo project is the Safety Gear Detector, which detects whether workers are wearing required safety gear (a hard hat and safety vest) as shown below.

This guide includes details for the following steps: 

Step 1: Install the Intel Distribution for Python.
Step 2: Configure the Python Interpreter.
Step 3: Add external Python modules to the configured interpreter.
Step 4: Use the Model Downloader and Model Optimizer with your Python project.
Step 5: Run a sample application.

Software/Hardware Requirements

  • Intel System Studio 2020 Update 1
  • Intel Distribution for Python 2020
  • Intel OpenVINO toolkit 2019 R3

Step 1: Install Intel Distribution for Python

Download the appropriate version of the Intel Distribution for Python:

Follow the online instructions to download and install the Intel Distribution for Python.

Note: Samples have been tested only with Python 3. Python 2 is not recommended. 

The Intel Distribution for Python ships as a tarball/zip file now and does not use a GUI installer. Follow the install guide from the Intel Distribution for Python page.

Note:    Take note of the IDP installation location. This is used later in this guide.

Step 2: Configure the Python Plugin

The Intel Distribution for Python is distributed as tarball or .zip files and no longer installs itself to the system PATH. To configure the interpreter, browse to the binary on the Microsoft Windows/Linux system from the IDE’s Preferences window.

Note: Browse to the appropriate Python binary on the disk. If you select one of the autoconfiguration options for the interpreter instead, a different (incompatible) interpreter may be selected as the default for new projects.

Update the IDE Preferences

Configure the plugin to use Intel Distribution for Python as the interpreter. Make sure you have installed this correctly, as described above. You can type “Python” in the search filter of the preferences window.

1. Click Window -> Preferences.

2. Expand the PyDev folder, select Python Interpreter, and click browse for python/pypy.exe.

3. Browse for python.exe from Intel Distribution of Python on the disk, select it, and click Open. This can be found under the installation path from Step 1.

4. Name the interpreter and click OK

5. When the “selection of folders to add to PYTHONPATH” window shows, click OK with all folders selected.

You should now have the Intel-provided interpreter configured with all the available Python packages listed under the Packages tab.

Test the Interpreter with the Python Console

The interactive console lets you run the configured Python interpreter from within Intel System Studio without leaving the development environment.

1. Confirm the interpreter has been properly configured by launching the interactive Python console. With the Console tab selected in the main IDE view, select the drop-down next to the Open Console icon and select PyDev Console.

2. Select the Python console radio button on the next window and click OK.

A new interactive Python console will open and print the name and version of the current interpreter. This should read:

C:\IntelSWTools\intelpython3\python.exe 3.6.8 |Intel Corporation| (default, Feb 27 2019, 19:55:17) [MSC v.1900 64 bit (AMD64)]

Note:  IDP is the recommended interpreter and it is optimized for Intel hardware. The PyDev Eclipse plugin should work with any version of Python but it is not tested as such by us.

Step 3: Add External Python Modules

This section assumes that external dependencies such as the OpenVINO toolkit are available and locally installed. To add external Python packages to the interpreter configuration, navigate to the Libraries and Environment tabs under the Python Interpreter preferences page.

Set up the Library Search Folders

1. Open the IDE Preferences window and select Python Interpreter from the list:

Window -> Preferences -> PyDev -> Interpreters -> Python Interpreter

2. On the Libraries tab, click New Folder and browse to the directory containing the Python modules you need for the application you are trying to run.

For OpenVINO toolkit samples and reference implementations, this is the python directory under the OpenVINO toolkit installation directory. For example, on Windows with a default OpenVINO toolkit installation path, this is:

C:\IntelSWTools\openvino\python\python3.6

Set up the Environment Variables

In some cases, especially when the Python module is a wrapper for a C library (OpenVINO toolkit), it is not enough to just add the required Python packages (.py) and dependencies to PYTHONPATH. The shared library binaries (.DLLs on Windows, .so on Linux) also need to be appended to the PATH variable on Windows, or LD_LIBRARY_PATH on Linux.

1. Using a Windows installation as an example, add the additional folders to the system PATH variable from the Environment tab, and click Select.

2. Select the checkbox next to the PATH variable, then click OK.

The Path variable is added to the Variables list.

3. Select the variable on the list, click Edit, and paste the following paths to the Inference
Engine and OpenCV* shared libraries at the end of the current value (adjust as needed
if you have a different "openvino" installation directory):

C:\IntelSWTools\openvino\opencv\bin;C:\IntelSWTools\openvino\deployment_tools\inference_engine\bin\intel64\Release; C:\IntelSWTools\openvino\deployment_tools\inference_engine\bin\intel64\Debug;

4. Click OK again and then Apply and Close to save all changes. Allow the IDE to resolve the updated PYTHONPATH and new modules.

   Tips for editing environment variables:

  • This is a semicolon-separated list of folders.
  • To get to the end of the list, press the End key.
  • The box is resizable.

[Optional] Test Module Imports with the Python Console

The interactive console lets you run the configured Python interpreter from within Intel System Studio without leaving the development environment. For instructions on using the interactive Python console, see “Step 2: Configure the Python interpreter.”
To check whether the OpenCV module can be loaded correctly, open a new Python console and paste the following commands:

import cv2
print (cv2.__version__)

Step 4: Set up Model Downloader and Model Optimizer

The OpenVINO toolkit Model Downloader and Model Optimizer Python tools can be easily linked to an existing Python project in Intel System Studio and then launched via the IDE’s Launch Configuration. This lets you stay within the development environment while setting up sample projects.

Warning:   Editing OpenVINO toolkit scripts in the IDE after linking them to a project also modifies them on the disk.

1. Start by creating a new Python project. This can be done from File -> New -> Project or by clicking Create a project… in the Project Explorer pane.

2. From the Code Samples tab, expand Reference Implementations and select the Safety Gear Detector sample.

3. Choose a project name and click Finish.

The project now appears in the Project Explorer pane.

 Set up the Model Downloader

Add the Model Downloader to a Project

1.To add the Model Downloader to an existing ISS project, right-click on the project name and selecting New -> Link to Existing Source.

2. Leave the sample project selected and click Browse... next to the Location of existing source path box. 

Note: Do not click the Browse button next to the Project box.

3. Browse to the Model Downloader, which on default installations of the OpenVINO toolkit for Windows is found at:

C:\IntelSWTools\openvino\deployment_tools\tools\model_downloader

After selecting the directory, the Name field receives the default value and may be changed if desired. The Finish button is now enabled.

4. Click Finish.

The Model Downloader is now soft-linked with the current project and added to the list view in the Project Explorer pane.

Create a Run Configuration

To run the Model Downloader Python script, you first need to create a run configuration.

1. Select the file downloader.py in the expanded Project Explorer tree.

2. With the file selected, select Run -> Run As -> Python Run. You can also right-click on the file and select Run As -> Python Run.

The IDE will generate an automatic run configuration and launch the script with no input arguments. The output displays in the console section of the IDE. By default, the script prints usage instructions and a list of available models.

If you see different output, you may have an interpreter configuration error (see “Troubleshooting and known ”).

Change the Launch Arguments

To modify the arguments passed to the script and download a specific model:

1. Open the run configuration from the menu bar by clicking Run -> Run Configurations. The run configuration previously created will appear in the list under Python Run.

2. Select the Safety_Gear_Detector downloader.py run configuration.

3. Click the Arguments tab.

The Safety Gear Detector Python reference implementation expects a model that can detect people, such as person-detection-retail-0013 from the Intel model list. Depending on the hardware target you will use, copy and paste one of the following launch arguments into the Program arguments field:

  • To download a FP32 pre-trained Neural Network model to be used with the code sample, use the following Run Configuration launch arguments:
            --name person-detection-retail-0013

To download a FP16 pre-trained Neural Network model to be used with the code sample, use the following Run Configuration launch arguments:

            --name person-detection-retail-0013-fp16

FP32 is more common, but either FP16 or FP32 will work with the Safety Gear Detector. For some reference implementations, FP16 will result in faster performance (see this Intel Developer Zone article for a detailed explanation). 

4. Next, click Run to download the files.

The progress displays in the console.

The model files are downloaded under the directory where the Model Downloader is installed (Retail/object_detection/pedestrian/rmnet_ssd/0013/dldt), and also appear in the Project Explorer. (This assumes the output directory option of the Model Downloader script was not used.

If you are not sure about write permissions to the location where the output file of either Model Downloader or Model Optimizer are going to get created, check with your system administrator.

Note:    If the output files are a binary model, you do not need to follow the steps in the next section, “Set up the Model Optimizer”.

Set up the Model Optimizer

Note:    If you are running the Safety Gear Detector demo, disregard this section.

This section shows how to use the Model Optimizer script with an existing ISS project to generate binary model files from Neural Network IR files, such as, for instance, some of the public models downloaded with the Model Downloader.

The Model Optimizer requires prerequisite Python modules not included with Intel Distribution of Python. Installing these prerequisites is not covered in this guide. Refer to the OpenVINO toolkit documentation.

Add the Model Optimizer to a Project

The Model Optimizer can be added to existing Python projects in Intel System Studio similar to the Model Downloader.

1. Right click on the project name and select New --> Link to Existing Source.

2. Browse to the installation directory of the Model Optimizer.

The Model Optimizer can be found at the following path, for default installations of the OpenVINO toolkit for Windows:

C:\IntelSWTools\openvino\deployment_tools\model_optimizer

3. Click Browse next to Location of Existing Source, and navigate to the Model Optimizer.

4. Click Finish

5. To launch the Model Optimizer, right-click the mo.py file in the Project Explorer, and select Run As -> Python Run.

Change the Launch Arguments

Now you can modify the newly created Run Configuration for the Model Optimizer to generate the needed run-time binary files for existing model files from popular frameworks such as Caffe*, TensorFlow*, Kaldi*, MXNet*, ONNX*. This can also be used with the pre-trained Intel models distributed as IR files with the OpenVINO toolkit.

1. Select the Model Optimizer and click the Arguments tab. Here you can define the input files, output files, and settings you would like to pass to the Model Optimizer.

For instance, to run the Model Optimizer on the SqeezeNet* 1.1 model with the OpenVINO toolkit installed at a default location, after the model’s .caffe and .prototxt files have been saved using the Model Downloader, use the following run arguments

--input_model C:\IntelSWTools\openvino\deployment_tools\tools\model_downloader\classification\squeezenet\1.1\caffe\squeezenet1.1.caffemodel
--input_proto C:\IntelSWTools\openvino\deployment_tools\tools\model_downloader\classification\squeezenet\1.1\caffe\squeezenet1.1.prototxt
-o ${workspace_loc:Image_Classification/src}

 

2. Click Run. The SqueezeNet 1.1 binary model files are placed in the src folder of the Image Classification project.

3. Refresh the project (F5) to see the files. If you are using this [DJ2] with another project, adjust the paths as necessary.

Both scripts can also be launched from a local system console in the IDE, or by regular system tools. Refer to the OpenVINO toolkit documentation for additional description of the supported formats and settings (see “Other Documentation”).

Step 5: Run a Sample

Intel System Studio 2019 Update 4 introduced the ability to import Python samples and use them as a starting point for launching Python projects.

A few Basic, IoT, and OpenVINO toolkit samples are provided as starters.

Create a Run Configuration

To run any sample, you first need to create a run configuration.

Note:    If you followed the previous section in this guide (“Step 4: Set up Model Downloader and Model Optimizer”), you have already created a run configuration. Go to the next section, “Change the launch arguments and run the sample project .”

To create a default run configuration, right-click safety-gear-detector.py in the Project Explorer and select Run -> Run As -> Python Run.

 

The sample will run and print usage help on the console, specifying the minimum arguments needed to run successfully: a model and a config file respectively.

If prerequisites are not entirely met, the sample will fail to run and display a different error message.

Change the Launch Arguments and Run the Sample Project

With the run configuration, you can configure the environment, append to it, as well as define individual project settings and Python module dependencies.

1. Select Run -> Run Configurations... and open the run configuration for the Safety Gear Detector. Then select the Arguments tab.

2. Use the following arguments to run the Safety Gear Detector sample on the CPU:

-m C:\IntelSWTools\openvino\deployment_tools\tools\model_downloader\Retail\object_detection\pedestrian\rmnet_ssd\0013\dldt\person-detection-retail-0013.xml
-c resources\conf.txt -e C:\IntelSWTools\openvino\deployment_tools\inference_engine\bin\intel64\Release\cpu_extension_avx2.dll

3. Click Run to launch the Safety Gear Detector sample on your host machine and observe the output.

For instructions on how to run this demo on other hardware targets, refer to the “Run the Application” section in the sample ReadMe.

Some samples might have additional environment requirements or third-party library dependencies, as well as specific hardware targets it can run on. The ReadMe for the sample will list these requirements, and may include solution-specific images, diagrams, or additional setup instructions, and estimated completion time requirement. Check your sample project's full ReadMe before attempting to build and run the sample.

Disclaimer

The Safety Gear Detector demo is merely offered for informative purpose to showcase the interoperability of multiple tools such as Intel System Studio, Intel Distribution for Python and OpenVINO toolkit. It does not represent the performance characteristics of the hardware platform the sample runs on, as the output is synced with the original input video frame rate.

Troubleshooting and Known Limitations

Problem CV2 module import missing.
Solution

Windows: If the error message states cv2 cannot be found or imported, the OpenCV Python module is not on PYTHONPATH. If the error message states the DLL cannot be loaded, the IE/OpenCV library binaries are not in the system’s PATH environment variables. Both steps are described in this guide (see “Set up the environment variables”). 

Linux: This can happen because cv2.so needs to be a symlink to the Intel build of OpenCV. In this case, create the link manually. Also on Linux, you must source the OpenVINO toolkit setupenv.sh script before launching ISS or set the LD_LIBRARY_PATH
env variable to the IE/OpenCV libraries within the IDE’s plugin configuration.

Problem Running the Model Downloader, Model Optimizer or a sample results in syntax or print() function errors.
Solution This is caused by using the wrong Python interpreter version for the script you are trying to run. Intel System Studio has a bundled version of Python for System Debugger that is configured as the default when you choose one of the autoconfiguration options. Browse to the version installed as part of the guide in Step 1 or a compatible version of Python instead.
Problem The Safety Gear Detector Python demo does not run on the GPU with IDP on Windows and shows the following error message.
Solution No known solution. This is potentially an issue with IE for OpenVINO toolkit. It may also be caused by the fact the demo code is using Python 3.5 IE APIs but is launched using IDP 3.6 interpreter and modules. Thus, this may work with a non-IDP 3.5 version of Python (untested). It may also work on Linux.

 

Problem 

The Model Optimizer does not run by default and has Python module import errors.

Solution Use the Preferences -> PyDev -> Interpreters -> Python Interpreter window and select the Packages tab. Click Manage with conda and Manage with pip to install the dependencies. For MO, the following Python modules are needed to follow the example in this guide networkx defusedxml (install these 2 with conda) test-generator (install this one with pip).

Also click New Egg/Zip to add the protobuf-3.6 dependency from: C:\IntelSWTools\openvino\deployment_tools\model_optimizer\install_prerequisites

Problem Not activating IDP on Linux will break the virtual environment when trying to install additional conda packages from the GUI. 
Solution On Linux, virtualenv activation is required in order to be able to use conda install for modifying the installation. On Windows this does not make a difference. Would not hurt to duplicate here even if mentioned on IDP page under install instructions. Deactivating the environment may also be required to use Model Downloader.
Problem Setting up conda proxy for IDP installations in corporate environments.
Solution

Add proxy entries under .condarc under user profile folder.

  • Windows: C:\Users\<username>\.condarc
Problem Known segfault on scikit & pandas reflection, in pydevcompletionserver.py (appears in both Linux/ and Windows as a runtime error).
Solution

There is no known solution to this yet apart from removing offending modules from IDP after installation. We are working with the plugin developer to acknowledge PyDev needs to catch these exceptions and fail gracefully in SW.

Problem

Setting up IDP with PyDev results in a segfault caused by scikit & pandas module reflection in Pr.py. This appears in both Linux/Win as a runtime error.

Solution The error can be dismissed and it will not affect Python interpreter usage. There is no known solution to this yet apart from removing offending modules from IDP after installation, if they are not required by the user.
Problem Project source folder is not automatically added to PYTHONPATH. This makes it impossible to add PyDev files to Intel Distribution for Python projects.
Solution Regular new files will be added to the project correctly and can have the .py extension.
Problem An empty Intel System Studio message window may appear when creating a regular PyDev file in an Intel Distribution for Python project, or at other stages during project configuration.
Solution This does not affect plugin usability with a Python interpreter and the empty windows can be dismissed.

Resources

Información sobre productos y desempeño

1

Los compiladores Intel pueden o no optimizar al mismo nivel para los microprocesadores que no son Intel en optimizaciones que no son exclusivas de los microprocesadores Intel. Estas optimizaciones incluyen los conjuntos de instrucciones SSE2, SSE3 y SSSE3, y otras optimizaciones. Intel no garantiza la disponibilidad, funcionalidad o eficacia de ninguna optimización en microprocesadores que no sean fabricados por Intel. Las optimizaciones dependientes del microprocesador en este producto fueron diseñadas para usarse con microprocesadores Intel. Ciertas optimizaciones no específicas de la microarquitectura Intel se reservan para los microprocesadores Intel. Consulte las guías de referencia y para el usuario para obtener más información acerca de los conjuntos de instrucciones específicos cubiertos por este aviso.

Revisión del aviso n.° 20110804