웹용 포즈 랜드마크 감지 가이드

MediaPipe 포즈 랜드마커 작업을 사용하면 이미지나 동영상에서 인체 랜드마크를 감지할 수 있습니다. 이 작업을 사용하여 주요 신체 위치를 식별하고, 자세를 분석하고, 움직임을 분류할 수 있습니다. 이 작업에서는 단일 이미지 또는 동영상과 함께 작동하는 머신러닝 (ML) 모델을 사용합니다. 이 작업은 이미지 좌표와 3차원 세계 좌표로 신체 포즈 랜드마크를 출력합니다.

이 안내에서는 웹 및 JavaScript 앱에 포즈 랜드마커를 사용하는 방법을 보여줍니다. 이 작업의 기능, 모델, 구성 옵션에 대한 자세한 내용은 개요를 참고하세요.

코드 예

포즈 랜드마커의 예시 코드에서는 이 작업을 JavaScript로 완전히 구현하여 참고할 수 있습니다. 이 코드를 사용하면 이 작업을 테스트하고 자체 포즈 랜드마커 앱을 빌드할 수 있습니다. 웹브라우저만 사용하여 포즈 랜드마커 예시를 보고 실행하고 수정할 수 있습니다.

설정

이 섹션에서는 포즈 랜드마커를 사용하기 위한 개발 환경을 설정하는 주요 단계를 설명합니다. 플랫폼 버전 요구사항을 비롯한 웹 및 JavaScript 개발 환경 설정에 관한 일반 정보는 웹 설정 가이드를 참고하세요.

JavaScript 패키지

자세 랜드마커 코드는 MediaPipe @mediapipe/tasks-vision NPM 패키지를 통해 사용할 수 있습니다. 플랫폼 설정 가이드의 안내에 따라 이러한 라이브러리를 찾아 다운로드할 수 있습니다.

다음 명령어를 사용하여 NPM을 통해 필요한 패키지를 설치할 수 있습니다.

npm install @mediapipe/tasks-vision

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

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

모델

MediaPipe 포즈 랜드마커 작업에는 이 작업과 호환되는 학습된 모델이 필요합니다. 포즈 랜드마커에 사용할 수 있는 학습된 모델에 관한 자세한 내용은 작업 개요의 모델 섹션을 참고하세요.

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

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

작업 만들기

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

아래 코드 예시에서는 createFromOptions() 함수를 사용하여 작업을 설정하는 방법을 보여줍니다. createFromOptions() 함수를 사용하면 구성 옵션으로 포즈 랜드마커를 맞춤설정할 수 있습니다. 구성 옵션에 대한 자세한 내용은 구성 옵션을 참고하세요.

다음 코드는 맞춤 옵션으로 작업을 빌드하고 구성하는 방법을 보여줍니다.

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const poseLandmarker = await poseLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "path/to/model"
      },
      runningMode: runningMode
    });

구성 옵션

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

옵션 이름 설명 값 범위 기본값
runningMode 작업의 실행 모드를 설정합니다. 두 가지 모드가 있습니다.

IMAGE: 단일 이미지 입력 모드입니다.

VIDEO: 카메라와 같은 입력 데이터의 동영상 또는 라이브 스트림에서 디코딩된 프레임의 모드입니다.		 {IMAGE, VIDEO} IMAGE
numPoses 포즈 랜드마커로 감지할 수 있는 최대 포즈 수입니다. Integer > 0 1
minPoseDetectionConfidence 포즈 감지가 성공으로 간주되기 위한 최소 신뢰도 점수입니다. Float [0.0,1.0] 0.5
minPosePresenceConfidence 포즈 랜드마크 감지에서 포즈 존재 점수의 최소 신뢰도 점수입니다. Float [0.0,1.0] 0.5
minTrackingConfidence 포즈 추적이 성공으로 간주되기 위한 최소 신뢰도 점수입니다. Float [0.0,1.0] 0.5
outputSegmentationMasks 포즈 랜드마커가 감지된 포즈의 세분화 마스크를 출력하는지 여부입니다. Boolean False

데이터 준비

포즈 랜드마커는 호스트 브라우저에서 지원하는 모든 형식의 이미지에서 포즈를 감지할 수 있습니다. 이 작업은 크기 조절, 회전, 값 정규화를 비롯한 데이터 입력 전처리도 처리합니다. 동영상에서 포즈를 랜드마크로 지정하려면 API를 사용하여 한 번에 한 프레임을 빠르게 처리하고 프레임의 타임스탬프를 사용하여 동영상 내에서 포즈가 발생하는 시점을 확인할 수 있습니다.

태스크 실행

포즈 랜드마커는 detect() (실행 모드 IMAGE) 및 detectForVideo() (실행 모드 VIDEO) 메서드를 사용하여 추론을 트리거합니다. 이 작업은 데이터를 처리하고, 포즈를 랜드마크로 지정하려고 시도한 후 결과를 보고합니다.

포즈 랜드마커 detect() 및 detectForVideo() 메서드 호출은 동기적으로 실행되며 사용자 인터포즈 스레드를 차단합니다. 기기 카메라의 동영상 프레임에서 포즈를 감지하면 각 감지가 기본 스레드를 차단합니다. 다른 스레드에서 detect() 및 detectForVideo() 메서드를 실행하도록 웹 워커를 구현하면 이를 방지할 수 있습니다.

다음 코드는 태스크 모델로 처리를 실행하는 방법을 보여줍니다.

이미지

const image = document.getElementById("image") as HTMLImageElement;
const poseLandmarkerResult = poseLandmarker.detect(image);

동영상

await poseLandmarker.setOptions({ runningMode: "VIDEO" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const poseLandmarkerResult = poseLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

포즈 랜드마커 작업을 실행하는 더 완전한 구현은 예시를 참고하세요.

결과 처리 및 표시

포즈 랜드마커는 감지 실행마다 poseLandmarkerResult 객체를 반환합니다. 결과 객체에는 각 포즈 랜드마크의 좌표가 포함됩니다.

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

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

출력에는 각 랜드마크의 정규화된 좌표 (Landmarks)와 실제 좌표 (WorldLandmarks)가 모두 포함됩니다.

출력에는 다음 정규화된 좌표 (Landmarks)가 포함됩니다.

  • x 및 y: 이미지 너비 (x)와 높이 (y)에 의해 0.0~1.0 사이로 정규화된 랜드마크 좌표입니다.

  • z: 랜드마크 깊이입니다. 엉덩이의 중간 지점의 깊이가 원점입니다. 값이 작을수록 랜드마크가 카메라에 더 가까이 있습니다. z의 크기는 x와 거의 동일한 스케일을 사용합니다.

  • visibility: 이미지를 통해 랜드마크를 볼 수 있을 가능성입니다.

출력에는 다음 세계 좌표 (WorldLandmarks)가 포함됩니다.

  • x, y, z: 미터 단위의 실제 3차원 좌표로, 엉덩이의 중간 지점이 원점입니다.

  • visibility: 이미지를 통해 랜드마크를 볼 수 있을 가능성입니다.

다음 이미지는 작업 출력의 시각화를 보여줍니다.

명상 자세를 취하고 있는 여성 포즈는 사지와 몸통의 위치를 나타내는 와이어프레임으로 강조 표시됩니다.

선택적 분할 마스크는 감지된 사람이 각 픽셀에 속할 가능성을 나타냅니다. 다음 이미지는 작업 출력의 세분화 마스크입니다.

여성의 모양을 윤곽으로 표시하는 이전 이미지의 분할 마스크

포즈 랜드마커 예시 코드에서는 작업에서 반환된 결과를 표시하는 방법을 보여줍니다. 예시를 참고하세요.