Merge pull request #3338 from openvinotoolkit/master

merge master to release

Author: eaidova

ci/prepare-documentation.py

@@ -382,6 +382,11 @@ def main():
         title='OMZ Model API OVMS adapter')
     ovms_adapter_element.attrib[XML_ID_ATTRIBUTE] = 'omz_model_api_ovms_adapter'
 
+    model_api_element = add_page(output_root, navindex_element, id='omz_python_model_api',
+        path='demos/common/python/openvino/model_zoo/model_api/README.md',
+        title='OMZ Python Model API')
+    model_api_element.attrib[XML_ID_ATTRIBUTE] = 'omz_python_model_api'
+
     for md_path in all_md_paths:
         if md_path not in documentation_md_paths:
             raise RuntimeError(f'{all_md_paths[md_path]}: '

demos/3d_segmentation_demo/python/README.md

@@ -10,12 +10,6 @@ On startup, the demo reads command-line parameters and loads a model and images
 
 ## Preparing to Run
 
-The demo dependencies should be installed before run. That can be achieved with the following command:
-
-```sh
-python3 -mpip install --user -r <omz_dir>/demos/3d_segmentation_demo/python/requirements.txt
-```
-
 For demo input image or video files, refer to the section **Media Files Available for Demos** in the [Open Model Zoo Demos Overview](../../README.md).
 The list of models supported by the demo is in `<omz_dir>/demos/3d_segmentation_demo/python/models.lst` file.
 This file can be used as a parameter for [Model Downloader](../../../tools/model_tools/README.md) and Converter to download and, if necessary, convert models to OpenVINO IR format (\*.xml + \*.bin).

demos/README.md

@@ -286,37 +286,17 @@ cmake -A x64 <open_model_zoo>/demos
   cmake --build . --config Debug
   ```
 
-### <a name="model_api_installation"></a>Python\* model API installation
+### <a name="python_requirements"></a>Dependencies for Python* Demos
 
-Python Model API with model wrappers and pipelines can be installed as a part of OpenVINO&trade; toolkit or from source.
-Installation from source is as follows:
-
-1. Install Python (version 3.6 or higher), [setuptools](https://pypi.org/project/setuptools/):
-
-2. Build the wheel with the following command:
+The dependencies for Python demos must be installed before running. It can be achieved with the following command:
 
 ```sh
-python <omz_dir>/demos/common/python/setup.py bdist_wheel
+python -mpip install --user -r <omz_dir>/demos/requirements.txt
 ```
-The built wheel should appear in the dist folder;
-Name example: `openmodelzoo_modelapi-0.0.0-py3-none-any.whl`
 
-3. Install the package in the clean environment with `--force-reinstall` key:
-```sh
-python -m pip install openmodelzoo_modelapi-0.0.0-py3-none-any.whl --force-reinstall
-```
-Alternatively, instead of building the wheel you can use the following command inside  `<omz_dir>/demos/common/python/` directory to build and install the package:
-```sh
-python -m pip install .
-```
-
-When the model API package is installed, you can import it as follows:
-```sh
-python -c "from openvino.model_zoo import model_api"
-```
+### <a name="python_model_api"></a>Python\* model API package
 
-> **NOTE**: On Linux and macOS, you may need to type `python3` instead of `python`. You may also need to [install pip](https://pip.pypa.io/en/stable/installation/).
-> For example, on Ubuntu execute the following command to get pip installed: `sudo apt install python3-pip`.
+To run Python demo applications, you need to install the Python* Model API package. Refer to [Python* Model API documentation](common/python/openvino/model_zoo/model_api/README.md#installing-python*-model-api-package) to learn about its installation.
 
 ### <a name="build_python_extensions"></a>Build the Native Python\* Extension Modules
 

demos/common/cpp/models/src/classification_model.cpp

@@ -42,7 +42,11 @@ std::unique_ptr<ResultBase> ClassificationModel::postprocess(InferenceResult& in
 
     result->topLabels.reserve(scoresTensor.get_size());
     for (size_t i = 0; i < scoresTensor.get_size(); ++i) {
-        result->topLabels.emplace_back(indicesPtr[i], labels[indicesPtr[i]], scoresPtr[i]);
+        int ind = indicesPtr[i];
+        if (ind < 0 || ind >= (int)labels.size()) {
+            throw std::runtime_error("Invalid index for the class label is found during postprocessing");
+        }
+        result->topLabels.emplace_back(ind, labels[ind], scoresPtr[i]);
     }
 
     return retVal;

demos/common/python/openvino/model_zoo/model_api/README.md

@@ -0,0 +1,136 @@
+# Python* Model API package
+
+Model API package is a set of wrapper classes for particular tasks and model architectures, simplifying data preprocess and postprocess as well as routine procedures (model loading, asynchronous execution, etc...)
+An application feeds model class with input data, then the model returns postprocessed output data in user-friendly format.
+
+## Package structure
+
+The Model API consists of 3 libraries:
+* _adapters_ implements a common interface to allow Model API wrappers usage with different executors. See [Model API adapters](#model-api-adapters) section
+* _models_ implements wrappers for Open Model Zoo models. See [Model API Wrappers](#model-api-wrappers) section
+* _pipelines_ implements pipelines for model inference and manage the synchronous/asynchronous execution. See [Model API Pipelines](#model-api-pipelines) section
+
+### Prerequisites
+
+The package requires
+- one of OpenVINO supported Python version (see OpenVINO documentation for the details)
+- OpenVINO™ toolkit
+
+If you build Model API package from source, you should install the OpenVINO™ toolkit. See the options:
+
+Use installation package for [Intel® Distribution of OpenVINO™ toolkit](https://www.intel.com/content/www/us/en/developer/tools/openvino-toolkit-download.html) or build the open-source version available in the [OpenVINO GitHub repository](https://github.com/openvinotoolkit/openvino) using the [build instructions](https://github.com/openvinotoolkit/openvino/wiki/BuildingCode).
+
+Also, you can install the OpenVINO Python\* package via the command:
+ ```sh
+pip install openvino
+ ```
+
+## Installing Python* Model API package
+
+Use the following command to install Model API from source:
+```sh
+pip install <omz_dir>/demos/common/python
+```
+
+Alternatively, you can generate the package using a wheel. Follow the steps below:
+1. Build the wheel.
+
+```sh
+python <omz_dir>/demos/common/python/setup.py bdist_wheel
+```
+The wheel should appear in the dist folder.
+Name example: `openmodelzoo_modelapi-0.0.0-py3-none-any.whl`
+
+2. Install the package in the clean environment with `--force-reinstall` key.
+```sh
+pip install openmodelzoo_modelapi-0.0.0-py3-none-any.whl --force-reinstall
+```
+
+To verify the package is installed, you might use the following command:
+```sh
+python -c "from openvino.model_zoo import model_api"
+```
+
+## Model API Wrappers
+
+The Model API package provides model wrappers, which implement standardized preprocessing/postprocessing functions per "task type" and incapsulate model-specific logic for usage of different models in a unified manner inside the application.
+
+The following tasks can be solved with wrappers usage:
+
+| Task type                  | Model API wrappers |
+|----------------------------|--------------------|
+| Background Matting         | <ul><li>`VideoBackgroundMatting`</li><li>`ImageMattingWithBackground`</li></ul> |
+| Classification             | <ul><li>`Classification`</li></ul> |
+| Deblurring                 | <ul><li>`Deblurring`</li></ul> |
+| Human Pose Estimation      | <ul><li>`HpeAssociativeEmbedding`</li><li>`OpenPose`</li></ul> |
+| Instance Segmentation      | <ul><li>`MaskRCNNModel`</li><li>`YolactModel`</li></ul> |
+| Monocular Depth Estimation | <ul><li> `MonoDepthModel`</li></ul> |
+| Named Entity Recognition   | <ul><li>`BertNamedEntityRecognition`</li></ul> |
+| Object Detection           | <ul><li>`CenterNet`</li><li>`DETR`</li><li>`CTPN`</li><li>`FaceBoxes`</li><li>`RetinaFace`</li><li>`RetinaFacePyTorch`</li><li>`SSD`</li><li>`UltraLightweightFaceDetection`</li><li>`YOLO`</li><li>`YoloV3ONNX`</li><li>`YoloV4`</li><li>`YOLOF`</li><li>`YOLOX`</li></ul> |
+| Question Answering         |  <ul><li>`BertQuestionAnswering`</li></ul> |
+| Salient Object Detection   |  <ul><li>`SalientObjectDetectionModel`</li></ul> |
+| Semantic Segmentation      |  <ul><li>`SegmentationModel`</li></ul> |
+
+## Model API Adapters
+
+Model API wrappers are executor-agnostic, meaning it does not implement the specific model inference or model loading, instead it can be used with different executors having the implementation of common interface methods in adapter class respectively.
+
+Currently, `OpenvinoAdapter` and `OVMSAdapter` are supported.
+
+#### OpenVINO Adapter
+
+`OpenvinoAdapter` hides the OpenVINO™ toolkit API, which allows Model API wrappers launching with models represented in Intermediate Representation (IR) format.
+It accepts a path to either `xml` model file or `onnx` model file.
+
+#### OpenVINO Model Server Adapter
+
+`OVMSAdapter` hides the OpenVINO Model Server python client API, which allows Model API wrappers launching with models served by OVMS.
+
+Refer to __[`OVMSAdapter`](adapters/ovms_adapter.md)__ to learn about running demos with OVMS.
+
+For using OpenVINO Model Server Adapter you need to install the package with extra module:
+```sh
+pip install <omz_dir>/demos/common/python[ovms]
+```
+
+## Model API Pipelines
+
+Model API Pipelines represent the high-level wrappers upon the input data and accessing model results management.
+They perform the data submission for model inference, verification of inference status, whether the result is ready or not, and results accessing.
+
+The `AsyncPipeline` is available, which handles the asynchronous execution of a single model.
+
+## Ready-to-use Model API solutions
+
+To apply Model API wrappers in custom applications, learn the provided example of common scenario of how to use Model API.
+
+ In the example, the SSD architecture is used to predict bounding boxes on input image `"sample.png"`. The model execution is produced by `OpenvinoAdapter`, therefore we submit the path to the model's `xml` file.
+
+Once the SSD model wrapper instance is created, we get the predictions by the model in one line: `ssd_model(input_data)` - the wrapper performs the preprocess method, synchronous inference on OpenVINO™ toolkit side and postprocess method.
+
+```python
+import cv2
+# import model wrapper class
+from openvino.model_zoo.model_api.models import SSD
+# import inference adapter and helper for runtime setup
+from openvino.model_zoo.model_api.adapters import OpenvinoAdapter, create_core
+
+
+# read input image using opencv
+input_data = cv2.imread("sample.png")
+
+# define the path to mobilenet-ssd model in IR format
+model_path = "public/mobilenet-ssd/FP32/mobilenet-ssd.xml"
+
+# create adapter for OpenVINO™ runtime, pass the model path
+model_adapter = OpenvinoAdapter(create_core(), model_path, device="CPU")
+
+# create model API wrapper for SSD architecture
+# preload=True loads the model on CPU inside the adapter
+ssd_model = SSD(model_adapter, preload=True)
+
+# apply input preprocessing, sync inference, model output postprocessing
+results = ssd_model(input_data)
+```
+
+To study the complex scenarios, refer to Open Model Zoo Python* demos, where the asynchronous inference is applied.

demos/common/python/setup.py

@@ -30,6 +30,9 @@
 with open(SETUP_DIR / 'requirements.txt') as f:
     required = f.read().splitlines()
 
+with open(SETUP_DIR / 'requirements_ovms.txt') as f:
+    ovms_required = f.read().splitlines()
+
 packages = find_packages(str(SETUP_DIR))
 package_dir = {'openvino': str(SETUP_DIR / 'openvino')}
 
@@ -47,4 +50,5 @@
     packages=packages,
     package_dir=package_dir,
     install_requires=required,
+    extras_require={'ovms': ovms_required}
 )

demos/face_recognition_demo/python/README.md

@@ -31,20 +31,6 @@ visualized and displayed on the screen or written to the output file.
 
 ## Preparing to Run
 
-### Installation and dependencies
-
-The demo depends on:
-
-* OpenVINO library (2021.4 or newer)
-* Python (any, which is supported by OpenVINO)
-* OpenCV (>=4.2.5)
-
-To install all the required Python modules you can use:
-
-``` sh
-pip install -r requirements.txt
-```
-
 For demo input image or video files, refer to the section **Media Files Available for Demos** in the [Open Model Zoo Demos Overview](../../README.md).
 The list of models supported by the demo is in `<omz_dir>/demos/face_recognition_demo/python/models.lst` file.
 This file can be used as a parameter for [Model Downloader](../../../tools/model_tools/README.md) and Converter to download and, if necessary, convert models to OpenVINO IR format (\*.xml + \*.bin).

demos/formula_recognition_demo/python/README.md

@@ -56,8 +56,6 @@ Regardless of what mode is selected (interactive or non-interactive) the process
 
 ##### Requirements for rendering
 
-Sympy python package is used for rendering. To install it, please, run:
-`pip install -r requirements.txt`
 Sympy package needs LaTeX system installed in the operating system.
 For Windows you can use [MiKTeX\*](https://miktex.org/) (just download and install it), for Ubuntu/MacOS you can use TeX Live\*:
 Ubuntu:

demos/gaze_estimation_demo/cpp/models.lst

@@ -1,6 +1,6 @@
 # This file can be used with the --list option of the model downloader.
-#facial-landmarks-98-detection-????
 facial-landmarks-35-adas-????
+facial-landmarks-98-detection-????
 face-detection-adas-????
 face-detection-retail-????
 gaze-estimation-adas-????

demos/gpt2_text_prediction_demo/python/gpt2_text_prediction_demo.py

@@ -70,7 +70,7 @@ def main():
     log.debug("Loaded vocab file from {}, get {} tokens".format(args.vocab, len(vocab)))
 
     # create tokenizer
-    tokenizer = Tokenizer(BPE(str(args.vocab), str(args.merges)))
+    tokenizer = Tokenizer(BPE.from_file(str(args.vocab), str(args.merges)))
     tokenizer.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=False)
     tokenizer.decoder = decoders.ByteLevel()