API 更改日志

本主题列出以前 VisionPro Deep Learning 版本中的 API 更改。

VisionPro Deep Learning 3.2

GPU 时钟稳定器

首先，您可以尝试调整 GPU 时钟设置以防止降低 GPU 时钟。请在“Nvidia 控制面板”>“管理 3D”设置中将“电源管理模式”更改为“首选最高性能”。不过，如果 GPU 时钟仍无法维护，请考虑与名为“GPU 时钟稳定器”的新功能一起使用。

在部署环境中维护稳定的 GPU 时钟的功能在多 GPU 场景或时钟不稳定导致处理速度降低或达到峰值的情况下非常有用。

有关详细信息，请参阅下面的示例代码。

注意:

默认情况下，此功能最初处于禁用状态。您可以通过 API 控制其激活或停用状态。
此功能应在计算设备初始化之后使用。在初始化之前尝试使用此功能会造成 C API 返回 VIDI_SUCCESS 之外的值，同时 .NET API 会触发异常。

复制

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);
            ...

复制

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() 已弃用

vidi_initialize2() 函数已弃用。
从版本 VisionPro Deep Learning 3.2.0 开始，您可以同时加载和使用训练 API 和运行时 API。尽管 vidi_initialize2() API 仍存在，但它不执行预期的操作。

复制

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

在 VisionPro Deep Learning 3.0 中引入的新功能中，由于 API 增强了运行时功能，部分功能只能通过 API 提供。

运行时 API 的分类批处理

绿色分类高细节现在可以通过批处理功能一次处理多个视图。使用下列运行时 API 可以通过 API 加快绿色分类高细节处理速度。

使用分类批处理 API 的步骤汇总如下。

修复批次大小并准备要处理的图像。最大批次大小取决于当前可用的 GPU 内存。
创建样本。
将准备好的图像添加到样本中。
运行批处理。
检查处理结果。

有关利用批次处理 API 的更多详细信息，请参阅下面的示例代码。

注意:如果您选择的批次大小大于在步骤 1 中根据当前 GPU 的可用内存计算的最大批次大小，批处理将无法开始。

复制

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);
...

复制

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}");
    }
}

注意:批处理不应在工具链中使用。如果您要在工具链中使用批处理，请为每个工具创建运行时工作区并将其链在一起。

运行时 API 支持 NVIDIA TensorRT

NVIDIA TensorRT 是 NVIDIA SDK，它加快了深度学习应用程序的推断速度。它通过 NVIDIA GPU 模型优化了深度神经网络的推断速度。从 VisionPro Deep Learning 3.0 开始，运行时 API 支持 TensorRT 加快在运行时的处理速度。要导出运行时 API 的 TensorRT，请执行以下步骤。仅针对红色分析高细节和绿色分类高细节运行时环境支持运行时 API 的 TensorRT。

在训练环境中，创建工作区、流和高细节工具。训练工具，让其可以随时部署在运行时环境中。训练环境可以是 VisionPro Deep Learning GUI 或 API。您可以创建工作区、流和高细节工具，并在 GUI 中训练工具。有关训练和运行时环境的更多详细信息，请参阅环境。
导出包含训练高细节工具的运行时工作区。您也可以在 GUI 中创建运行时工作区（“工作区”>“导出运行时工作区”）。有关运行时工作区的更多详细信息，请参阅运行时工作区。
在前端设备上部署运行时工作区及其高细节工具。有关运行时部署的更多详细信息，请参阅运行时工作区和运行时部署。

在运行时工作区中使用 TensorRT 运行 TensorRT 优化 API 来优化高细节工具，从而节省运行时工作区。优化完成时间通常不到 10 分钟。在第一次运行优化后，该工具的神经网络会针对您使用的特定 NVIDIA GPU 型号进行优化，从此时开始，您便可以更快的速度处理尽可能多的图像。

复制

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;
...

复制

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}."); 
...

如果您要将运行时 API 的分类批处理与 TensorRT 优化的处理一起使用，则需要在调用优化功能前设置批次大小。

复制

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);

复制

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);

C++ 完整示例代码目录：

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

C# 完整示例代码的目录：

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

将您的运行时工作区加载到您的应用中，并将其部署到设备上，以便使用 TensorRT 优化工具处理图像。为此，您需要在处理前设置参数。
复制
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", "");
```
复制
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);
```
请参阅下面的示例代码以使用运行时工作区处理图像。

C# 示例代码的目录：
- 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
C++ 示例代码的目录：
- 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
注意:TensorRT 优化 API（vidi_runtime_tool_convert_trt，.OptimizeTensorRT）应在 NVIDIA GPU 型号变更后再次调用，因为只有 NVIDIA GPU 型号才能执行优化。如果您在设备中更改了 NVIDIA GPU 型号，请重复步骤 4 和 5。

VisionPro Deep Learning 2.1.1

在 VisionPro Deep Learning 2.1.1 中，仅在 API 中为蓝色定位和蓝色读取添加了新处理参数 max_scan_iterations。该参数限制了处理过程中图像扫描的最大迭代次数，为该参数提供固定次数可加快处理速度。

注意:当 max_scan_iterations 的值设置得太低时，检测到的特征或字符特征数可能比预期的少。该参数的适当值取决于图像。

您可以通过下列参数获取此参数的值：

vidi_runtime_get_parameter
vidi_runtime_tool_get_parameter

您可以通过下列参数更改此参数的值：

vidi_runtime_set_parameter
vidi_runtime_tool_set_parameter

max_scan_iterations 的参数路径是：

processing/blue/max_scan_iterations

示例

此主题介绍 C 和 .NET API 的 max_scan_iterations 参数的代码示例

符号	定义
工作区	工作区的名称。
流	工作区中流的名称。
工具	流中工具的名称。
40	参数的值。

复制

C API

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

复制

.NET API

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

VisionPro Deep Learning 2.1

由于在 VisionPro Deep Learning3.2 中添加了高细节快速模式，API 也发生了一些变化。

绿色分类高细节快速训练 - C API

复制

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");
...

要训练绿色分类高细节快速，应将 vidi_training_set_parameter 的参数路径设置为“green_quick”。

参数路径的示例：

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

符号	定义
WORKSPACE_NAME	工作区的名称。
STREAM_NAME	工作区中流的名称。
TOOL_NAME	流中工具的名称。

要为绿色分类高细节快速配置工具参数，还应设置参数路径。例如，如果要更改训练参数中的时期数，请将参数路径设置为：

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

符号	定义
WORKSPACE_NAME	工作区的名称。
STREAM_NAME	工作区中流的名称。
TOOL_NAME	流中工具的名称。

有关训练 C API 代码的更详细示例，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Training.HDGreen\example_training_hdgreen.cpp”。

绿色分类高细节快速训练 - .NET API

复制

Green High Detail Quick Training with .NET API

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

要训练绿色分类高细节快速，应将 ViDi2.Training.ITool.Type 设置为 ToolType.GreenQuickHighDetail。

要为绿色分类高细节快速配置工具参数，应设置 ViDi2.Training.IGreenHighDetailParameters。例如，应为 IGreenHighDetailParameters 设置 CountEpochs 的值。

有关训练 .NET API 代码的更详细示例，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Training.HDGrProgrameen.Console\.cs”。

绿色分类高细节快速处理 - C API

使用 API 处理绿色分类高细节快速的方式与绿色分类聚焦和绿色分类高细节相同。有关详细信息，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Runtime.HDGreen\example_runtime_hdgreen.cpp”。

绿色分类高细节快速处理 - .NET API

使用 API 处理绿色分类高细节快速的方式与绿色分类聚焦和绿色分类高细节相同。有关详细信息，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Runtime.HDGreen.Console\Program.cs”。

红色分析高细节快速训练 - C API

复制

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");
...

要训练红色分析高细节快速，应将 vidi_training_set_parameter 的参数路径设置为“red_quick”。

参数路径的示例：

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

符号	定义
WORKSPACE_NAME	工作区的名称。
STREAM_NAME	工作区中流的名称。
TOOL_NAME	流中工具的名称。

要为红色分析高细节快速配置工具参数，还应设置参数路径。例如，如果要更改训练参数中的时期数，请将参数路径设置为：

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

符号	定义
WORKSPACE_NAME	工作区的名称。
STREAM_NAME	工作区中流的名称。
TOOL_NAME	流中工具的名称。

有关训练 C API 代码的更详细示例，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Training.HDRed\example_training_hdred.cpp”。

红色分析高细节快速训练 - .NET API

复制

Red High Detail Quick Training with .NET API

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

要训练红色分析高细节快速，应将 ViDi2.Training.ITool.Type 设置为 ToolType.RedQuickHighDetail。

要为红色分析高细节快速配置工具参数，应设置 ViDi2.Training.IRedHighDetailParameters。例如，应为 IRedHighDetailParameters 设置 CountEpochs 的值。

有关训练 .NET API 代码的更详细示例，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Training.HDRed.Console\Program.cs”。

红色分析高细节快速处理 - C API

使用 API 处理红色分析高细节快速的方式与红色分析聚焦监督和红色分析高细节相同。有关详细信息，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c++\Example.Runtime.Red\example_runtime_red.cpp”。

红色分析高细节快速处理 - .NET API

使用 API 处理红色分析高细节快速的方式与红色分析聚焦监督和红色分析高细节相同。有关详细信息，请参阅“C:\ProgramData\Cognex\VisionPro Deep Learning\2.1\Examples\c#\Example.Runtime.HDRed.Console\Program.cs”。