UI 모듈 개요

PetnowUI 모듈이란?

PetnowUI는 반려동물 생체 데이터 캡처를 위한 즉시 사용 가능한 카메라 UI를 제공하는 모듈입니다. 복잡한 카메라 설정, 탐지 로직, 이미지 처리 등을 모두 처리하여 개발자는 몇 줄의 코드만으로 전문적인 생체 인식 기능을 앱에 통합할 수 있습니다.

UI Module Intro

핵심 가치

🚀 빠른 통합: 복잡한 카메라 API를 알 필요 없음
🎯 실시간 가이드: 사용자에게 최적의 촬영 방법 안내
🎨 커스터마이즈 가능: 앱의 디자인에 맞게 조정 가능
📱 SwiftUI & UIKit 지원: 모든 iOS 앱에서 사용 가능

아키텍처

PetnowUI 모듈은 복잡한 상태관리와 ML 프레임워크 연동 로직을 숨기고, 개발자에게 간단한 인터페이스만 제공합니다.

핵심 컴포넌트

CameraView

SwiftUI View로 카메라 프리뷰와 탐지 오버레이를 표시합니다.

역할:

카메라 프리뷰 렌더링
탐지 오버레이 표시
사용자 상호작용 처리

간단한 사용 예시:

// 기본 사용
CameraView(viewModel: cameraViewModel)

// 커스텀 오버레이 추가
CameraView(viewModel: cameraViewModel) {
    Text("코를 가운데에 맞춰주세요")
        .foregroundColor(.white)
        .padding()
        .background(Color.black.opacity(0.7))
        .cornerRadius(8)
}

CameraViewModel

ObservableObject로 CameraView에 주입되는 뷰모델입니다.

세션 개념

촬영 과정은 두 가지 세션으로 관리됩니다:

Capture Session (캡처 세션)

서버에서 createCaptureSession API를 호출하여 생성
생성된 captureSessionId를 initializeCamera()에 전달하여 촬영 시작
하나의 Capture Session은 여러 Detection Session을 포함할 수 있음
Petify Console에서 전체 촬영 과정을 추적하고 메트릭 분석에 활용

Detection Session (탐지 세션)

실제 탐지를 시작한 시점부터 탐지가 완료되거나 실패할 때까지의 세션
사용자가 재촬영하면 새로운 Detection Session이 시작됨

참고: 재촬영 시 새로운 Detection Session이 시작됩니다. Petify Console에서 각 세션을 개별적으로 추적할 수 있습니다.

상태 관리

DetectionStatus

카메라 프레임의 탐지 결과 상태를 나타냅니다. 1초마다 업데이트됩니다.

public enum DetectionStatus {
    case noObject           // 대상 미탐지
    case processing         // 탐지 진행 중
    case detected           // 탐지 완료
    case failed(DetectionFailureReason)     // 실패 (사유 포함)
}

CaptureStage

캡처 세션의 단계를 나타냅니다.

public enum CaptureStage {
    case findSpecies       // 대상 탐지 중
    case capturing         // 촬영 중
    case finished          // 촬영 완료
}

CameraResult

최종 촬영 결과입니다.

public enum CameraResult {
    case success(
        fingerprintImages: [URL],  // 지문/코무늬 이미지
        appearanceImages: [URL]    // 외형 이미지
    )
    case fail                      // 촬영 실패
}

데이터 흐름

핵심 포인트: CameraViewModel이 상태를 발행하면, 개발자가 만든 커스텀 카메라 화면에서 CameraView와 함께 상태값을 활용한 UI를 구성합니다. 촬영 완료 시 CameraResult가 콜백으로 전달됩니다.

데이터 흐름 설명

1. 실시간 상태 업데이트

CameraViewModel이 다음 상태를 @Published로 발행합니다:
- detectionStatus: .noObject, .processing, .detected, .failed(reason)
- detectionProgress: 0.0 ~ 1.0 (탐지 진행률)
- captureStage: .findSpecies, .capturing, .finished
커스텀 카메라 화면에서 이 상태값을 구독하여 UI를 업데이트합니다.

2. 최종 결과 전달

탐지가 완료되면 CameraViewModel이 이미지를 저장하고 CameraResult를 생성합니다.
CameraResult.success 또는 CameraResult.fail이 콜백을 통해 전달됩니다.

모범 사례

1. ViewModel 생명주기 관리

// SwiftUI: @StateObject 사용
@StateObject private var viewModel = CameraViewModel(...)

// 정리
.onDisappear {
    viewModel.stopDetection()
}

2. 에러 처리

do {
    try await viewModel.initializeCamera(...)
} catch PetnowUIError.invalidLicense(let error) {
    // 라이선스 오류 처리
} catch PetnowUIError.permissionDenied(let message) {
    // 권한 오류 처리
} catch {
    // 기타 오류 처리
}

3. 상태 관찰

// 특정 상태에 따른 액션
.onChange(of: viewModel.detectionStatus) { status in
    switch status {
    case .detected:
        playSuccessSound()
    case .failed(let reason):
        showErrorMessage(reason)
    default:
        break
    }
}

다음 단계

UI 모듈의 구조를 이해했다면 다음 문서를 참고하세요:

기본 사용법 - CameraView 통합하기
커스터마이즈 - 오버레이 커스터마이즈
사운드 가이드 - 사운드 재생 상세 가이드

참고 자료

시작하기 - SDK 설치
트러블슈팅 - 문제 해결

UI 모듈 개요

On this page