웹용 이미지 분류 가이드

MediaPipe Image Classifier 작업을 사용하면 이미지를 분류할 수 있습니다. 이 작업을 사용하여 학습 시 정의된 카테고리 집합에서 이미지가 나타내는 내용을 식별할 수 있습니다. 이 안내에서는 노드 및 웹 앱에 이미지 분류기를 사용하는 방법을 보여줍니다.

데모를 통해 이 작업의 실제 동작을 확인할 수 있습니다. 이 작업의 기능, 모델, 구성 옵션에 대한 자세한 내용은 개요를 참조하세요.

코드 예시

Image Classifier의 코드 예는 참조할 수 있도록 JavaScript로 이 작업의 완전한 구현을 제공합니다. 이 코드는 이 작업을 테스트하고 자체 이미지 분류 앱 빌드를 시작하는 데 도움이 됩니다. 웹브라우저를 사용하여 Image Classifier 예시 코드를 보고 실행하고 편집할 수 있습니다.

설정

이 섹션에서는 특히 Image Classifier를 사용하도록 개발 환경과 코드 프로젝트를 설정하는 주요 단계를 설명합니다. 플랫폼 버전 요구사항을 포함하여 MediaPipe 작업을 사용하기 위한 개발 환경 설정에 관한 일반적인 정보는 웹 설정 가이드를 참고하세요.

JavaScript 패키지

이미지 분류기 코드는 MediaPipe @mediapipe/tasks-vision NPM 패키지를 통해 제공됩니다. 플랫폼 설정 가이드에 제공된 링크에서 이러한 라이브러리를 찾고 다운로드할 수 있습니다.

다음 명령어를 사용하여 로컬 스테이징을 위해 다음 코드가 포함된 필수 패키지를 설치할 수 있습니다.

npm install @mediapipe/tasks-vision

CDN (콘텐츠 전송 네트워크) 서비스를 통해 작업 코드를 가져오려면 HTML 파일의 태그에 다음 코드를 추가합니다.

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

모델

MediaPipe Image Classifier 작업에는 이 작업과 호환되는 학습된 모델이 필요합니다. Image Classifier에 사용할 수 있는 학습된 모델에 대한 자세한 내용은 작업 개요 모델 섹션을 참조하세요.

모델을 선택하고 다운로드한 후 프로젝트 디렉터리에 저장합니다.

<dev-project-root>/app/shared/models/

할 일 만들기

Image Classifier createFrom...() 함수 중 하나를 사용하여 추론 실행을 위한 작업을 준비합니다. 학습된 모델 파일의 상대 또는 절대 경로와 함께 createFromModelPath() 함수를 사용합니다. 모델이 이미 메모리에 로드된 경우 createFromModelBuffer() 메서드를 사용할 수 있습니다.

아래 코드 예에서는 createFromOptions() 함수를 사용하여 작업을 설정하는 방법을 보여줍니다. createFromOptions 함수를 사용하면 구성 옵션으로 이미지 분류 기준을 맞춤설정할 수 있습니다. 구성 옵션에 관한 자세한 내용은 구성 옵션을 참고하세요.

다음 코드는 커스텀 옵션을 사용하여 작업을 빌드하고 구성하는 방법을 보여줍니다.

async function createImageClassifier {
  const vision = await FilesetResolver.forVisionTasks(
    "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.0/wasm"
  );
  imageClassifier = await ImageClassifier.createFromOptions(vision, {
    baseOptions: {
      modelAssetPath: `https://storage.googleapis.com/mediapipe-models/image_classifier/efficientnet_lite0/float32/1/efficientnet_lite0.tflite`
    },
  });
}

구성 옵션

이 작업에는 웹 애플리케이션을 위한 다음과 같은 구성 옵션이 있습니다.

옵션 이름	설명	값 범위	기본값
`runningMode`	작업의 실행 모드를 설정합니다. 다음과 같은 두 가지 모드가 있습니다. 이미지: 단일 이미지 입력 모드입니다. 동영상: 동영상의 디코딩된 프레임 또는 입력 데이터 라이브 스트림(예: 카메라)의 모드입니다.	{`IMAGE, VIDEO`}	`IMAGE`
`displayNamesLocale`	가능한 경우 작업 모델의 메타데이터에 제공된 표시 이름에 사용할 라벨의 언어를 설정합니다. 기본값은 영어의 경우 `en`입니다. TensorFlow Lite Metadata Writer API를 사용하여 커스텀 모델의 메타데이터에 현지화된 라벨을 추가할 수 있습니다.	언어 코드	한국어
`maxResults`	반환할 최고 점수 분류 결과의 최대 개수(선택사항)를 설정합니다. 0보다 작은 경우 사용 가능한 모든 결과가 반환됩니다.	모든 양수	`-1`
`scoreThreshold`	모델 메타데이터에 제공된 값 (있는 경우)을 재정의하는 예측 점수 임곗값을 설정합니다. 이 값 미만의 결과는 거부됩니다.	모든 부동 소수점 수	설정되지 않음
`categoryAllowlist`	허용되는 카테고리 이름의 목록(선택사항)을 설정합니다. 비어 있지 않으면 카테고리 이름이 이 세트에 없는 분류 결과가 필터링됩니다. 중복되거나 알 수 없는 카테고리 이름은 무시됩니다. 이 옵션은 `categoryDenylist`와 상호 배타적이며 두 가지를 모두 사용하면 오류가 발생합니다.	모든 문자열	설정되지 않음
`categoryDenylist`	허용되지 않는 카테고리 이름의 목록(선택사항)을 설정합니다. 비어 있지 않으면 카테고리 이름이 이 집합에 있는 분류 결과가 필터링됩니다. 중복되거나 알 수 없는 카테고리 이름은 무시됩니다. 이 옵션은 `categoryAllowlist`와 상호 배타적이며 두 가지를 모두 사용하면 오류가 발생합니다.	모든 문자열	설정되지 않음
`resultListener`	이미지 분류기가 라이브 스트림 모드일 때 분류 결과를 비동기식으로 수신하도록 결과 리스너를 설정합니다. 달리기 모드가 `LIVE_STREAM`로 설정된 경우에만 사용할 수 있습니다.	해당 사항 없음	설정되지 않음

데이터 준비

Image Classifier는 호스트 브라우저에서 지원하는 모든 형식의 이미지로 객체를 분류할 수 있습니다. 이 작업은 크기 조절, 회전, 값 정규화를 포함한 데이터 입력 사전 처리도 처리합니다.

이미지 분류 기준 classify() 및 classifyForVideo() 메서드 호출은 동기식으로 실행되며 사용자 인터페이스 스레드를 차단합니다. 기기 카메라의 동영상 프레임에서 객체를 분류하는 경우 각 분류에서 기본 스레드를 차단합니다. 다른 스레드에서 classify() 및 classifyForVideo()를 실행하도록 웹 작업자를 구현하면 이를 방지할 수 있습니다.

작업 실행

이미지 분류기는 이미지 모드에서는 classify() 메서드를 사용하고 video 모드에서는 classifyForVideo() 메서드를 사용하여 추론을 트리거합니다. Image Classifier API는 입력 이미지 내 객체에 가능한 카테고리를 반환합니다.

다음 코드는 작업 모델을 사용하여 처리를 실행하는 방법을 보여줍니다.

이미지

const image = document.getElementById("image") as HTMLImageElement;
const imageClassifierResult = imageClassifier.classify(image);

동영상

const video = document.getElementById("video");
await imageClassifier.setOptions({ runningMode: "VIDEO" });

const timestamp = performance.now();
const classificationResult = await imageClassifier.classifyForVideo(
    video,
    timestamp
  );

이미지 분류기 작업 실행을 좀 더 완전히 구현하려면 코드 예를 참고하세요.

결과 처리 및 표시

추론을 실행하면 이미지 분류기 작업은 입력 이미지 또는 프레임 내 객체의 가능한 카테고리 목록이 포함된 ImageClassifierResult 객체를 반환합니다.

다음은 이 작업의 출력 데이터 예시를 보여줍니다.

ImageClassifierResult:
 Classifications #0 (single classification head):
  head index: 0
  category #0:
   category name: "/m/01bwb9"
   display name: "Passer domesticus"
   score: 0.91406
   index: 671
  category #1:
   category name: "/m/01bwbt"
   display name: "Passer montanus"
   score: 0.00391
   index: 670

이 결과는 다음에서 Bird Classifier를 실행하여 얻은 것입니다.

이미지 분류 기준 예시 코드는 작업에서 반환된 분류 결과를 표시하는 방법을 보여줍니다. 자세한 내용은 코드 예를 참고하세요.