inference-engine/samples/calibration_tool/README.md

   1 # C++ Calibration Tool [DEPRECATED]
   2
   3 > **NOTE**: OpenVINO 2019 R1 release introduced a [Python\* version of the Calibration Tool](./inference-engine/tools/calibration_tool/README.md). This is now a recommended version since it supports a larger set of topologies and datasets. The [C++ version of the Calibration Tool](./inference-engine/samples/calibration_tool/README.md) is still in the package but deprecated and will not be updated for new releases.
   4
   5 The C++ Calibration Tool calibrates a given FP32 model so that is can be run in low-precision 8-bit integer
   6 mode while keeping the input data of this model in the original precision.
   7
   8 > **NOTE**: INT8 models are currently supported only by the CPU plugin. For the full list of supported configurations, see the [Supported Devices](./docs/IE_DG/supported_plugins/Supported_Devices.md) topic.
   9
  10 > **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 Reverse Input Channels** section of [Converting a Model Using General Conversion Parameters](./docs/MO_DG/prepare_model/convert_model/Converting_Model_General.md).
  11
  12 ## Calibration Tool Options
  13
  14 The core command-line options for the Calibration Tool are the same as for
  15 [Validation Application](./inference-engine/samples/validation_app/README.md). However, the Calibration Tool has the following specific options: `-t`, `-subset`, `-output`, and `-threshold`.
  16
  17 Running the Calibration Tool with the `-h` option yields the following usage message:
  18 ```sh
  19 Usage: calibration_tool [OPTION]
  20
  21 Available options:
  22
  23     -h                        Print a help message
  24     -t <type>                 Type of an inferred network ("C" by default)
  25       -t "C" to calibrate Classification network and write the calibrated network to IR
  26       -t "OD" to calibrate Object Detection network and write the calibrated network to IR
  27       -t "RawC" to collect only statistics for Classification network and write statistics to IR. With this option, a model is not calibrated. For calibration and statisctics collection, use "-t C" instead.
  28       -t "RawOD" to collect only statistics for Object Detection network and write statistics to IR. With this option, a model is not calibrated. For calibration and statisctics collection, use "-t OD" instead
  29     -i <path>                 Required. Path to a directory with validation images. For Classification models, the directory must contain folders named as labels with images inside or a .txt file with a list of images. For Object Detection models, the dataset must be in VOC format.
  30     -m <path>                 Required. Path to an .xml file with a trained model, including model name and extension.
  31     -lbl <path>               Labels file path. The labels file contains names of the dataset classes
  32     -l <absolute_path>        Required for CPU custom layers. Absolute path to a shared library with the kernel implementations.
  33     -c <absolute_path>        Required for GPU custom kernels. Absolute path to an .xml file with the kernel descriptions.
  34     -d <device>               Target device to infer on: CPU (default), GPU, FPGA, HDDL or MYRIAD. The application looks for a suitable plugin for the specified device.
  35     -b N                      Batch size value. If not specified, the batch size value is taken from IR
  36     -ppType <type>            Preprocessing type. Options: "None", "Resize", "ResizeCrop"
  37     -ppSize N                 Preprocessing size (used with ppType="ResizeCrop")
  38     -ppWidth W                Preprocessing width (overrides -ppSize, used with ppType="ResizeCrop")
  39     -ppHeight H               Preprocessing height (overrides -ppSize, used with ppType="ResizeCrop")
  40     --dump                    Dump file names and inference results to a .csv file
  41     -subset                   Number of pictures from the whole validation set tocreate the calibration dataset. Default value is 0, which stands forthe whole provided dataset
  42     -output <output_IR>       Output name for calibrated model. Default is <original_model_name>_i8.xml|bin
  43     -threshold                Threshold for a maximum accuracy drop of quantized model. Must be an integer number (percents) without a percent sign. Default value is 1, which stands for accepted accuracy drop in 1%
  44     -stream_output            Flag for printing progress as a plain text.When used, interactive progress bar is replaced with multiline output
  45
  46     Classification-specific options:
  47       -Czb true               "Zero is a background" flag. Some networks are trained with a modified dataset where the class IDs  are enumerated from 1, but 0 is an undefined "background" class (which is never detected)
  48
  49     Object detection-specific options:
  50       -ODkind <kind>          Type of an Object Detection model. Options: SSD
  51       -ODa <path>             Required for Object Detection models. Path to a directory containing an .xml file with annotations for images.
  52       -ODc <file>             Required for Object Detection models. Path to a file with a list of classes
  53       -ODsubdir <name>        Directory between the path to images (specified with -i) and image name (specified in the .xml file). For VOC2007 dataset, use JPEGImages.
  54 ```
  55
  56 The tool options are divided into two categories:
  57 1. **Common options** named with a single letter or a word, such as <code>-b</code> or <code>--dump</code>.
  58    These options are the same in all calibration tool modes.
  59 2. **Network type-specific options** named as an acronym of the network type (<code>C</code> or <code>OD</code>)
  60    followed by a letter or a word.
  61
  62 You can run the tool with public or pre-trained models. To download the pre-trained models, use the OpenVINO [Model Downloader](https://github.com/opencv/open_model_zoo/tree/2018/model_downloader) or go to [https://download.01.org/opencv/](https://download.01.org/opencv/).
  63
  64 > **NOTE**: Before running the tool on 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).
  65
  66 ## Calibrate a Classification Model
  67
  68 To calibrate a classification convolutional neural network (CNN)
  69 on a subset of images (first 2000 images) from the given dataset (specified with the `-i` option), run the following command:
  70
  71 ```bash
  72 ./calibration_tool -t C -i <path_to_images_directory_or_txt_file> -m <path_to_classification_model>/<model_name>.xml -d <CPU|GPU> -subset 2000
  73 ```
  74
  75 The dataset must have the correct format. Classification models support two formats: folders
  76 named as labels that contain all images of this class and ImageNet*-like format, with the
  77 `.txt` file containing list of images and IDs of classes.
  78
  79 For more information on the structure of the datasets, refer to the **Prepare a Dataset** section of the
  80 [Validation Application document](./inference-engine/samples/validation_app/README.md).
  81
  82 If you decide to use the subset of the given dataset, use the ImageNet-like format
  83 instead of "folder as classes" format. This brings a more accurate calibration as you are likely to get images
  84 representing different classes.
  85
  86 To run the sample you can use classification models that can be downloaded with the OpenVINO [Model Downloader](https://github.com/opencv/open_model_zoo/tree/2018/model_downloader) or other image classification models.
  87
  88 For example, to calibrate the trained Caffe\* `resnet-50` classification model, run the following command:
  89
  90 ```bash
  91 ./calibration_tool -t C -m <path_to_model>/resnet-50.xml -i ILSVRC2012_val.txt -Czb false -ppType "ResizeCrop" -ppSize 342 -b 1 -d CPU -subset 2000
  92 ```
  93
  94 ## Calibrate Object Detection Model
  95
  96 This topic demonstrates how to run the Calibration Tool on the Object Detection CNN on a set of images. Please
  97 review the list of Object Detection models used for validation of the Calibration Tool
  98 in the [8-bit Inference Introduction](./docs/IE_DG/Int8Inference.md).
  99 Any network that can be inferred with the Inference Engine and has the same input and output
 100 format as the SSD CNN should be supported as well.
 101
 102 ### Run SSD Network on the VOC dataset
 103
 104 Before you start calibrating the model, make sure your dataset is in the correct format. For more information,
 105 refer to the **Prepare a Dataset** section of the
 106 [Validation Application document](./inference-engine/samples/validation_app/README.md).
 107
 108 Once you have prepared the dataset, you can calibrate the model on it by running the following command:
 109 ```bash
 110 ./calibration_tool -d CPU -t OD -ODa "<path_to_image_annotations>/VOCdevkit/VOC2007/Annotations" -i "<path_to_image_directory>/VOCdevkit" -m "<path_to_model>/vgg_voc0712_ssd_300x300.xml" -ODc "<path_to_classes_list>/VOC_SSD_Classes.txt" -ODsubdir JPEGImages -subset 500
 111 ```
 112
 113 ## See Also
 114
 115 * [Using Inference Engine Samples](./docs/IE_DG/Samples_Overview.md)
 116 * [Model Optimizer](./docs/MO_DG/Deep_Learning_Model_Optimizer_DevGuide.md)
 117 * [Model Downloader](https://github.com/opencv/open_model_zoo/tree/2018/model_downloader)