Computer Vision API C# 자습서

등록일시: 2017-11-21 08:00,  수정일시: 2018-01-25 07:23
조회수: 5,653
이 문서는 Cognitive Services 기술을 널리 알리고자 하는 개인적인 취지로 제공되는 번역문서입니다. 이 문서에 대한 모든 저작권은 마이크로소프트에 있으며 요청이 있을 경우 언제라도 게시가 중단될 수 있습니다. 번역 내용에 오역이 존재할 수 있고 주석은 번역자 개인의 의견일 뿐이며 마이크로소프트는 이에 관한 어떠한 보장도 하지 않습니다. 번역이 완료된 이후에도 대상 제품 및 기술이 개선되거나 변경됨에 따라 원문의 내용도 변경되거나 보완되었을 수 있으므로 주의하시기 바랍니다.
본문에서는 Computer Vision API를 활용하는 기초적인 WPF 예제 응용 프로그램을 살펴봅니다.

본 자습서에서는 Computer Vision API를 이용해서 광학 문자 인식(OCR)을 수행하거나 스마트하게 자른 썸네일을 생성하고, 이미지에서 얼굴을 비롯한 다양한 시각적 특징들을 감지해서 분류하고, 태깅하고, 설명하는 기초적인 Windows 응용 프로그램을 살펴봅니다. 본문의 예제 응용 프로그램은 이미지의 URL을 전달하거나 로컬에 저장된 이미지 파일을 제출하는 방식으로 동작합니다. 이 오픈 소스 예제 응용 프로그램을 템플릿으로 삼아서 Vision API와 .NET 프레임워크의 일부인 WPF(Windows Presentation Foundation)를 활용하는 자신만의 개별 Windows 응용 프로그램을 개발해도 무방합니다.

요구 사항

플랫폼 요구 사항

본문의 예제는 Visual Studio 2015, Community 에디션을 사용해서 .NET Framework로 개발되었습니다.

Computer Vision API 구독 및 구독 키 발급받기

예제 응용 프로그램을 직접 실행해보려면, 먼저 Microsoft Cognitive Services의 (구 프로젝트 Oxford) 일부인 Computer Vision API에 가입해야 합니다. 구독 및 구독 키 관리에 관한 세부적인 사항들은 Cognitive Services 체험하기 페이지를 참고하시기 바랍니다. 본 자습서에서는 발급된 기본 키와 보조 키, 모두 사용 가능합니다.

노트

본 자습서는 westcentralus 지역의 구독 키를 사용하도록 설계됐습니다. 기본적으로 Computer Vision 무료 평가판 서비스를 통해서 발급받은 구독 키는 westcentralus 지역에서만 유효하기 때문에, 해당 지역을 사용해야만 정상적으로 동작합니다. 만약, 여러분의 Azure 계정을 사용해서 https://azure.microsoft.com/en-us/에서 구독 키를 생성했다면 westcentralus 지역을 지정해야 합니다. westcentralus 이외의 지역에서 생성된 구독 키는 동작하지 않습니다.

역주

자습서 예제 프로젝트의 소스를 검색해서 VisionServiceClient 클래스 생성자에 전달되는 URL의 지역을 변경하면 다른 지역에서 발급받은 구독 키도 사용할 수 있습니다. 또한 VisionServiceClient 클래스 생성자 중, 구독 키 하나만 전달받는 오버로드를 API 루트의 URL까지 전달 받는 오버로드로 모두 변경해야 합니다.

클라이언트 라이브러리 및 예제 가져오기

SDK를 통해서 Computer Vision API 클라이언트 라이브러리와 예제 응용 프로그램을 로컬 컴퓨터에 복제할 수 있습니다. ZIP 파일로 다운로드 받지 마십시오.

역주

ZIP 파일을 다운로드 받아도 문제는 없습니다. 다만 사용한 복제 또는 다운로드 방식에 따라서, Visual Studio로 복제한 솔루션을 열었을 때, SampleUserControlLibrary 프로젝트가 누락됐다고 표시되고 빌드 역시 실패하는 경우가 있습니다. 이 누락된 프로젝트는 다양한 Cognitive Services 관련 예제 프로젝트들에서 함께 공유되는 프로젝트로 이런 상황이 발생할 경우, 약간의 추가 작업을 필요로 합니다.

Cognitive-Common-Windows의 소스 코드를 ZIP 파일로 다운로드 받은 다음, 압축을 풉니다. 그리고 하위의 SampleUserControlLibrary 폴더를 자습서 예제 프로젝트 폴더의 Cognitive-Common-Windows 폴더 하위에 복사한 다음, 솔루션 탐색기에서 프로젝트를 다시 로드하면 됩니다.

또 다른 방법은 git submodule init 명령과 git submodule update 명령을 이용해서 서브 모듈을 복제하는 것입니다. 보다 자세한 설명은 GitHub 문서의 Build the sample 절을 참고하시기 바랍니다.

마지막으로 Visual Studio 최신 버전을 사용해서 Git 저장소를 복제할 때, "재귀적으로 하위 모듈 복제" 옵션을 선택하고 복제를 수행하면 필요한 하위 모듈들이 모두 복제됩니다.

단계 1: 예제 설치하기

  • GitHub Desktop에서 Sample-WPF\VisionAPI-WPF-Samples.sln 파일을 엽니다.

단계 2: 예제 빌드하기

  • Ctrl+Shift+B 단축키를 누르거나, 리본 메뉴에서 빌드(Build)를 클릭한 다음, 솔루션 빌드(Build Solution)를 선택합니다.

단계 3: 예제 실행하기

  1. 빌드가 완료되면, F5 키를 누르거나, 리본 메뉴에서 시작(Start) 버튼을 클릭해서 예제 응용 프로그램을 실행합니다
  2. 예제 응용 프로그램이 실행되면, "Paste your subscription key here to start"라는 메시지가 표시된 텍스트 편집 상자를 포함하고 있는 Computer Vision API 사용자 인터페이스 창이 나타납니다. 이 텍스트 편집 상자에 구독 키를 입력하고 "Save Key" 버튼을 클릭하면, PC나 노트북에 구독 키를 저장해 놓을 수 있습니다. 반대로 시스템에서 구독 키를 삭제하고 싶다면, "Delete Key" 버튼을 클릭해서 PC나 노트북에서 구독 키를 제거합니다.

    Vision Subscription Key

    역주

    예제 응용 프로그램의 UI에 일부 변경이 있지만, 동작 방식은 동일합니다.

  3. 좌측에 위치한 "Select Scenario" 라벨 하위의 6 가지 시나리오 중 하나를 클릭한 다음, 화면의 지시 사항에 따르면 기능을 테스트할 수 있습니다. 참고로 Microsoft는 여러분이 예제 응용 프로그램을 통해서 업로드 한 이미지를 Computer Vision API 및 관련 서비스를 개선하기 위해서 활용할 수 있습니다. 여러분이 이미지를 업로드해서 제출할 경우, Microsoft의 개발자 준수 사항을 승인한 것으로 간주된다는 점에 유의하시기 바랍니다.

    Analyze Image Interface

  4. 예제 응용 프로그램과 함께 사용할 수 있는 예제 이미지도 제공됩니다. 이 이미지들은 Face API Windows Github 저장소의 Data 폴더에서 확인할 수 있습니다. 이 이미지들은 LICENSE-IMAGE 계약에 의거 라이센스가 부여된다는 점에 주의하시기 바랍니다.

검토 및 학습하기

이제 예제 응용 프로그램을 실행하기 위한 준비를 마쳤으므로, 계속해서 예제 응용 프로그램이 어떤 방식으로 Cognitive Services 기술과 통합되는지 살펴보겠습니다. 이 과정을 거치고 나면 예제 응용 프로그램을 더욱 개선하거나 Microsoft Computer Vision API를 사용해서 직접 응용 프로그램을 개발하는 작업이 더 수월해질 것입니다.

본 자습서의 예제 응용 프로그램은 Microsoft Visual Vision API의 간단한 C# 클라이언트 래퍼인 Computer Vision API 클라이언트 라이브러리를 사용합니다. 이전 절에서 설명한 방식으로 예제 응용 프로그램을 빌드하면 NuGet 패키지를 통해서 이 클라이언트 라이브러리를 가져오게 됩니다. 참고로 클라이언트 라이브러리 및 예제 가져오기 절에서 살펴본, 다운로드한 파일 저장소의 일부분인 "Client Library" 폴더에서 클라이언트 라이브러리의 소스 코드를 살펴볼 수도 있습니다.

이번에는 솔루션 탐색기를 이용해서 클라이언트 라이브러리 코드를 사용하는 방법을 확인하겠습니다. 먼저 VisionAPI-WPF_Samples 프로젝트 하위의 AnalyzePage.xaml 노드를 확장해서, 이미지 분석 끝점에 이미지를 전송하는 작업을 수행하는 AnalyzePage.xaml.cs 파일을 찾습니다. 그런 다음, AnalyzePage.xaml.cs 파일을 더블 클릭해서 Visual Studio의 새 편집 창으로 엽니다.

예제 응용 프로그램이 Vision 클라이언트 라이브러리를 사용하는 방법을 살펴보기 위해서 찾아봐야 할 AnalyzePage.xaml.cs 파일의 코드 스니핏은 모두 두 부분입니다. 참고로 이 파일에는 다음에 제시된 코드 스니핏을 쉽게 찾을 수 있도록 "KEY SAMPLE CODE STARTS HERE"와 "KEY SAMPLE CODE ENDS HERE"라는 코드 주석이 추가되어 있습니다.

이미지 분석 끝점은 이미지의 URL 또는 이진 이미지 데이터(8비트 스트림 형식)를 입력으로 사용합니다. 먼저, Vision 클라이언트 라이브러리를 사용하기 위한 using 지시문은 다음과 같습니다.

// ----------------------------------------------------------------------
// KEY SAMPLE CODE STARTS HERE
// Use the following namespace for VisionServiceClient 
// ----------------------------------------------------------------------
using Microsoft.ProjectOxford.Vision; 
using Microsoft.ProjectOxford.Vision.Contract; 
// ----------------------------------------------------------------------
// KEY SAMPLE CODE ENDS HERE 
// ----------------------------------------------------------------------

UploadAndAnalyzeImage(…) 이 코드 스니핏은 클라이언트 라이브러리를 사용해서 구독 키와 로컬에 저장된 이미지의 스트림을 Computer Vision API 서비스의 분석 끝점에 전송하는 방법을 보여줍니다.

private async Task<AnalysisResult> UploadAndAnalyzeImage(string imageFilePath)
{
    // -----------------------------------------------------------------------
    // KEY SAMPLE CODE STARTS HERE
    // -----------------------------------------------------------------------  

    //
    // Create Project Oxford Computer Vision API Service client
    //
    VisionServiceClient VisionServiceClient = new VisionServiceClient(SubscriptionKey, "https://westcentralus.api.cognitive.microsoft.com/vision/v1.0");
    Log("VisionServiceClient is created");

    using (Stream imageFileStream = File.OpenRead(imageFilePath))
    {
        //
        // Analyze the image for all visual features
        //
        Log("Calling VisionServiceClient.AnalyzeImageAsync()...");
        VisualFeature[] visualFeatures = new VisualFeature[] { VisualFeature.Adult, VisualFeature.Categories, VisualFeature.Color, VisualFeature.Description, VisualFeature.Faces, VisualFeature.ImageType, VisualFeature.Tags };
        AnalysisResult analysisResult = await VisionServiceClient.AnalyzeImageAsync(imageFileStream, visualFeatures);
        return analysisResult;
    }

    // -----------------------------------------------------------------------
    // KEY SAMPLE CODE ENDS HERE
    // -----------------------------------------------------------------------
}

AnalyzeUrl(…) 이 코드 스니핏은 클라이언트 라이브러리를 사용해서 구독 키와 사진의 URL을 Computer Vision API 서비스의 분석 끝점에 전송하는 방법을 보여줍니다.

private async Task<AnalysisResult> AnalyzeUrl(string imageUrl)
{
    // -----------------------------------------------------------------------
    // KEY SAMPLE CODE STARTS HERE
    // -----------------------------------------------------------------------

    //
    // Create Project Oxford Computer Vision API Service client
    //
    VisionServiceClient VisionServiceClient = new VisionServiceClient(SubscriptionKey);
    Log("VisionServiceClient is created");

    //
    // Analyze the url for all visual features
    //
    Log("Calling VisionServiceClient.AnalyzeImageAsync()...");
    VisualFeature[] visualFeatures = new VisualFeature[] { VisualFeature.Adult, VisualFeature.Categories, VisualFeature.Color, VisualFeature.Description, VisualFeature.Faces, VisualFeature.ImageType, VisualFeature.Tags };
    AnalysisResult analysisResult = await VisionServiceClient.AnalyzeImageAsync(imageUrl, visualFeatures);
    return analysisResult;

    // -----------------------------------------------------------------------
    // KEY SAMPLE CODE ENDS HERE
    // -----------------------------------------------------------------------
}

그 밖의 페이지 및 끝점들 Computer Vision API 서비스에서 제공되는 다른 끝점들과 상호 작용하는 방법은 예제 응용 프로그램의 다른 페이지들을 살펴보면 확인할 수 있습니다. 가령, OCR 끝점을 사용하는 방법은 OCRPage.xaml.cs 페이지의 코드에서 확인할 수 있습니다.

관련 자료