add inference API doc

deploy/mx_infer/args.py

@@ -23,10 +23,9 @@ def get_args():
     parser.add_argument('--device', type=str, default='Ascend', required=False,
                         choices=['Ascend'], help='Device type.')
     parser.add_argument('--device_id', type=int, default=0, required=False, help='Device id.')
-    parser.add_argument('--parallel_num', type=int, default=1, required=False, help='Number of parallel inference.')
+    parser.add_argument('--parallel_num', type=int, default=1, required=False, help='Number of parallel in each stage of pipeline parallelism.')
     parser.add_argument('--precision_mode', type=str, default="fp32", choices=['fp16', 'fp32'], required=False,
                         help='Precision mode.')
-
     parser.add_argument('--det_algorithm', type=str, default='DBNet', choices=SUPPORT_DET_MODEL, required=False,
                         help='Detection algorithm name.')
     parser.add_argument('--rec_algorithm', type=str, default='CRNN', choices=SUPPORT_REC_MODEL, required=False,
@@ -44,7 +43,7 @@ def get_args():
     parser.add_argument('--vis_det_save_dir', type=str, required=False,
                         help='Saving dir for visualization of detection results.')
     parser.add_argument('--vis_pipeline_save_dir', type=str, required=False,
-                        help='Saving dir for visualization of pipeline inference results.')
+                        help='Saving dir for visualization of  det+cls(optional)+rec pipeline inference results.')
     parser.add_argument('--vis_font_path', type=str, required=False,
                         help='Font file path for recognition model.')
     parser.add_argument('--pipeline_crop_save_dir', type=str, required=False,

deploy/mx_infer/pipeline.py

@@ -93,6 +93,63 @@ def build_pipeline_kernel(args, input_queue):
 
 
 def build_pipeline(args):
+    """
+    Build the inference pipeline. Four modes are supported:
+        Mode 1: Text detection + text direction classification + text recognition.
+        Mode 2: Text detection + text recognition.
+        Mode 3: Text detection.
+        Mode 4: Text recognition.
+
+    Args:
+        args (argparse.Namespace):
+            - input_images_dir (str): Input images dir for inference, can be dir containing multiple images or path of single image. This arg is reuqired.
+            - device (str): Device type. Only 'Ascend' is supported at this stage.
+            - device_id (int): Device id.
+            - parallel_num (int): Number of parallel in each stage of pipeline parallelism.
+            - precision_mode (str): Precision mode. Only fp32 is supported at this stage.
+            - det_algorithm (str): Detection algorithm name. Please check the SUPPORT_DET_MODEL in deploy/mx_infer/processors/detection/__init__.py
+            - rec_algorithm (str): Recognition algorithm name. Please check the SUPPORT_REC_MODEL in deploy/mx_infer/processors/recognition/__init__.py
+            - det_model_path (str): Detection model file path.
+            - cls_model_path (str): Classification model file path.
+            - rec_model_path (str): Recognition model file path or directory which contains multiple recognition models.
+            - rec_char_dict_path (str): Character dict file path for recognition models.
+            - res_save_dir (str): Saving dir for inference results. If it's not set, the results will not be saved.
+            - vis_det_save_dir (str): Saving dir for visualization of detection results. If it's not set, the results will not be saved.
+            - vis_pipeline_save_dir (str): Saving dir for visualization of det+cls(optional)+rec pipeline inference results. If it's not set, the results will not be saved.
+            - vis_font_path (str): Font file path for recognition model.
+            - pipeline_crop_save_dir (str): Saving dir for images cropped during pipeline. If it's not set, the results will not be saved.
+            - show_log (str): Whether show log when inferring. If the lower case of this arg is in ("true", "t", "1"), then True, else False.
+            - save_log_dir (str): Log saving dir.
+
+    Return:
+        NoneType
+
+    Notes:
+        Args configuration guidelines for four different modes of inference pipeline:
+            - Mode 1: Text detection + text direction classification + text recognition.
+                These args must be set to correct dir or path: `input_images_dir`, `det_model_path`, `cls_model_path`, `rec_model_path`, `rec_char_dict_path`.
+                Other args can be set if needed.
+            - Mode 2: Text detection + text recognition.
+                These args must be set to correct dir or path: `input_images_dir`, `det_model_path`, `rec_model_path`, `rec_char_dict_path`.
+                This arg CANNOT be set: `cls_model_path`.
+                Other args can be set if needed.
+            - Mode 3: Text detection.
+                These args must be set to correct dir or path: `input_images_dir`, `det_model_path`.
+                These args CANNOT be set: `cls_model_path`, `rec_model_path`, `rec_char_dict_path`.
+                Other args can be set if needed.
+            - Mode 4: Text recognition.
+                These args must be set to correct dir or path: `input_images_dir`, `rec_model_path`, `rec_char_dict_path`.
+                These args CANNOT be set: `det_model_path`, `cls_model_path`.
+                Other args can be set if needed.
+        If the guidelines above are not followed, the inference pipeline cannot be built. Check your args configurations.
+
+    Example:
+    >>> from deploy.mx_infer.args import get_args
+    >>> import deploy.mx_infer.pipeline as pipeline
+    >>> args = get_args()
+    >>> pipeline.build_pipeline(args)
+    """
+
     if args.res_save_dir:
         save_path_init(args.res_save_dir)
     if args.save_pipeline_crop_res: