Computer Vision cURL 퀵 스타트

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

본문에서는 cURL과 Computer Vision API를 사용해서 다음과 같은 작업을 신속하게 수행하기 위해 필요한 유용한 정보와 예제 코드를 제공합니다:

무료 구독 키를 발급받는 방법은 Computer Vision API 구독 키 발급받기 문서를 참고하시기 바랍니다.

역주

본문에서는 본격적인 프로그래밍 언어를 사용해서 Computer Vision API를 사용하는 방법을 살펴보기에 앞서, 먼저 cURL이라는 명령줄 도구를 사용합니다. 이 도구에 친숙하지 않은 분들을 위해서 간단히 설명드리면 다양한 프로토콜을 이용해서 통신을 수행하는, 마치 Fiddler 같은 역할을 하는 명령줄 도구라고 생각하시면 이해가 쉽습니다. HTTP, HTTPS, FTP, FTPS, Gopher, IMAP, IMAPS 등 수십 여 가지에 달하는 프로토콜을 지원하고, 다양한 운영 체제에서 사용할 수 있기 때문에 본격적인 코드를 작성하기에 앞서 테스트를 해보거나 API의 응답 내역 등을 확인하는 작업에 유용합니다.

cURL에 대한 보다 자세한 정보는 공식 홈페이지위키피디아를 참고하시기 바랍니다. 또한 cURL의 한글 메뉴얼과 설치 방법 등은 정광섭님이 정리하신 curl 설치 및 사용법 - HTTP GET/POST, REST API 연계등 문서를 추천드립니다. 특히 해당 문서의 설치 절을 참고하시면 Windows용으로 빌드된 cURL을 다운로드 받을 수 있는 위치를 알 수 있습니다.

cURL을 이용해서 Computer Vision API로 이미지 분석하기

이미지 분석 메서드를 사용하면 이미지 내용에 기반한 시각적 특징들을 추출해낼 수 있습니다. 이미지를 업로드하거나 이미지의 URL을 지정하고, 다음 중 어떤 시각적 특징을 반환할지 선택하면 됩니다:

  • 86 가지 범주 분류에 정의된 범주
  • 이미지 내용에 관한 태그들의 상세한 목록
  • 이미지 내용에 관한 완전한 문장으로 구성된 설명
  • 이미지에 포함된 얼굴의 좌표, 성별 및 나이
  • 이미지 유형 (클립아트 또는 선 그리기)
  • 지배적 색상, 강조색 또는 이미지의 흑백 여부
  • 이미지에 포르노 또는 음란물이 포함되어 있는지 여부

이미지 분석 curl 요청 예제

예제에서 사용하는 URL을 구독 키를 발급받은 지역의 주소로 변경하고, "Ocp-Apim-Subscription-Key"의 값을 여러분이 발급받은 유효한 구독 키로 대체합니다.

노트

REST 호출 시 반드시 구독 키를 발급받은 위치와 동일한 위치의 주소를 사용해야 합니다. 가령 westus 지역에서 구독 키를 발급받았다면, 아래 예제 코드의 URL에서 "westcentralus"를 "westus"로 변경해야 합니다.

@ECHO OFF

curl -v -X POST "https://westcentralus.api.cognitive.microsoft.com/vision/v1.0/analyze?visualFeatures=Categories&details={string}&language=en"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"
역주

본문의 모든 cURL 예제는 명령줄에 한 줄로 입력해야 하며, --data-ascii 줄도 마찬가지입니다. 본문의 예제들은 cURL 명령어가 너무 길기 때문에 가독성을 위해서 정리된 것입니다. 또한 @ECHO OFF 명령은 그냥 무시하는 것을 권해드립니다. 그리고 --data-ascii 줄의 "{body}" 부분에는 "{'url':'http://<image url>'}"과 같이 작업 대상 이미지의 경로를 JSON 형식으로 지정하면 됩니다. 가령 이번 예제의 경우, details 쿼리 매개 변수를 지정하지 않는다고 가정할 때 다음과 같이 입력하게 됩니다. 또한, 구독 키를 헤더에 지정해서 전달하는 방법에 유의하시기 바랍니다.

curl -v -X POST "https://eastasia.api.cognitive.microsoft.com/vision/v1.0/analyze?visualFeatures=Categories" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: <subscription key>" --data-ascii "{'url':'<image url>'}"

이미지 분석 결과 응답 살펴보기

정상적으로 처리된 응답은 JSON 형식으로 반환됩니다. 다음은 성공한 응답의 사례입니다:

{
  "categories": [
    {
      "name": "abstract_",
      "score": 0.00390625
    },
    {
      "name": "people_",
      "score": 0.83984375,
      "detail": {
        "celebrities": [
          {
            "name": "Satya Nadella",
            "faceRectangle": {
              "left": 597,
              "top": 162,
              "width": 248,
              "height": 248
            },
            "confidence": 0.999028444
          }
        ]
      }
    }
  ],
  "adult": {
    "isAdultContent": false,
    "isRacyContent": false,
    "adultScore": 0.0934349000453949,
    "racyScore": 0.068613491952419281
  },
  "tags": [
    {
      "name": "person",
      "confidence": 0.98979085683822632
    },
    {
      "name": "man",
      "confidence": 0.94493889808654785
    },
    {
      "name": "outdoor",
      "confidence": 0.938492476940155
    },
    {
      "name": "window",
      "confidence": 0.89513939619064331
    }
  ],
  "description": {
    "tags": [
      "person",
      "man",
      "outdoor",
      "window",
      "glasses"
    ],
    "captions": [
      {
        "text": "Satya Nadella sitting on a bench",
        "confidence": 0.48293603002174407
      }
    ]
  },
  "requestId": "0dbec5ad-a3d3-4f7e-96b4-dfd57efe967d",
  "metadata": {
    "width": 1500,
    "height": 1000,
    "format": "Jpeg"
  },
  "faces": [
    {
      "age": 44,
      "gender": "Male",
      "faceRectangle": {
        "left": 593,
        "top": 160,
        "width": 250,
        "height": 250
      }
    }
  ],
  "color": {
    "dominantColorForeground": "Brown",
    "dominantColorBackground": "Brown",
    "dominantColors": [
      "Brown",
      "Black"
    ],
    "accentColor": "873B59",
    "isBWImg": false
  },
  "imageType": {
    "clipArtType": 0,
    "lineDrawingType": 0
  }
}

curl을 이용해서 Computer Vision API로 썸네일 이미지 생성하기

썸네일 생성 메서드를 사용하면 이미지의 관심 영역(ROI)을 중심으로 원하는 높이와 너비로 이미지를 자르고, 원본 이미지와 종횡비가 다른 썸네일을 생성할 수도 있습니다.

썸네일 이미지 생성하기 curl 요청 예제

예제에서 사용하는 URL을 구독 키를 발급받은 지역의 주소로 변경하고, "Ocp-Apim-Subscription-Key"의 값을 여러분이 발급받은 유효한 구독 키로 대체합니다.

노트

REST 호출 시 반드시 구독 키를 발급받은 위치와 동일한 위치의 주소를 사용해야 합니다. westus에서 구독 키를 발급받았다면, 다음 예제 코드의 URL에서 "westcentralus"를 "westus"로 변경해야 합니다.

@ECHO OFF

curl -v -X POST "https://westcentralus.api.cognitive.microsoft.com/vision/v1.0/generateThumbnail?width={number}&height={number}&smartCropping=true"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"

썸네일 응답 가져오기

정상적으로 성공한 응답에는 썸네일 이미지의 이진 데이터가 담겨서 반환됩니다. 반면 요청이 실패한 경우에는 오류 코드와 잘못된 사항을 확인하는데 도움이 되는 메시지가 응답에 포함됩니다.

curl과 Computer Vision API를 이용한 광학 문자 인식 (OCR)

광학 문자 인식 (OCR) 메서드를 사용하면 이미지에 포함된 텍스트를 인식하고 식별된 텍스트를 기계가 읽을 수 있는 문자 스트림으로 추출할 수 있습니다.

OCR curl 요청 예제

예제에서 사용하는 URL을 구독 키를 발급받은 지역의 주소로 변경하고, "Ocp-Apim-Subscription-Key"의 값을 여러분이 발급받은 유효한 구독 키로 대체합니다.

노트

REST 호출 시 반드시 구독 키를 발급받은 위치와 동일한 위치의 주소를 사용해야 합니다. westus에서 구독 키를 발급받았다면, 다음 예제 코드의 URL에서 "westcentralus"를 "westus"로 변경해야 합니다.

@ECHO OFF

curl -v -X POST "https://westcentralus.api.cognitive.microsoft.com/vision/v1.0/ocr?language=unk&detectOrientation=true"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"

OCR 결과 응답 살펴보기

성공 시 OCR 결과에는 텍스트, 영역의 경계를 이루는 사각형 좌표, 텍스트 라인 및 단어들이 포함되어 반환됩니다.

{
  "language": "en",
  "textAngle": -2.0000000000000338,
  "orientation": "Up",
  "regions": [
    {
      "boundingBox": "462,379,497,258",
      "lines": [
        {
          "boundingBox": "462,379,497,74",
          "words": [
            {
              "boundingBox": "462,379,41,73",
              "text": "A"
            },
            {
              "boundingBox": "523,379,153,73",
              "text": "GOAL"
            },
            {
              "boundingBox": "694,379,265,74",
              "text": "WITHOUT"
            }
          ]
        },
        {
          "boundingBox": "565,471,289,74",
          "words": [
            {
              "boundingBox": "565,471,41,73",
              "text": "A"
            },
            {
              "boundingBox": "626,471,150,73",
              "text": "PLAN"
            },
            {
              "boundingBox": "801,472,53,73",
              "text": "IS"
            }
          ]
        },
        {
          "boundingBox": "519,563,375,74",
          "words": [
            {
              "boundingBox": "519,563,149,74",
              "text": "JUST"
            },
            {
              "boundingBox": "683,564,41,72",
              "text": "A"
            },
            {
              "boundingBox": "741,564,153,73",
              "text": "WISH"
            }
          ]
        }
      ]
    }
  ]
}