# API Changelog

This topic lists the API changes in previous releases of VisionPro Deep Learning.

## VisionPro Deep Learning 4.1

### View

VisionPro Deep Learning 4.1 introduces the following view A view of an image is a region of pixels in an image. Tool processing is limited to the pixels within the view. You can manually specify a view, or you can use the results of an upstream tool to generate a view.-related changes:

#### Added

The ViDi2.IRedView.FilteredScores (ReadOnlyDictionary<string, double>) C# parameter is added to support using filtered scores for each class.

#### Changed

The threshold is changed to be applied to each class. Add TagThresholds to use the threshold for each predicted tag.

The following C# parameters are added and changed:

- The ViDi2.IGreenView.TagThresholds (ReadOnlyDictionary<string, double>) parameter is added.

- ViDi2.IGreenView.Threshold (double)

  Note: An exception is thrown only when the values of all tags in TagThresholds are not the same: The thresholds for each class are set differently. Use IGreenView.TagThresholds to verify.

### Tool Parameters

VisionPro Deep Learning 4.1 introduces the following tool parameter-related changes:

#### Added TagThresholds

Added the TagThresholds parameter to use the threshold for each predicted tag, implemented on the IGreenStandardParameters parameters.

The following C# parameters are changed:

- ViDi2.Runtime.IGreenLegacyParameters.Threshold (double)

- ViDi2.Training.IGreenLegacyParameters.Threshold (double)

  Note: An exception is thrown only when the values of all tags in TagThresholds are not the same: The thresholds for each class are set differently. Use IGreenView.TagThresholds to verify.

- ViDi2.Runtime.IGreenStandardParameters.ProbabilityThreshold (double)

- ViDi2.Training.IGreenStandardParameters.ProbabilityThreshold (double)

  Note: An exception is thrown only when the values of all tags in TagThresholds are not the same: The thresholds for each class are set differently. Use IGreenView.TagThresholds to verify.

The following C# parameters are added:

- ViDi2.Runtime.IGreenLegacyParameters.TagThresholds (IReadOnlyDictionary<string, double>)

- ViDi2.Training.IGreenLegacyParameters.TagThresholds (IReadOnlyDictionary<string, double>)

- ViDi2.Runtime.IGreenStandardParameters.TagThresholds (IReadOnlyDictionary<string, double>)

- ViDi2.Training.IGreenStandardParameters.TagThresholds (IReadOnlyDictionary<string, double>)

#### Changed the Value Range of Epoch Counts

You can now set the epoch count Deep learning tools are trained by repeatedly supplying sampled image data as input to the network, processing the data, comparing the results with the expected ground truth, and then adjusting the network weights and trying again. The epoch count is the number of times that each input sample is processed through the network. to a minimum value of 1. In previous versions, the minimum value was 50.

The following parameters are changed:

- C++ parameter: training Training is the process that your tool, which is a neural network, is learning about the features (pixels) based on the labels you made. For example, a tool will learn the defect/normal pixels in each image based on the defect/normal labels you drew. The goal of the tool Training is learning enough to give the correct inspection results of whether an unseen image is defective or not. The key to training is to ensure that you include all possible variations within your training set, and that your images are accurately labeled. Training times vary by the application, tool setup and the GPU in the PC being used to train the network._parameters/count_epochs

- C# parameter: ViDi2.Training.IToolParametersStandard.CountEpochs

#### Removed

The training/red/exclusive C++ parameter was removed.

### API Functions

VisionPro Deep Learning 4.1 introduces the following API function-related changes:

#### Added

The following C# functions are added to directly import and export the tool archive as a file:

- ViDi2.Training.ITool.ImportFromFile

- ViDi2.Training.ITool.ExportToFile

The following functions are added to convert the heat map to the polygons or labels for the Red Analyze tool:

- C++

  - vidi_training_green_heatmap_to_polygons

  - vidi_training_green_heatmap_to_labels

- C#

  - ViDi2.Training.IDatabase.HeatmapToPolygons

  - ViDi2.Training.IDatabase.HeatmapToLabels

### Changed

The fetch_from_cache(bool) function is added to use cache when getting the resource image.

The following parameters are changed:

- C++ parameter: vidi_resource_get_image

- C# parameter: ViDi.NET.Local.ILbraryAccess.ResourceGetImage

The name of the following parameters changed:

- gpu_hdm to gpu_standard

- gpuHdm to gpuStandard

The following parameters are changed:

- C++ parameter: vidi_runtime_open_workspace_from_file2

- C# parameter: ViDi2.Runtime.IWorkspaceList.Add

The schema of the runtime workspace A runtime workspace is a configuration file that does not contain images or databases, containing only streams and tools, which makes it a smaller version of a full Workspace. This configuration file can be loaded in the library in order to perform some analysis. export option is changed. For more information, see vidi_training_export_runtime_workspace_to_file2 or vidi_training_export_runtime_workspace_to_memory2 in the API reference.

The visual_debugger_on C++ parameter is renamed to heat_map_on.

## VisionPro Deep Learning 4.0

### Introduced Tool Parameters and API Functions

#### Multiclass Segmentation

Introduced support for multiclass segmentation Segmentation is the process of selecting a view from an image.. The threshold parameter is deprecated and replaced by region_thresholds parameter.

C++ parameters (JSON-formatted strings):

- post_process_parameters/red/region_thresholds

- post_process_parameters/red/region_colors

- post_processing/red/region_thresholds

- post_processing/red/region_colors

C# parameters:

- region_thresholds

  - ViDi2.Training.IRedStandardParameters.RegionThresholds

  - ViDi2.Training.IRedToolParameters.RegionThresholds

  - ViDi2.Training.IAnomalyDetectionParameters.RegionThresholds

  - ViDi2.Runtime.IRedStandardParameters.RegionThresholds

  - ViDi2.Runtime.IRedToolParameters.RegionThresholds

  - ViDi2.Runtime.IAnomalyDetectionParameters.RegionThresholds

- region_colors

  - ViDi2.Training.IRedStandardParameters.ClassColors

  - ViDi2.Training.IRedToolParameters.RegionColors

  - ViDi2.Training.IAnomalyDetectionParameters.RegionColors

  - ViDi2.Runtime.IRedStandardParameters.ClassColors

  - ViDi2.Runtime.IRedToolParameters.RegionColors

  - ViDi2.Runtime.IAnomalyDetectionParameters.RegionColors

#### Heatmap for Training

Introduced support for heatmap in the training API.

- C++ parameter: training_parameters/heat_map_on

- C# parameter: ViDi2.Training.IGreenStandardParameters.HeatMapOn

#### Outlier Score

Introduced support for outlier score in the training API.

- C++ parameter: training_parameters/outlier_check_on

- C# parameter: ViDi2.Training.IGreenStandardParameters.OutlierOn

#### Accelerated Training

Introduced support for the accelerated training option in the training API.

- C++ parameter: training_parameters/accelerated_training

- C# parameter: ViDi2.Training.IToolParametersStandard.AcceleratedTraining

#### Runtime Export Option for Outlier Score and Runtime Heatmap

Introduced runtime export option for Outlier Score and Runtime Heatmap.

C++ functions:

- vidi_training_export_runtime_workspace_to_memory2

- vidi_training_export_runtime_workspace_to_file2

  Set the additional export option with the export_option parameter when you want to use heatmap or outlier score in runtime.

- @param export_option: You must provide a JSON-formatted string to set the outlier_check_on and heat_map_on flag for each tool.

C# functions:

- ViDi2.Training.IWorkspace.ExportRuntimeWorkspace

- ViDi2.Training.IWorkspace.ExportRuntimeWorkspaceToFile

#### TensorRT conversion in training API

Introduced support for TensorRT conversion for both training and runtime. Run TensorRT conversion in the training API with this function. All parameters are the same as in the runtime API.

- C++ function: vidi_training_tool_convert_trt

- C# function: ViDi2.Training.ITool.OptimizeTensorRT

### Changed Tool Parameters and API Functions

#### TensorRT related parameter changes

Replaced the boolean parameter process_with_trt with string parameter trt_mode to introduce the "int8" option for TensorRT optimization.

C++ parameters:

- runtime_parameters/trt_mode (string)

  - "none" option: Do not use TensorRT optimization.

  - "basic" option: Use default TensorRT optimization.

  - "int8" option: Use int8 TensorRT optimization.

- vidi_training_tool_convert_trt

- vidi_runtime_tool_convert_trt

- @param mode parameter: Optimization mode in string.

  - "basic" option: Same as the previous version without this parameter.

  - "int8" option: Mode for int8 TensortRT optimization.

C# parameters:

- ViDi2.Training.IToolParametersStandard.TensorRTMode

- ViDi2.Runtime.IToolParametersStandard.TensorRTMode

- ViDi2.Training.ITool.OptimizeTensorRT

- ViDi2.Runtime.ITool.OptimizeTensorRT

#### Parameters Changed Related to Renewed Tool Categorization

Removed the network_type parameter and changed the training_mode parameter.

C++ parameters:

- training_parameters/training_mode (string)

  - "accurate" option: Same as "standard" in the previous version.

  - "fast" option: Same as "quick" in the previous version.

  - "robust" option: Replaces "adaptation". The parameters "basic" and "adaptation" are deprecated.

  - "fewsample" option: Use this option to train a Green Classify tool with a small sample set of images.

- vidi_training_calculate_max_buffer_size

  - "model A specific spatial arrangement of a set of features (Blue Locate and Blue Read tools only.) During a post-processing step, the Blue Locate and Blue Read tools can fit all of the features detected in an image to the models defined for the tool. The overall pose and identity of the model is then returned._capacity" option: Removed as we adopt renewed tool categorization.

C# parameters:

- ViDi2.Training.IToolParametersStandard.Mode

- ViDi2.Training.IGreenTool.CalculateMaxBuffSize

### Deprecated Features

The following features are deprecated:

- Similarity

- Incremental

- Adaptation

- Runtime heatmap

  Heatmap is now supported for both training and runtime. To use heatmap in runtime, use the export_option parameter in vidi_training_export_runtime_workspace_to_memory2 or the vidi_training_export_runtime_workspace_to_file2 function.

- Incremental learning

For more information, see API Deprecated Features.

### Updated Project Example Names

Due to the change in the type and mode of the tools, the names of the example code also changed between the VisionPro Deep Learning 3.3.0 and 4.0.0 versions.

#### C# API Examples

Path: C:\ProgramData\Cognex\VisionPro Deep Learning\4.0\Examples\c#

Outdated Name | New Name
Example.Runtime.HDGreen.Console | Example.Runtime.GreenStandard.Console
Example.Runtime.HDRed.Console | Example.Runtime.RedStandard.Console
Example.Training.HDGreen.Console | Example.Training.GreenStandard.Console
Example.Training.HDRed.Console | Example.Training.RedStandard.Console
Example.Runtime.HDGreen.Batched.Console | Example.Runtime.GreenStandard.Batched.Console
Example.Runtime.OptimizeHDTool.Console | Example.Runtime.OptimizeStandardTool.Console

#### C API Examples

Path: C:\ProgramData\Cognex\VisionPro Deep Learning\4.0\Examples\c++

Outdated Name | New Name
Example.Runtime.HDGreen | Example.Runtime.GreenStandard
Example.Runtime.HDRed | Example.Runtime.RedStandard
Example.Training.HDGreen | Example.Training.GreenStandard
Example.Training.HDRed | Example.Training.RedStandard
Example.Runtime.HDGreen.Batched | Example.Runtime.GreenStandard.Batched
Example.Runtime.OptimizeHDTool | Example.Runtime.OptimizeStandardTool

## VisionPro Deep Learning 3.3

### Deprecated extra_large Capacity

- In the vidi_training.h vidi_training_tool_train2 C++ function, the extra_large option is no longer valid for the training_artifact_key parameter.

- In the ViDi2.Training.IToolParametersHighDetail.NetworkModel C# function, the extra_large option is no longer valid.

### Deprecated extra_small Capacity

- In the vidi_training.h vidi_training_tool_train2 C++ function, the extra_small option is no longer valid for the training_artifact_key parameter.

- In the ViDi2.Training.IToolParametersHighDetail.NetworkModel C# function, the extra_small option is no longer valid.

### Deprecated green_quick and red_quick Tool Types

- In the vidi_training.h vidi_runtime_set_parameter C++ function, the tool_type/green_quick and tool_type/red_quick options are no longer valid.

- The ViDi2.ITool.ToolType.GreenQuickHighDetail and ViDi2.ITool.ToolType.RedQuickHighDetail C# function properties are no longer valid and will be removed from the future release.

### Deprecated use_patchcrop_prediction Parameter in runtime_parameters

- In the vidi_runtime.h vidi_runtime_set_parameter and vidi_runtime.h vidi.runtime_tool_set_parameter C++ functions, the runtime_parameters/use_patchcrop_prediction parameter is no longer valid.

- The ViDi2.Training.IRedHighDetailParameters.UsePatchcropPrediction and ViDi2.Runtime.IRedHighDetailParameters.UsePatchcropPrediction C# function properties are removed.

### Deprecated max_downsampling_size Parameter in runtime_parameters

- In the vidi_runtime.h vidi_runtime_set_parameter and vidi_runtime.h vidi.runtime_tool_set_parameter C++ functions, the runtime_parameters/max_downsampling_size parameter is no longer valid.

- The ViDi2.Training.IRedHighDetailParameters.MaxDownSamplingSize and ViDi2.Runtime.IRedHighDetailParameters.MaxDownSamplingSize C# function properties are removed.

### Deprecated minimum_epochs Parameter in training_parameters

- In the vidi_training.h vidi_training_set_parameter and vidi_training.h vidi.training_tool_set_parameter C++ functions, the training_parameters/minimum_epochs parameter is no longer valid.

- The ViDi2.Training.IToolParametersHighDetail.MinimumEpochs C# function property is no longer valid and will be removed from the future release.

### Changed the Internal Model Architecture for small Capacity Model

- In the vidi_training.h vidi_training_tool_train2 C++ function, the small option is changed for the training_artifact_key parameter.

- In the ViDi2.Training.IToolParametersHighDetail.NetworkModel C# function, the small option is changed.

### Changed the Mechanism and Valid Value Range of the count_epochs and patience training_parameters

- In the vidi_training.h vidi_training_set_parameter and the vidi_training.h vidi_training_tool_set_parameter C++ functions:

  - The valid value range of the training_parameters/count_epochs parameter is changed to [50, 100000].

  - The valid value range of the training_parameters/patience parameter is changed to [0, 100].

- The ViDi2.Training.IToolParametersHighDetail.CountEpochs and the ViDi2.Training.IToolParametersHighDetail.Patience C# functions are changed.

For more information about the new mechanism, see the VisionPro Deep Learning Software Help.

### Introduced Parameters for the Auto Resize Mode

- In the vidi_training.h vidi_training_set_parameter and the vidi_training.h vidi_training_tool_set_parameter C++ functions, the training_parameters/adaptive_downsampling parameter is introduced with the following details:

  - Type: float

  - Valid range: [0, 1]

  - Description: Scale to resize the views for training and processing. You can manually set the 0 and the 1 values. Value 1 is the default value, resizing is disabled. Value 0 enables resizing in auto mode The auto mode is a grid-search mode in the Cognex Deep Learning Parameter Search utility, which automatically optimizes the search schedule by adopting a policy that obtain the best results with minimizing the search time. Given a list of parameters and their values, auto mode stops training the loaded tool and moves on to training with another parameter values when it finds no reason for better results from the current parameter values. Only Standard type tools support auto mode.. In auto mode, the software automatically finds and uses the proper size ratio.

- In the vidi_runtime.h vidi_runtime_get_parameter and the vidi_runtime.h vidi_runtime_tool_get_parameter C++ functions, the runtime_parameters/adaptive_downsampling parameter is introduced with the following details:

  - Type: float

  - Valid range: [0, 1]

  - Description: This is a read-only parameter that is automatically set to the same value as the training_parameters/adaptive_downsampling parameter when the runtime workspace is exported.

    Note: You cannot call the vidi_runtime_set_parameter/vidi_runtime_tool_set_parameter function for this parameter.

- The following C# functions are introduced:

  - ViDi2.Training.IRedHighDetailParameters.AdaptiveDownsampling

  - ViDi2.Runtime.IRedHighDetailParameters.TrainedAdaptiveDownsampling

    For example, see Examples/c#/Example.Training.HDRed.Console, lines 156-158

### Removed the Default Parameter for the width, height Parameters of the vidi_runtime_tool_convert_trt function

- The vidi_runtime.h vidi_runtime_tool_convert_trt function is changed compared to the previous release as follows:

  - VisionPro Deep Learning 3.2.0:

    - VIDI_INT width = 0

    - VIDI_INT height=0

  - VisionPro Deep Learning 3.3.0:

    - VIDI_INT width,

    - VIDI_INT height,

- The ViDi2.Runtime.ITool.OptimizeTensorRT C# function is changed as follows:

  - VisionPro Deep Learning 3.2.0:
    - int width = 0, int height = 0

  - VisionPro Deep Learning 3.3.0:

    - int width, int height,

These parameters are the target size of the optimized TensorRT model. If the image sizes for processing are the same, use the exact same image width and height. However, if the image sizes are different, set each width and height based on the largest width and height among the images to be processed.

## VisionPro Deep Learning 3.2

### GPU Clock Stabilizer

First, you can try adjusting the GPU clock settings to prevent lowering the GPU clock. Please change the 'Power management mode' in Nvidia Control Panel > Manage 3D settings to 'Prefer maximum performance. However, if the GPU clock still cannot be maintained, consider using together with the new feature A feature is a visually distinguishable area in an image. Features typically represent something of interest for the application (a defect, an object, a particular component of an object). called GPU Clock Stabilizer.

The feature to maintain a stable GPU clock in a deployment environment can be helpful in multi-GPU scenarios or in situations where clock instability leads to reduced processing speed or spikes.

For more details, see the below example codes.

Note:

- This feature is initially disabled by default. You can control its activation or deactivation through the API.
- It should be employed after Compute Device initialization. Attempting to use it before initialization will result in the C API returning a value other than VIDI_SUCCESS, while the .NET API will trigger an exception.

Copy
C++ Example of GPU Clock Stabilizer

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    ...
                    /** @brief disable stabilize feature  */
                    #define VIDI_STABILIZE_OFF 0

                    /** @brief enable stabilize feature on GPUs  */
                    #define VIDI_STABILIZE_GPU 1

                    /** @brief stabilize the compute devices
                    *   @param mode mode of operation
                    *   @return 0 if passed, otherwise an error_code that can be used with vidi_get_error_message()
                    *
                    *   @see VIDI_STABILIZE_GPU, VIDI_STABILIZE_OFF
                    *   This method must be called after the compute devices have been initialized.
                    */
                    VIDI_DLLEXPORT  VIDI_UINT vidi_stabilize_compute_device(VIDI_INT mode);

                    ///////////////////////////////////////////////////////
                    // example
                    ///////////////////////////////////////////////////////

                    // Turns on.
                    vidi_stabilize_compute_device(VIDI_STABILIZE_GPU);

                    // Turns off
                    vidi_stabilize_compute_device(VIDI_STABILIZE_OFF);
                ...

Copy
C# Example of GPU Clock Stabilizer

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    ...
                    /// <summary>
                        /// Offers the possibility to stabilize the compute devices when the control is created, without unloading the vidi dll
                        /// example: mode =  "StabilizeMode.Off"
                        ///          mode =  "StabilizeMode.GPU"
                        /// This can only be called after compute devices initialized.
                    /// </summary>
                    void StabilizeComputeDevices(Enum mode);

                    ///////////////////////////////////////////////////////
                    // example
                    ///////////////////////////////////////////////////////

                    // Turns on
                    control.StabilizeComputeDevices(StabilizeMode.GPU);

                    // Turns off
                    control.StabilizeComputeDevices(StabilizeMode.Off);
                ...

### vidi_initialize2() is Deprecated

vidi_initialize2() function has been deprecated.
Starting from version VisionPro Deep Learning 3.2.0, you can load and use both the training API and runtime API simultaneously. Although the vidi_initialize2() API still exists, it does not perform the intended operation.

Copy
Deprecated vidi_initialize2()

    1
    VIDI_DLLEXPORT  VIDI_UINT vidi_initialize2(VIDI_INT compute_mode, VIDI_STRING compute_devices, VIDI_INT cuda_load_mode);

## VisionPro Deep Learning 3.0

Among the new features introduced in VisionPro Deep Learning 3.0, some of them are only provided through API as they enhance runtime functionality.

### Classification Batch Processing for Runtime API

Processing multiple views at once through batch processing is now available for Green Classify Standard. Using the following Runtime APIs can speed up the Green Classify Standard processing via API.

The steps to use classification batch processing API are summarized as follows.

1. Fix the batch size and prepare the images to process. The maximum batch size is dependent on the current available GPU memory.

2. Create a sample.

3. Add the prepared images to the sample.

4. Run batch processing.

5. Check the processing results.

For more details of utilizing batch processing API, see the below example codes.

Note:

- If you select a batch size larger than the maximum batch size which is calculated based on the available memory of the current GPU in Step 1, the batch processing will fail to start.
- Set the batch size and perform dummy processing twice initially. The processing time might be slow for the first two runs due to the warm-up.

Copy
C++ Example of Batch Processing API for Runtime (Green High Detail)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    ...
    // The maximum batch size depends on the available GPU memory size.
    // let's suppose the available maximum batch size is 12.
    constexpr int batch_size = 12;

    // you need to set "runtime_parameters/batch_size" as the batch size you chose above.
    // "workspace": the name of your workspace
    // "default": the name of the stream in your workspace
    // "Classify": the name of the Green High Detail tool in your stream.
    string batch_size_str = std::to_string(batch_size);
    vidi_runtime_tool_set_parameter("workspace", "default", "Classify", "runtime_parameters/batch_size", batch_size_str.c_str());
    ...
    // you also need to prepare the same number of the images as the batch size
    vector<VIDI_IMAGE> images(batch_size);
    for (int i = 0; i < batch_size; i++)
    {
        ...
        status = vidi_load_image(image_path.c_str(), &images[i]);
        ...
    }
    ...
    // create a sample for batch processing. Note that a sample is the basic unit of processing task.
    // "my_sample": the name of the sample you create.
    status = vidi_runtime_create_batched_sample("workspace", "default", "my_sample");
    ...
    // add the prepared images to the sample
    for (int i = 0; i < batch_size; i++)
    {
        ...
        status = vidi_runtime_batched_sample_add_image("workspace", "default", "my_sample", &images[i]);
        ...
    }
    ...
    // execute batch processing
    status = vidi_runtime_batched_sample_process("workspace", "default", "Classify", "my_sample", "");
    ...
    // get result of batch processing
    status = vidi_runtime_get_batched_sample("workspace", "default", "my_sample", &result_buffer);
    ...

Copy
C# Example of Batch Processing API for Runtime (Green High Detail)

    ...
    // The maximum batch size depends on the available GPU memory size.
    // let's suppose the available maximum batch size is 12.
    int batch_size = 12;
    ...
    // you also need to prepare the same number of the images as the batch size
    // the paths list should contain the paths of images
    List<IImage> imgs = new List<IImage>();
    for (int i = 0; i < batch_size; ++i)
        imgs.Add(new LibraryImage(paths[i]));

    // create a sample for batch processing. Note that a sample is the basic unit of processing task.
    // "Classify": the name of the Green High Detail tool in your stream.
    using (IBatchedSample sample = stream.CreateBatchedSample())
    {
        // add images to sample
        for (int i = 0; i < batch_size; ++i)
            sample.AddImage(imgs[i]);

        ITool greenTool = stream.Tools["Classify"];

          // set batch size parameter
          var param = greenTool.ParametersBase as ViDi2.Runtime.IGreenHighDetailParameters;
        param.BatchSize = batch_size;

        // run processing
        sample.Process(greenTool);

        // get processing result of batch
        for (int i = 0; i < batch_size; ++i)
        {
            var tags = sample.Tags(greenTool, i);
            foreach (var tag in tags)
                Console.WriteLine($"tag: name={tag.Key}, score={tag.Value}");
        }
    }

Note: Batch processing should not be used in a tool chain. If you want to use batch processing in a chain of tools, create a runtime workspace for each tool and chain them.

### NVIDIA TensorRT Support for Runtime API

NVIDIA TensorRT is an NVIDIA SDK that boosts the inference speed of a deep learning application. It optimizes the inference speed of a deep neural network by NVIDIA GPU model. From VisionPro Deep Learning 3.0, Runtime API supports TensorRT to boost the processing speed at runtime. To use TensorRT for Runtime API, go through the following steps. The TensorRT for Runtime API is supported only for Red Analyze Standard and Green Classify Standard runtime environment.

1. In the training environment, create a workspace, stream, and a Standard tool. Train the tool to make it ready to be deployed in the runtime environment. The training environment can be either VisionPro Deep Learning GUI or API. You can create a workspace, stream, and a High Detail tool and train the tool in GUI.

2. Export a runtime workspace which includes the trained Standard tool. You also can create a runtime workspace in GUI (Workspace > Export Runtime Workspace).

3. Deploy the runtime workspace and its Standard tool on the device on your front line.

4. Run TensorRT Optimization API to optimize the Standard tools in your runtime workspace with TensorRT, then save your runtime workspace.

   Note: If the image sizes are the same, use the exact same image width and height. However, if the image sizes are different, set each width and height based on the largest width and height among the images to be processed.

5. The optimization normally takes under 10 minutes to be completed. After the first run of optimization, the neural network of the tool is optimized to the specific NVIDIA GPU model you use. From this point, you can process as many images you want with faster speed.

   Copy

   C++ Example of TensorRT Optimization API for Runtime (Red High Detail and Green High Detail)

       1
       2
       3
       4
       5
       6
       7
       8
       9
       10
       11
       12
       13
       14
       15
       16
       17
       18
       19
       ...
       // open the given workspace.
       // "workspace": the name of your runtime workspace
       //"..\\..\\resources\\runtime\\Green High-detail Tool.vrws": the path to the runtime workspace file
       status = vidi_runtime_open_workspace_from_file("workspace", "..\\..\\resources\\runtime\\Green High-detail Tool.vrws");
       ...

       // optimize the High-detail tool
       // "default": the name of the stream in your workspace
       // "Classify": the name of the Green High Detail tool in your stream.
       clog << "Start optimization. It will take a few minutes." << endl;
       status = vidi_runtime_tool_convert_trt("workspace", "default", "Classify", 0);
       ...

       // save runtime workspace with the optimized tool
       string save_path = "..\\..\\resources\\runtime\\Green High-detail Tool optimized.vrws";
       status = vidi_runtime_save_workspace("workspace", save_path.c_str());
       clog << "The workspace with the optimized tool is saved at " << save_path.c_str() << endl;
       ...

   Copy
   C# Example of TensorRT Optimization API for Runtime (Red High Detail and Green High Detail)

       1
       2
       3
       4
       5
       6
       7
       8
       9
       10
       11
       12
       13
       14
       15
       16
       17
       18
       19
       20
       21
       22
       ...
       // Open a runtime workspace from file
       // the path to this file relative to the example root folder
       // and assumes the resource archive was extracted there.
       // "workspace": the name of your runtime workspace
       ViDi2.Runtime.IWorkspace workspace = control.Workspaces.Add("workspace", "..\\..\\..\\..\\resources\\runtime\\Green High-detail Tool.vrws");

       // Store a reference to the stream 'default'
       IStream stream = workspace.Streams["default"];

       // "Classify": the name of the Green High Detail tool in your stream.
       var greenTool = stream.Tools["Classify"] as ViDi2.Runtime.IGreenTool;

       // Optimizes the High-Detail tool with TensorRT. It takes some time to optimize the tool.
       greenTool.OptimizeTensorRT(0);

       // Save runtime workspace with the optimized tool.
       // You can use this workspace to process with the optimized tool.
       string savePath = "..\\..\\..\\..\\resource\\runtime\\Green High-detail Tool Optimized.vrws";
       workspace.Save(savePath);
       Console.Write($"The workspace with the optimized tool is saved at {savePath}.");
       ...

   If you want to use the Classification Batch Processing for Runtime API together with TensorRT-optimized processing, you need to set batch size before calling the optimization.

   Copy
   C++ Example of Setting Batch Size Before Calling TensorRT Optimization (Green High Detail)

       1
       2
       3
       4
       5
       6
       // Optimize with batchSize=16
       // The 5th(width) and 6th(height) parameter of vidi_runtime_tool_convert_trt() are for target width and height for optimization
       // If width=0 or height=0 is provided, the trained size is used. So we just recommend use width=0, height=0 in normal case.
       int gpu_index = 0;
       int batch_size = 16;
       vidi_runtime_tool_convert_trt("workspace", "default", "Analyze", gpu_index, 0, 0, batch_size);

   Copy
   C# Example of Setting Batch Size Before Calling TensorRT Optimization (Green High Detail)

       1
       2
       3
       4
       5
       6
       // Optimize with batchSize=16
       // The second(width) and third(height) parameter of OptimizeTensorRT() are for target width and height for optimization
       // If width=0 or height=0 is provided, the trained size is used. So we just recommend use width=0, height=0 in normal case.
       int gpuIndex = 0;
       int batchSize = 16;
       greenTool.OptimizeTensorRT(gpuIndex, 0, 0, batchSize);

   Directory to C++ Full Example Codes:

   C:/ProgramData/Cognex/VisionPro Deep Learning/3.0/Examples/c++/Example.Runtime.OptimizeHDTool

   C:\ProgramData\Cognex\VisionPro Deep Learning\3.0\Examples\c++\Example.Runtime.HDGreen.Batched

   Directory to C# Full Example Codes:

   C:/ProgramData/Cognex/VisionPro Deep Learning/3.0/Examples/c#/Example.Runtime.OptimizeHDTool.Console

   C:\ProgramData\Cognex\VisionPro Deep Learning\3.0\Examples\c#\Example.Runtime.HDGreen.Batched.Console

   Load your runtime workspace in your application and deploy it on the device to process images with the TensorRT-optimized tool. To do this, you need to set a parameter before processing.

   Copy
   C++ Example of Setting Parameter to Use TensorRT Optimized-model for Processing (Red High Detail and Green High Detail)

       1
       2
       3
       4
       5
       // If you want to process with optimized tool, you have to set ProcessTensorRT to true.
       // Setting this option to true will trigger TensorRT processing.
       status = vidi_runtime_tool_set_parameter("workspace", "default", "Analyze", "runtime_parameters/process_with_trt", "true");
       ...
       status = vidi_runtime_sample_process("workspace", "default", "Analyze", "my_sample", "");

   Copy
   C# Example of Setting Parameter to Use TensorRT Optimized-model for Processing (Red High Detail and Green High Detail)

       1
       2
       3
       4
       5
       6
       // If you want to process with optimized tool, you have to set ProcessTensorRT to true.
       // Setting this option to true will trigger TensorRT processing.
       var hdParam = hdTool.ParametersBase as ViDi2.Runtime.IToolParametersHighDetail;
       hdParam.ProcessTensorRT = true;
       ...
       sample.Process(hdTool);

   See the example codes below to process images with a runtime workspace.

   Directory to C# Example Codes:

   - C:/ProgramData/Cognex/VisionPro Deep Learning/3.0/Examples/c#/Example.Runtime.HDGreen.Console

   - C:/ProgramData/Cognex/VisionPro Deep Learning/3.0/Examples/c#/Example.Runtime.HDRed.Console

   Directory to C++ Example Codes:

   - C:/ProgramData/Cognex/VisionPro Deep Learning/3.0/Examples/c++/Example.Runtime.HDGreen

   - C:/ProgramData/Cognex/VisionPro Deep Learning/3.0/Examples/c++/Example.Runtime.HDRed

   Note: TensorRT Optimization API (vidi_runtime_tool_convert_trt, .OptimizeTensorRT) should be called again after your NVIDIA GPU model is changed because its optimization works by NVIDIA GPU model. If you changed your NVIDIA GPU model in your device, repeat the Step 4 and 5.

## VisionPro Deep Learning 2.1.1

In VisionPro Deep Learning 2.1.1, a new processing parameter max_scan_iterations is added only in API for Blue Locate and Blue Read. This parameter limits the maximum number of iterations for image scanning during processing and providing a fixed number for this parameter speeds up the processing.

Note: The features or the character features can be less detected than expected when the value of max_scan_iterations is set too low. The appropriate value for this parameter is dependent on the images.

You can get the value of this parameter by:

- vidi_runtime_get_parameter

- vidi_runtime_tool_get_parameter

You can change the value of this parameter by:

- vidi_runtime_set_parameter

- vidi_runtime_tool_set_parameter

The parameter path for max_scan_iterations is:

- processing/blue/max_scan_iterations

### Examples

This topic introduces the code examples of max_scan_iterations parameter for C and .NET API

Symbol | Definition
--- | ---
WORKSPACE | The name of your workspace.
STREAM | The name of the stream in your workspace.
TOOL | The name of the tool in the stream.
40 | The value of the parameter.

Copy

C API

    1
    VIDI_UINT status = vidi_runtime_tool_set_parameter("WORKSPACE", "STREAM", "TOOL", "processing/blue/max_scan_iterations", "40");

Copy

.NET API

    1
    libraryAccess.SetToolParameter("WORKSPACE", "STREAM", "TOOL", "processing/blue/max_scan_iterations", "40"); // libraryAccess is ILibraryAccess

## VisionPro Deep Learning 2.1

As High Detail Quick modes are added in VisionPro Deep Learning 4.1, there are some changes to API as well.

### Green Classify High Detail Quick Training - C API

Copy

Green High Detail Quick Training with C API

    1
    2
    3
    4
    5
    6
    // Green high-detail-quick mode
    ...
    param_ss << "workspaces/" << workspace_name << "/streams/" << stream_name << "/tools/" << tool_name << "/tool_type";
    status = vidi_training_set_parameter(param_ss.str().c_str(), "green_quick");
    ...

To train Green Classify High Detail Quick, the parameter path should be set to "green_quick" for vidi_training_set_parameter.

The example of parameter path:

- workspaces/WORKSPACE_NAME/streams/STREAM_NAME/tools/TOOL_NAME/tool_type

Symbol | Definition
--- | ---
WORKSPACE_NAME | The name of your workspace.
STREAM_NAME | The name of the stream in the workspace.
TOOL_NAME | The name of the tool in the stream.

To configure the Tool Parameters for Green Classify High Detail Quick, the parameter path also should be set. For example, if you want to change Epoch Count in Training Parameters, set the parameter path as:

- workspaces/WORKSPACE_NAME/streams/STREAM_NAME/tools/TOOL_NAME/training_parameters/count_epochs

Symbol | Definition
--- | ---
WORKSPACE_NAME | The name of your workspace.
STREAM_NAME | The name of the stream in the workspace.
TOOL_NAME | The name of the tool in the stream.

See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Training.HDGreen\example_training_hdgreen.cpp for the more detailed examples of training C API codes.

### Green Classify High Detail Quick Training - .NET API

Copy

Green High Detail Quick Training with .NET API

    1
    2
    3
    4
    5
    ...
    // Green high-detail-quick mode
    hdGreenTool.Database.Tool.Type = ToolType.GreenQuickHighDetail;
    ...

To train Green Classify High Detail Quick, the ViDi2.Training.ITool.Type should be set to ToolType.GreenQuickHighDetail.

To configure the Tool Parameters for Green Classify High Detail Quick, the ViDi2.Training.IGreenHighDetailParameters should be set. For example, you should set the value of CountEpochs for IGreenHighDetailParameters.

See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Training.HDGreen.Console\Program.cs for the more detailed examples of training .NET API codes.

### Green Classify High Detail Quick Processing - C API

The way to process Green Classify High Detail Quick with API is the same as those of Green Classify Focused and Green Classify High Detail. See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Runtime.HDGreen\example_runtime_hdgreen.cpp for the details.

### Green Classify High Detail Quick Processing - .NET API

The way to process Green Classify High Detail Quick with API is the same as those of Green Classify Focused and Green Classify High Detail. See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Runtime.HDGreen.Console\Program.cs for the details.

### Red Analyze High Detail Quick Training - C API

Copy

Red High Detail Quick Training with C API

    1
    2
    3
    4
    5
    6
    ...
    // Red high-detail quick mode
    param_ss << "workspaces/" << workspace_name << "/streams/" << stream_name << "/tools/" << tool_name << "/tool_type";
    status = vidi_training_set_parameter(param_ss.str().c_str(), "red_quick");
    ...

To train Red Analyze High Detail Quick, the parameter path should be set to "red_quick" for vidi_training_set_parameter.

The example of parameter path:

- workspaces/WORKSPACE_NAME/streams/STREAM_NAME/tools/TOOL_NAME/tool_type

Symbol | Definition
--- | ---
WORKSPACE_NAME | The name of your workspace.
STREAM_NAME | The name of the stream in the workspace.
TOOL_NAME | The name of the tool in the stream.

To configure the Tool Parameters for Red Analyze High Detail Quick, the parameter path also should be set. For example, if you want to change Epoch Count in Training Parameters, set the parameter path as:

- workspaces/WORKSPACE_NAME/streams/STREAM_NAME/tools/TOOL_NAME/training_parameters/count_epochs

Symbol | Definition
--- | ---
WORKSPACE_NAME | The name of your workspace.
STREAM_NAME | The name of the stream in the workspace.
TOOL_NAME | The name of the tool in the stream.

See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Training.HDRed\example_training_hdred.cpp for the more detailed examples of training C API codes.

### Red Analyze High Detail Quick Training - .NET API

Copy

Red High Detail Quick Training with .NET API

    1
    2
    3
    4
    ...
    // Red high-detail quick mode
    hdRedTool.Database.Tool.Type = ToolType.RedQuickHighDetail;
    ...

To train Red Analyze High Detail Quick, the ViDi2.Training.ITool.Type should be set to ToolType.RedQuickHighDetail.

To configure the Tool Parameters for Red Analyze High Detail Quick, the ViDi2.Training.IRedHighDetailParameters should be set. For example, you should set the value of CountEpochs for IRedHighDetailParameters.

See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Training.HDRed.Console\Program.cs for the more detailed examples of training .NET API codes.

### Red Analyze High Detail Quick Processing - C API

The way to process Red Analyze High Detail Quick with API is the same as those of Red Analyze Focused Supervised and Red Analyze High Detail. See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Runtime.Red\example_runtime_red.cpp for the details.

### Red Analyze High Detail Quick Processing - .NET API

The way to process Red Analyze High Detail Quick with API is the same as those of Red Analyze Focused Supervised and Red Analyze High Detail. See C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Runtime.HDRed.Console\Program.cs for the details.