SB SDK 1.11
sb_t_par_model Struct Reference

Parameters of a model. More...

#include <sb.h>

Collaboration diagram for sb_t_par_model:

Data Fields

char name [SB_PAR_STRING_LEN]
 Model name. More...
 
sb_t_size obj_size
 Model size. More...
 
int enabled
 Enabling status of the model. More...
 
sb_t_par_levels levels
 Array of levels parameters for this model. More...
 
sb_t_par_perturbations perturbations
 Perturbations of the samples. More...
 
sb_t_rgba color
 Color of the defects. More...
 
sb_t_rgba color_opt
 Color of the optional defects. More...
 
sb_t_size obj_min_distance
 Minimum distance between two samples. More...
 
sb_t_size obj_stride_coarse
 Coarse search step. More...
 
sb_t_size obj_stride_fine
 Fine search step. More...
 
int num_occurrences
 Number of occurrences of the model that the function sb_project_get_res should export. More...
 
float defect_area_percentage
 Threshold percentage bad area of the sample to discard it as an occurrency. More...
 
float defect_area_threshold
 Threshold weight value for the bad area of the sample. More...
 

Detailed Description

Parameters of a model.

See also
Solution and projects management

Definition at line 9394 of file sb.h.

Field Documentation

◆ color

sb_t_rgba sb_t_par_model::color

Color of the defects.

The value it is not used by the SB library but only by the SB GUI to draw the defect.
Used only by Surface and Deep Surface projects.

See also
ROI management

Definition at line 9512 of file sb.h.

◆ color_opt

sb_t_rgba sb_t_par_model::color_opt

Color of the optional defects.

The value it is not used by the SB library but only by the SB GUI to draw the optional defect.
Used only by Surface and Deep Surface projects.

See also
ROI management

Definition at line 9520 of file sb.h.

◆ defect_area_percentage

float sb_t_par_model::defect_area_percentage

Threshold percentage bad area of the sample to discard it as an occurrency.

This parameter sets the minimum contiguous bad area to give a "bad" even if the total occurrency weight is positive.
The parameter is expresses as a percentage [0, 1.0] of the total sample area.
The admitted values are [0-1.0f].
Set the parameter to 0 to disable the control. The default value is 0.
Used only by Retina project.

See also
How to use Retina to sort good and bad samples

Definition at line 9610 of file sb.h.

◆ defect_area_threshold

float sb_t_par_model::defect_area_threshold

Threshold weight value for the bad area of the sample.

This parameter sets the threshold above which to consider a pixel as a "bad" value.
The default value is 0 and the range is [-1.0, 1.0].
The admitted values are [-1.0f-1.0f].
The default value is 0.
Used only by Retina project.

See also
How to use Retina to sort good and bad samples

Definition at line 9621 of file sb.h.

◆ enabled

int sb_t_par_model::enabled

Enabling status of the model.

You can enable/disable each model independently, both when you perform the training (only for Retina and Surface projects) and when you perform the analysis.
In the example Enable/disable a model in a project you can see how to enable/disable a model of a project. The possible values are:

Definition at line 9486 of file sb.h.

◆ levels

sb_t_par_levels sb_t_par_model::levels

Array of levels parameters for this model.

Defines the levels properties:

  • Retina projects: only the first level must be enabled and the scale factor must be 1. See the parameter see sb_t_sample::scale for more informations on how to maganed the scale with Retina.
  • Surface projects: more levels enabled simultaneously, each with its own classifier.
  • Deep Cortex and Deep Surface projects: the parameter is not used and the scale is automatically managed.
    See also
    Levels

Definition at line 9498 of file sb.h.

◆ name

char sb_t_par_model::name[SB_PAR_STRING_LEN]

Model name.

The string must be compliant to UTF-8 format.

Definition at line 9400 of file sb.h.

◆ num_occurrences

int sb_t_par_model::num_occurrences

Number of occurrences of the model that the function sb_project_get_res should export.

The possibile values of the parameter are the following:

Value Description
-1 All occurrences with positive weight and, if exist, the first negative are exported.
0 All occurrences with positive weight are exported
>0 num_occurrences starting from those with greater weight are exported, regardless of whether the weight is positive or negative. Of course, less than num_occurrences samples may be exported

The default value is zero.
Used only by Retina project.
The value must be greater equal than

Attention
Values different from 0 are not compatible with a speed boost value > 0.
If speed boost value > 0 it could be that samples with negative weight are not exported. So if you are interested in TRUE_NEGATIVE sample, set speed boost equal to 0.
See also
sb_t_par_sl::speed_boost

Definition at line 9598 of file sb.h.

◆ obj_min_distance

sb_t_size sb_t_par_model::obj_min_distance

Minimum distance between two samples.

The parameter allows you to set the minimum distance between two samples. In the event that two or more samples are closer, the sb_project_detection function chooses the one with the greatest weight and eliminates the others.
You can set the minimum distance in x and y separately.
The parameter is used differently by the sb_svl_run and sb_project_detection functions. See Different results in SVL and Test for more information.
The values width and height represent, respectively, the dimensions of the horizontal and vertical axes of an ellipse centered in the center of the sample. The ellipse defines a buffer zone in which the ellipse of no other sample must enter. If this condition is met then the sample is considered isolated, otherwise, the sample is considered close to other samples. The function sb_samples_distance, to find out if two samples are close or not, checks the intersections between their respective ellipses: if the intersection is zero, the samples are distant, otherwise the samples are considered close. The following image shows samples 1 and sample 2 of two different models in two conditions: on the left the samples are distant and the ellipses do not intersect, while on the right the ellipses intersect so as to consider the samples close.

Minimum distance between object, in green the ellipse that defines the buffer zone.

The sb_samples_distance function also takes into account the scale of the sample: the width and height are multiplied by the scale factor of the sample.
The value must be greater than sb_t_par_model::obj_stride_coarse.
Used only by Retina and Surface projects.

Warning
With Surface projects the parameter is readable only.
See also
sb_samples_distance
Different results in SVL and Test

Definition at line 9547 of file sb.h.

◆ obj_size

sb_t_size sb_t_par_model::obj_size

Model size.

Width and height, in pixel, of the rectangular window of the model.
Here are some rules for setting the model size correctly:

  1. Constraints
    The width and height of the model must be a multiple of 8 pixels in the range from SB_PAR_RETINA_OBJ_SIZE_MIN to SB_PAR_RETINA_OBJ_SIZE_MAX pixels.
  2. Border around the sample
    It is advisable to keep the size of the model about 8 pixels wider on each side than the inclusion rectangle of the object as shown in the image below. the SB GUI shows a viewfinder with an inner rectangle of 8 pixels, to facilitate the setting of the border of 8 pixels around the object. Generally the object should be inside this rectangle.
    How to correctly set the model size.
    In the example the object has a size of 40x64 pixels, then the model is 56x80 pixels. The border of 8 pixel is necessary so that the classifier also learns to describe the relationship between the object and the background. To understand this concept, the image below shows an example of recognition of a square. In the upper row the model is as large as the object so it happens that an occurrence is also found within the larger rectangle on the right. While in the lower row the model is larger than the object so that the classifier learns not only the object but also its relationship with the background. In this case, only the occurrence that is similar to the object is found. Theoretically it is not a mistake to set the size of the model as large as the object, but it is important to understand what the consequences will be on recognition.
    Upper row: the model is as large as the object, lower row: the model is bigger than the object
  3. Scale
    When an object is present in images with different scale factors, the size of the model must be set to the worst case, ie to the minimum size at which the object is still reliably recognizable. In other words, the resolution that still has enough information to recognize the object. For example if you want to recognize a person standing in an image the size of the model is 64x128 pixels.
    When labeling images and a sample has a different size than the model, you have two possibilities:
    • it has a size smaller than the minimum: you will place an optional sample. See the person in the center, with a pink gilet, in the image below.
    • it has a size larger than the model, you will place a sample with a scale factor greater than 1 and that includes the sample correctly, keeping in mind that a suitable background border is always left around the object. See the person on the left in the image below.
      Labeling with scale factor different than 1
      See also
      sb_t_sample::scale
      sb_t_sample::classify_mode
  4. Image with higher resolution
    It may happen that the images have a higher resolution than necessary so that the objects are too large in size, incompatible with the needs of classification. In this case we recommend creating the model with the correct size for the classifier (i.e. smaller) and then adding all the samples with a scale factor (greater than 1) in order to thicken the occurrences on the images. This has two benefits:

    • a model with a size that fits the classifier
    • a reduction in the computation times of the sb_project_detection function

    If the samples vary in size but are contained (variability <25%), we recommend choosing a medium scale factor and using it for all the samples. The classifier handles such small scale variations very well. Using more than one scale would unnecessarily increase calculation times.

    See also
    sb_t_sample::scale
  5. Dimension vs Classifier
    One must be careful not to increase the size of the model too much for two reasons:

    • too much detailed information does not allow the classifier to evaluate the object as a whole. To give an example it would be as if you were looking at a picture very closely: you see the details but you are not well able to get an idea of the whole picture. Here, the same phenomenon also happens to the classifier of SB library.
    • increasing the size increases the number of model parameters for which the classifier can overfit the data. See Under and Over fitting for more information.

    In any case the model does not categorize the data correctly, because of too many details and noise. An indicative maximum size limit of the model is 256x256 pixels. If you are passing it ask yourself if it is really necessary and maybe it is not better to reduce the size and increase the scale factor of the samples.

The default value is (64,64).
Used only by Retina and Surface projects.

Warning
With Surface projects the parameter is readable only.
See also
sb_t_sample::scale
How SB works

Definition at line 9470 of file sb.h.

◆ obj_stride_coarse

sb_t_size sb_t_par_model::obj_stride_coarse

Coarse search step.

Coarse scan step of the model window on the image.
The parameter has a big impact on the analysis time, the lower the value the greater the analysis time. But the higher the value the greater the probability of having FALSE NEGATIVE samples.
A good rule of thumb for setting the value is: the larger the model size, the larger the parameter value can be.
This value must be greater or equal than sb_t_par_model.obj_stride_fine.
The admitted values are powers of 2, in the range from SB_PAR_RETINA_OBJ_STRIDE_COARSE_MIN to SB_PAR_RETINA_OBJ_STRIDE_COARSE_MAX pixels.
The default value is (8,8).
Used only by Retina and Surface projects.

Warning
With Surface projects the parameter is readable only.
See also
How SB works

Definition at line 9562 of file sb.h.

◆ obj_stride_fine

sb_t_size sb_t_par_model::obj_stride_fine

Fine search step.

Fine scan step of the model window on the image.
The parameter has a big impact on the analysis time, the lower the value the greater the analysis time. But the higher the value the greater the probability of having FALSE NEGATIVE samples.
A good rule of thumb for setting the value is: the larger the model size, the larger the parameter value can be.
This value must be less or equal than sb_t_par_model.obj_stride_coarse.
The permitted values are between SB_PAR_RETINA_OBJ_STRIDE_FINE_MIN and SB_PAR_RETINA_OBJ_STRIDE_FINE_MAX, but the admitted values are only 1,2,4,8.
The default value is (4,4).
Used only by Retina project.

See also
How SB works

Definition at line 9576 of file sb.h.

◆ perturbations

sb_t_par_perturbations sb_t_par_model::perturbations

Perturbations of the samples.

See also
Shallow Learning Perturbations

Definition at line 9504 of file sb.h.


The documentation for this struct was generated from the following file: