IntenseWebs/openvino
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: Edits to Basic OpenVINO Workflow page (#13807)

Browse Source 
* docs: Update intro and prerequisites

* docs: Update Steps 1 - 3

* docs: Re-organize CPU, GPU, MYRIAD examples

* docs: Change examples header

* docs: revise Other Demos/Samples section

* docs: Change OpenVINO Runtime install links

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* docs: edit OpenVINO Runtime section

* docs: add link to build from source

* Update docs/get_started/get_started_demos.md

Co-authored-by: Karol Blaszczak <karol.blaszczak@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Karol Blaszczak <karol.blaszczak@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Karol Blaszczak <karol.blaszczak@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Karol Blaszczak <karol.blaszczak@intel.com>

* Update docs/get_started/get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>

* docs: change Basic OpenVINO Workflow in toctree

* docs: minor edit to OpenVINO Dev Tools section

* docs: edit Build Samples section

* docs: change Prerequisites section header levels

* docs: edits to Step 1

* docs: remove links to OMZ Demos build instructions

* docs: fix links, remove "the"s , TMs, and *s

* Apply suggestions from code review

* Update get_started_demos.md

* Update get_started_demos.md

* Update get_started_demos.md

Co-authored-by: Yuan Xu <yuan1.xu@intel.com>
Co-authored-by: Karol Blaszczak <karol.blaszczak@intel.com>
This commit is contained in:
Evan
2022-12-02 03:02:06 +03:00
committed by GitHub
co-authored by Yuan Xu Karol Blaszczak
parent 3ec084074a
commit 5e24219446
2 changed files with 118 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/OV_Runtime_UG/Samples_Overview.md
+1 -1
View File
@@ -8,7 +8,7 @@
:maxdepth: 1
:hidden:
Basic OpenVINO Workflow <openvino_docs_get_started_get_started_demos>
Get Started with C++ Samples <openvino_docs_get_started_get_started_demos>
openvino_inference_engine_samples_classification_sample_async_README
openvino_inference_engine_ie_bridges_python_sample_classification_sample_async_README
openvino_inference_engine_samples_hello_classification_README
docs/get_started/get_started_demos.md
+117 -195
View File
@@ -1,86 +1,39 @@
# Basic OpenVINO™ Workflow {#openvino_docs_get_started_get_started_demos}
# Get Started with C++ Samples {#openvino_docs_get_started_get_started_demos}
This guide will walk you through a basic workflow for Intel® Distribution of OpenVINO™ toolkit, including how to use code samples.
The guide presents a basic workflow for building and running C++ code samples in OpenVINO. Note that these steps will not work with the Python samples.
This guide assumes you have completed all the installation and preparation steps. If you have not, check out the <a href="prerequisites">Prerequisites</a> section to install OpenVINO Runtime, install OpenVINO Development Tools, or build samples and demos.
To get started, you must first install OpenVINO Runtime, install OpenVINO Development tools, and build the sample applications. See the <a href="#prerequisites">Prerequisites</a> section for instructions.
After that, you will perform the following steps:
Once the prerequisites have been installed, perform the following steps:
1. <a href="#download-models">Use Model Downloader to download a suitable model.</a>
2. <a href="#convert-models-to-intermediate-representation">Convert the model with Model Optimizer.</a>
3. <a href="#download-media">Download media files to run inference.</a>
4. <a href="#run-image-classification">Run inference on a sample and see the results.</a> The following code sample is used as an example:
- <a href="#run-image-classification">Image Classification Code Sample</a>
4. <a href="#run-image-classification">Run inference with the Image Classification sample application and see the results.</a>
## <a name="prerequisites"></a>Prerequisites
### Install OpenVINO Runtime
If you have not yet installed and configured the toolkit, see the following guides:
To use sample applications, install OpenVINO Runtime via one of the following distribution channels (other distributions do not include sample files):
@sphinxdirective
.. tab:: Linux
* Archive files (recommended) - [Linux](@ref openvino_docs_install_guides_installing_openvino_from_archive_linux) | [Windows](@ref openvino_docs_install_guides_installing_openvino_from_archive_windows) | [macOS](@ref openvino_docs_install_guides_installing_openvino_from_archive_macos)
* Docker image - [Linux](@ref openvino_docs_install_guides_installing_openvino_docker_linux) | [Windows](@ref openvino_docs_install_guides_installing_openvino_docker_windows)
* [Build from source](https://github.com/openvinotoolkit/openvino/wiki/BuildingCode)
See :doc:`Install Intel® Distribution of OpenVINO™ toolkit for Linux <openvino_docs_install_guides_installing_openvino_linux_header>`
.. tab:: Windows
See :doc:`Install Intel® Distribution of OpenVINO™ toolkit for Windows <openvino_docs_install_guides_installing_openvino_windows_header>`
.. tab:: macOS
See :doc:`Install Intel® Distribution of OpenVINO™ toolkit for macOS <openvino_docs_install_guides_installing_openvino_macos_header>`
@endsphinxdirective
Make sure that you also [install OpenCV](https://github.com/opencv/opencv/wiki/BuildOpenCV4OpenVINO), as it's required for running sample applications.
### Install OpenVINO Development Tools
To install OpenVINO Development Tools for working with Caffe models, use the following command:
To install OpenVINO Development Tools, follow the [instructions for C++ developers on the Install OpenVINO Development Tools page](../install_guides/installing-model-dev-tools.md#cpp-developers). This guide uses the `googlenet-v1` model from the Caffe framework, therefore, when you get to Step 4 of the installation, run the following command to install OpenVINO with the Caffe requirements:
``` sh
pip install openvino-dev[caffe]
```
For more detailed steps, see [Install OpenVINO™ Development Tools](../install_guides/installing-model-dev-tools.md)
### Build Samples
### Build Samples and Demos
If you have already built the demos and samples, you can skip this section. The build will take about 5-10 minutes, depending on your system.
To build OpenVINO samples:
@sphinxdirective
.. tab:: Linux
Go to :doc:`OpenVINO Samples page <openvino_docs_OV_UG_Samples_Overview>` and see the "Build the Sample Applications on Linux" section.
.. tab:: Windows
Go to :doc:`OpenVINO Samples page <openvino_docs_OV_UG_Samples_Overview>` and see the "Build the Sample Applications on Microsoft Windows OS" section.
.. tab:: macOS
Go to :doc:`OpenVINO Samples page <openvino_docs_OV_UG_Samples_Overview>` and see the "Build the Sample Applications on macOS" section.
@endsphinxdirective
To build OpenVINO demos:
@sphinxdirective
.. tab:: Linux
Go to :doc:`Open Model Zoo Demos page <omz_demos>` and see the "Build the Demo Applications on Linux" section.
.. tab:: Windows
Go to :doc:`Open Model Zoo Demos page <omz_demos>` and see the "Build the Demo Applications on Microsoft Windows OS" section.
.. tab:: macOS
Go to :doc:`Open Model Zoo Demos page <omz_demos>` and see the "Build the Demo Applications on Linux*" section. You can use the requirements from "To build OpenVINO samples" above and adapt the Linux build steps for macOS.
@endsphinxdirective
To build OpenVINO samples, follow the build instructions for your operating system on the [OpenVINO Samples](../OV_Runtime_UG/Samples_Overview.md) page. The build will take about 5-10 minutes, depending on your system.
## <a name="download-models"></a> Step 1: Download the Models
@@ -90,140 +43,124 @@ You must have a model that is specific for your inference task. Example model ty
- Object Detection (SSD, YOLO): Draws bounding boxes around multiple types of objects in an image
- Custom: Often based on SSD
Options to find a model suitable for the OpenVINO™ toolkit:
You can use one of the following options to find a model suitable for OpenVINO:
- Download public or Intel pre-trained models from the [Open Model Zoo](https://github.com/openvinotoolkit/open_model_zoo) using the [Model Downloader tool](@ref omz_tools_downloader)
- Download from GitHub*, Caffe* Zoo, TensorFlow* Zoo, etc.
- Download public or Intel pre-trained models from [Open Model Zoo](@ref model_zoo) using [Model Downloader tool](@ref omz_tools_downloader)
- Download from GitHub, Caffe Zoo, TensorFlow Zoo, etc.
- Train your own model with machine learning tools
This guide uses the OpenVINO™ Model Downloader to get pre-trained models. You can use one of the following commands to find a model:
This guide uses OpenVINO Model Downloader to get pre-trained models. You can use one of the following commands to find a model with this method:
* List the models available in the downloader
* List the models available in the downloader.
``` sh
omz_info_dumper --print_all
```
* Use `grep` to list models that have a specific name pattern
* Use `grep` to list models that have a specific name pattern (e.g. `ssd-mobilenet`, `yolo`). Replace `<model_name>` with the name of the model.
``` sh
omz_info_dumper --print_all | grep <model_name>
```
* Use Model Downloader to download models.
This guide uses `<models_dir>` and `<models_name>` as placeholders for the models directory and model name:
* Use Model Downloader to download models. Replace `<models_dir>` with the directory to download the model to and `<model_name>` with the name of the model.
``` sh
omz_downloader --name <model_name> --output_dir <models_dir>
```
* Download the following models to run the Image Classification Sample:
This guide used the following model to run the Image Classification Sample:
|Model Name | Code Sample or Demo App |
|-----------------------------------------------|------------------------------------------|
|`googlenet-v1` | Image Classification Sample |
@sphinxdirective
.. raw:: html
<div class="collapsible-section" data-title="Click for an example of downloading the GoogleNet v1 Caffe* model">
.. dropdown:: Click to view how to download the GoogleNet v1 Caffe model
@endsphinxdirective
To download the GoogleNet v1 Caffe model to the `models` folder:
To download the GoogleNet v1 Caffe model to the `models` folder:
.. tab:: Linux
@sphinxdirective
.. code-block:: sh
.. tab:: Linux
omz_downloader --name googlenet-v1 --output_dir ~/models
.. code-block:: sh
.. tab:: Windows
omz_downloader --name googlenet-v1 --output_dir ~/models
.. code-block:: bat
.. tab:: Windows
omz_downloader --name googlenet-v1 --output_dir %USERPROFILE%\Documents\models
.. code-block:: bat
.. tab:: macOS
omz_downloader --name googlenet-v1 --output_dir %USERPROFILE%\Documents\models
.. code-block:: sh
.. tab:: macOS
omz_downloader --name googlenet-v1 --output_dir ~/models
.. code-block:: sh
omz_downloader --name googlenet-v1 --output_dir ~/models
Your screen will look similar to this after the download and show the paths of downloaded files:
@endsphinxdirective
.. tab:: Linux
Your screen looks similar to this after the download and shows the paths of downloaded files:
.. code-block:: sh
@sphinxdirective
.. tab:: Linux
###############|| Downloading models ||###############
.. code-block:: sh
========= Downloading /home/username/models/public/googlenet-v1/googlenet-v1.prototxt
###############|| Downloading models ||###############
========= Downloading /home/username/models/public/googlenet-v1/googlenet-v1.caffemodel
... 100%, 4834 KB, 3157 KB/s, 1 seconds passed
========= Downloading /home/username/models/public/googlenet-v1/googlenet-v1.prototxt
###############|| Post processing ||###############
========= Downloading /home/username/models/public/googlenet-v1/googlenet-v1.caffemodel
... 100%, 4834 KB, 3157 KB/s, 1 seconds passed
========= Replacing text in /home/username/models/public/googlenet-v1/googlenet-v1.prototxt =========
###############|| Post processing ||###############
.. tab:: Windows
========= Replacing text in /home/username/models/public/googlenet-v1/googlenet-v1.prototxt =========
.. code-block:: bat
.. tab:: Windows
################|| Downloading models ||################
.. code-block:: bat
========== Downloading C:\Users\username\Documents\models\public\googlenet-v1\googlenet-v1.prototxt
... 100%, 9 KB, ? KB/s, 0 seconds passed
################|| Downloading models ||################
========== Downloading C:\Users\username\Documents\models\public\googlenet-v1\googlenet-v1.caffemodel
... 100%, 4834 KB, 571 KB/s, 8 seconds passed
========== Downloading C:\Users\username\Documents\models\public\googlenet-v1\googlenet-v1.prototxt
... 100%, 9 KB, ? KB/s, 0 seconds passed
################|| Post-processing ||################
========== Downloading C:\Users\username\Documents\models\public\googlenet-v1\googlenet-v1.caffemodel
... 100%, 4834 KB, 571 KB/s, 8 seconds passed
========== Replacing text in C:\Users\username\Documents\models\public\googlenet-v1\googlenet-v1.prototxt
################|| Post-processing ||################
.. tab:: macOS
========== Replacing text in C:\Users\username\Documents\models\public\googlenet-v1\googlenet-v1.prototxt
.. code-block:: sh
.. tab:: macOS
###############|| Downloading models ||###############
.. code-block:: sh
========= Downloading /Users/username/models/public/googlenet-v1/googlenet-v1.prototxt
... 100%, 9 KB, 44058 KB/s, 0 seconds passed
###############|| Downloading models ||###############
========= Downloading /Users/username/models/public/googlenet-v1/googlenet-v1.caffemodel
... 100%, 4834 KB, 4877 KB/s, 0 seconds passed
========= Downloading /Users/username/models/public/googlenet-v1/googlenet-v1.prototxt
... 100%, 9 KB, 44058 KB/s, 0 seconds passed
###############|| Post processing ||###############
========= Downloading /Users/username/models/public/googlenet-v1/googlenet-v1.caffemodel
... 100%, 4834 KB, 4877 KB/s, 0 seconds passed
###############|| Post processing ||###############
========= Replacing text in /Users/username/models/public/googlenet-v1/googlenet-v1.prototxt =========
@endsphinxdirective
@sphinxdirective
.. raw:: html
</div>
========= Replacing text in /Users/username/models/public/googlenet-v1/googlenet-v1.prototxt =========
@endsphinxdirective
## <a name="convert-models-to-intermediate-representation"></a>Step 2: Convert the Model with Model Optimizer
In this step, your trained models are ready to run through the Model Optimizer to convert them to the IR (Intermediate Representation) format. For most model types, this is required before using the OpenVINO Runtime with the model.
In this step, your trained models are ready to run through the Model Optimizer to convert them to the IR (Intermediate Representation) format. For most model types, this is required before using OpenVINO Runtime with the model.
Models in the IR format always include an `.xml` and `.bin` file and may also include other files such as `.json` or `.mapping`. Make sure you have these files together in a single directory so the OpenVINO Runtime can find them.
Models in the IR format always include an `.xml` and `.bin` file and may also include other files such as `.json` or `.mapping`. Make sure you have these files together in a single directory so OpenVINO Runtime can find them.
REQUIRED: `model_name.xml`
REQUIRED: `model_name.bin`
OPTIONAL: `model_name.json`, `model_name.mapping`, etc.
This tutorial uses the public GoogleNet v1 Caffe* model to run the Image Classification Sample. See the example in the Download Models section of this page to learn how to download this model.
This tutorial uses the public GoogleNet v1 Caffe model to run the Image Classification Sample. See the example in the Download Models section of this page to learn how to download this model.
The googlenet-v1 model is downloaded in the Caffe* format. You must use the Model Optimizer to convert the model to IR.
The googlenet-v1 model is downloaded in the Caffe format. You must use Model Optimizer to convert the model to IR.
Create an `<ir_dir>` directory to contain the model's Intermediate Representation (IR).
@@ -249,7 +186,7 @@ Create an `<ir_dir>` directory to contain the model's Intermediate Representatio
@endsphinxdirective
To save disk space for your IR file, you can apply [weights compression to FP16](../MO_DG/prepare_model/FP16_Compression.md). To generate an IR with FP16 weights, run the Model Optimizer with the `--compress_to_fp16` option.
To save disk space for your IR file, you can apply [weights compression to FP16](../MO_DG/prepare_model/FP16_Compression.md). To generate an IR with FP16 weights, run Model Optimizer with the `--compress_to_fp16` option.
Generic Model Optimizer script:
@@ -257,7 +194,7 @@ Generic Model Optimizer script:
mo --input_model <model_dir>/<model_file>
```
IR files produced by the script are written to the <ir_dir> directory.
The IR files produced by the script are written to the `<ir_dir>` directory.
The command with most placeholders filled in and FP16 precision:
@@ -285,21 +222,15 @@ The command with most placeholders filled in and FP16 precision:
## <a name="download-media"></a> Step 3: Download a Video or a Photo as Media
Many sources are available from which you can download video media to use the code samples and demo applications. Possibilities include:
Most of the samples require you to provide an image or a video as the input to run the model on. You can get them from sites like [Pexels](https://pexels.com) or [Google Images](https://images.google.com).
- [Pexels](https://pexels.com)
- [Google Images](https://images.google.com)
As an alternative, the Intel® Distribution of OpenVINO™ toolkit includes several sample images and videos that you can use for running code samples and demo applications:
As an alternative, OpenVINO also provides several sample images and videos for you to run code samples and demo applications:
- [Sample images and video](https://storage.openvinotoolkit.org/data/test_data/)
- [Sample videos](https://github.com/intel-iot-devkit/sample-videos)
## <a name="run-image-classification"></a>Step 4: Run Inference on a Sample
### Run the Image Classification Code Sample
To run the **Image Classification** code sample with an input image using the IR model:
1. Set up the OpenVINO environment variables:
@@ -369,19 +300,12 @@ To run the **Image Classification** code sample with an input image using the IR
@endsphinxdirective
### Examples
@sphinxdirective
#### Running Inference on CPU
.. raw:: html
The following command shows how to run the Image Classification Code Sample using the [dog.bmp](https://storage.openvinotoolkit.org/data/test_data/images/224x224/dog.bmp) file as an input image, the model in IR format from the `ir` directory, and the CPU as the target hardware:
<div class="collapsible-section" data-title="Click for examples of running the Image Classification code sample on different devices">
@endsphinxdirective
The following commands run the Image Classification Code Sample using the [dog.bmp](https://storage.openvinotoolkit.org/data/test_data/images/224x224/dog.bmp) file as an input image, the model in IR format from the `ir` directory, and on different hardware devices:
**CPU:**
@sphinxdirective
.. tab:: Linux
@@ -403,49 +327,9 @@ The following commands run the Image Classification Code Sample using the [dog.b
@endsphinxdirective
**GPU:**
> **NOTE**: Running inference on Intel® Processor Graphics (GPU) requires [additional hardware configuration steps](../install_guides/configurations-for-intel-gpu.md), as described earlier on this page. Running on GPU is not compatible with macOS*.
When the sample application is complete, you are given the label and confidence for the top 10 categories. The input image and sample output of the inference results is shown below:
@sphinxdirective
.. tab:: Linux
.. code-block:: sh
./classification_sample_async -i ~/Downloads/dog.bmp -m ~/ir/googlenet-v1.xml -d GPU
.. tab:: Windows
.. code-block:: bat
.\classification_sample_async.exe -i %USERPROFILE%\Downloads\dog.bmp -m %USERPROFILE%\Documents\ir\googlenet-v1.xml -d GPU
@endsphinxdirective
**MYRIAD:**
> **NOTE**: Running inference on VPU devices (Intel® Movidius™ Neural Compute Stick or Intel® Neural Compute Stick 2) with the MYRIAD plugin requires [additional hardware configuration steps](../install_guides/configurations-for-ncs2.md), as described earlier on this page.
@sphinxdirective
.. tab:: Linux
.. code-block:: sh
./classification_sample_async -i ~/Downloads/dog.bmp -m ~/ir/googlenet-v1.xml -d MYRIAD
.. tab:: Windows
.. code-block:: bat
.\classification_sample_async.exe -i %USERPROFILE%\Downloads\dog.bmp -m %USERPROFILE%\Documents\ir\googlenet-v1.xml -d MYRIAD
.. tab:: macOS
.. code-block:: sh
./classification_sample_async -i ~/Downloads/dog.bmp -m ~/ir/googlenet-v1.xml -d MYRIAD
@endsphinxdirective
When the sample application is complete, you see the label and confidence for the top 10 categories on the display. Below is a sample output with inference results on CPU:
<img src="https://storage.openvinotoolkit.org/data/test_data/images/224x224/dog.bmp">
@sphinxdirective
@@ -470,17 +354,55 @@ When the sample application is complete, you see the label and confidence for th
@endsphinxdirective
@sphinxdirective
.. raw:: html
The following two examples show how to run the same sample using GPU or MYRIAD as the target device.
</div>
#### Running Inference on GPU
> **NOTE**: Running inference on Intel® Processor Graphics (GPU) requires [additional hardware configuration steps](../install_guides/configurations-for-intel-gpu.md), as described earlier on this page. Running on GPU is not compatible with macOS.
@sphinxdirective
.. tab:: Linux
.. code-block:: sh
./classification_sample_async -i ~/Downloads/dog.bmp -m ~/ir/googlenet-v1.xml -d GPU
.. tab:: Windows
.. code-block:: bat
.\classification_sample_async.exe -i %USERPROFILE%\Downloads\dog.bmp -m %USERPROFILE%\Documents\ir\googlenet-v1.xml -d GPU
@endsphinxdirective
## Other Demos/Samples
#### Running Inference on MYRIAD
For more samples and demos, you can visit the samples and demos pages below. You can review samples and demos by complexity or by usage, run the relevant application, and adapt the code for your use.
> **NOTE**: Running inference on VPU devices (Intel® Movidius™ Neural Compute Stick or Intel® Neural Compute Stick 2) with the MYRIAD plugin requires [additional hardware configuration steps](../install_guides/configurations-for-ncs2.md), as described earlier on this page.
[Samples](../OV_Runtime_UG/Samples_Overview.md)
@sphinxdirective
.. tab:: Linux
[Demos](@ref omz_demos)
.. code-block:: sh
./classification_sample_async -i ~/Downloads/dog.bmp -m ~/ir/googlenet-v1.xml -d MYRIAD
.. tab:: Windows
.. code-block:: bat
.\classification_sample_async.exe -i %USERPROFILE%\Downloads\dog.bmp -m %USERPROFILE%\Documents\ir\googlenet-v1.xml -d MYRIAD
.. tab:: macOS
.. code-block:: sh
./classification_sample_async -i ~/Downloads/dog.bmp -m ~/ir/googlenet-v1.xml -d MYRIAD
@endsphinxdirective
## Other Demos and Samples
See the [Samples](../OV_Runtime_UG/Samples_Overview.md) page for more sample applications. Each sample page explains how the application works and shows how to run it. Use the samples as a starting point that can be adapted for your own application.
OpenVINO also provides demo applications for using off-the-shelf models from [Open Model Zoo](@ref model_zoo). Visit [Open Model Zoo Demos](@ref omz_demos) if you'd like to see even more examples of how to run model inference with the OpenVINO API.