MODEL_GUIDE.md

YOLO 모델 사용 가이드

📦 모델 변환 완료!

best.pt → louvre.mlpackage 변환 완료

위치: /Users/parkjh/Documents/ios/hackseoul-2025/louvre.mlpackage

---

🔧 모델 모드 전환 방법

ModelConfig.swift 파일에서 다음 설정을 변경하세요:

1. 로컬 모델 사용 (louvre.mlpackage)

// ModelConfig.swift
class ModelConfig {
    static var useLocalModel: Bool = true  // ✅ 로컬 모델 사용
    static var currentModel: YOLOModel = .louvre
}

동작:

• Xcode 프로젝트에 번들된 louvre.mlpackage 사용
• API 다운로드 불필요
• 앱 설치 시 모델 포함됨

---

2. API 다운로드 모델 사용

// ModelConfig.swift
class ModelConfig {
    static var useLocalModel: Bool = false  // ❌ API 모델 사용
    static var currentModel: YOLOModel = .museum
}

동작:

• ContentView의 "스캔 시작" 버튼 클릭 시 API에서 다운로드
• Documents 디렉토리에 저장
• 네트워크 연결 필요

---

📱 Xcode 프로젝트 설정

1. louvre.mlpackage 추가

   1) Xcode에서 hackseoul-2025 프로젝트 열기
   2) louvre.mlpackage를 프로젝트에 드래그 앤 드롭
      위치: /Users/parkjh/Documents/ios/hackseoul-2025/louvre.mlpackage
   3) "Copy items if needed" 체크
   4) Target: hackseoul-2025 선택
   5) Finish 클릭
   

2. 빌드 확인

   프로젝트 내비게이터에서 louvre.mlpackage 확인
   Target Membership이 체크되어 있는지 확인
   Xcode가 자동으로 louvre.swift 클래스 생성함 (자동)
   

3. Clean Build (중요!)

   Cmd+Shift+K (Clean Build Folder)
   Cmd+B (Build)
   

---

⚙️ 사용 가능한 모델

.louvre (추천)

• 파일: louvre.mlpackage
• 학습: best.pt에서 변환
• 용도: 루브르 박물관 객체 인식
• 사용: 로컬 모드에서 사용

.museum

• 파일: museum_detector.mlpackage
• 용도: 일반 박물관 객체
• 사용: API 모드 또는 번들 폴백

.coco

• 파일: yolov8n.mlpackage
• 용도: 80가지 일반 객체 (테스트용)
• 사용: 개발/디버깅

---

🧪 테스트 방법

로컬 모델 테스트

1. ModelConfig.useLocalModel = true 설정
2. ModelConfig.currentModel = .louvre 설정
3. 앱 실행
4. 콘솔 로그 확인:

   📦 로컬 번들 모델 사용: louvre
   ✅ louvre.mlpackage 로드 성공
   ✅ 번들 모델 로드 완료: louvre
   

API 모델 테스트

1. ModelConfig.useLocalModel = false 설정
2. ModelConfig.currentModel = .museum 설정
3. 앱 실행 → "스캔 시작" 클릭
4. 콘솔 로그 확인:

   📦 API 다운로드 모델 사용: museum
   ✅ 다운로드 모델 로드 완료: museum
   

---

🔍 모델 성능

louvre.mlpackage (best.pt)

• mAP@0.5: 99.5%
• Precision: 99.6%
• Recall: 100%
• 학습: 30 epochs
• 클래스: 모나리자 등 루브르 전용

---

🚨 문제 해결

Cannot find 'louvre' in scope

❌ Cannot find 'louvre' in scope

해결:

1. Xcode에서 louvre.mlpackage를 프로젝트에 추가
2. File Inspector에서 Target Membership 체크
3. Clean Build Folder (Cmd+Shift+K)
4. 프로젝트 리빌드 (Cmd+B)

모델 로드 실패

❌ 번들 모델 로드 실패

해결:

1. louvre.mlpackage가 프로젝트에 추가되었는지 확인
2. Target Membership이 체크되어 있는지 확인
3. Clean Build Folder (Cmd+Shift+K)
4. 프로젝트 재시작

---

📝 추가 모델 변환

새로운 best.pt가 생성되면:

cd /Users/parkjh/Documents/ios/hackseoul-2025/hackseoul-2025
python3 ../convert_to_coreml.py

자동으로 louvre.mlpackage로 변환됩니다.