tools/accuracy_checker/accuracy_checker/annotation_converters/README.md

   1 # Annotation Converters
   2
   3 Annotation converter is a function which converts annotation file to suitable for metric evaluation format.
   4 Each annotation converter expects specific annotation file format or data structure, which depends on original dataset.
   5 If converter for your data format is not supported by Accuracy Checker, you can provide your own annotation converter.
   6 Each annotation converter has parameters available for configuration.
   7
   8 Process of conversion can be implemented in two ways:
   9 * via configuration file
  10 * via command line
  11
  12 ### Describing annotation conversion in configuration file.
  13
  14 Annotation conversion can be provided in `dataset` section your configuration file to convert annotation inplace before every evaluation.
  15 Each conversion configuration should contain `converter` field filled selected converter name and provide converter specific parameters (more details in supported converters section). All paths can be prefixed via command line with `-s, --source` argument.
  16
  17 You can additionally use optional parameters like:
  18 * `subsample_size` - Dataset subsample size. You can specify the number of ground truth objects or dataset ration in percentage. Please, be careful to use this option, some datasets does not support subsampling.
  19 * `annotation` - path to store converted annotation pickle file. You can use this parameter if you need to reuse converted annotation to avoid subsequent conversions.
  20 * `meta` - path to store mata information about converted annotation if it is provided.
  21
  22 Example of usage:
  23 ```yaml
  24    annotation_conversion:
  25      converter: sample
  26      data_dir: sample/sample_dataset
  27 ```
  28
  29
  30 ### Conversing process via command line.
  31
  32 The command line for annotation conversion looks like:
  33
  34 ```bash
  35 python3 convert_annotation.py <converter_name> <converter_specific parameters>
  36 ```
  37 All converter specific options should have format `--<parameter_name> <parameter_value>`
  38 You may refer to `-h, --help` to full list of command line options. Some optional arguments are:
  39
  40 * `-o, --output_dir` - directory to save converted annotation and meta info.
  41 * `-a, --annotation_name` - annotation file name.
  42 * `-m, --meta_name` - meta info file name.
  43
  44 ### Supported converters
  45
  46 Accuracy Checker supports following list of annotation converters and specific for them parameters:
  47 * `wider` - converts from Wider Face dataset to `DetectionAnnotation`.
  48   * `annotation_file` - path to txt file, which contains ground truth data in WiderFace dataset format.
  49   * `label_start` - specifies face label index in label map. Default value is 1. You can provide another value, if you want to use this dataset for separate label validation,
  50   in case when your network predicts other class for faces.
  51 * `sample` - converts annotation for SampleNet to `ClassificationAnnotation`.
  52   * `data_dir` - path to sample dataset root directory.
  53 * `voc07` - converts Pascal VOC 2007 annotation for detection task to `DetectionAnnotation`.
  54    * `image_set_file` - path to file with validation image list.
  55    * `annotations_dir` - path to directory with annotation files.
  56    * `images_dir` - path to directory with images related to devkit root (default JPEGImages).
  57   * `has_background` - allows convert dataset with/without adding background_label. Accepted values are True or False. (default is True)
  58 * `voc_segmentation` - converts Pascal VOC annotation for semantic segmentation task to `SegmentationAnnotation`.
  59   * `image_set_file` - path to file with validation image list.
  60   * `images_dir` - path to directory with images related to devkit root (default JPEGImages).
  61   * `mask_dir` - path to directory with ground truth segmentation masks related to devkit root (default SegmentationClass).
  62 * `mars` - converts MARS person reidentification dataset to `ReidentificationAnnotation`.
  63   * `data_dir` - path to data directory, where gallery (`bbox_test`) and `query` subdirectories are located.
  64 * `market1501` - converts Market1501 person reidentification dataset to `ReidentificationAnnotation`.
  65   * `data_dir` - path to data directory, where gallery (`bounding_box_test`) and `query` subdirectories are located.
  66 * `detection_opencv_storage` - converts detection annotation stored in Detection OpenCV storage format to `DetectionAnnotation`.
  67   * `annotation_file` - path to annotation in xml format.
  68   * `image_names_file` - path to txt file, which contains image name list for dataset.
  69   * `label_start` - specifies label index start in label map. Default value is 1. You can provide another value, if you want to use this dataset for separate label validation.
  70   * `background_label` - specifies which index will be used for background label. You can not provide this parameter if your dataset has not background label
  71 * `face_reid_pairwise` - converts Labeled Faces in the Wild dataset for face reidentification to `ReidentificationClassificationAnnotation`.
  72   * `pairs_file` - path to file with annotation positive and negative pairs.
  73   * `train_file` - path to file with annotation positive and negative pairs used for network train (optional parameter).
  74   * `landmarks_file` - path to file with facial landmarks coordinates for annotation images (optional parameter).
  75 * `landmarks_regression` - converts VGG Face 2 dataset for facial landmarks regression task to `FacialLandmarksAnnotation`.
  76   * `landmarks_csv_file` - path to csv file with coordinates of landmarks points.
  77   * `bbox_csv_file` - path to cvs file which contains bounding box coordinates for faces (optional parameter).
  78 * `cityscapes` - converts CityScapes Dataset to `SegmentationAnnotation`.
  79   * `dataset_root_dir` - path to dataset root.
  80   * `images_subfolder` - path from dataset root to directory with validation images (Optional, default `imgsFine/leftImg8bit/val`).
  81   * `masks_subfolder` - path from dataset root to directory with ground truth masks (Optional, `gtFine/val`).
  82   * `masks_suffix` - suffix for mask file names (Optional, default `_gtFine_labelTrainIds`).
  83   * `images_suffix` - suffix for image file names (Optional, default `_leftImg8bit`).
  84   * `use_full_label_map` - allows to use full label map with 33 classes instead train label map with 18 classes (Optional, default `False`).
  85 * `icdar15_detection` - converts ICDAR15 dataset for text detection  task to `TextDetectionAnnotation`.
  86   * `data_dir` - path to folder with annotations on txt format.
  87 * `icdar13_recognition` - converts ICDAR13 dataset for text recognition task to `CharecterRecognitionAnnotation`.
  88   * `annotation_file` - path to annotation file in txt format.
  89 * `mscoco_detection` - converts MS COCO dataset for object detection task to `DetectionAnnotation`.
  90   * `annotation_file` - path ot annotation file in json format.
  91   * `has_background` - allows convert dataset with/without adding background_label. Accepted values are True or False. (default is False).
  92   * `use_full_label_map` - allows to use original label map (with 91 object categories) from paper instead public available(80 categories).
  93 * `mscoco_keypoints` - converts MS COCO dataset for keypoints localization task to `PoseEstimationAnnotation`.
  94   * `annotation_file` - path ot annotation file in json format.
  95 * `imagenet` - convert ImageNet dataset for image classification task to `ClassificationAnnotation`.
  96   * `annotation_file` - path to annotation in txt format.
  97   * `labels_file` - path to file with word description of labels (synset words).
  98   * `has_background` - allows to add background label to original labels and convert dataset for 1001 classes instead 1000 (default value is False).