앱 연동 가이드

서버 연동은 REST API 호출 한 번이지만, 등록 UX(얼굴 각도 추적·자동촬영)는 온디바이스 구현이 필요합니다. 플랫폼별 데모앱과 소스코드를 그대로 받아 빌드하거나, 아래 공통 스펙대로 직접 구현하세요. 등록 방식은 5방향 정밀등록과 원형(Face ID식) 등록 두 가지가 제공되며, 둘 다 같은 5장을 만들어 같은 API 로 올립니다.

5방향 정밀등록 UX 스펙 · 플랫폼 공통

정면 + 네 모서리, 총 5장을 자동 촬영해 얼굴등록 API로 업로드합니다. 온디바이스 얼굴탐지기(ML Kit 등)에서 얼굴 각도(yaw·pitch)를 읽어 아래 조건을 만족하면 자동 촬영하고 다음 단계로 넘어갑니다.

포즈 판정 기준 · 부호 규약: +yaw = 화면 왼쪽으로 고개 돌림, +pitch = 위로 듦 (기기·카메라에 따라 반전될 수 있으니 반전 플래그를 두세요)

안정화 규칙 · 흔들림·오탐 방지 (실기기 튜닝값)

가이드 UI 권장

중앙 타원 가이드 + 목표 모서리에 점멸 마커(파랑→충족 시 초록 체크) + 타원에서 마커로 흐르는 점선 애니메이션. 문구만으로는 방향 전달이 어렵습니다 — 시각 타겟이 핵심입니다.

업로드

POST /api/register  (multipart/form-data)
files=@frontal.jpg files=@left_up.jpg files=@right_up.jpg files=@left_down.jpg files=@right_down.jpg
poses=frontal,left_up,right_up,left_down,right_down
unique_key=member-1024  group_key=A  extra='{"name":"홍길동"}'

업로드 전 이미지는 짧은변 720px · JPEG 품질 82 정도로 축소하면 전송이 빨라지고 인식 품질 손실이 없습니다. 상세 파라미터는 API 문서 참고.

원형 등록 UX · 아이폰 Face ID 식 · 선택

단계별로 한 방향씩 찍는 대신, 고개로 원을 한 바퀴 그리면서 대각 네 방향을 순서 없이 담는 방식입니다. Flutter·React Native 데모앱에 "원형 등록" 화면으로 함께 들어 있습니다. 업로드 결과(포즈 라벨 5종·5장)는 5방향 방식과 완전히 동일하므로 서버·API는 아무것도 바꿀 필요가 없고, 두 방식을 같은 조건에서 비교해 볼 수 있습니다.

링 좌표 정규화 · 고개 방향을 링 위의 한 점으로 바꾸는 계산

// 부호 규약은 5방향과 동일 (+yaw = 화면 왼쪽, +pitch = 위)
upT = clamp(pitch / 3.5, 0, 1)              // 위로 들수록 좌우 기준도 완화
nx  = yaw   / (11 - (11 - 7) * upT)         // 11°=기본, 7°=위쪽 완화치
ny  = pitch / (pitch >= 0 ? 3.5 : 7)        // 위 3.5° / 아래 7°
mag   = sqrt(nx*nx + ny*ny)                 // 1.0 = 링에 닿음
angle = atan2(ny, nx) * 180 / PI            // 화면 좌표 = 중심 + (-cos, -sin)

구역·촬영 조건

얼굴 크기 게이트·눈 감김 게이트·상한(|yaw| ≤ 50°, |pitch| ≤ 45°)은 5방향 스펙과 같은 값을 씁니다. 촬영 순서가 사용자마다 다르므로, 결과는 파일과 포즈 라벨을 쌍으로 넘겨 poses 파라미터 순서를 맞춰야 합니다.

가이드 UI 권장

중앙 정원 가이드(지름 280) + 그 바깥 링 24눈금(지나간 구간 점등) + 대각 4곳 타겟 마커(파랑 점멸 → 촬영되면 초록 체크) + 현재 고개 방향을 나타내는 점. 사용자는 이 점을 링 위로 몰고 다니게 됩니다 — 점이 없으면 "얼마나 돌려야 하는지"를 알 수 없어 방식 자체가 성립하지 않습니다.

프레임 저장 구현

저장할 때 프레임 회전각(rotationDegrees)을 적용해 똑바로 세우고, 좌우반전은 하지 않습니다 — 등록 사진과 인식 사진의 좌우가 다르면 유사도가 떨어집니다. 참고 성능(스냅드래곤 8 Gen2): 얼굴검출 720p 프레임당 ~50ms(≈20fps), 프레임 저장 1280×720 ~50ms.

React Native 연동

데모앱 소스 ZIP은 그대로 빌드되는 완성 앱입니다(React Native 0.86 · TypeScript). 핵심 파일은 아래와 같고, 기존 앱에 이식할 때는 src/poses.ts · src/api.ts · src/FaceEnrollScreen.tsx 세 파일만 복사한 뒤 디자인을 맞추면 됩니다.

의존성

npm install react-native-vision-camera@^4 react-native-vision-camera-face-detector react-native-worklets-core

react-native-vision-camera 4.x의 프레임 프로세서로 매 프레임 얼굴 각도(yawAngle·pitchAngle)와 눈 열림 확률을 받아 위 공통 스펙대로 판정합니다. 카메라 권한(Android CAMERA, iOS NSCameraUsageDescription)과 babel 플러그인(react-native-worklets-core/plugin) 등록이 필요합니다.

빌드

npm install
cd android && ./gradlew assembleRelease   # 데모앱과 동일한 APK 생성

⚠️ 프로젝트 경로에 공백/한글이 있으면 Metro 번들링이 실패합니다. 공백 없는 경로에서 빌드하세요. minSdk 26 이상 필요.

Flutter 연동

데모 소스 ZIP은 그대로 빌드되는 완성 앱입니다. camera + google_mlkit_face_detection 기반이며, 핵심 파일은 아래와 같습니다. 기존 앱에 이식할 때는 lib/face_enroll_screen.dart · lib/api.dart 두 파일만 복사한 뒤 디자인을 맞추면 됩니다.

빌드

flutter pub get
flutter build apk --release   # 데모앱과 동일한 APK 생성