开发指南¶

句柄创建¶

要使用 SaigeVision 推理功能，需要一个推理句柄和一个结果句柄。

推理句柄可以从训练过的模型文件中创建。当推理句柄创建 API 成功调用时，模型文件中的所有信息都会加载到推理句柄中，以便后续的推理操作使用。

std::string trainedModelPath = "your_model_path.saigeiad";
int deviceIndex = 0;
SaigeInferenceHandle handle = nullptr;
SaigeHandleConfig config;
SaigeCreateInferenceHandle(
    &handle, kProjectTypeIAD, trainedModelPath.c_str(), deviceIndex, &config, 0
    );

(通用) 批量大小设置

如果要对多张图像进行批量推理，请调整推理句柄设置，并使用 'SAIGE_SET_BATCH_SIZE' 标志。

std::string trainedModelPath = "your_model_path.saigeiad";
int deviceIndex = 0;
SaigeInferenceHandle handle = nullptr;
SaigeHandleConfig config;
config.batchSize = 2;
SaigeCreateInferenceHandle(
    &handle, kProjectTypeIAD, trainedModelPath.c_str(), deviceIndex, &config, SAIGE_SET_BATCH_SIZE
    );

(通用) 应用推理优化

为了提高推理速度，请使用 'SAIGE_OPTIMIZE_HANDLE' 标志来应用推理优化。

std::string trainedModelPath = "your_model_path.saigeiad";
int deviceIndex = 0;
SaigeInferenceHandle handle = nullptr;
SaigeHandleConfig config;
SaigeCreateInferenceHandle(
    &handle, kProjectTypeIAD, trainedModelPath.c_str(), deviceIndex, &config, SAIGE_OPTIMIZE_HANDLE
    );

(SEG) 设置检测尺寸

如果项目类型是分割（Segmentation），可以指定检测尺寸。修改推理句柄设置，并使用 'SAIGE_SET_INSPECTION_SIZE' 标志。

std::string trainedModelPath = "your_model_path.saigeseg";
int deviceIndex = 0;
SaigeInferenceHandle handle = nullptr;
SaigeHandleConfig config;
config.inspectionSizeWidth = 512;
config.inspectionSizeHeight = 512;
SaigeCreateInferenceHandle(
    &handle, kProjectTypeSEG, trainedModelPath.c_str(), deviceIndex, &config, SAIGE_SET_INSPECTION_SIZE
    );

有关检测尺寸的详细说明，请参阅 SaigeHandleConfig

结果句柄用于存储和检索推理结果。使用推理 API 时，结果将存储在结果句柄中，可通过推理结果 API 访问。

SaigeInferenceResult result = nullptr;
SaigeCreateInferenceResult(&result);

更多关于句柄创建的详细信息，请参阅 SaigeVision API 文档中的 句柄创建。

检查模型信息（可选）¶

可以从推理句柄中检索在训练期间设置的模型信息。SaigeModelInfo 是一个结构，通过其成员变量轻松访问模型详细信息。

SaigeInferenceHandle handle = ...;
SaigeModelInfo modelInfo;
SaigeGetModelInfo(handle, &modelInfo);

std::cout << "网络类型: " << modelInfo.networkType << std::endl;
std::cout << "类别数量: " << modelInfo.numOfClasses << std::endl;
std::cout << "训练开发者版本: " << modelInfo.developerVersion << std::endl;

跳过模型信息检查不会影响推理性能。

有关模型相关的 SaigeVision API 的更多详细信息，请参阅 模型信息

检查和设置推理选项（可选）¶

可以从推理句柄中检索推理选项。SaigeInferenceOption 是一个结构，通过其成员变量轻松访问推理选项。

SaigeInferenceHandle handle = ...;
SaigeInferenceOption options;
SaigeGetInferenceOption(handle, &options);

std::cout << "计算时间: " << (options.calcTime ? "True" : "False") << std::endl;
std::cout << "异常分数阈值: (" << options.anomalyScoreThreshold << ")" << std::endl;
std::cout << "计算掩码: " << (options.calcMask ? "True" : "False") << std::endl;
std::cout << "对象边界阈值: (" << options.objectBoundaryThreshold << ")" << std::endl;

也可以设置新的推理选项。更新选项后，加载到推理句柄的值将被修改并在推理期间应用。

如需设置新选项，请在 SaigeInferenceOption 结构的成员变量中填入所需的值，并调用推理选项设置 API。确保根据当前项目类型和您想配置的选项指定适当的标志。

SaigeInferenceHandle handle = ...;
SaigeInferenceOption options;
options.calcHeatmap = true;
unsigned int flags = SAIGE_SET_CALC_HEATMAP;
SaigeSetInferenceOption(handle, &options, flags);

如果希望覆盖存储在模型文件中的值，请添加 SAIGE_WRITE_ON_MODEL_FILE 标志。

SaigeInferenceHandle handle = ...;
SaigeInferenceOption options;
options.calcHeatmap = true;
unsigned int flags = SAIGE_SET_CALC_HEATMAP | SAIGE_WRITE_ON_MODEL_FILE;
SaigeSetInferenceOption(handle, &options, flags);

跳过检查和设置推理选项的过程不会影响推理性能。

有关推理选项相关的 SaigeVision API 的更多详细信息，请参阅 推理选项

推理¶

推理是使用推理句柄、结果句柄和图像来完成的。

有三种将图像传递给推理 API 的方式，每种方式都有相应的 API：

可以使用图像文件路径进行推理。

SaigeInferenceHandle handle = ...;
SaigeInferenceResult result = ...;
std::string imagePath = "your_image_path.png";
SaigeInferFromImageFile(handle, imagePath.c_str(), result);

可以使用表示为 unsigned char 数组的单个图像数据进行推理。为获得准确的结果，请确保图像宽度、高度和标志设置正确。

SaigeInferenceHandle handle = ...;
SaigeInferenceResult result = ...;
unsigned char* image = ...;
int w = ..., h = ...;
unsigned int flags = SAIGE_IMAGE_DATA_FLAG_COLOR;
SaigeInferFromByteArray(handle, image, w, h, flags, result);

可以使用表示为二维 unsigned char 数组的图像数据进行批量推理。批次中的所有图像必须具有相同的宽度和高度。同样，请正确设置宽度、高度和标志以获得准确结果。

int batchSize = ...;
SaigeInferenceHandle handle = ...;
SaigeInferenceResult* batchResults = ...;
unsigned char** batchImages = ...;
int w = ..., h = ...;
unsigned int flags = SAIGE_IMAGE_DATA_FLAG_COLOR;
SaigeInferFromMultipleByteArray(handle, batchSize, batchImages, w, h, flags, batchResults);

可以通过 unsigned short 数组处理 16 位深度的图像。使用示例中的实用函数 SaigeGetImageData 和 SaigeConvertImageType 来确定图像类型，并获取用于推理函数的适当标志。调用时，将数据类型转换为 const unsigned char*。

SaigeInferenceHandle handle = ...;
SaigeInferenceResult result = ...;
int w, h, c, type;
void* image_ptr = SaigeGetImageData(path, &w, &h, &c, &type);
if (type == SaigeImageType::U16){
    unsigned short* image_data = image_ptr;
    for(int i=0; i<h; ++i){
        for(int j=0; j<w; ++j){
            for(int k=0; k<c; ++k){
                image_data[i*w*c + j*c + k] ... // image operation
            }

        }
    }
}
unsigned int imageFlag = SaigeConvertImageType(c, type);
int retval = SaigeInferFromByteArray(handle, (const unsigned char*)image_ptr, w, h, imageFlag, result);

在推理中，可以更详细地了解与 SaigeVision 推理相关的 API。

推理结果¶

推理成功完成后，可以从结果句柄中检索结果信息。

根据所需的特定结果项使用适当的 API。例如，检索 IAD 推理结果中图像正常性状态的 API 与检索分数的 API 不同。

SaigeInferenceResult result = ...;
bool isNg;
SaigeGetInferenceResultIsNg(result, &isNg);

double anomalyScore, scoreMin, scoreMax;
SaigeGetInferenceResultAnomalyScores(result, &anomalyScore, &scoreMin, &scoreMax);

对于具有多个值的结果项，首先检索结果计数，然后获取每个值。

int numSegObj;
std::vector<SaigeSegmentedObject> segObjs;
SaigeGetInferenceResultNumOfSegmentedObjects(result, &numSegObj);
segObjs.resize(numSegObj);
SaigeGetInferenceResultSegmentedObjects(result, segObjs.data());

更多有关推理结果的 SaigeVision API 详细信息，请参阅 推理结果

句柄销毁¶

完成所有推理操作后，销毁推理和结果句柄以释放分配的内存并防止内存泄漏。

SaigeInferenceHandle handle = ...;
SaigeInferenceResult result = ...;
SaigeDestroyInferenceHandle(handle);
SaigeDestroyInferenceResult(result);

有关句柄销毁的更多 SaigeVision API 信息，请参阅 句柄销毁。