inference-engine/ie_bridges/python/sample/classification_sample_async/README.md

   1 # Image Classification Python* Sample Async
   2
   3 This sample demonstrates how to build and execute inference in pipelined mode on example of classifications networks.
   4
   5 The pipelined mode might increase the throughput of the pictures. The latency of one inference will be the same as for synchronous execution.
   6 <br>
   7 The throughput increases due to follow reasons:
   8 * Some plugins have heterogeneity inside themselves: data transferring, execution on remote device, pre-processing and post-processing on the host.
   9 * Using of explicit heterogeneous plugin with execution of different parts of network on different devices, for example HETERO:CPU,GPU.
  10
  11 When two or more devices process one image, creating several infer requests and starting asynchronous inference allow for using devices in the most efficient way.
  12 If two devices are involved in execution, the most optimal value for `-nireq` option is 2.
  13 To process infer requests more efficiently, Classification Sample Async uses round-robin algorithm. It starts execution of the current infer request and switches to waiting for results of the previous one. After finishing of waiting, it switches infer requests and repeat the procedure.
  14
  15 Another required aspect of good throughput is a number of iterations. Only with big number of iterations you can emulate the real application work and get good performance.
  16
  17 The batch mode is an independent attribute on the pipelined mode. Pipelined mode works efficiently with any batch size.
  18
  19 ### How It Works
  20
  21 Upon the start-up, the sample application reads command line parameters and loads a network and an image to the Inference
  22 Engine plugin.
  23 Then application creates several infer requests pointed in `-nireq` parameter and loads images for inference.
  24
  25 Then in a loop it starts inference for the current infer request and switches to waiting for the previous one. When results are ready, it swaps infer requests.
  26
  27 When inference is done, the application outputs data to the standard output stream.
  28
  29 > **NOTE**: By default, Inference Engine samples and demos expect input with BGR channels order. If you trained your model to work with RGB order, you need to manually rearrange the default channels order in the sample or demo application or reconvert your model using the Model Optimizer tool with `--reverse_input_channels` argument specified. For more information about the argument, refer to **When to Specify Input Shapes** section of [Converting a Model Using General Conversion Parameters](./docs/MO_DG/prepare_model/convert_model/Converting_Model_General.md).
  30
  31 ## Running
  32
  33 Running the application with the <code>-h</code> option yields the following usage message:
  34 ```
  35 python3 classification_sample_async.py -h
  36 ```
  37 The command yields the following usage message:
  38 ```
  39 usage: classification_sample_async.py [-h] -m MODEL -i INPUT [INPUT ...]
  40                                       [-l CPU_EXTENSION] [-pp PLUGIN_DIR]
  41                                       [-d DEVICE] [--labels LABELS]
  42                                       [-nt NUMBER_TOP] [-ni NUMBER_ITER] [-pc]
  43
  44 Options:
  45   -h, --help            Show this help message and exit.
  46   -m MODEL, --model MODEL
  47                         Required. Path to an .xml file with a trained model.
  48   -i INPUT [INPUT ...], --input INPUT [INPUT ...]
  49                         Required. Path to a folder with images or path to an
  50                         image files
  51   -l CPU_EXTENSION, --cpu_extension CPU_EXTENSION
  52                         Optional. Required for CPU custom layers. Absolute
  53                         path to a shared library with the kernels
  54                         implementations.
  55   -pp PLUGIN_DIR, --plugin_dir PLUGIN_DIR
  56                         Optional. Path to a plugin folder
  57   -d DEVICE, --device DEVICE
  58                         Optional. Specify the target device to infer on; CPU,
  59                         GPU, FPGA, HDDL or MYRIAD is acceptable. The sample
  60                         will look for a suitable plugin for device specified.
  61                         Default value is CPU
  62   --labels LABELS       Optional. Labels mapping file
  63   -nt NUMBER_TOP, --number_top NUMBER_TOP
  64                         Optional. Number of top results
  65   -ni NUMBER_ITER, --number_iter NUMBER_ITER
  66                         Optional. Number of inference iterations
  67   -pc, --perf_counts    Optional. Report performance counters
  68
  69 ```
  70
  71 Running the application with the empty list of options yields the usage message given above and an error message.
  72
  73 To run the sample, you can use AlexNet and GoogLeNet or other image classification models. You can download the pre-trained models with the OpenVINO [Model Downloader](https://github.com/opencv/open_model_zoo/tree/2018/model_downloader) or from [https://download.01.org/opencv/](https://download.01.org/opencv/).
  74
  75 > **NOTE**: Before running the sample with a trained model, make sure the model is converted to the Inference Engine format (\*.xml + \*.bin) using the [Model Optimizer tool](./docs/MO_DG/Deep_Learning_Model_Optimizer_DevGuide.md).
  76
  77
  78 You can do inference on an image using a trained AlexNet network on FPGA with fallback to CPU using the following command:
  79 ```
  80     python3 classification_sample_async.py -i <path_to_image>/cat.bmp -m <path_to_model>/alexnet_fp32.xml -nt 5 -d HETERO:FPGA,CPU -nireq 2 -ni 200
  81 ```
  82
  83 ### Sample Output
  84
  85 By default, the application outputs top-10 inference results for each infer request.
  86 It also provides throughput value measured in frames per seconds.
  87
  88 ## See Also
  89 * [Using Inference Engine Samples](./docs/IE_DG/Samples_Overview.md)