Skip to content

quickstart.md

Latest commit

 

History

History
302 lines (222 loc) · 7.86 KB

quickstart.md

File metadata and controls

302 lines (222 loc) · 7.86 KB
Raw
title Quick Start
description Get YOLO running in your Flutter app in under 2 minutes - minimal setup guide
path /integrations/flutter/quickstart/

Quick Start Guide

Get YOLO object detection running in your Flutter app in under 2 minutes! ⚡

🎯 Goal

By the end of this guide, you'll have a working Flutter app that can detect objects in images using YOLO.

📋 Prerequisites

  • ✅ Flutter SDK installed
  • ✅ Android/iOS device or emulator
  • ✅ 2 minutes of your time

🚀 Step 1: Create New Flutter App

flutter create yolo_demo
cd yolo_demo

📦 Step 2: Add YOLO Plugin

Add to pubspec.yaml:

Package: https://pub.dev/packages/ultralytics_yolo

dependencies:
  flutter:
    sdk: flutter
  ultralytics_yolo: ^0.5.1
  image_picker: ^1.2.1 # For image selection

Install dependencies:

flutter pub get

🎯 Step 3: Add a model

The simplest path is to use an official model ID and let the plugin download it automatically. Call YOLO.officialModels() to see which IDs are available on the current platform.

final yolo = YOLO(modelPath: 'yolo26n');

Custom local models are still supported:

  • iOS: drag .mlpackage or .mlmodel into ios/Runner.xcworkspace, or bundle .mlpackage.zip in Flutter assets
  • Android native assets: place .tflite files in android/app/src/main/assets/
  • Flutter assets: place .tflite on Android or .mlpackage.zip on iOS in assets/models/ and use that asset path directly

Task and labels are auto-detected from the model's embedded metadata. If your custom model has no task in its metadata, pass it explicitly.

Android inference runs on LiteRT 2.x with an automatic GPU → CPU accelerator ladder; iOS uses Core ML. Official int8 YOLO26 TFLite assets can compile on the LiteRT GPU path on supported devices, but int8 GPU coverage depends on the device driver and graph; graphs the GPU cannot compile fall back to CPU. non-end-to-end exports are useful for GPU benchmarking (the GPU delegate runs them in FP16):

YOLO("yolo26n.pt").export(format="litert", nms=False, end2end=False, imgsz=640)

⚡ Step 4: Minimal Detection Code

Replace lib/main.dart with this complete working example:

import 'package:flutter/material.dart';
import 'package:ultralytics_yolo/ultralytics_yolo.dart';
import 'package:image_picker/image_picker.dart';
import 'dart:io';

void main() => runApp(YOLODemo());

class YOLODemo extends StatefulWidget {
  @override
  _YOLODemoState createState() => _YOLODemoState();
}

class _YOLODemoState extends State<YOLODemo> {
  YOLO? yolo;
  File? selectedImage;
  List<dynamic> results = [];
  bool isLoading = false;

  @override
  void initState() {
    super.initState();
    loadYOLO();
  }

  Future<void> loadYOLO() async {
    setState(() => isLoading = true);

    yolo = YOLO(
      modelPath: 'yolo26n',
    );

    await yolo!.loadModel();
    setState(() => isLoading = false);
  }

  Future<void> pickAndDetect() async {
    final picker = ImagePicker();
    final image = await picker.pickImage(source: ImageSource.gallery);

    if (image != null) {
      setState(() {
        selectedImage = File(image.path);
        isLoading = true;
      });

      final imageBytes = await selectedImage!.readAsBytes();
      final detectionResults = await yolo!.predict(imageBytes);

      setState(() {
        results = detectionResults['boxes'] ?? [];
        isLoading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('YOLO Quick Demo')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              if (selectedImage != null)
                Container(
                  height: 300,
                  child: Image.file(selectedImage!),
                ),

              SizedBox(height: 20),

              if (isLoading)
                CircularProgressIndicator()
              else
                Text('Detected ${results.length} objects'),

              SizedBox(height: 20),

              ElevatedButton(
                onPressed: yolo != null ? pickAndDetect : null,
                child: Text('Pick Image & Detect'),
              ),

              SizedBox(height: 20),

              // Show detection results
              Expanded(
                child: ListView.builder(
                  itemCount: results.length,
                  itemBuilder: (context, index) {
                    final detection = results[index];
                    return ListTile(
                      title: Text(detection['class'] ?? 'Unknown'),
                      subtitle: Text(
                        'Confidence: ${(detection['confidence'] * 100).toStringAsFixed(1)}%'
                      ),
                    );
                  },
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

🏃‍♂️ Step 5: Run Your App

flutter run

🎉 That's It!

You now have a working YOLO object detection app! The app will:

  1. Load the YOLO model when it starts
  2. Let you pick an image from your gallery
  3. Detect objects in the selected image
  4. Show results with class names and confidence scores

🚀 Next Steps

Add Real-time Camera

Want real-time detection? Add the YOLOView widget:

import 'package:ultralytics_yolo/ultralytics_yolo.dart';

// Replace the Column with:
YOLOView(
  modelPath: 'yolo26n',
  onResult: (results) {
    print('Detected ${results.length} objects');
  },
)

Dynamic Model Switching

Switch models without restarting the camera:

final controller = YOLOViewController();

YOLOView(
  modelPath: 'yolo26n',  // Initial model
  controller: controller,
  onResult: (results) {
    print('Detected ${results.length} objects');
  },
)

// Later, switch to another official model or a custom export
await controller.switchModel('assets/models/custom.tflite', YOLOTask.detect);

🎯 Multi-Instance Quick Example

Want to run multiple models? Try this:

// Create two YOLO instances
final detector = YOLO(
  modelPath: 'yolo26n',
  useMultiInstance: true, // Enable multi-instance
);

final classifier = YOLO(
  modelPath: 'assets/models/yolo26n-cls.tflite',
  task: YOLOTask.classify,
  useMultiInstance: true,
);

// Load both models
await detector.loadModel();
await classifier.loadModel();

// Run both on the same image
final detections = await detector.predict(imageBytes);
final classifications = await classifier.predict(imageBytes);

🛠️ Troubleshooting

App crashes on startup?

  • Make sure the model file exists in the right place

No detections found?

  • Try a different image with clear objects
  • Check model file is not corrupted
  • Verify model matches the task type

Build errors?

  • Run flutter clean && flutter pub get
  • Check minimum SDK versions in installation guide

Slow detections on Android?

  • Keep useGpu: true and verify LiteRT delegate placement in device logs; benchmark non-end-to-end exports (run in FP16 on the GPU delegate) when comparing GPU paths.

📚 Learn More

Now that you have YOLO working, explore more features:

💡 Pro Tips

  • Start small: Use yolo26n for development, then move up in size if needed
  • Test on device: Emulators don't show real performance
  • Monitor memory: Watch usage when running multiple instances
  • Cache models: Keep loaded models in memory for better performance

🎉 Congratulations! You've successfully integrated YOLO into your Flutter app. Ready to build something amazing? 🚀