inference-engine/tools/accuracy_checker_tool/README.md

   1 # Deep Learning accuracy validation framework
   2
   3 #### Usage
   4
   5 You may test your installation and get familiar with accuracy checker by running [sample][sample-readme].
   6
   7 Once you installed accuracy checker you can evaluate your configurations with:
   8
   9 ```python
  10 python3 accuracy_check.py -c path/to/configuration_file -m /path/to/models -s /path/to/source/data -a /path/to/annotation
  11 ```
  12
  13 All relative paths in config files will be prefixed with values specified in command line:
  14
  15 - `-c, --config` path to configuration file.
  16 - `-m, --models` specifies directory in which models and weights declared in config file will be searched.
  17 - `-s, --source` specifies directory in which input images will be searched.
  18 - `-a, --annotations` specifies directory in which annotation and meta files will be searched.
  19
  20 You may refer to `-h, --help` to full list of command line options. Some optional arguments are:
  21
  22 - `-e, --extensions` directory with InferenceEngine extensions.
  23 - `-b, --bitstreams` directory with bitstream (for Inference Engine with fpga plugin).
  24 - `-C, '--converted_models` directory to store Model Optimizer converted models (used for DLSDK launcher only).
  25 - `-tf, --target_framework` framework for infer.
  26 - `-td, --target_devices` devices for infer. You can specify several devices using space as a delimiter.
  27
  28 #### Configuration
  29
  30 There is config file which declares validation process.
  31 Every validated model has to have its entry in `models` list
  32 with distinct `name` and other properties described below.
  33
  34 There is also definitions file, which declares global options shared across all models.
  35 Config file has priority over definitions file.
  36
  37 example:
  38
  39 ```yaml
  40 models:
  41 - name: model_name
  42   launchers:
  43     - framework: caffe
  44       model:   public/alexnet/caffe/bvlc_alexnet.prototxt
  45       weights: public/alexnet/caffe/bvlc_alexnet.caffemodel
  46       adapter: classification
  47       batch: 128
  48   datasets:
  49     - name: dataset_name
  50 ```
  51
  52 ### Launchers
  53
  54 Launcher is a description of how your model should be executed.
  55 Each launcher configuration starts with setting `framework` name. Currently *caffe* and *dlsdk* supported. Launcher description can have differences.
  56
  57 Please view:
  58
  59 - [how to configure Caffe launcher][caffe-launcher-configuration].
  60 - [how to configure DLSDK launcher][dlsdk-launcher-configuration].
  61
  62 ### Datasets
  63
  64 Dataset entry describes data on which model should be evaluated,
  65 all required preprocessing and postprocessing/filtering steps,
  66 and metrics that will be used for evaluation.
  67
  68 If your dataset data is a well-known competition problem (COCO, Pascal VOC, ...) and/or can be potentially reused for other models
  69 it is reasonable to declare it in some global configuration file (*definition* file). This way in your local configuration file you can provide only
  70 `name` and all required steps will be picked from global one. To pass path to this global configuration use `--definition` argument of CLI.
  71
  72 Each dataset must have:
  73
  74 - `name` - unique identifier of your model/topology.
  75 - `data_source`: path to directory where input data is stored.
  76 - `metrics`: list of metrics that should be computed.
  77
  78 And optionally:
  79 - `preprocessing`: list of preprocessing steps applied to input data. If you want calculated metrics to match reported, you must reproduce preprocessing from canonical paper of your topology or ask topology author about required steps if it is ICV topology.
  80 - `postprocessing`: list of postprocessing steps.
  81 - `reader`: approach for data reading. You can specify: `opencv_imread` or `pillow_imread` for reading images and `opencv_capture` for reading frames from video. Default reader is `opencv_imread`.
  82
  83 Also it must contain data related to annotation.
  84 You can convert annotation inplace using:
  85 - `annotation_conversion`: parameters for annotation conversion
  86
  87
  88 or use existing annotation file and dataset meta:
  89 - `annotation` - path to annotation file, you must **convert annotation to representation of dataset problem first**, you may choose one of the converters from *annotation-converters* if there is already converter for your dataset or write your own.
  90 - `dataset_meta`: path to metadata file (generated by converter).
  91 More detailed information about annotation conversion you can find [here][converters]
  92
  93 example of dataset definition:
  94
  95 ```yaml
  96 - name: dataset_name
  97   annotation: annotation.pickle
  98   data_source: images_folder
  99
 100   preprocessing:
 101     - type: resize
 102       dst_width: 256
 103       dst_height: 256
 104
 105     - type: normalization
 106       mean: imagenet
 107
 108     - type: crop
 109       dst_width: 227
 110       dst_height: 227
 111
 112   metrics:
 113     - type: accuracy
 114 ```
 115
 116 ### Preprocessing, Metrics, Postprocessing
 117
 118 Each entry of preprocessing, metrics, postprocessing must have `type` field,
 119 other options are specific to type. If you do not provide any other option, then it
 120 will be picked from *definitions* file.
 121
 122 You can find useful following instructions:
 123
 124 - [how to use preprocessings][preprocessors].
 125 - [how to use postprocessings][postprocessors].
 126 - [how to use metrics][metrics].
 127
 128 You may optionally provide `reference` field for metric, if you want calculated metric
 129 tested against specific value (i.e. reported in canonical paper).
 130
 131 Some metrics support providing vector results ( e. g. mAP is able to return average precision for each detection class).  You can change view mode for metric results using `presenter` (e.g. `print_vector`, `print_scalar`).
 132
 133 example:
 134
 135 ```yaml
 136 metrics:
 137 - type: accuracy
 138   top_k: 5
 139   reference: 86.43
 140   threshold: 0.005
 141 ```
 142
 143 ### Testing new models
 144
 145 Typical workflow for testing new model include:
 146
 147 1. Convert annotation of your dataset. Use one of the converters from annotation-converters, or write your own if there is no converter for your dataset. You can find detailed instruction how to use converters [here][converters].
 148
 149 ```bash
 150 python3 convert_annotation.py converter --converter_specific_parameter --output_dir data/annotations
 151 ```
 152
 153 1. Choose one of *adapters* or write your own. Adapter converts raw output produced by framework to high level problem specific representation (e.g. *ClassificationPrediction*, *DetectionPrediction*, etc).
 154 1. Reproduce preprocessing, metrics and postprocessing from canonical paper.
 155 1. Create entry in config file and execute.
 156
 157 [sample-readme]: ./tools/accuracy_checker/sample/README.md
 158 [preprocessors]: ./tools/accuracy_checker/accuracy_checker/preprocessor/README.md
 159 [postprocessors]: ./tools/accuracy_checker/accuracy_checker/postprocessor/README.md
 160 [metrics]: ./tools/accuracy_checker/accuracy_checker/metrics/README.md
 161 [converters]: ./tools/accuracy_checker/accuracy_checker/annotation_converters/README.md
 162 [caffe-launcher-configuration]: ./tools/accuracy_checker/accuracy_checker/launcher/caffe_launcher_readme.md
 163 [dlsdk-launcher-configuration]: ./tools/accuracy_checker/accuracy_checker/launcher/dlsdk_launcher_readme.md