Python Model API: update docstrings for Model, ImageModel, DetectionModel wrappers (#3375)

anzhella-pankratova · web-flow · commit 903f900b082c · 2022-03-25T12:46:03.000+03:00
* Modify docstrings for Model, ImageModel, DetectionModel classes in Python Model API

* Small fixes

* suggestions: use inputs/outputs, remove by wrapper

* Apply suggestions
diff --git a/demos/common/python/openvino/model_zoo/model_api/adapters/model_adapter.py b/demos/common/python/openvino/model_zoo/model_api/adapters/model_adapter.py
@@ -35,7 +35,7 @@ class ModelAdapter(metaclass=abc.ABCMeta):
 
         - Reading the model from disk or other place
         - Loading the model to the device
-        - Accessing the information about input/output layers
+        - Accessing the information about inputs/outputs
         - The model reshaping
         - Synchronous model inference
         - Asynchronous model inference
@@ -58,34 +58,36 @@ def load_model(self):
     @abc.abstractmethod
     def get_input_layers(self):
         '''
-        Gets the names of model input layers and for each layer creates the Metadata structure,
-           which contains the information about the layer shape, blob precision in OpenVINO format, meta (optional)
+        Gets the names of model inputs and for each one creates the Metadata structure,
+           which contains the information about the input shape, layout, precision
+           in OpenVINO format, meta (optional)
 
         Returns:
-            - the dict containing Metadata for all input layers
+            - the dict containing Metadata for all inputs
         '''
 
     @abc.abstractmethod
     def get_output_layers(self):
         '''
-        Gets the names of model output layers and for each layer creates the Metadata structure,
-           which contains the information about the layer shape, blob precision in OpenVINO format, meta (optional)
+        Gets the names of model outputs and for each one creates the Metadata structure,
+           which contains the information about the output shape, layout, precision
+           in OpenVINO format, meta (optional)
 
         Returns:
-            - the dict containing Metadata for all output layers
+            - the dict containing Metadata for all outputs
         '''
 
     @abc.abstractmethod
     def reshape_model(self, new_shape):
         '''
-        Reshapes the model input layers to fit the new input shape.
+        Reshapes the model inputs to fit the new input shape.
 
         Args:
-            - new_shape(dict): the dictionary with input layers as keys and
+            - new_shape (dict): the dictionary with inputs names as keys and
                 list of new shape as values in the following format:
                 {
-                    'input_layer_1': [1, 128, 128, 3],
-                    'input_layer_2': [1, 128, 128, 3],
+                    'input_layer_name_1': [1, 128, 128, 3],
+                    'input_layer_name_2': [1, 128, 128, 3],
                     ...
                 }
         '''
@@ -98,16 +100,16 @@ def infer_sync(self, dict_data):
         Args:
             - dict_data: it's submitted to the model for inference and has the following format:
                 {
-                    'input_layer_1': data_1,
-                    'input_layer_2': data_2,
+                    'input_layer_name_1': data_1,
+                    'input_layer_name_2': data_2,
                     ...
                 }
 
         Returns:
-            - raw result(dict) - model raw output in the following format:
+            - raw result (dict) - model raw output in the following format:
                 {
-                    'output_layer_1': raw_result_1,
-                    'output_layer_2': raw_result_2,
+                    'output_layer_name_1': raw_result_1,
+                    'output_layer_name_2': raw_result_2,
                     ...
                 }
         '''
@@ -123,8 +125,8 @@ def infer_async(self, dict_data, callback_fn, callback_data):
         Args:
             - dict_data: it's submitted to the model for inference and has the following format:
                 {
-                    'input_layer_1': data_1,
-                    'input_layer_2': data_2,
+                    'input_layer_name_1': data_1,
+                    'input_layer_name_2': data_2,
                     ...
                 }
             - callback_fn: the callback function, which is defined outside the adapter
diff --git a/demos/common/python/openvino/model_zoo/model_api/adapters/openvino_adapter.py b/demos/common/python/openvino/model_zoo/model_api/adapters/openvino_adapter.py
@@ -38,9 +38,9 @@ def create_core():
 
 
 class OpenvinoAdapter(ModelAdapter):
-    """
+    '''
     Works with OpenVINO model
-    """
+    '''
 
     def __init__(self, core, model_path, weights_path=None, model_parameters = {}, device='CPU', plugin_config=None, max_num_requests=0):
         self.core = core
diff --git a/demos/common/python/openvino/model_zoo/model_api/adapters/ovms_adapter.py b/demos/common/python/openvino/model_zoo/model_api/adapters/ovms_adapter.py
@@ -28,9 +28,9 @@
 
 
 class OVMSAdapter(ModelAdapter):
-    """
+    '''
     Class that allows working with models served by the OpenVINO Model Server
-    """
+    '''
 
     tf2ov_precision = {
         "DT_INT64": "I64",
diff --git a/demos/common/python/openvino/model_zoo/model_api/models/detection_model.py b/demos/common/python/openvino/model_zoo/model_api/models/detection_model.py
@@ -19,30 +19,31 @@
 
 
 class DetectionModel(ImageModel):
-    '''An abstract detection model class
+    '''An abstract wrapper for object detection model
 
-    This class supports detection models. The Detection Model must have single image input.
+    The DetectionModel must have a single image input.
+    It inherits `preprocess` from `ImageModel` wrapper. Also, it defines `_resize_detections` method,
+    which should be used in `postprocess`, to clip bounding boxes and resize ones to original image shape.
 
-    Attributes:
-        labels(List[str]): list of labels for classes (could be None)
-        threshold(float): threshold for detection filtering, any detection with confidence less than this value
-            should be omitted in ``posptrocess`` method (0<=thresold<=1.0 for most models)
-        iou_threshold(float): threshold for NMS detection filtering
+    The `postprocess` method must be implemented in a specific inherited wrapper.
     '''
 
     def __init__(self, model_adapter, configuration=None, preload=False):
-        '''The Detection Model constructor
+        '''Detection Model constructor
 
-        Calls the ``ImageModel`` construtor first.
+        It extends the `ImageModel` construtor.
 
         Args:
-            labels(Iterable[str], str, Path): list of labels for detection classes or path to file with them
-            threshold(float): threshold for detections filtering by confidence
-            iou_threshold(float): threshold for NMS filtering
+            model_adapter (ModelAdapter): allows working with the specified executor
+            configuration (dict, optional): it contains values for parameters accepted by specific
+              wrapper (`confidence_threshold`, `labels` etc.) which are set as data attributes
+            preload (bool, optional): a flag whether the model is loaded to device while
+              initialization. If `preload=False`, the model must be loaded via `load` method before inference
 
         Raises:
-            WrapperError: If loaded model has more than one image inputs
+            WrapperError: if the model has more than 1 image inputs
         '''
+
         super().__init__(model_adapter, configuration, preload)
 
         if not self.image_blob_name:
@@ -66,25 +67,25 @@ def parameters(cls):
         return parameters
 
     def _resize_detections(self, detections, meta):
-        '''Resizes detection bounding boxes according to initial image size
+        '''Resizes detection bounding boxes according to initial image shape.
 
-        Implements resize operations for different image resize types (see ``ImageModel`` class for details).
-        Applies clipping bounding box to original image size.
+        It implements image resizing depending on the set `resize_type`(see `ImageModel` for details).
+        Next, it applies bounding boxes clipping.
 
         Args:
-            detections(List[Detection]): list of detections with coordinates in normalized form
-            meta: meta information with fields `resized_shape` and `original_shape`
+            detections (List[Detection]): list of detections with coordinates in normalized form
+            meta (dict): the input metadata obtained from `preprocess` method
 
         Returns:
-            List of detections fit to initial image (resized and clipped)
+            - list of detections with resized and clipped coordinates fit to initial image
 
         Raises:
-            WrapperError: If model uses custom resize or `resize_type` not set
+            WrapperError: If the model uses custom resize or `resize_type` is not set
         '''
         resized_shape = meta['resized_shape']
         original_shape = meta['original_shape']
 
-        if self.resize_type=='fit_to_window_letterbox':
+        if self.resize_type == 'fit_to_window_letterbox':
             detections = resize_detections_letterbox(detections, original_shape[1::-1], resized_shape[1::-1])
         elif self.resize_type == 'fit_to_window':
             detections = resize_detections_with_aspect_ratio(detections, original_shape[1::-1], resized_shape[1::-1], (self.w, self.h))
diff --git a/demos/common/python/openvino/model_zoo/model_api/models/image_model.py b/demos/common/python/openvino/model_zoo/model_api/models/image_model.py
@@ -22,25 +22,38 @@
 class ImageModel(Model):
     '''An abstract wrapper for an image-based model
 
-    An image-based model is a model which has one or more inputs with image - 4D tensors with NHWC or NCHW layout.
-    Also it may support additional inputs - 2D tensor.
-    Implements basic preprocessing for image: resizing and aligning to model input.
+    The ImageModel has 1 or more inputs with images - 4D tensors with NHWC or NCHW layout.
+    It may support additional inputs - 2D tensors.
+
+    The ImageModel implements basic preprocessing for an image provided as model input.
+    See `preprocess` description.
+
+    The `postprocess` method must be implemented in a specific inherited wrapper.
 
     Attributes:
-        resize_type(str): one of the preimplemented resize types
-        image_blob_names(List[str]): names of all image-like inputs (4D tensors)
-        image_info_blob_names(List[str]): names of all secondary inputs (2D tensors)
-        image_blob_name(str): name of image input (None, if they are many)
+        image_blob_names (List[str]): names of all image-like inputs (4D tensors)
+        image_info_blob_names (List[str]): names of all secondary inputs (2D tensors)
+        image_blob_name (str): name of the first image input
+        nchw_layout (bool): a flag whether the model input layer has NCHW layout
+        resize_type (str): the type for image resizing (see `RESIZE_TYPE` for info)
+        resize (function): resizing function corresponding to the `resize_type`
+        input_transform (InputTransform): instance of the `InputTransform` for image normalization
     '''
 
     def __init__(self, model_adapter, configuration=None, preload=False):
         '''Image model constructor
 
-        Calls the `Model` constructor first
+        It extends the `Model` constructor.
 
         Args:
-            model_adapter(ModelAdapter): allows working with the specified executor
-            resize_type(str): sets the type for image resizing (see ``RESIZE_TYPE`` for info)
+            model_adapter (ModelAdapter): allows working with the specified executor
+            configuration (dict, optional): it contains values for parameters accepted by specific
+              wrapper (`confidence_threshold`, `labels` etc.) which are set as data attributes
+            preload (bool, optional): a flag whether the model is loaded to device while
+              initialization. If `preload=False`, the model must be loaded via `load` method before inference
+
+        Raises:
+            WrapperError: if the wrapper failed to define appropriate inputs for images
         '''
         super().__init__(model_adapter, configuration, preload)
         self.image_blob_names, self.image_info_blob_names = self._get_inputs()
@@ -75,6 +88,15 @@ def parameters(cls):
         return parameters
 
     def _get_inputs(self):
+        '''Defines the model inputs for images and additional info.
+
+        Raises:
+            WrapperError: if the wrapper failed to define appropriate inputs for images
+
+        Returns:
+            - list of inputs names for images
+            - list of inputs names for additional info
+        '''
         image_blob_names, image_info_blob_names = [], []
         for name, metadata in self.inputs.items():
             if len(metadata.shape) == 4:
@@ -90,24 +112,27 @@ def _get_inputs(self):
     def preprocess(self, inputs):
         '''Data preprocess method
 
-        Performs some basic preprocessing with single image:
-        - resizing to net input size
-        - applying tranform orerations: mean and scale values, BGR-RGB conversions
-        - changing layout according to net input layout
+        It performs basic preprocessing of a single image:
+            - Resizes the image to fit the model input size via the defined resize type
+            - Normalizes the image: subtracts means, divides by scales, switch channels BGR-RGB
+            - Changes the image layout according to the model input layout
 
-        Adds the size of initial image and after resizing to metadata as `original_shape` and `resized_shape`
-        correspondenly.
+        Also, it keeps the size of original image and resized one as `original_shape` and `resized_shape`
+        in the metadata dictionary.
 
         Note:
-            This method supports only models with single image input. If model has more image inputs
-            or has additional support inputs, their preprocessing should be implemented in concrete class
+            It supports only models with single image input. If the model has more image inputs or has
+            additional supported inputs, the `preprocess` should be overloaded in a specific wrapper.
 
         Args:
-            inputs: single image as 3D array in HWC layout
+            inputs (ndarray): a single image as 3D array in HWC layout
 
         Returns:
-            - the dict with preprocessed image data
-            - The dict with metadata
+            - the preprocessed image in the following format:
+                {
+                    'input_layer_name': preprocessed_image
+                }
+            - the input metadata, which might be used in `postprocess` method
         '''
         image = inputs
         meta = {'original_shape': image.shape}
@@ -121,8 +146,16 @@ def preprocess(self, inputs):
         return dict_inputs, meta
 
     def _change_layout(self, image):
+        '''Changes the input image layout to fit the layout of the model input layer.
+
+        Args:
+            inputs (ndarray): a single image as 3D array in HWC layout
+
+        Returns:
+            - the image with layout aligned with the model layout
+        '''
         if self.nchw_layout:
-            image = image.transpose((2, 0, 1))  # Change data layout from HWC to CHW
+            image = image.transpose((2, 0, 1))  # HWC->CHW
             image = image.reshape((1, self.c, self.h, self.w))
         else:
             image = image.reshape((1, self.h, self.w, self.c))
diff --git a/demos/common/python/openvino/model_zoo/model_api/models/model.py b/demos/common/python/openvino/model_zoo/model_api/models/model.py
