Segmentation

이 문서는 SaigieVision을 통해 이미지를 'Segmentation(분할)' 하는 방법에 대해 설명합니다.

'Segmentation' 검사를 살펴보기 전에, 'Classification'과 'Detection' 검사에 대한 내용을 먼저 읽어 보길 권장합니다.

'Segmentation'은 다른 검사들과 비슷한 흐름을 가지나 약간 특별한 요소들을 가지고 있습니다. 또한 'Classification' 혹은 'Detection' 검사를 충분히 이해하지 못한 상태라면, 'Segmentation' 검사에 사용되는 SegInspectionOptions와 SegmentationEngine.Inspect()는 다소 어렵게 느껴질 수 있습니다.

아래 코드 블럭은 간단하게 Segmentation 검사 진행 방법에 대해서 설명합니다.

{
    //Initialize
    SaigeVision.Core.SaigeVisionApp.Init();

    //Prepare
    var gpuService = new NvGpuService();
    gpuService.DetectConnectedGPUs();

    SrImage sample = new SrImage("../../sample.jpg");
    var modelUri = new Uri(@"../../../model.srSeg");

    //Inspect
    using (SegmentationEngine segEngine = EngineLoader.LoadFrom<SegmentationEngine>(modelUri))
    {
        SegInspectionOptions option = segEngine.ReadInspectionOptions();
        option.TimeLimit = default;
        option.ContourOptions.SaveCroppedPatch = true;

        segEngine.AllocateNetwork(gpuService.CurrentDetectedGPUs[0], option);

        SegmentationReport<SegContourResult> report = segEngine.Inspect<SegContourResult>(sample);
    }

    //clean up (optional)
    sample.DisposeAll();
}

Initialize

SaigeVision.Core를 사용하기 위해서는 런타임에 돌입하는 시점에서 1회 SaigeVisionApp.Init()을 통해 SaigeVision.Core를 초기화해야 합니다.

초기화를 진행하기 적절한 장소는 작성중인 애플리케이션의 main() 함수 최상단입니다.

여러분이 Console App이 아닌 다른 플랫폼을 사용하여 main()함수를 찾기 어렵다면 (WPF, WinForms 와 같은...) 어느 위치라도 좋으나 오직 '단 한번' 호출 하는것을 보장하는 장소가 좋습니다.

또한, EngineLoader를 사용하기 전이어야 합니다.

Prepare

SegmentationEngine을 사용하기 위해 필요한 모든 데이터를 준비하는 과정입니다.
일반적으로 아래와 같은 3가지를 요구합니다.

• 검사에 사용할 GPU
• 검사에 사용할 샘플 이미지들
• 검사에 사용할 모델( .srSeg 파일)

SaigeVision은 NVIDIA사의 GPU만을 지원하고 있습니다.

또한, SaigeVision은 모든 이미지 개체를 SrImage를 통해 전달 받고 있습니다.
SrImage는 내부적으로 ArrayPool<T>과 같은 .Net의 도구들을 통해 성능 최적화를 이루는데 많은 노력을 기울였습니다.

다양한 생성자를 지원하니 꼭 SrImage에 대한 API docs 확인을 권장합니다.

Inspection

'Inspection'부는 SegmentationEngine을 EngineLoader를 통해 로드하는 것으로 시작합니다.
'Inspection'부는 알아보기 쉽게 아래와 같이 절차를 구분하여 설명하겠습니다.

1. Load engine

이 예제에서는 사용의 안전을 위해 C# 언어의 using 문을 사용합니다.
여러분의 시나리오에서 해당 using문 사용이 알맞지 않다고 생각한다면, 무시 할 수 있습니다.
하지만 using문을 사용하지 않는 경우, 사용이 완료된 SegmentationEngine은 반드시 관리 하에 SegmentationEngine.Dispose() 되어야합니다.

• EngineLoader.LoadFrom<T>()는 완료하는데 약간이 시간이 소요 될 수 있습니다. 이는 일반적으로 Thread가 Blocking 될 수 있는 정도의 수준입니다.

2. Inspection Options

다시 샘플 코드의 설명으로 돌아가면, 샘플 코드는 Engine을 로드하고 나서 해당 Engine을 통해 SegInspectionOptions를 로드하고 있습니다.

SegInspectionOptions option = segEngine.ReadInspectionOptions();
option.TimeLimit = default;
option.ContourOptions.SaveCroppedPatch = true;

SegmentationEngine은 Inspection을 수행할 때 여러가지 옵션을 지정할 수 있습니다.
해당 옵션들은 실제 Inspection을 수행하는데 영향을 주며, 레포트(결과)에 반영됩니다.

이 예제에서는 뒤에 이어지는 코드에서 보이는것 처럼, 몇가지 검사 옵션들을 지정하고 있습니다. Segmentation 검사는 다른 검사와 다르게 많은 검사 옵션들을 포함하고 있습니다.

그 중에서도 지금 살펴 볼 옵션은 ContourInspectionOptions입니다.

SegmentationEngine의 Inspect() 함수는 다른 'Engine'들과 다르게 반환받고자 하는 결과 종류의 선택할 수 있습니다. 선택 할 수 있는 결과 종류는 총 2개로 SegContourResult와 SegScoremapResult입니다. 이 예제에서는 SegContourResult를 사용하였습니다. (engine.Inspect(data))

다시 Option 이야기로 돌아가자면, ContourInspectionOptions는 SegContourResult로 결과를 반환 받을 때 적용되는 검사 옵션입니다.

이 예제에서는 ContourOptions.SaveCroppedPatch = true;를 지정하여, 결과를 레포트 받을때 검출된 Contour 영역의 이미지를 잘라서 반환 받는 기능을 활성화 시켰습니다. 이 옵션을 활성화 하면 Inspect() 함수로 반환받는 레포트에 잘라진 영역의 이미지 값이 포함됩니다.(이미지 개체)

SegmentationOptions가 지원하는 옵션은 해당 API Docs를 확인하세요.

이렇게 만들어진 새로운 옵션은(SegmentationOptions)는 Engine의 AllocateNetowrk()를 통해 주입이 가능합니다.

• 이후 진행되는 모든 'Inspection'의 결과는 해당 Option이 적용된 값입니다.

특정한 시나리오에서는 이렇게 설정한 Option 값을 모델에 기록할 필요가 있을 수 있습니다.
사실 LoadInspectionOptions()는 모델에 기록된 제일 최근의 Option 값을 로드하는 함수입니다.

여러분이 해당 Option을 모델에 기록하길 원한다면 WirteInspectionOptions()를 사용하세요.
또한, WriteInspectionOptionsAsDefault()를 통해 Default options로 되돌릴 수 있습니다.

• 만약 AllocateNetowrk()를 통해 Options를 지정하지 않는다면, 자동적으로 모델에 기록되어있는 Option을 사용합니다.

• AllocateNetowrk()는 약간의 시간이 소요될 수 있습니다. 일반적으로 Thread가 Blocking될 수 있는 수준입니다.

3. Inspect

앞서 언급했던대로, SegmentationEngine의 Inspect(SrImage) 함수는 다른 Engine들의 것들과 조금 차이가 있습니다.

SegmentationReport<SegContourResult> report = segEngine.Inspect<SegContourResult>(sample);

기본적으로 제공되는 함수는 Inspect<T>(SrImage)로, 전달 받고자 하는 결과 타입을 Generic 형식으로 지정받고 있습니다.

그리고 Generic T에 지정할 수 있는 형식은 다음과 같습니다.

SegScoremapResult : 검출된 Scoremap 데이터를 표현합니다.
SegContourResult : 검출된 Contour 데이터를 표현합니다.

여러분은 위 2가지 타입중 반환 받길 원하는 것을 지정 할 수 있습니다. 만약 여러분의 시나리오에서 2가지 모두 필요하다면 Inspect<T1, T2>(SrImage)를 사용하세요.

Inspect<T>(SrImage)가 반환하는 SegmentationReport는 검사를 진행한 후 전달해야 하는 모든 결과를 레포트합니다.

Clean up (Optional)

이 예제에서는 검사에 사용했던 SrImage들을 더 이상 사용할 곳이 없이게 Dispose() 합니다.

많은 수의 이미지를 한번에 검사

'Segmentation' 기능은 'Classification' 기능과 동일하게 '많은 수의 이미지'를 한번에 검사하는 기능을 제공합니다. 사용법은 'Classification'과 유사합니다.