ultralytics/yolo-flutter-app

Official Ultralytics YOLO Flutter plugin for real-time inference on Android and iOS across major vision tasks.

📦 YOLO Flutter란 무엇인가요?

YOLO Flutter는 인기 있는 YOLO 컴퓨터 비전 모델 제품군을 Flutter 모바일 앱 내에서 직접 실행할 수 있게 해주는 공식 Ultralytics 플러그인입니다. 플랫폼별 세부 사항(iOS의 Core ML, Android의 LiteRT/TFLite, 선택적 Qualcomm NPU 지원)을 추상화하여 다음을 위한 단일 Dart API를 제공합니다:

단일 이미지 추론 – YOLO
실시간 카메라 추론 – YOLOView

두 진입점 모두 iOS 및 Android에서 전체 YOLO 작업(객체 탐지, 인스턴스/의미론적 세그멘테이션, 깊이, 분류, 포즈, 회전 경계 상자)을 지원합니다.

✨ 주요 기능 (README 설명 기준)

기능	세부 정보
크로스 플랫폼 API	하나의 Dart API로 iOS와 Android에서 작동합니다.
메타데이터 우선 모델 로드	공식 모델 ID 또는 사용자 지정 내보내기 모델을 제공하면 플러그인이 내장된 메타데이터를 읽어 작업 및 클래스 레이블을 추론합니다.
실시간 카메라 추론	`YOLOView`가 기기 카메라의 결과를 스트리밍합니다.
단일 이미지 추론	`YOLO`가 이미지의 바이트 배열에 대해 예측을 수행합니다.
지원되는 작업	탐지, 인스턴스 세그멘테이션, 의미론적 세그멘테이션, 깊이 추정, 분류, 포즈, OBB.
모델 제품군	YOLOv8 26 및 YOLOv11 제품군.
공식 모델 처리	Ultralytics 호스팅 자산(Android용 LiteRT .tflite, iOS용 Core ML .mlpackage)의 자동 다운로드 및 캐싱.
사용자 지정 모델	내보낸 TFLite, Core ML 또는 ONNX (QNN) 모델을 로드하며, 메타데이터가 있으면 사용됩니다.
Qualcomm NPU (QNN) 지원	ONNX Runtime QNN 공급자를 통해 Snapdragon 기기에서 선택적 Hexagon NPU 추론을 지원합니다.
가속기 선택	런타임에 CPU, GPU (LiteRT delegate) 또는 NPU를 선택할 수 있습니다.
결과 스트리밍	추론 결과는 콜백 (`onResult`)을 통해 전달됩니다.
버전 관리 릴리스	모델 자산은 GitHub 릴리스 태그에 고정되어 재현 가능한 다운로드를 보장합니다.

🚀 빠른 시작 개요 (README 기준)

패키지 추가
```
dependencies:
  ultralytics_yolo: ^0.6.16
```
그런 다음 flutter pub get을 실행합니다.

기본 모델 실행

import 'package:ultralytics_yolo/ultralytics_yolo.dart';

final modelId = YOLO.defaultOfficialModel() ?? 'yolo26n';

YOLOView(
  modelPath: modelId,
  onResult: (results) {
    for (final r in results) {
      debugPrint('${r.className}: ${r.confidence}');
    }
  },
);

단일 이미지 추론

final yolo = YOLO(modelPath: 'yolo26n');
await yolo.loadModel();
final results = await yolo.predict(imageBytes);

사용자 지정 또는 원격 모델 – 로컬 자산 경로, 번들된 .tflite/.mlpackage 또는 HTTP URL을 제공합니다. 플러그인이 원격 모델을 자동으로 다운로드하고 캐시합니다.

📂 모델 로드 작동 방식

흐름	제공 항목	플러그인 동작
공식 모델 ID	`YOLO.defaultOfficialModel()` 또는 `yolo26n`과 같은 특정 ID	Ultralytics GitHub 릴리스에서 일치하는 LiteRT (Android) 또는 Core ML (iOS) 자산을 다운로드, 캐시 및 로드합니다.
사용자 지정 내보내기 모델	`.tflite` (Android) 또는 `.mlpackage`/`.mlmodel` (iOS) 파일 경로	내장된 메타데이터(있는 경우)를 읽어 작업 및 클래스 목록을 추론합니다. 그렇지 않으면 `task`를 전달해야 합니다.
원격 URL	`https://…/mymodel.tflite`	파일을 앱 저장소로 다운로드한 후 로드합니다.
Qualcomm NPU 모델	`_qnn.onnx`로 끝나는 경로	모델을 ONNX Runtime QNN 실행 공급자로 라우팅합니다(추가 Gradle 종속성 및 Snapdragon 기기 필요).

🛠️ 플랫폼별 세부 정보

Android – LiteRT(Google의 엣지 런타임)를 사용하며 GPU 델리게이트 폴백을 지원합니다. 모델은 w8a32 .tflite 파일(int8 가중치, FP32 활성화)입니다. 선택적 QNN 지원은 onnxruntime-android-qnn 및 qnn-runtime 라이브러리를 추가합니다.
iOS – 기본적으로 Core ML (.mlpackage)을 사용합니다. iOS 27+ 기기에서는 선택적 Core AI (.aimodel) 형식을 사용할 수 있습니다.
가속기 사다리 – 런타임은 사용 가능한 경우 자동으로 GPU를 선택하며, 그렇지 않으면 CPU에서 실행됩니다. NPU는 _qnn.onnx 모델이 제공되고 기기가 하드웨어 요구 사항을 충족하는 경우에만 사용됩니다.

📚 문서 및 가이드 (README 링크)

설치 가이드 – doc/install.md
빠른 시작 – doc/quickstart.md
모델 가이드 – doc/models.md (공식 ID, 내보내기 매트릭스, 메타데이터)
사용 가이드 – doc/usage.md
API 참조 – doc/api.md
성능 가이드 – doc/performance.md
문제 해결 – doc/troubleshooting.md

🤝 커뮤니티 및 지원

Discord, 포럼, Reddit – 공식 Ultralytics 채널.
GitHub Issues – 버그 보고 및 기능 요청용.
기여 – Ultralytics 기여 가이드를 따르세요. 코드, 문서 및 피드백을 환영합니다.

📄 라이선스

이 저장소는 이중 라이선스가 적용됩니다. 오픈 소스 사용을 위한 AGPL-3.0과 독점 프로젝트를 위한 상용 라이선스 옵션이 있습니다(자세한 내용은 README 참조).

요약

YOLO Flutter는 Ultralytics의 YOLO 모델을 모든 Flutter 앱으로 가져오는 프로덕션 준비 완료 브리지입니다. 모델 다운로드, 플랫폼별 런타임, 실시간 카메라 추론을 깔끔한 Dart API로 처리합니다. 네이티브 iOS/Android 코드를 작성하지 않고도 기기 내 컴퓨터 비전(탐지, 세그멘테이션, 깊이, 포즈 등)을 구현하려는 개발자에게 이상적입니다.