SB SDK 1.11
SVL - Training

Collection of functions to manage SVL or training of Retina and Surface. More...

Collaboration diagram for SVL - Training:

Modules

 Features defines
 

Data Structures

struct  sb_t_svl_pre_elaboration
 Contains the results of the image pre-processing. More...
 
struct  sb_t_svl_dl_par_network
 Deep Learning modules parameters. More...
 
struct  sb_t_svl_dl_par_perturbation
 Describes the perturbation of the image / defect. More...
 
struct  sb_t_svl_dl_par
 SVL parameters to configure the Deep Learning training. More...
 
struct  sb_t_svl_sl_par
 SVL parameters that configure the Shallow Learning training. More...
 
struct  sb_t_devices_par
 Property of computational devices. More...
 
struct  sb_t_svl_par
 SVL parameters. More...
 
struct  sb_t_svl_err
 Contains information regarding the error of the SVL. More...
 
struct  sb_t_svl_res_image
 Defines the results of the elaboration of the SVL of an image. More...
 
struct  sb_t_svl_res_images
 Defines the results of the elaboration of the SVL images. More...
 
struct  sb_t_svl_res_epoch
 Results of a training epoch. More...
 
struct  sb_t_svl_res_epochs
 Results of the training epochs. More...
 
struct  sb_t_svl_res_level
 Results of the SVL of a level per model. More...
 
struct  sb_t_svl_res_levels
 Results of the SVL of a levels processed. More...
 
struct  sb_t_svl_res_model
 Results of the SVL of a specific model. More...
 
struct  sb_t_svl_res_models
 Results of the SVL of a models processed. More...
 
struct  sb_t_svl_res
 Defines the results of SVL. More...
 

Macros

#define SB_PAR_FEATURES_NAMES_LEN   256
 Maximum lenght, in byte, of the features names string.
 
#define SB_DL_WEIGHTS_EXT   "weights"
 Extension of the Squeezebrains pre-trained network weights file.
 
#define SB_DEVICES_MAX_NUMBER   4
 Maximum number of computational devices managed by the sb library. More...
 
#define SB_CLS_0   "cls0"
 classificator type 0
 
#define SB_CLS_1   "cls1"
 classificator type 1
 
#define SB_FEATURES
 < List of all the features separated by SB_DELIMITER
 
#define SB_SVL_STEP_INITIALIZATION   "initializing data for svl"
 SVL step: initialization.
 
#define SB_SVL_STEP_SEARCHING_RECIPE   "choosing recipe"
 SVL step: choosing recipe.
 
#define SB_SVL_STEP_TRAINING_RECIPE   "training recipe"
 SVL step: training recipe.
 
#define SB_SVL_STEP_FINALIZATION   "finalization of svl"
 SVL step: finalization of svl.
 
#define SB_SVL_STEP_FINISHED   "svl has finished"
 SVL step: svl has finished.
 

Typedefs

typedef sb_t_err(* sb_fp_svl_pre_elaboration) (const SB_HANDLE image_info, void *const user_data, const char *const image_file, int image_index, sb_t_svl_pre_elaboration *const pre_elaboration)
 Definition of the callback for image pre elaboration. More...
 
typedef sb_t_err(* sb_fp_svl_progress) (void *const user_data, sb_t_svl_res *res, int force)
 Definition of the callback for the working progress. More...
 
typedef sb_t_err(* sb_fp_svl_command) (void *const user_data, sb_t_svl_res *res, sb_t_svl_command *const command, const char *const msg)
 Definition of the callback that the SVL calls when it needs to know how to continue. More...
 

Enumerations

enum  sb_t_svl_command {
  SB_SVL_COMMAND_STOP = 0 , SB_SVL_COMMAND_CONTINUE , SB_SVL_COMMAND_ABORT , SB_SVL_COMMAND_CONTINUE_NO_RESET ,
  SB_SVL_COMMAND_NEXT_STEP
}
 Enumerates the actions that SVL has to do after a stop. More...
 
enum  sb_t_svl_par_optimization_mode { SB_SVL_PAR_OPTIMIZATION_TIME_SLOW = 0 , SB_SVL_PAR_OPTIMIZATION_TIME_MEDIUM , SB_SVL_PAR_OPTIMIZATION_TIME_FAST , SB_SVL_PAR_OPTIMIZATION_USE_SELECTED }
 Describes the optimization mode of SVL. More...
 
enum  sb_t_network_type {
}
 Deep learning network types. More...
 
enum  sb_t_perturbation_mode { SB_PERTURBATION_MODE_ONLINE = 0 , SB_PERTURBATION_MODE_OFFLINE , SB_PERTURBATION_MODE_BOTH }
 Enumerates the mode of the perturbations. More...
 
enum  sb_t_perturbation_type { SB_PERTURBATION_TYPE_IMAGE = 0 , SB_PERTURBATION_TYPE_DEFECTS , SB_PERTURBATION_TYPE_BOTH }
 Enumerates the range of application of the perturbations. More...
 
enum  sb_t_svl_stop_reason {
  SB_SVL_STOP_NONE = 0 , SB_SVL_STOP_CONFLICT , SB_SVL_STOP_USER_REQUEST , SB_SVL_STOP_MEMORY ,
  SB_SVL_STOP_RESET_MANDATORY , SB_SVL_STOP_RESET_OPTIONAL , SB_SVL_STOP_WARNING
}
 Enumerates the reasons why SVL is terminated or why the callback sb_t_svl_par::fp_command has been called. More...
 

Functions

const char * sb_svl_command_format (sb_t_svl_command command)
 Returns the string of the SVL command. More...
 
const char * sb_svl_par_optimization_mode_format (sb_t_svl_par_optimization_mode mode)
 Returns the string of the SVL optimization mode. More...
 
const char * sb_network_type_format (sb_t_network_type type)
 Returns the string of the network type. More...
 
const char * sb_perturbation_mode_format (sb_t_perturbation_mode mode)
 Returns the string of the Deep Learning SVL image perturbation mode. More...
 
const char * sb_perturbation_type_format (sb_t_perturbation_type type)
 Returns the string of the Deep Learning SVL image perturbation type. More...
 
const char * sb_feature_description (const char *const feature)
 Returns a string with a brief description of a feature. More...
 
sb_t_err sb_svl_run (SB_HANDLE handle)
 Runs the SVL. More...
 
sb_t_err sb_svl_reset (SB_HANDLE handle)
 Resets the history of previous executions of the SVL. More...
 
sb_t_err sb_svl_stop_request (SB_HANDLE handle)
 Sends a request to the SVL for stop. More...
 
sb_t_err sb_svl_get_res (SB_HANDLE handle, sb_t_svl_res **const res)
 Retrieves the results of SVL. More...
 
sb_t_err sb_svl_destroy_res (sb_t_svl_res **const res)
 Destroys the structure of the results of SVL. More...
 
sb_t_err sb_svl_clone_res (sb_t_svl_res **const dst, const sb_t_svl_res *const src)
 Copies the structure of the results of SVL. More...
 

Detailed Description

Collection of functions to manage SVL or training of Retina and Surface.

See SVL - training for more information.

Macro Definition Documentation

◆ SB_DEVICES_MAX_NUMBER

#define SB_DEVICES_MAX_NUMBER   4

Maximum number of computational devices managed by the sb library.

See also
sb_t_devices_par

Definition at line 9158 of file sb.h.

Typedef Documentation

◆ sb_fp_svl_command

typedef sb_t_err(* sb_fp_svl_command) (void *const user_data, sb_t_svl_res *res, sb_t_svl_command *const command, const char *const msg)

Definition of the callback that the SVL calls when it needs to know how to continue.

Attention
You must destroy the parameter res with sb_svl_destroy_res function before exit the callback
Parameters
[in,out]user_dataPointer to the user data.
[in]rescurrent results of the SVL.
[out]commandPointer to the SVL command. The user can decided what SVL has to do.
[in]msgMessage for the user.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL Callbacks
sb_svl_destroy_res

Definition at line 8715 of file sb.h.

◆ sb_fp_svl_pre_elaboration

typedef sb_t_err(* sb_fp_svl_pre_elaboration) (const SB_HANDLE image_info, void *const user_data, const char *const image_file, int image_index, sb_t_svl_pre_elaboration *const pre_elaboration)

Definition of the callback for image pre elaboration.

Parameters
[in]image_infoSqueezebrains image info handle.
[in,out]user_dataPointer to the user data.
[in]image_fileImage file name.
[in]image_indexIndex of the image.
[out]pre_elaborationPointer to the structure where the user implements the pre-elaboration of the images and set the ROI
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL Callbacks

Definition at line 8690 of file sb.h.

◆ sb_fp_svl_progress

typedef sb_t_err(* sb_fp_svl_progress) (void *const user_data, sb_t_svl_res *res, int force)

Definition of the callback for the working progress.

Attention
You must destroy the parameter res with sb_svl_destroy_res function before exit the callback
Parameters
[in,out]user_dataPointer to the user data.
[in]rescurrent results of the SVL.
[in]forceIf different that 0 means that in the results something is changed.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL Callbacks
sb_svl_destroy_res

Definition at line 8702 of file sb.h.

Enumeration Type Documentation

◆ sb_t_network_type

Deep learning network types.

Enumerator
SB_NETWORK_TYPE_EFFICIENTNET_B0 

Deep Learning EfficientNet b0.

Note
The value sb_t_svl_dl_par_network.input_size must be (224,224)
SB_NETWORK_TYPE_EFFICIENTNET_B1 

Deep Learning EfficientNet b1.

Note
The value sb_t_svl_dl_par_network.input_size must be (240,240)
SB_NETWORK_TYPE_EFFICIENTNET_B2 

Deep Learning EfficientNet b2.

Note
The value sb_t_svl_dl_par_network.input_size must be (260,260)
SB_NETWORK_TYPE_SDINET0_331 

Deep Learning Surface Defects Inspection Network 0 with input size 331x331.

Note
The value sb_t_svl_dl_par_network.input_size must be (331,331)
SB_NETWORK_TYPE_ICNET0_64 

Deep Learning Image Classification Network 0 with input size 64x64.

Note
The value sb_t_svl_dl_par_network.input_size must be (64,64)
SB_NETWORK_TYPE_ICNET0_128 

Deep Learning Image Classification Network 0 with input size 128x128.

Note
The value sb_t_svl_dl_par_network.input_size must be (128,128)

Definition at line 8720 of file sb.h.

◆ sb_t_perturbation_mode

Enumerates the mode of the perturbations.

See also
Deep Learning Perturbations
Enumerator
SB_PERTURBATION_MODE_ONLINE 

Online perturbation.

Images are perturbated at the beginning of each epoch in a repeatable pseudo randomic way, different for each epoch

SB_PERTURBATION_MODE_OFFLINE 

Offline perturbation.

the learning images set is increased by perturbating the images before the training starts.

SB_PERTURBATION_MODE_BOTH 

Both online and offline perturbations.

Definition at line 8824 of file sb.h.

◆ sb_t_perturbation_type

Enumerates the range of application of the perturbations.

See also
Deep Learning Perturbations
Enumerator
SB_PERTURBATION_TYPE_IMAGE 

The whole image is perturbated.

SB_PERTURBATION_TYPE_DEFECTS 

Only the defect area is perturbated.

SB_PERTURBATION_TYPE_BOTH 

Both image and defects perturbation type.

Definition at line 8857 of file sb.h.

◆ sb_t_svl_command

Enumerates the actions that SVL has to do after a stop.

On a stop the sb_svl_run calls the callback sb_t_svl_par::fp_command.
The values are 32 bits both for 32 and 64 bits library version.

See also
SVL Callbacks
sb_t_svl_par::fp_command
sb_t_svl_stop_reason
Enumerator
SB_SVL_COMMAND_STOP 

The SVL stops and exits, applying the training to the module.

After the sb_svl_run finished, you can call sb_project_save to save the results.

SB_SVL_COMMAND_CONTINUE 

The SVL continues and, if necessary, resets the training.

SB_SVL_COMMAND_ABORT 

The SVL stops and exits, without applying the training reached to the module.

After the sb_svl_run finished, You can not call sb_project_save to save the results.

SB_SVL_COMMAND_CONTINUE_NO_RESET 

The SVL continues without reset.

SB_SVL_COMMAND_NEXT_STEP 

The SVL go to next step.

Definition at line 8603 of file sb.h.

◆ sb_t_svl_par_optimization_mode

Describes the optimization mode of SVL.

The values are 32 bits both for 32 and 64 bits library version.

See also
License configurations
SVL - training
Features
sb_t_svl_sl_par::optimization_mode
Enumerator
SB_SVL_PAR_OPTIMIZATION_TIME_SLOW 

SVL promotes accuracy with respect to execution time.

  • Retina: it chooses the best classificator and the most significant features indipendently for each model.
  • Surface: SVL chooses the best classificator and the most significant features indipendently for each model. At least three features are chosen.
SB_SVL_PAR_OPTIMIZATION_TIME_MEDIUM 
  • Retina: SVL chooses the best classificator and the best feature for each model, only one feature for each model.
  • Surface: SVL chooses the best classificator and the most significant features indipendently for each model. At least two features are chosen.
SB_SVL_PAR_OPTIMIZATION_TIME_FAST 
  • Retina: SVL finds the best classificator and the best feature and sets them for all model.
  • Surface: SVL chooses the best classificator and the most significant features indipendently for each model. At least one feature is chosen.
SB_SVL_PAR_OPTIMIZATION_USE_SELECTED 

SVL will use the features selected by the user and which are compatible with the data set. The user can select the features with the parameter sb_t_svl_sl_par.features.

Definition at line 8646 of file sb.h.

◆ sb_t_svl_stop_reason

Enumerates the reasons why SVL is terminated or why the callback sb_t_svl_par::fp_command has been called.

The values are 32 bits both for 32 and 64 bits library version.
See sb_svl_run for the default action in case the sb_t_svl_par::fp_command is not set.

See also
SVL Callbacks
sb_t_svl_res::stop_reason
Enumerator
SB_SVL_STOP_NONE 

SVL finishes without errors.

SB_SVL_STOP_CONFLICT 

There are errors which can not be eliminated.

The function sb_svl_run calls sb_t_svl_par.fp_command with sb_t_svl_res::stop_reason equal to SB_SVL_STOP_CONFLICT in the following case:

  1. If after a few attempts some FALSE NEGATIVE and FALSE POSITIVE samples remain, the sb_svl_run function ask the user if stop or continue the SVL.
    Retina and Surface projects only.
SB_SVL_STOP_USER_REQUEST 

The user has stopped the SVL.

SB_SVL_STOP_MEMORY 

Insufficient memory to complete the SVL.

SB_SVL_STOP_RESET_MANDATORY 

Request for a mandatory reset of SVL.

The function sb_svl_run calls sb_t_svl_par.fp_command with sb_t_svl_res::stop_reason equal to SB_SVL_STOP_RESET_MANDATORY in the following case:

  1. the features selected in the previous SVL are not more compatible with the format (BW, color) of the images in the data set for SVL. It happen when a new training image is added which is not compatible with the current feature set, for example you add a BW image but there is a feature exclusively for color images.
    Retina and Surface projects only.
  2. the number of features is greater than the maximum allowed based on the license configuration.
    Retina and Surface projects only
  3. some images used for previuos training will be used for validation. For more reliable training results it would be recommended to reset SVL.
    Deep Cortex and Deep Surface projects only

The check for automatic reset is done separately for each model.

SB_SVL_STOP_RESET_OPTIONAL 

Ask for an optional reset of SVL.

The function sb_svl_run calls sb_t_svl_par.fp_command with sb_t_svl_res::stop_reason equal to SB_SVL_STOP_RESET_OPTIONAL in the following case:

  1. internal differences in current SDK version compared to that has been used for the exisiting training
  2. if optimization_mode is equal fast and some models are trained and some are not.
    Retina and Surface projects only
  3. if optimization_mode is equal to fast and models has different feature.
    Retina and Surface projects only
  4. the optimization_mode is changed.
    Retina and Surface projects only
  5. some features used by the current training are removed from sb_t_svl_sl_par::features.
    Retina and Surface projects only
  6. the features available (sb_t_svl_sl_par.features) when the last SVL was done are changed.
    Retina and Surface projects only

The check for automatic reset is done separately for each model.

SB_SVL_STOP_WARNING 

Send a warning message.

The function sb_svl_run calls sb_t_svl_par.fp_command with sb_t_svl_res::stop_reason equal to SB_SVL_STOP_WARNING in the following case:

  1. During the sb_t_svl_res.running_step "SVL step" equal to SB_SVL_STEP_SEARCHING_RECIPE, if no suitable features set can be found, the sb_svl_run function asks if the user want to proceed anyway using all selected features.
    Retina and Surface projects only
  2. if optimization_mode is equal to fast and no suitable common features set can be found for all models, the sb_svl_run function asks if the user want to proceed anyway using all chosen features.
    Retina and Surface projects only
  3. During the sb_t_svl_res.running_step "SVL step" equal to SB_SVL_STEP_INITIALIZATION, if no perturbation is set, the sb_svl_run function suggests the user to stop the SVL and set some perturbations before running the SVL.
    Deep Cortex and Deep Surface projects only
  4. During the sb_t_svl_res.running_step "SVL step" equal to SB_SVL_STEP_INITIALIZATION, if the data is missing to make an incremental svl, the sb_svl_run function warns that if you continue a training will be done from scratch.
    This happen when the project has been save with parameter mode equal to SB_PROJECT_MODE_DETECTION_ONLY, see sb_project_save.
    Deep Cortex and Deep Surface projects only

Definition at line 11227 of file sb.h.

Function Documentation

◆ sb_feature_description()

const char * sb_feature_description ( const char *const  feature)

Returns a string with a brief description of a feature.

In the description returned by the function there is also information about the image format compatibile with the feature.

  • There is the string **"BW"** if the feature is compatibile with BW image
  • There is the string **"color"** if the feature is compatibile with color images (BGR or RGB)
  • There is the string **"BW, color"** if the feature is compatible both with BW and color images
    Attention
    The string must not be freed.
    Parameters
    [in]featureString with the feature name. It should be one of the define SB_RETINA_FEATURE_XY.
    Returns
    A C-string containing a brief description for a feature.
    See also
    Features defines
    Features

◆ sb_network_type_format()

const char * sb_network_type_format ( sb_t_network_type  type)

Returns the string of the network type.

Interprets the contents of the code and converts it to a C-string containing a human-readable version of the corresponding value.

Warning
The string must not be freed.
Parameters
[in]typeNetwork type.
Returns
A C-string containing the network type in a human-readable format.

◆ sb_perturbation_mode_format()

const char * sb_perturbation_mode_format ( sb_t_perturbation_mode  mode)

Returns the string of the Deep Learning SVL image perturbation mode.

Interprets the contents of the mode and converts it to a C-string containing a human-readable version of the corresponding perturbation mode.
The string must not be freed.

Parameters
[in]modeDeep Learning SVL image perturbation mode.
Returns
A C-string containing the perturbation mode in a human-readable format.

◆ sb_perturbation_type_format()

const char * sb_perturbation_type_format ( sb_t_perturbation_type  type)

Returns the string of the Deep Learning SVL image perturbation type.

Interprets the contents of the type and converts it to a C-string containing a human-readable version of the corresponding perturbation type.
The string must not be freed.

Parameters
[in]typeDeep Learning SVL image perturbation type.
Returns
A C-string containing the perturbation type in a human-readable format.

◆ sb_svl_clone_res()

sb_t_err sb_svl_clone_res ( sb_t_svl_res **const  dst,
const sb_t_svl_res *const  src 
)

Copies the structure of the results of SVL.

Parameters
[out]dstThe variable will be filled with the pointer of the new structure.
[in]srcPointer of the structure to be copied.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL - training

◆ sb_svl_command_format()

const char * sb_svl_command_format ( sb_t_svl_command  command)

Returns the string of the SVL command.

Interprets the contents of the command and converts it to a C-string containing a human-readable version of the corresponding command.
The string must not be freed.

Parameters
[in]commandSVL command.
Returns
A C-string containing the command in a human-readable format.

◆ sb_svl_destroy_res()

sb_t_err sb_svl_destroy_res ( sb_t_svl_res **const  res)

Destroys the structure of the results of SVL.

Parameters
[in,out]resPointer to the structure. It is set to NULL.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL - training

◆ sb_svl_get_res()

sb_t_err sb_svl_get_res ( SB_HANDLE  handle,
sb_t_svl_res **const  res 
)

Retrieves the results of SVL.

Parameters
[in]handleProject handle.
[out]resPointer to the structure of SVL results.
On successful return, this parameter will be filled with the pointer of the structure sb_t_svl_res.
The structure should be freed using the function sb_svl_destroy_res.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL - training
sb_svl_destroy_res

◆ sb_svl_par_optimization_mode_format()

const char * sb_svl_par_optimization_mode_format ( sb_t_svl_par_optimization_mode  mode)

Returns the string of the SVL optimization mode.

Interprets the contents of the mode and converts it to a C-string containing a human-readable version of the corresponding mode.
The string must not be freed.

Parameters
[in]modeSVL running mode.
Returns
A C-string containing the mode in a human-readable format.

◆ sb_svl_reset()

sb_t_err sb_svl_reset ( SB_HANDLE  handle)

Resets the history of previous executions of the SVL.

Parameters
handleProject handle
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL - training
sb_svl_run

◆ sb_svl_run()

sb_t_err sb_svl_run ( SB_HANDLE  handle)

Runs the SVL.

The functions calls some callbacks to interact with the caller. See SVL Callbacks for more information.
The function uses the images in the folder specified with the parameter sb_t_svl_par::project_path.
In particular it uses the images with type equal to SB_IMAGE_INFO_TYPE_SVL , see sb_image_info_set_type.
For eack image the function calls the callback sb_t_svl_par::fp_pre_elaboration, if set, otherwise it calls the function sb_image_info_load to get the analysis roi, the samples in case of Retina or Deep Cortex projects, the roi defects in case of Surface or Deep Surface projects.
In same cases, when the user modifies the SVL parameters or the dataset, a reset of the training may be required. There are also a set of conditions in which the reset is only optional and the final decision is left to the user using the callback sb_t_svl_par::fp_command.
If the callback sb_t_svl_par::fp_command is not set, the function automatically manages the particular situations that occur during training.
The table below shows what the function does depending on the value of the sb_t_svl_res::stop_reason parameter:

sb_t_svl_res::stop_reason action
SB_SVL_STOP_CONFLICT stop
SB_SVL_STOP_USER_REQUEST stop
SB_SVL_STOP_MEMORY stop
SB_SVL_STOP_RESET_MANDATORY reset
SB_SVL_STOP_RESET_OPTIONAL reset
SB_SVL_STOP_WARNING continue, Retina or Surface stop, Deep Cortex or Deep Surface
Warning
With Deep Surface or Deep Cortex projects incremental svl results my be affected by a fall down of the accuracy and an increase of the loss, if the type or index of the device is changed.
Note
The function needs that the license be active and valid.
Parameters
[in]handleProject handle.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
If a Deep Cortex or Deep Surface project returns error code SB_ERR_DL_CUDA_OUT_OF_MEMORY, try do decrease batch size or use a network with lower input size.
See also
SVL - training
License configurations
Solution structure
sb_svl_reset
sb_project_load

◆ sb_svl_stop_request()

sb_t_err sb_svl_stop_request ( SB_HANDLE  handle)

Sends a request to the SVL for stop.

Parameters
handleProject handle
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
SVL - training