개발 가이드¶

핸들 생성¶

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

(Common) Batch size 설정

여러 이미지를 모아 배치 추론을 하고 싶다면, 추론 핸들 설정을 바꾸고 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
    );

(Common) 추론 최적화 적용

추론 최적화를 적용하여 더 빠른 속도로 추론을 수행하고 싶다면, 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) Inspection size 설정

프로젝트 타입이 Segmentation일 경우 inspection size를 지정할 수 있습니다. 추론 핸들 설정을 바꾸고 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
    );

Inspection size에 대한 상세한 설명은 SaigeHandleConfig를 확인하시기 바랍니다.

결과 핸들은 추론 결과를 저장하고 받아 오는 데 사용됩니다. 추론 API를 사용할 때 결과 핸들에 추론 결과를 저장하며, 이후 추론 결과 API를 사용하여 결과 정보를 받아 올 수 있습니다.

SaigeInferenceResult result = nullptr;
SaigeCreateInferenceResult(&result);

핸들 생성에서 핸들 생성과 관련된 SaigeVision API를 더 자세히 살펴볼 수 있습니다.

모델 정보 확인(Optional)¶

추론 핸들로부터 학습 시 설정한 모델 정보를 불러 올 수 있습니다. SaigeModelInfo는 구조체로, 멤버 변수에 접근하여 모델 정보를 쉽게 확인할 수 있습니다.

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

std::cout << "Network Type: " << modelInfo.networkType << std::endl;
std::cout << "Number of Classes: " << modelInfo.numOfClasses << std::endl;
std::cout << "Trained Developer Version: " << modelInfo.developerVersion << std::endl;

모델 정보 확인 과정을 거치지 않아도 추론을 수행하는 데에는 문제가 없습니다.

모델 정보에서 모델 정보와 관련된 SaigeVision API를 더 자세히 살펴볼 수 있습니다.

추론 옵션 확인 및 설정(Optional)¶

추론 핸들로부터 추론 옵션을 불러 올 수 있습니다. SaigeInferenceOption은 구조체로, 멤버 변수에 접근하여 추론 옵션을 쉽게 확인할 수 있습니다.

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

std::cout << "Calc Time: " << (options.calcTime ? "True" : "False") << std::endl;
std::cout << "Anomaly Score Threshold: (" << options.anomalyScoreThreshold << ")"
            << std::endl;
std::cout << "Calc Mask: " << (options.calcMask ? "True" : "False") << std::endl;
std::cout << "Object Boundary Threshold: (" << options.objectBoundaryThreshold << ")"
            << std::endl;

추론 옵션을 새롭게 설정할 수도 있습니다. 새로운 옵션 값을 설정하면 추론 핸들에 로드되어 있던 옵션 값이 수정되어 추론에 반영됩니다.

SaigeInferenceOption 구조체의 멤버 변수에 원하는 값을 넣어 준 뒤, 추론 옵션 설정 API를 호출해 주세요. 현재 프로젝트 타입 및 설정하고자 하는 옵션 항목에 따라 플래그를 알맞게 지정해 주어야 합니다.

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

여러 추론 옵션을 한번에 설정할 때에는 각 플래그를 비트 연산자 OR (|)을 이용해 연결해 주세요.

SaigeInferenceHandle handle = ...;
SaigeInferenceOption options;
options.calcHeatmap = true;
options.calcObject = true;
options.calcObjectAreaAndApplyThreshold = true;
options.calcObjectScoreAndApplyThreshold = true;
unsigned int flags = SAIGE_SET_CALC_HEATMAP | SAIGE_SET_CALC_OBJECT |
                    SAIGE_SET_CALC_OBJECT_AREA_AND_APPLY_THRESHOLD |
                    SAIGE_SET_CALC_OBJECT_SCORE_AND_APPLY_THRESHOLD;
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 2차원 배열로 표현되는 배치 이미지 데이터를 통해 추론을 수행할 수 있습니다. 배치에 속하는 이미지들의 너비와 높이는 모두 같아야 합니다. 정확한 결과를 얻으려면 이미지의 너비와 높이, 그리고 플래그를 올바르게 설정해 주세요.

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 배열을 통해 16bit depth를 가지는 이미지를 다룰 수 있습니다. 예제의 Util함수 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와 score 값을 받아 오는 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를 더 자세히 살펴볼 수 있습니다.