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

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 2019 Update 4

Intel® Distribution for Python* 2019 Update 4

Intel® OpenVINO™ toolkit 2019 R1.1

    Step 1: Install Intel® Distribution for Python*

    Install Intel® Distribution for Python* from https://software.intel.com/en-us/distribution-for-python/choose-download/

    • Choose a version from the menu (usually the lastest release).
    • Choose a download option Python 3.6 for Windows*.

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

    click icon Click the images below to open the full image in a new window.

    download options

    The Intel® Distribution for Python ships as a tarball/zip file now and doesn’t 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* Interpreter

    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 their 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.

    Click Window -> Preferenceswindow preferences

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

    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.

    Name the interpreter and select OK

    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.

    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.

    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 to a project

    This section assumes that external dependencies such as the OpenVINO™ toolkitare 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

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

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

    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 instance, for OpenVINO™ toolkit samples and reference implementations, this is the python folder 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

    n 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.

    Following our Windows example, additional folders need to be added to the system PATH variable from the Environment tab. Click Select.

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

    The Path variable is added to the Variables list.

    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;

    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.

    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.

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

    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

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

    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.

    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.

    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.

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

    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, 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.

    Select the Safety_Gear_Detector downloader.py run configuration.

    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). 

      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. Right click on the project name and select New -> Link to Existing Source. 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

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

      Then click Finish

      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.

      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}

      Click Run. The SqueezeNet 1.1 binary model files are placed in the src folder of the Image Classification project. 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: Running 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.

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

      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

      Click Run to launch the Safety Gear Detector sample on your host machine and observe the output,which should look like the following:

      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 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 framerate.

      Troubleshooting and Known Limitations

      ProblemCV2 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.

      ProblemRunning the Model Downloader, Model Optimizer or a sample results in syntax or print() function errors.
      SolutionThis 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.
      ProblemThe Safety Gear Detector Python demo does not run on the GPU with IDP on Windows and shows the following error message.
      SolutionNo 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.

      SolutionUse 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 protobuf-3.6 dependency from: C:\IntelSWTools\openvino\deployment_tools\model_optimizer\install_prerequisites

      ProblemNot activating IDP on Linux will break the virtual environment when trying to install additional conda packages from the GUI. 
      SolutionOn 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.
      ProblemSetting up conda proxy for IDP installations in corporate environments.
      Solution

      Add proxy entries under .condarc under user profile folder.

      • Windows*: C:\Users\<username>\.condarc
      ProblemKnown segfault on scikit & pandas reflection, in pydevcompletionserver.py (appears in both Linux/Win 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.

      SolutionThe 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.
      ProblemProject source folder is not automatically added to PYTHONPATH. This makes it impossible to add PyDev* files to Intel® Distribution for Python* projects.
      SolutionRegular new files will be added to the project correctly and can have the .py extension.
      ProblemAn 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.
      SolutionThis does not affect plugin usability with a Python interpreter and the empty windows can be dismissed.

      Resources

      General OpenVINO™ toolkit documentation: https://software.intel.com/en-us/openvino-toolkit/documentation/featured

      有关编译器优化的更完整信息,请参阅优化通知