JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q39687F
  • License MIT

웹 기반 얼굴 인식을 통해 실시간으로 심박수, 스트레스, 혈압 등의 건강 정보를 측정하는 SDK

Package Exports

  • face-detection-web-sdk

Readme

FaceDetection_Web

📋 프로젝트 개요

웹 기반 얼굴 인식을 통해 실시간으로 RGB 데이터를 추출하는 시스템입니다.
이를 통해 심박수, 스트레스, 혈압 등의 건강 정보를 측정할 수 있습니다.
MediaPipe와 Canvas API를 활용하여 비접촉식 생체 신호 측정을 제공합니다.

✨ 주요 기능

  • 실시간 얼굴 인식: MediaPipe 기반 고정밀 얼굴 감지
  • 비접촉 생체 신호 측정: RGB 데이터 추출
  • 상태 관리 시스템: 체계적인 측정 과정 관리
  • 크로스 플랫폼: Chrome, Safari 브라우저 지원
  • Manager 기반 아키텍처: 모듈화된 기능별 관리 시스템
  • 플랫폼별 다운로드: Android/iOS 환경 감지 및 최적화

🛠 기술 스택

  • 핵심 기술: MediaPipe Face Detection, Canvas API, Web Workers
  • 개발 도구: Vite, TypeScript/JavaScript
  • 상태 관리: Custom State Management System with Manager Architecture

🏗️ 아키텍처 개요

Manager 기반 구조

SDK는 기능별로 분리된 Manager 클래스들로 구성되어 있습니다:

  • ConfigManager: 설정 관리 및 검증
  • EventManager: 이벤트 발생 및 콜백 처리
  • MediapipeManager: MediaPipe 얼굴 인식 처리
  • StateManager: 상태 전환 및 관리
  • WebcamManager: 웹캠 스트림 관리
  • FacePositionManager: 얼굴 위치 추적 및 검증
  • WorkerManager: Web Worker를 통한 데이터 처리
  • MeasurementManager: 측정 과정 및 데이터 수집 관리

🔄 상태 관리 시스템

상태 정의

export enum FaceDetectionState {
  INITIAL = 'initial', // 초기 상태 (준비, 얼굴 위치 조정)
  READY = 'ready', // 준비 완료 (카운트다운 중)
  MEASURING = 'measuring', // 측정 중 (RGB 데이터 수집)
  COMPLETED = 'completed', // 측정 완료
}

상태 전환 흐름

INITIAL → READY → MEASURING → COMPLETED
   ↑↓       ↓         ↑↓
 ERROR  ← ERROR     ERROR

📱 지원 플랫폼

  • 데스크톱: Chrome, Safari
  • 모바일: Android Chrome, iOS Safari
  • 요구사항: 웹캠 접근 권한, 안정적인 네트워크 연결

🚀 설치 및 실행

설치

npm install

개발 모드 실행

npm run dev

프로덕션 빌드

npm run build
npm run preview

🎯 예제 및 데모

기본 데모

# 예제 데모 실행
cd node_modules/face-detection-web-sdk
npm run demo

# 브라우저에서 접속
http://localhost:8080

예제 구조

examples/
└── basic-demo/          # 기본 사용법 데모
    ├── index.html       # HTML 예제
    ├── demo.js         # JavaScript 예제
    └── README.md       # 상세 설명

빠른 시작

import { FaceDetectionSDK } from 'face-detection-web-sdk';

// 1. SDK 설정
const config = {
  elements: { video, canvasElement, videoCanvas, container },
  measurement: { readyToMeasuringDelay: 5 },
  dataDownload: {
    enabled: true,
    autoDownload: false,
    filename: 'rgb_data.txt',
  },
  platform: {
    isAndroid: /Android/i.test(navigator.userAgent),
    isIOS: /iPad|iPhone|iPod/.test(navigator.userAgent),
  },
};

// 2. 콜백 설정
const callbacks = {
  onMeasurementComplete: (result) => {
    console.log('심박수:', result.heartRate);
    console.log('품질 정보:', result.quality);
  },
  onCountdown: (remainingSeconds, totalSeconds) => {
    console.log(`카운트다운: ${remainingSeconds}/${totalSeconds}`);
  },
  onStateChange: (newState, prevState) => {
    console.log(`상태 변경: ${prevState}${newState}`);
  },
};

// 3. 초기화 및 시작 (한 번에 처리)
const sdk = new FaceDetectionSDK(config, callbacks);
await sdk.initializeAndStart();

💡 사용법

1. 기본 사용 과정

  1. 카메라 권한 허용

    • 웹캠 접근 권한 필수
    • 권한 거부 시 측정 불가
  2. 얼굴 위치 조정 (INITIAL → READY)

    • 얼굴을 화면 중앙 원 안에 위치
    • 적절한 조명 환경 확보
  3. 자동 카운트다운 (READY → MEASURING)

    • 설정된 시간(기본 3초) 카운트다운 후 자동 측정 시작
    • onCountdown 콜백으로 실시간 카운트다운 정보 제공
  4. 데이터 수집 (MEASURING)

    • 15초간 RGB 데이터 자동 수집
    • 실시간 진행률 표시
    • Web Worker를 통한 비동기 처리
  5. 결과 분석 (COMPLETED)

    • RGB 데이터 수집 완료
    • 품질 정보 포함 (위치 오차, 데이터 포인트 수 등)

2. SDK 사용법

import { FaceDetectionSDK, FaceDetectionState } from './faceDetectionCore';

// SDK 초기화 및 설정
const sdk = new FaceDetectionSDK(
  {
    measurement: {
      readyToMeasuringDelay: 3,
      frameInterval: 33.33,
      frameProcessInterval: 30,
    },
    faceDetection: {
      timeout: 3000,
      minDetectionConfidence: 0.5,
    },
    dataDownload: {
      enabled: true,
      autoDownload: false,
      filename: 'measurement_data.txt',
    },
    platform: {
      isAndroid: /Android/i.test(navigator.userAgent),
      isIOS: /iPad|iPhone|iPod/.test(navigator.userAgent),
    },
    debug: {
      enabled: true,
      enableConsoleLog: true,
    },
  },
  {
    onStateChange: (newState, prevState) => {
      console.log(`상태 변경: ${prevState}${newState}`);
    },
    onProgress: (progress, dataCount) => {
      console.log(`진행률: ${(progress * 100).toFixed(1)}% (${dataCount}개)`);
    },
    onCountdown: (remainingSeconds, totalSeconds) => {
      console.log(`카운트다운: ${remainingSeconds}/${totalSeconds}`);
    },
    onMeasurementComplete: (result) => {
      console.log('측정 완료:', result);
      console.log('품질 정보:', result.quality);
    },
    onFaceDetectionChange: (detected, boundingBox) => {
      console.log('얼굴 인식:', detected ? '감지됨' : '감지 안됨');
    },
    onFacePositionChange: (inCircle) => {
      console.log('얼굴 위치:', inCircle ? '원 안' : '원 밖');
    },
  },
);

// 초기화 및 측정 시작
await sdk.initializeAndStart();

📊 측정 알고리즘

데이터 수집 과정

  1. 비디오 프레임 캡처: 설정 가능한 프레임 간격으로 웹캠 영상 수집
  2. 얼굴 인식: MediaPipe Face Detection 모델 적용
  3. ROI 추출: 바운딩 박스 기반 얼굴 영역 분리
  4. RGB 데이터 추출: 얼굴 영역에서 평균 RGB 값 계산
  5. 실시간 처리: Web Worker를 통한 비동기 데이터 처리
  6. 품질 관리: 위치 오차 및 신호 품질 모니터링
  7. 플랫폼별 최적화: Android/iOS 환경에 따른 다운로드 처리

🔧 API 참조

주요 메서드

// 🚀 초기화 및 시작
initializeAndStart(): Promise<void>

// 📊 상태 관리
getCurrentState(): FaceDetectionState
isState(state: FaceDetectionState): boolean
isAnyState(...states: FaceDetectionState[]): boolean

// 🔍 상태 확인
isFaceInsideCircle(): boolean

// 🧹 정리
dispose(): void

이벤트 콜백

interface SDKEventCallbacks {
  onStateChange?: (newState: FaceDetectionState, previousState: FaceDetectionState) => void;
  onProgress?: (progress: number, dataCount: number) => void;
  onCountdown?: (remainingSeconds: number, totalSeconds: number) => void; // 새로운 콜백
  onFaceDetectionChange?: (detected: boolean, boundingBox: CalculatedBoundingBox | null) => void;
  onFacePositionChange?: (inCircle: boolean) => void;
  onMeasurementComplete?: (result: MeasurementResult) => void;
  onError?: (error: FaceDetectionError) => void;
}

설정 옵션

interface FaceDetectionSDKConfig {
  measurement?: {
    readyToMeasuringDelay?: number; // 카운트다운 시간 (초)
    frameInterval?: number; // 프레임 간격 (ms)
    frameProcessInterval?: number; // 프레임 처리 간격
  };
  faceDetection?: {
    timeout?: number; // 얼굴 인식 타임아웃 (ms)
    minDetectionConfidence?: number; // 최소 감지 신뢰도
  };
  dataDownload?: {
    enabled?: boolean; // 다운로드 기능 활성화
    autoDownload?: boolean; // 자동 다운로드
    filename?: string; // 파일명
  };
  platform?: {
    isAndroid?: boolean; // Android 플랫폼 여부
    isIOS?: boolean; // iOS 플랫폼 여부
  };
  debug?: {
    enabled?: boolean; // 디버그 모드
    enableConsoleLog?: boolean; // 콘솔 로그 활성화
  };
}

🚨 오류 처리

주요 오류 타입

  • WEBCAM_PERMISSION_DENIED: 웹캠 권한 거부
  • WEBCAM_ACCESS_FAILED: 웹캠 접근 실패
  • FACE_NOT_DETECTED: 얼굴 인식 실패
  • FACE_OUT_OF_CIRCLE: 얼굴 위치 이탈
  • MEASUREMENT_TIMEOUT: 측정 시간 초과
  • INITIALIZATION_FAILED: SDK 초기화 실패

디버깅

// 디버그 모드 활성화
const sdk = new FaceDetectionSDK({
  debug: {
    enabled: true,
    enableConsoleLog: true,
  },
});

// 실시간 상태 모니터링
setInterval(() => {
  console.log('현재 상태:', sdk.getCurrentState());
  console.log('얼굴 위치:', sdk.isFaceInsideCircle());
}, 1000);

📋 변경이력

모든 주요 변경사항은 CHANGELOG.md에서 확인할 수 있습니다.

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.