Using the Configuration File - 1.4.1 English

Vitis AI Library User Guide (UG1354)

Document ID
UG1354
Release Date
2021-12-11
Version
1.4.1 English

The Vitis™ AI Library provides a way to read model parameters by reading the configuration file. It facilitates uniform configuration management of model parameters. The configuration file is located in /usr/share/vitis_ai_library/models/[model_name]/[model_name].prototxt.

model
{
  name: "yolov3_voc"
  kernel {
     name: "yolov3_voc"
     mean: 0.0
     mean: 0.0
     mean: 0.0
     scale: 0.00390625
     scale: 0.00390625
     scale: 0.00390625
  }
  model_type : YOLOv3
  yolo_v3_param {
    …
  }
  is_tf: false
}
Table 1. Compiling Model and Kernel Parameters
Model/Kernel Parameter Type Description
model name This name should be same as the ${MODEL_NAME}.
model_type This type should depend on which type of model you used.
kernel name

This name should be filled as the result of your DNNC compile. Sometimes, its name may have an extra postfix “_0”.Here, fill the name with such postfix.

(For example: inception_v1_0)

mean Normally there are three lines. Each of them corresponding to the mean-value of “BRG”, which are pre-defined in the model.
scale Normally there are three lines. Each of them corresponds to the RGB-normalized scale. If the model had no scale in training stage, here should fill with one.
is_tf Bool type. If your model is trained by TensorFlow, please add this and set with “true”. It could be blank in the prototxt or set as “false” when the model is Caffe.

yolo_v3_param

  model_type : YOLOv3
  yolo_v3_param {
    num_classes: 20
    anchorCnt: 3
    layer_name: "59"
    layer_name: "67"
    layer_name: "75"
    conf_threshold: 0.3
    nms_threshold: 0.45
    biases: 10
    biases: 13
    biases: 16
    biases: 30
    biases: 33
    biases: 23
    biases: 30
    biases: 61
    biases: 62
    biases: 45
    biases: 59
    biases: 119
    biases: 116
    biases: 90
    biases: 156
    biases: 198
    biases: 373
    biases: 326
    test_mAP: false
  }

The parameters for the YOLOv3 model are listed in the following table. You can modify them as your model requires.

Table 2. YOLOv3 Model Parameters
Parameter Type Description
num_classes The actual number of the model’s detection categories
anchorCnt The number of this model’s anchor
layer_name The kernel's output layer names. When your model's output is more than one, you need to use this parameter to ensure a certain sequence. Such name should be same as these in kernel's. (If you fill it as an invalid name, the model creator will use the kernel default order.)
conf_threshold The threshold of the boxes’ confidence, which can be modified to fit your practical application
nms_threshold The threshold of NMS
biases These parameters are the same as the model’s. Each bias need writes in a separate line. (Biases amount) = anchorCnt * (output-node amount) * 2. Set correct lines in the prototxt.
test_mAP If your model was trained with letterbox and you want to test its mAP, set this as “true”. Normally, it is “false” for executing much faster.

SSD_param

model_type : SSD
ssd_param :
{
    num_classes : 4
    nms_threshold : 0.4
    conf_threshold : 0.0
    conf_threshold : 0.6
    conf_threshold : 0.4
    conf_threshold : 0.3
    keep_top_k : 200
    top_k : 400
    prior_box_param {
    layer_width : 60,
    layer_height: 45,
    variances: 0.1
    variances: 0.1
    variances: 0.2
    variances: 0.2
    min_sizes: 21.0
    max_sizes: 45.0
    aspect_ratios: 2.0
    offset: 0.5
    step_width: 8.0
    step_height: 8.0
    flip: true
    clip: false
    }
}

Following are the SSD parameters. The parameters of SSD-model include all kinds of threshold and PriorBox requirements. You can reference your SSD deploy.prototxt to fill them.

Table 3. SSD Model Parameters
Parameter Type Description
num_classes The actual number of the model’s detection categories
anchorCnt The number of this model’s anchor
conf_threshold

The threshold of the boxes’ confidence. Each category can have a different threshold, but its amount must be equal to num_classes.

nms_threshold The threshold of NMS
biases These parameters are same as the model’s. Each bias need writes in a separate line. (Biases amount) = anchorCnt * (output-node amount) * 2. Set correct lines in the prototxt.
test_mAP If your model was trained with letterbox and you want to test its mAP, set this as “true”. Normally it is “false” for executing much faster
keep_top_k Each category of detection objects’ top K boxes
top_k All the detection object’s top K boxes, except the background (the first category)
prior_box_param

There is more than one PriorBox, which could be found in the original model (deploy.prototxt) for corresponding each different scale. These PriorBoxes should oppose each other.

Table 4. PriorBox Parameters
Parameter Type Description
layer_width/layer_height The input width/height of this layer. Such numbers can be computed from the net structure.

ariances

These numbers are used for boxes regression, only to fill them as the original model. There should be four variances.
min_sizes/max_size Filled as the “deploy.prototxt”, but each number should be written in a separate line.
aspect_ratios The ratio’s number (each one should be written in a separate line). Default has 1.0 as its first ratio. If you set a new number here, there will be two ratios created when the opposite is true. One is a filled number; other is its reciprocal. For example, this parameter has only one set element, “ratios: 2.0”. The ratio vector has three numbers: 1.0, 2.0. 0.5
offset Normally, the PriorBox is created by each central point of the feature map, so that the offset is 0.5.
step_width/step_height Copy from the original file. If there are no such numbers there, you can use the following formula to compute them:

step_width = img_width ÷ layer_width

step_height = img_height ÷ layer_height

offset Normally, PriorBox is created by each central point of the feature map, so that the offset is 0.5.
flip Control whether to rotate the PriorBox and change the ratio of length/width.
clip Set as "false". If true, it will let the detection boxes’ coordinates keep at [0, 1].

Example Code

The following is the example code.

Mat img = cv::imread(argv[1]);
auto yolo = vitis::ai::YOLOv3::create("yolov3_voc",   true);
auto results   = yolo->run(img);
for(auto   &box : results.bboxes){
    int label = box.label;
    float xmin = box.x * img.cols + 1;
    float ymin = box.y * img.rows + 1;
    float xmax = xmin + box.width * img.cols;
    float ymax = ymin + box.height * img.rows;
    if(xmin < 0.) xmin = 1.;
    if(ymin < 0.) ymin = 1.;
    if(xmax > img.cols) xmax = img.cols;
    if(ymax > img.rows) ymax = img.rows;
    float confidence = box.score;
    cout << "RESULT: "   << label <<   "\t" << xmin << "\t"   << ymin << "\t"
            << xmax <<   "\t"   << ymax << "\t" << confidence   << "\n";
    rectangle(img, Point(xmin, ymin), Point(xmax, ymax), Scalar(0, 255, 0), 1, 1, 0);
}
imshow("", img);
waitKey(0);

To create the YOLOv3 object, use create.

static std::unique_ptr<YOLOv3> create(const std::string& model_name, bool need_mean_scale_process = true);
Note: The model_name is same as the prototxt. For more details about the example, refer to ~/Vitis-AI/Vitis-AI-Library/yolov3/test/test_yolov3.cpp.