get_dl_model_param — Return the parameters of a deep learning model.
get_dl_model_param( : : DLModelHandle, GenParamName : GenParamValue)
get_dl_model_param returns the parameter values
GenParamValue of GenParamName for the deep learning
model DLModelHandle.
For a deep learning model, parameters GenParamName can be set using
set_dl_model_param or create_dl_model_detection, depending
on the parameter and the model type.
With this operator, get_dl_model_param, you can retrieve
the parameter values GenParamValue.
Below we give an overview of the different parameters and an explanation,
except of those you can only set. For latter ones, please see the
documentation of corresponding operator.
GenParamName |
Object Detection | Semantic Segmentation | |||
|---|---|---|---|---|---|
| create | set | get | set | get | |
| 'batch_size' | n | y | y | y | y |
| 'class_ids' | y | y | y | y | y |
| 'gpu' | n | y | y | y | y |
| 'image_dimensions' | y | n | y | y | y |
| 'image_height' | y | n | y | y | y |
| 'image_width' | y | n | y | y | y |
| 'image_num_channels' | y | n | y | y | y |
| 'image_range_max' | n | n | y | y | y |
| 'image_range_min' | n | n | y | y | y |
| 'learning_rate' | n | y | y | y | y |
| 'momentum' | n | y | y | y | y |
'num_classes' (NumClasses) |
y | n | y | n | y |
| 'runtime' | n | y | y | y | y |
| 'runtime_init' | n | y | n | y | n |
| 'type' | n | n | y | n | y |
| 'weight_prior' | n | y | y | y | y |
| 'aspect_ratios' | y | n | y | - | - |
'backbone' (Backbone) |
y | n | y | - | - |
| 'capacity' | y | n | y | - | - |
| 'class_weights' | y | n | y | - | - |
| 'max_level' | y | n | y | - | - |
| 'min_level' | y | n | y | - | - |
| 'max_num_detections' | y | y | y | - | - |
| 'max_overlap' | y | y | y | - | - |
| 'max_overlap_class_agnostic' | y | y | y | - | - |
| 'min_confidence' | y | y | y | - | - |
| 'num_subscales' | y | n | y | - | - |
| 'ignore_class_ids' | - | - | - | y | y |
Thereby, 'set' denotes set_dl_model_param, 'get'
get_dl_model_param, and 'create'
create_dl_model_detection.
We note 'y' if the operator can be used for this parameter and model,
'n' if not, and '-' if the parameter is not applicable for this type of
model.
Certain parameters are set as non-optional parameters, the corresponding
notation is given in brackets.
In the following we list and explain the parameters GenParamName
for which you can retrieve their value using this operator,
get_dl_model_param.
They are sorted according to the model type.
Note, for models of 'type'='segmentation' the default
values depend on the specific network and therefore have to be retrieved.
Number of input images in a batch and thus the number of images that
are processed simultaneously in a single iteration of the training
and inference, respectively.
Please refer to train_dl_model_batch for further details.
Unique IDs of the classes the model shall distinguish. Thereby, you can set any integer within the interval as class id value. The tuple is of length 'num_classes'.
We stress out the slightly different meanings and restrictions depending on the model type:
Only the classes of the objects to be detected are included and therewith no background class.
Default: 'class_ids' = '[0,...,num_classes-1]'
Every class used for training has to be included and therewith also the class ID of the 'background' class. Therefore, for such a model the tuple has a minimal length of 2.
Identifier of the GPU where the training and inference operators
(train_dl_model_batch and apply_dl_model) are
executed.
Per default, the first available GPU is used.
get_system with 'cuda_devices' can be used to
retrieve a list of available GPUs. Pass the index in this list to
'gpu'.
Default: 'gpu' = '0'
Tuple containing the input image dimensions 'image_width', 'image_height', and number of channels 'image_num_channels'.
The respective default values and possible value ranges depend on the model and model type. Please see the individual dimension parameter description for more details.
Height and width of the input images, respectively, that the network will process.
This parameter can attain different values depending on the model type:
The network architectures allow changes of the image dimensions.
But the image lengths are halved for every level, thats why the
dimensions 'image_width' and 'image_height'
need to be an integer multiple of
.
depends on the 'backbone'
and the parameter 'max_level', see
create_dl_model_detection for further information.
Default: 'image_height' = '640', 'image_width' = '640'
The network architectures allow changes of the image dimensions.
The default and minimal values are given by the network, see
read_dl_model.
Number of channels of the input images the network will process.
The default value is given by the network, see
read_dl_model and create_dl_model_detection.
Any number of input image channels is possible.
If number of channels is changed to a value >1, the weights of the first layers after the input image layer will be initialized with random values. Note, in this case more data for the retraining is needed. If the number of channels is changed to 1, the weights of the concerned layers are fused.
Default: 'image_num_channels' = '3'
Maximum and minimum gray value of the input images, respectively, the network will process.
The default values are given by the network, see
read_dl_model and create_dl_model_detection.
Value of the factor determining the gradient influence during
training.
Please refer to train_dl_model_batch for further details.
The default values depend on the model.
When updating the weights of the network,
the hyperparameter 'momentum' specifies to which extent
previous updating vectors will be added to the current updating
vector.
Please refer to train_dl_model_batch for further details.
The default value is given by the model.
Number of distinct classes that the model is able to distinguish for its predictions.
This parameter differs between the models.
For a model of 'type'='detection'
the 'background' class is not included, as background is not
predicted by a detector. Also, this parameter is set
as NumClasses over create_dl_model_detection
and 'class_ids' always needs to have a number of entries
equal 'num_classes'.
But a model of 'type'='segmentation' does predict
background and therefore in this case the 'background' class is
included in 'num_classes'. For these models,
'num_classes' is determined implicitly by the length of
'class_ids'.
Defines the device on which the operators will be executed. Default: 'runtime' = 'gpu'
The operator apply_dl_model will be executed on the
CPU, whereas the operator train_dl_model_batch is not
executable.
In case the GPU has been used before, CPU memory is initialized, and if necessary values stored on the GPU memory are moved to the CPU memory.
The 'cpu' runtime uses OpenMP for the parallelization of
apply_dl_model. Per default, all threads available to
the OpenMP runtime are used. Use the thread specific
set_system parameter 'tsp_thread_num' to specify
the number of threads to use.
The GPU memory is initialized.
The operators apply_dl_model and
train_dl_model_batch will be executed on the GPU.
For the specific requirements please refer to the HALCON
“Installation Guide”.
This parameter returns the model type. The following types are distinguished: 'detection' and 'segmentation'.
Regularization parameter used for
the regularization of the loss function.
For a detailed description of the regularization term we refer to
train_dl_model_batch.
Simply put: Regularization favors simpler models that are less likely
to learn noise in the data and generalize better. Per default no
regularization is used, i.e. 'weight_prior' is set to
0.0. In case the classifier overfits the data, it is strongly
recommended to try different values for the parameter
'weight_prior' to improve the generalization properties of
the neural network. Choosing its value is a trade-off between the
models ability to generalize, overfitting, and underfitting.
If is too small, the model might overfit, if its too
large the model might loose its ability to fit the data, because all
weights are effectively zero. For finding an ideal value for
, we recommend a cross-validation, i.e. to perform the
training for a range of values and choose the value that results in
the best validation error. For typical applications, we recommend
testing the values for 'weight_prior' on a logarithmic scale
between . If the training
takes a very long time, one might consider performing the
hyperparameter optimization on a reduced amount of data.
Default: 'weight_prior' = '0.0'
The parameter 'aspect_ratios' determines the aspect ratio height to width of the reference bounding boxes. E.g., the ratio 2 gives a narrow and 0.5 a broad initial reference box. The size of the reference bounding box is affected by the parameter 'num_subscales' and with its explanation we give the formula for the sizes and lengths of the generated reference bounding boxes. See the chapter Deep Learning / Object Detection for more explanations to bounding boxes.
Default: 'aspect_ratios' = '[1.0, 2.0, 0.5]'
You can set a tuple of values. A higher number of aspect ratios increases the number of proposed reference bounding boxes which might lead to a better localization but also increases the runtime and memory-consumption.
The parameter 'backbone' is the name (together with the path)
of the backbone network which is used to create the model. A list of
the delivered backbone networks can be found under
create_dl_model_detection.
This parameter roughly determines the number of parameters (or filter weights) in the deeper sections of the object detection network (after the backbone). Its possible values are 'high', 'medium', and 'low'.
It can be used to trade off between detection performance and speed. For simpler object detection tasks, the 'low' or 'medium' settings may be sufficient to achieve the same detection performance as with 'high'.
Default: 'capacity' = 'high'
The parameter 'class_weights' is a tuple of class specific weighting factors for the loss. Thereby, these factors are sorted according to the classes in the tuple 'class_ids'. One exception is the case where all classes have the same value 'class_weights', in this case you will get the value as a single number.
Default: 'class_weights' = '0.25' (for each class).
These parameters determine on which levels the additional networks are attached on the feature pyramid. We refer to the chapter Deep Learning / Object Detection for further explanations to the feature pyramid and the attached networks.
From these ('max_level' - 'min_level' + 1) networks all predictions with a minimum confidence value are kept as long they do not strongly overlap (see 'min_confidence' and 'max_overlap').
The level declares how often the size of the feature map already has been scaled down. Thus, level 0 corresponds to the feature maps with size of the input image, level 1 to feature maps subscaled once, and so on. As a consequence, smaller objects are detected in the lower levels, whereas larger objects are detected in higher levels.
The value for 'min_level' needs to be at least 2.
If 'max_level' is larger than the number of levels the backbone can provide, the backbone is extended with additional (randomly initialized) convolutional layers in order to generate deeper levels. Further, 'max_level' may have an influence on the minimal input image size.
Note, for small input image dimensions, high levels might not be meaningful, as the feature maps could already be too small to contain meaningful information.
A higher number of used levels might increases the runtime and memory-consumption, whereby especially lower levels carry weight.
Default: 'max_level' = '6', 'min_level' = '2'
This parameter determines the maximum number of detections (bounding boxes) per image proposed from the network.
Default: 'max_num_detections' = '100'
The maximum allowed intersection over union (IoU) for two predicted bounding boxes of the same class. Or, vice-versa, when two bounding boxes are classified into the same class and have an IoU higher than 'max_overlap', the one with lower confidence value gets suppressed. We refer to the chapter Deep Learning / Object Detection for further explanations to the IoU.
Default: 'max_overlap' = '0.5'
The maximum allowed intersection over union (IoU) for two predicted bounding boxes independently of their predicted classes. Or, vice-versa, when two bounding boxes have an IoU higher than 'max_overlap_class_agnostic', the one with lower confidence value gets suppressed. As default, 'max_overlap_class_agnostic' is set to 1.0, hence class agnostic bounding box suppression has no influence.
Default: 'max_overlap_class_agnostic' = '1.0'
This parameter determines the minimum confidence, when the image part
within the bounding box is classified in order to keep the proposed
bounding box.
This means, when apply_dl_model is called, all output bounding
boxes with a confidence value smaller than 'min_confidence'
are suppressed.
Default: 'min_confidence' = '0.5'
This parameter determines the number of reference bounding boxes which are generated at different scales for each given aspect ratio.
In HALCON for every pixel of every feature map of the feature pyramid a reference bounding box is proposed. Thereby the parameter 'aspect_ratios' affects the form and 'num_subscales' affects the size. In this way 'aspect_ratios' times 'num_subscales' reference bounding boxes are generated for every pixel mentioned before. See the chapter Deep Learning / Object Detection for more explanations to bounding boxes. An example is shown in the figure below.
A reference bounding box of level has by default a size of in the input image, whereby the paramter has the value . With the parameter 'num_subscales' additional reference bounding boxes can be generated, which converge in size to the smallest reference bounding box of the level . More precisely, these reference bounding boxes of level have in the input image the size where . For subscale , this results on level in a reference bounding box of height and width equal where is the ratio of this reference bounding box (see 'aspect_ratios').
A larger number of subscales increases the number of reference bounding boxes and will therefore increase the runtime and memory-consumption.
Default: 'num_subscales' = '3'
With this parameter you can declare one or multiple classes as 'ignore' classes, see the chapter Deep Learning / Semantic Segmentation for further information. These classes are declared over their ID (integers).
Note, you can not set a class ID in 'ignore_class_ids' and 'class_ids' simultaneously.
DLModelHandle (input_control) dl_model → (handle)
Handle of the deep learning model.
GenParamName (input_control) attribute.name → (string)
Name of the generic parameter.
Default value: 'batch_size'
List of values: 'aspect_ratios', 'backbone', 'batch_size', 'capacity', 'class_ids', 'ignore_class_ids', 'image_dimensions', 'image_height', 'image_num_channels', 'image_range_max', 'image_range_min', 'image_width', 'learning_rate', 'max_level', 'max_num_detections', 'max_overlap', 'max_overlap_class_agnostic', 'min_confidence', 'min_level', 'momentum', 'num_classes', 'num_subscales', 'runtime', 'runtime_init', 'type', 'weight_prior'
GenParamValue (output_control) attribute.name(-array) → (integer / string / real)
Value of the generic parameter.
If the parameters are valid, the operator get_dl_model_param
returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.
read_dl_model,
set_dl_model_param
set_dl_model_param,
apply_dl_model,
train_dl_model_batch
Deep Learning Inference