### Install Dependencies

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/AGENTS.md

Installs project dependencies. This command should be repeated in the 'example/' directory for the example app.

```bash
flutter pub get
```

--------------------------------

### Run Flutter Example App

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/example/README.md

Navigate to the example directory, get dependencies, and run the Flutter application.

```bash
cd example
flutter pub get
flutter run
```

--------------------------------

### Troubleshoot Flutter App Installation

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/troubleshooting.md

Run these commands to clean, get dependencies, install CocoaPods, and restart your Flutter application to resolve common installation issues.

```bash
flutter clean
flutter pub get
cd ios && pod install --repo-update # CocoaPods apps only; Swift Package Manager resolves on build
cd ..
flutter run
```

--------------------------------

### Example Usage of YOLOPerformanceMetrics

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Callback example demonstrating how to use performance metrics, including checking for issues and displaying ratings.

```dart
onPerformanceMetrics: (metrics) {
  print('Performance: ${metrics.performanceRating}');
  print('FPS: ${metrics.fps.toStringAsFixed(1)}');
  print('Processing: ${metrics.processingTimeMs.toStringAsFixed(1)}ms');

  if (metrics.hasPerformanceIssues) {
    print('⚠️ Performance issues detected');
  }
}
```

--------------------------------

### Initializing YOLOView with a Known-Good Model

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/troubleshooting.md

Use this snippet to start with a known-good model path to verify basic functionality before switching to custom models. This helps isolate issues if the camera starts but no detections appear.

```dart
YOLOView(
  modelPath: 'yolo26n',
  onResult: (results) {
    print(results.length);
  },
)
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/AGENTS.md

Installs Python dependencies using 'uv pip install'. Avoid using bare 'pip install'.

```bash
uv pip install
```

--------------------------------

### Example Usage of YOLOStreamingConfig

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Demonstrates creating instances of YOLOStreamingConfig using factory constructors and custom parameters.

```dart
// Power-saving configuration
final config = YOLOStreamingConfig.powerSaving(
  inferenceFrequency: 10,
  maxFPS: 15,
);

// Custom configuration
final customConfig = YOLOStreamingConfig(
  includeDetections: true,
  includeMasks: true,
  maxFPS: 20,
  skipFrames: 2,
);
```

--------------------------------

### Run QNN Benchmark Test

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/performance.md

Reproduce the QNN benchmark results by running the integration test. Ensure the example app's QNN runtime is opt-in.

```bash
ENABLE_QNN=1 flutter test integration_test/qnn_benchmark_test.dart -d <device> --dart-define=RUN_BENCH=true
```

--------------------------------

### YOLO Multi-Instance Example

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Demonstrates the creation of a multi-instance YOLO object and checks its registration status and the count of active instances.

```dart
// Create multi-instance YOLO
final yolo = YOLO(
  modelPath: 'model.tflite',
  task: YOLOTask.detect,
  useMultiInstance: true,
);

// Check instance registration
print('Instance registered: ${YOLOInstanceManager.hasInstance(yolo.instanceId)}');
print('Active instances: ${YOLOInstanceManager.getActiveInstanceIds().length}');
```

--------------------------------

### Bundling Nano Models at Build Time

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/performance.md

Nano models are bundled into the example app at build time for local/release builds to enable offline functionality. Larger models are hosted on releases and downloaded on demand.

```text
ping: unknown host github.com
SocketException: Failed host lookup: 'github.com'
```

--------------------------------

### Export Android LiteRT Assets

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/models.md

Use this command to set up a virtual environment and install dependencies for LiteRT export. Ensure Python version is 3.10 or higher.

```bash
uv venv --python 3.12 .venv
uv pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision
uv pip install "ultralytics-opencv-headless[export-litert]">=8.4.83
uv run python scripts/export-tflite-models.py --verify
```

--------------------------------

### Verify Model Assets Configuration

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

If a model file is not found, ensure your assets are correctly configured in `pubspec.yaml` and then run 'flutter packages get'.

```bash
# Solution: Verify assets are correctly configured in pubspec.yaml
flutter packages get
```

--------------------------------

### Test YOLO Plugin Installation in Flutter

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

A simple Flutter widget to test YOLO plugin installation. It attempts to load a model and displays a success or error message.

```dart
// lib/test_yolo.dart
import 'package:flutter/material.dart';
import 'package:ultralytics_yolo/ultralytics_yolo.dart';

class TestYOLO extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('YOLO Test')),
      body: Center(
        child: ElevatedButton(
          child: Text('Test YOLO'),
          onPressed: () async {
            try {
              final yolo = YOLO(
                modelPath: 'yolo26n',
              );

              await yolo.loadModel();
              debugPrint('YOLO loaded successfully');

              ScaffoldMessenger.of(context).showSnackBar(
                const SnackBar(content: Text('YOLO plugin working!')),
              );
            } catch (e) {
              debugPrint('Error: $e');
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Error: $e')),
              );
            }
          },
        ),
      ),
    );
  }
}
```

--------------------------------

### Clean and Rebuild Flutter Project

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

Perform a clean build of your Flutter project. For CocoaPods users, run 'pod install --repo-update' in the ios directory before rebuilding.

```bash
flutter clean
flutter pub get
cd ios && pod install --repo-update # CocoaPods apps only; Swift Package Manager resolves on build
cd .. && flutter run
```

--------------------------------

### Minimal YOLO Detection in Flutter

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/quickstart.md

Use this complete example to integrate YOLO object detection into your Flutter app. It includes model loading, image selection, and result display. Ensure you have the `ultralytics_yolo` and `image_picker` packages added to your `pubspec.yaml`.

```dart
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)}%'
                      ),
                    );
                  },
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

```

--------------------------------

### Get YOLO Storage Paths

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Retrieves the available storage paths for the app. Returns a map of storage location names to their corresponding paths.

```dart
static Future<Map<String, String?>> getStoragePaths()
```

--------------------------------

### Enable Multi-Instance Mode

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/performance.md

Enable multi-instance mode only when parallel model execution is required. This setup is for advanced use cases requiring multiple YOLO instances.

```dart
final detector = YOLO(
  modelPath: 'yolo26n',
  useMultiInstance: true,
);
```

--------------------------------

### Refresh CocoaPods for iOS Builds

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

For CocoaPods projects, navigate to the ios directory and run 'pod install --repo-update' to refresh pods and resolve 'No such module' errors.

```bash
cd ios && pod install --repo-update
```

--------------------------------

### Add YOLO Plugin to pubspec.yaml

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/quickstart.md

Add the ultralytics_yolo and image_picker dependencies to your pubspec.yaml file. Then, run 'flutter pub get' to install them.

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

--------------------------------

### Build Play Store Assets with Custom Notes

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/play-store-assets/README.md

Use the --notes flag to specify a custom file for Play release notes instead of extracting from CHANGELOG.md.

```bash
scripts/build_play_store_assets.sh --notes /path/to/whats-new.txt
```

--------------------------------

### Get Performance Rating

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Provides a string rating ('Excellent', 'Good', 'Fair', 'Poor') based on performance metrics.

```dart
String get performanceRating
```

--------------------------------

### Initialize YOLOViewController

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Instantiate the YOLOViewController to manage YOLOView.

```dart
class YOLOViewController {
  YOLOViewController();
}
```

--------------------------------

### Build Play Store Assets Script

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/play-store-assets/README.md

Execute this script from the repository root to build the signed release bundle and generate release notes and checksums.

```bash
scripts/build_play_store_assets.sh
```

--------------------------------

### Get Official YOLO Models

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Lists official model IDs that can be downloaded on the current platform. Can be filtered by task type.

```dart
static List<String> officialModels({YOLOTask? task})
```

--------------------------------

### Get Available Camera Lenses

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Retrieve a list of physical camera lenses available on the device, including their zoom factors and labels.

```dart
Future<List<LensInfo>> getAvailableLenses()
```

--------------------------------

### Create New Flutter App

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/quickstart.md

Use this command to create a new Flutter project and navigate into its directory.

```bash
flutter create yolo_demo
cd yolo_demo
```

--------------------------------

### Get Active YOLO Instance IDs

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Returns a list of all currently active YOLO instance IDs. This method is part of the YOLOInstanceManager class.

```dart
static List<String> getActiveInstanceIds()
```

--------------------------------

### Run the Flutter App

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/quickstart.md

Execute this command in your project directory to build and run the Flutter application.

```bash
flutter run
```

--------------------------------

### Access Classification Results

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Instantiate and load a YOLO model for classification. Iterate through the 'detections' list to get class names and confidence scores.

```dart
final classifier = YOLO(
  modelPath: 'assets/models/custom-cls.tflite',
  task: YOLOTask.classify,
);
await classifier.loadModel();

final results = await classifier.predict(imageBytes);
for (final item in results['detections'] ?? <dynamic>[]) {
  print('${item['className']}: ${item['confidence']}');
}
```

--------------------------------

### Configure Gradle for QNN Models (Android)

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/README.md

Add these configurations to your android/app/build.gradle file to enable Qualcomm NPU support for QNN models.

```groovy
android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging = true // the Hexagon DSP loader needs real .so files, not APK-mmapped ones
        }
    }
}

dependencies {
    implementation 'com.microsoft.onnxruntime:onnxruntime-android-qnn:1.26.0'
    implementation 'com.qualcomm.qti:qnn-runtime:2.46.0' // newer than the AAR's bundled QAIRT; required for the latest Snapdragons
}
```

--------------------------------

### Clean and Rebuild Flutter Project

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

Use this command sequence to resolve MissingPluginException by cleaning the project, fetching dependencies, and running the app.

```bash
flutter clean
flutter pub get
flutter run
```

--------------------------------

### Switch YOLO Models

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/models.md

Demonstrates switching YOLO models using official IDs and asset paths with a specified task. Ensure the `yoloview` package is imported.

```dart
final controller = YOLOViewController();

await controller.switchModel('yolo26n');
await controller.switchModel('assets/models/custom.tflite', YOLOTask.detect);
```

--------------------------------

### Run All Tests

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/AGENTS.md

Executes all tests defined in the project.

```bash
flutter test
```

--------------------------------

### Get Registered YOLO Instance

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Retrieves a registered YOLO instance by its instance ID. Returns null if the instance is not found. This method is part of the YOLOInstanceManager class.

```dart
static YOLO? getInstance(String instanceId)
```

--------------------------------

### YOLOView Constructor

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Initializes the YOLOView widget with various configuration options for object detection and model management.

```APIDOC
## YOLOView Constructor

### Description
Initializes the YOLOView widget with various configuration options for object detection and model management.

### Parameters
#### Constructor Parameters
- **`modelPath`** (String) - Required - Official model ID, local path, asset path, or URL
- **`task`** (YOLOTask?) - Optional - YOLO task type when metadata is missing
- **`controller`** (YOLOViewController?) - Optional - Custom view controller
- **`cameraResolution`** (String) - Optional - Camera resolution (Default: "720p")
- **`onResult`** (Function(List<YOLOResult>)?) - Optional - Detection results callback
- **`onPerformanceMetrics`** (Function(YOLOPerformanceMetrics)?) - Optional - Performance metrics callback
- **`onStreamingData`** (Function(Map<String, dynamic>)?) - Optional - Comprehensive streaming callback
- **`onZoomChanged`** (Function(double)?) - Optional - Zoom level change callback
- **`onModelError`** (void Function(Object, String, YOLOTask?)?) - Optional - Called when a model load or in-place switch fails; carries the failed request's model path and requested task
- **`onModelLoad`** (void Function(String, YOLOTask?)?) - Optional - Called after a model loads or switches successfully; carries the request's model path and requested task (null when inferred from metadata)
- **`streamingConfig`** (YOLOStreamingConfig?) - Optional - Streaming configuration
- **`confidenceThreshold`** (double) - Optional - Initial confidence threshold for YOLOView (Default: 0.25)
- **`iouThreshold`** (double) - Optional - Initial IoU threshold for YOLOView (Default: 0.7)
- **`useGpu`** (bool) - Optional - Allow GPU acceleration on Android (LiteRT 2.x GPU → CPU ladder); set `false` to force CPU (Default: true)
- **`lensFacing`** (LensFacing) - Optional - Initial camera lens selection (Default: LensFacing.back)

### Example
```dart
// Basic usage
YOLOView(
  modelPath: 'yolo26n',
  controller: controller,
  onResult: (results) {
    print('Detections: ${results.length}');
  },
)
```
```

--------------------------------

### Live Camera App Model Loading

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/README.md

Use YOLOView for live camera feeds. Specify the model path directly.

```dart
YOLOView(modelPath: 'yolo26n')
```

--------------------------------

### Initialize YOLOView Widget

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Basic usage of the YOLOView widget. Specify the model path and provide a callback for detection results. Ensure the modelPath is a valid official model ID, local path, asset path, or URL.

```dart
YOLOView(
  modelPath: 'yolo26n',
  controller: controller,
  onResult: (results) {
    print('Detections: ${results.length}');
  },
)
```

--------------------------------

### Re-resolve Packages for Swift Package Manager

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

For Swift Package Manager projects, clean the Flutter project, get dependencies, and then re-resolve packages to fix iOS build issues.

```bash
flutter clean && flutter pub get
```

--------------------------------

### Live Camera Inference with YOLOView

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/README.md

Utilize YOLOView for real-time camera inference. A controller is needed to manage the view and switch models.

```dart
final controller = YOLOViewController();

YOLOView(
  modelPath: 'yolo26n',
  controller: controller,
  onResult: (results) {},
)

await controller.switchModel('assets/models/custom.tflite', YOLOTask.detect);
```

--------------------------------

### switchCamera()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Switch between front and back camera.

```APIDOC
## switchCamera()

Switch between front and back camera.

### Method

```dart
Future<void> switchCamera()
```
```

--------------------------------

### Load Custom Model from Local File Path

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/models.md

Initialize the YOLO plugin with a custom model from a local file path already downloaded by the app.

```dart
final yolo = YOLO(modelPath: file.path);
```

--------------------------------

### Minimal Streaming Configuration

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Factory constructor for a minimal streaming configuration optimized for best performance.

```dart
factory YOLOStreamingConfig.minimal()
```

--------------------------------

### Shell script to fetch bundled models

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/performance.md

Shell script to download YOLO nano models for bundling into the app. It's designed to be run at build time and is skipped under CI to maintain fast builds.

```shell
scripts/fetch_bundled_models.sh
```

--------------------------------

### Switching YOLO Models

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/troubleshooting.md

Demonstrates various ways to switch models in YOLOViewController. Ensure the path or URL is valid and check custom export metadata if switching fails.

```dart
await controller.switchModel('yolo26n');
```

```dart
await controller.switchModel('assets/models/custom.tflite', YOLOTask.detect);
```

```dart
await controller.switchModel('https://example.com/model.tflite', YOLOTask.detect);
```

--------------------------------

### Import YOLOShowcase Widget

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Import the necessary package to use the YOLOShowcase widget. This provides a complete camera UI with a single import.

```dart
import 'package:ultralytics_yolo/ultralytics_yolo.dart';

YOLOShowcase()
```

--------------------------------

### Export LiteRT model for GPU benchmarking (Python)

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/use_gpu_feature.md

Export a LiteRT model for GPU benchmarking. This command exports the FP32 model to run in FP16 on the LiteRT GPU delegate, with NMS handled by the plugin and the raw YOLO26 head kept for Android LiteRT conversion. Use this when `useGpu: true` and verify the delegate from LiteRT logs.

```python
from ultralytics import YOLO

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

--------------------------------

### Real-time Camera Inference with YOLOView

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/index.md

Use the YOLOView widget for live camera inference. Provide the model path and a callback function to receive the detection results.

```dart
YOLOView(
  modelPath: 'yolo26n',
  onResult: (results) {},
)
```

--------------------------------

### Full Streaming Configuration

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Factory constructor for a full streaming configuration with all features enabled except for the original image.

```dart
factory YOLOStreamingConfig.full()
```

--------------------------------

### YOLOViewController Class

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Controller for managing YOLOView behavior and settings.

```APIDOC
## YOLOViewController Class

Controller for managing YOLOView behavior and settings.

```dart
class YOLOViewController {
  YOLOViewController();
}
```

### Properties

| Property              | Type             | Description                                                         |
| --------------------- | ---------------- | ------------------------------------------------------------------- |
| `confidenceThreshold` | `double`         | Current confidence threshold (0.0-1.0)                              |
| `iouThreshold`        | `double`         | Current IoU threshold (0.0-1.0)                                     |
| `numItemsThreshold`   | `int`            | Maximum number of detections (1-100)                                |
| `isInitialized`       | `bool`           | Whether controller is initialized                                   |
| `zoomEvents`          | `Stream<double>` | Broadcast stream of zoom-factor changes emitted by the native layer |
| `lensEvents`          | `Stream<String>` | Broadcast stream of lens-switch events emitted by the native layer  |
| `focusEvents`         | `Stream<Offset>` | Broadcast stream of tap-to-focus coordinates (view-relative)        |
```

--------------------------------

### Power-Saving Streaming Configuration

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Factory constructor for a power-saving streaming configuration with a default inference frequency of 10 and max FPS of 15.

```dart
factory YOLOStreamingConfig.powerSaving({
  int inferenceFrequency = 10,
  int maxFPS = 15,
})
```

--------------------------------

### YOLO Class Constructor

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Initializes a YOLO instance with specified model path and optional configurations for task, GPU usage, multi-instance support, classifier options, and item threshold.

```APIDOC
## YOLO Class Constructor

### Description
Initializes a YOLO instance with specified model path and optional configurations for task, GPU usage, multi-instance support, classifier options, and item threshold.

### Parameters
#### Constructor Parameters
- **modelPath** (String) - Required - Official model ID, local path, asset path, or URL
- **task** (YOLOTask?) - Optional - Type of YOLO task to perform when metadata is missing
- **useGpu** (bool) - Optional - Allow GPU acceleration on Android (LiteRT 2.x GPU → CPU ladder); iOS uses Core ML. Set `false` to force CPU. Default: `true`
- **useMultiInstance** (bool) - Optional - Enable multi-instance support. Default: `false`
- **classifierOptions** (Map<String, dynamic>?) - Optional - Optional classifier preprocessing and label overrides
- **numItemsThreshold** (int?) - Optional - Maximum number of returned detections. Default: `30`
```

--------------------------------

### Initialize and Load Semantic Segmentation Model

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Instantiate and load a YOLO model for semantic segmentation. Access the 'semanticMask' from the results.

```dart
final segmenter = YOLO(
  modelPath: 'yolo26n-sem',
  task: YOLOTask.semantic,
);
await segmenter.loadModel();

final results = await segmenter.predict(imageBytes);
final semanticMask = results['semanticMask'] as Map?;
print('Mask: ${semanticMask?['width']}x${semanticMask?['height']}');
```

--------------------------------

### Runtime Model Switching for Pose Estimation

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Demonstrates runtime switching between an official model and a custom export for pose estimation tasks. This allows for dynamic model updates during application runtime.

```dart
final controller = YOLOViewController();

await controller.switchModel('yolo26n');
await controller.switchModel('assets/models/custom-pose.tflite', YOLOTask.pose);
```

--------------------------------

### setStreamingConfig()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Configure the streaming behavior of the camera.

```APIDOC
## setStreamingConfig()

### Description
Configure streaming behavior.

### Method
`Future<void> setStreamingConfig(YOLOStreamingConfig config)`

### Parameters
#### Path Parameters
- `config` (YOLOStreamingConfig) - Required - The streaming configuration object.
```

--------------------------------

### withClassifierOptions()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Creates a YOLO instance specifically configured for classification models, including options for custom preprocessing and GPU usage.

```APIDOC
## withClassifierOptions()

### Description
Create a YOLO instance configured for classification models that need custom preprocessing.

### Method
```dart
static YOLO withClassifierOptions({
  required String modelPath,
  YOLOTask? task,
  required Map<String, dynamic> classifierOptions,
  bool useGpu = true,
  bool useMultiInstance = false,
})
```

### Parameters
#### Path Parameters
- `modelPath` (String) - Required - Path to the classification model file.
- `task` (YOLOTask?) - Optional - The task type for the model.
- `classifierOptions` (Map<String, dynamic>) - Required - Custom options for classifier preprocessing.
- `useGpu` (bool) - Optional - Default: `true` - Whether to use GPU for inference.
- `useMultiInstance` (bool) - Optional - Default: `false` - Whether to use multi-instance inference.
```

--------------------------------

### Configure Streaming

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Configure the behavior of the camera's video streaming.

```dart
Future<void> setStreamingConfig(YOLOStreamingConfig config)
```

--------------------------------

### YOLOStreamingConfig

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Configuration options for controlling real-time streaming behavior, including which data types to include and performance-related settings.

```APIDOC
## YOLOStreamingConfig Class

Configuration for real-time streaming behavior.

### Properties

| Property                  | Type        | Default | Description                      |
| ------------------------- | ----------- | ------- | -------------------------------- |
| `includeDetections`       | `bool`      | `true`  | Include detection results        |
| `includeClassifications`  | `bool`      | `true`  | Include classification results   |
| `includeProcessingTimeMs` | `bool`      | `true`  | Include processing time          |
| `includeFps`              | `bool`      | `true`  | Include FPS metrics              |
| `includeMasks`            | `bool`      | `false` | Include segmentation masks       |
| `includePoses`            | `bool`      | `false` | Include pose keypoints           |
| `includeOBB`              | `bool`      | `false` | Include oriented bounding boxes  |
| `includeOriginalImage`    | `bool`      | `false` | Include original frame data      |
| `maxFPS`                  | `int?`      | `null`  | Maximum FPS limit                |
| `throttleInterval`        | `Duration?` | `null`  | Throttling interval              |
| `inferenceFrequency`      | `int?`      | `null`  | Inference frequency (per second) |
| `skipFrames`              | `int?`      | `null`  | Number of frames to skip         |

### Factory Constructors

##### `minimal()`

Minimal streaming configuration for best performance.

```dart
factory YOLOStreamingConfig.minimal()
```

##### `withMasks()`

Configuration including segmentation masks.

```dart
factory YOLOStreamingConfig.withMasks()
```

##### `full()`

Full configuration with all features except original image.

```dart
factory YOLOStreamingConfig.full()
```

##### `debug()`

Debug configuration including original image data.

```dart
factory YOLOStreamingConfig.debug()
```

##### `throttled()`

Throttled configuration with FPS limiting.

```dart
factory YOLOStreamingConfig.throttled({
  required int maxFPS,
  bool includeMasks = false,
  bool includePoses = false,
  int? inferenceFrequency,
  int? skipFrames,
})
```

##### `powerSaving()`

Power-saving configuration with reduced frequency.

```dart
factory YOLOStreamingConfig.powerSaving({
  int inferenceFrequency = 10,
  int maxFPS = 15,
})
```

##### `highPerformance()`

High-performance configuration for maximum throughput.

```dart
factory YOLOStreamingConfig.highPerformance({
  int inferenceFrequency = 30,
})
```

### Example

```dart
// Power-saving configuration
final config = YOLOStreamingConfig.powerSaving(
  inferenceFrequency: 10,
  maxFPS: 15,
);

// Custom configuration
final customConfig = YOLOStreamingConfig(
  includeDetections: true,
  includeMasks: true,
  maxFPS: 20,
  skipFrames: 2,
);
```
```

--------------------------------

### Exporting LiteRT Model for GPU Comparison

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/troubleshooting.md

Export a non-end-to-end LiteRT model to compare FP16 throughput on Android. This is useful for diagnosing slow performance or GPU/CPU fallback issues.

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

--------------------------------

### Upgrade YOLOView from 0.3.x to 0.4.0

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Demonstrates typical upgrade paths from older YOLO Flutter versions, replacing Dart-side overlays and controls with native solutions or custom Flutter widgets.

```dart
// 0.3.x: YOLOView plus package-provided Dart controls/overlays.
YOLOView(
  modelPath: 'yolo26n',
  onResult: (results) {},
)

// 0.4.0: full built-in experience.
YOLOShowcase()

// 0.4.0: custom experience.
Stack(
  children: [
    YOLOView(modelPath: 'yolo26n', controller: controller),
    Align(
      alignment: Alignment.bottomCenter,
      child: ThresholdSliderRow(
        label: 'Confidence',
        value: confidence,
        min: 0.0,
        max: 1.0,
        onChanged: controller.setConfidenceThreshold,
      ),
    ),
  ],
)
```

--------------------------------

### Dynamic Model Switching with YOLOViewController

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/quickstart.md

Utilize YOLOViewController to switch between different YOLO models without restarting the app. Initialize the controller and pass it to the YOLOView widget.

```dart
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);
```

--------------------------------

### YOLOStreamingConfig Class Definition

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Defines the default configuration for real-time streaming, including options for detections, classifications, and performance metrics.

```dart
class YOLOStreamingConfig {
  const YOLOStreamingConfig({
    this.includeDetections = true,
    this.includeClassifications = true,
    this.includeProcessingTimeMs = true,
    this.includeFps = true,
    this.includeMasks = false,
    this.includePoses = false,
    this.includeOBB = false,
    this.includeOriginalImage = false,
    this.maxFPS,
    this.throttleInterval,
    this.inferenceFrequency,
    this.skipFrames,
  });
}
```

--------------------------------

### Load YOLO Model and Predict

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/index.md

Instantiate the YOLO class with a model path, load the model, and then perform predictions on image bytes. Ensure the model is loaded before making predictions.

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

--------------------------------

### YOLOView Widget Constructor

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Defines the constructor for the YOLOView widget, which provides a real-time camera view with YOLO processing. It accepts various parameters for model configuration, performance metrics, and event handling.

```dart
class YOLOView extends StatefulWidget {
  const YOLOView({
    Key? key,
    required this.modelPath,
    this.task,
    this.controller,
    this.cameraResolution = "720p",
    this.onResult,
    this.onPerformanceMetrics,
    this.onStreamingData,
    this.onZoomChanged,
    this.onModelError,
    this.onModelLoad,
    this.streamingConfig,
    this.confidenceThreshold = 0.25,
    this.iouThreshold = 0.7,
    this.useGpu = true,
    this.lensFacing = LensFacing.back,
  }) : super(key: key);
}
```

--------------------------------

### Configure ProGuard/R8 for Release Builds

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

If using custom R8 configurations, add these rules to android/app/proguard-rules.pro to prevent crashes in release builds by keeping necessary LiteRT and TensorFlow classes.

```proguard
# android/app/proguard-rules.pro
-keep class com.google.ai.edge.litert.** { *; }
-keep interface com.google.ai.edge.litert.** { *; }
-dontwarn com.google.ai.edge.litert.**
-keep class org.tensorflow.** { *; }
-keep class com.ultralytics.** { *; }
-dontwarn org.tensorflow.**
```

--------------------------------

### High-Performance Streaming Configuration

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Factory constructor for a high-performance streaming configuration with a default inference frequency of 30.

```dart
factory YOLOStreamingConfig.highPerformance({
  int inferenceFrequency = 30,
})
```

--------------------------------

### Initialize YOLO Model

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Instantiate the YOLO class to initialize a YOLO model. Specify the model path and optional parameters like task type, GPU usage, and multi-instance support.

```dart
class YOLO {
  YOLO({
    required String modelPath,
    YOLOTask? task,
    bool useGpu = true,
    bool useMultiInstance = false,
    Map<String, dynamic>? classifierOptions,
    int? numItemsThreshold,
  });
}
```

--------------------------------

### toggleTorch()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Toggle the active camera torch (flashlight) between on and off.

```APIDOC
## toggleTorch()

Toggle the active camera torch (flashlight) between on and off.

### Method

```dart
Future<void> toggleTorch()
```
```

--------------------------------

### Live Detection with Default Model

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Implement a camera-first application displaying live object detection results using the default official YOLO model. The controller manages the camera feed and result callbacks.

```dart
class LiveDetectionScreen extends StatelessWidget {
  final controller = YOLOViewController();

  @override
  Widget build(BuildContext context) {
    return YOLOView(
      modelPath: 'yolo26n',
      controller: controller,
      onResult: (results) {
        if (results.isNotEmpty) {
          print(results.first.className);
        }
      },
    );
  }
}
```

--------------------------------

### R8/ProGuard Rules for Release Builds (Android)

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/troubleshooting.md

If release builds crash on model load or show no detections on Android, R8 might be stripping necessary classes. Add these rules to `android/app/proguard-rules.pro` to keep LiteRT and TensorFlow classes.

```proguard
-keep class com.google.ai.edge.litert.** { *; }
-keep interface com.google.ai.edge.litert.** { *; }
-dontwarn com.google.ai.edge.litert.**
-keep class org.tensorflow.** { *; }
-dontwarn org.tensorflow.**
```

--------------------------------

### Throttled Streaming Configuration

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Factory constructor for a throttled streaming configuration with FPS limiting and optional parameters for masks, poses, inference frequency, and skipped frames.

```dart
factory YOLOStreamingConfig.throttled({
  required int maxFPS,
  bool includeMasks = false,
  bool includePoses = false,
  int? inferenceFrequency,
  int? skipFrames,
})
```

--------------------------------

### Full Ultralytics Camera UI with YOLOShowcase

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Use `YOLOShowcase` for a complete Ultralytics camera UI, including model/task controls, thresholds, lens controls, capture, and performance labels.

```dart
YOLOShowcase(
  initialTask: YOLOTask.detect,
  initialModelSize: 'n',
  onCapture: (bytes) {},
)
```

--------------------------------

### NDK r28 Page Size Message

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/android/src/main/cpp/CMakeLists.txt

Logs a status message indicating that 16KB page size support is enabled by default for arm64-v8a and x86_64 ABIs with NDK r28. This configuration is noted for documentation but is no longer strictly necessary.

```cmake
if(ANDROID_ABI STREQUAL "arm64-v8a" OR ANDROID_ABI STREQUAL "x86_64")
    message(STATUS "NDK r28: 16KB page size support enabled by default for ${ANDROID_ABI}")
endif()
```

--------------------------------

### Load Custom Model from Remote URL

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/models.md

Initialize the YOLO plugin with a custom model from a remote URL, specifying the task explicitly.

```dart
final yolo = YOLO(
  modelPath: 'https://example.com/models/custom.tflite',
  task: YOLOTask.detect,
);
```

--------------------------------

### Define Native Library

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/android/src/main/cpp/CMakeLists.txt

Defines the shared native library named 'ultralytics' and specifies the source file 'native-lib.cpp'. This is the main entry point for the native code.

```cmake
add_library(
ultralytics           # Library name (used in System.loadLibrary)
SHARED
native-lib.cpp        # C++ source file
)
```

--------------------------------

### switchModel()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Dynamically switch to a different YOLO model without restarting the camera. Supports official model IDs, local paths, asset paths, URLs, and metadata-based task resolution.

```APIDOC
## switchModel()

### Description
Dynamically switch to a different model without restarting the camera.

### Method
`Future<void> switchModel(String modelPath, [YOLOTask? task])`

### Parameters
#### Path Parameters
- `modelPath` (String) - Required - Official model ID, local path, asset path, or URL
- `task` (YOLOTask?) - Optional - The YOLO task type when metadata is missing

### Throws
- `PlatformException` - If model file cannot be found or loaded

### Note
This method uses the same model resolver as `YOLO` and `YOLOView`, so it supports official IDs, asset paths, local files, remote URLs, and metadata-based task resolution.

### Example
```dart
// Switch to a custom model
await controller.switchModel(
  'assets/models/custom.tflite',
  YOLOTask.detect,
);

// Handle errors
try {
  await controller.switchModel('new_model.tflite');
} catch (e) {
  print('Failed to load model: $e');
}
```
```

--------------------------------

### Photo Picker/Gallery Workflow Model Loading

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/README.md

Use the YOLO class for photo picker or gallery workflows. Specify the model path.

```dart
YOLO(modelPath: 'yolo26n')
```

--------------------------------

### Run Test by Exact Name

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/AGENTS.md

Executes a single test identified by its exact name.

```bash
flutter test --plain-name 'exact test name'
```

--------------------------------

### Load Smallest YOLO Model

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/performance.md

Instantiate the YOLO model with a small, fast model like 'yolo26n'. This is suitable for the default app flow.

```dart
final fast = YOLO(modelPath: 'yolo26n');
```

--------------------------------

### zoomIn()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Increase the camera zoom level by one step.

```APIDOC
## zoomIn()

### Description
Increase camera zoom by one step.

### Method
`Future<void> zoomIn()`
```

--------------------------------

### Access Pose Estimation Results

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Instantiate and load a YOLO model for pose estimation. Access the 'keypoints' list for each detected pose.

```dart
final poseModel = YOLO(
  modelPath: 'assets/models/custom-pose.tflite',
  task: YOLOTask.pose,
);
await poseModel.loadModel();

final results = await poseModel.predict(imageBytes);
for (final pose in results['detections'] ?? <dynamic>[]) {
  print('Keypoints: ${(pose['keypoints'] as List?)?.length ?? 0}');
}
```

--------------------------------

### Run Specific Test File

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/AGENTS.md

Executes tests located in a particular file.

```bash
flutter test test/yolo_test.dart
```

--------------------------------

### Initialize and Detect Objects in Single Image

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Use the `YOLO` class for single-image inference when you have image bytes. Ensure the model is loaded before prediction.

```dart
import 'dart:io';
import 'package:ultralytics_yolo/ultralytics_yolo.dart';

class ObjectDetector {
  late final YOLO yolo;

  Future<void> initialize() async {
    yolo = YOLO(modelPath: 'yolo26n');
    await yolo.loadModel();
  }

  Future<List<dynamic>> detect(File imageFile) async {
    final imageBytes = await imageFile.readAsBytes();
    final results = await yolo.predict(imageBytes);
    return results['boxes'] ?? [];
  }
}
```

--------------------------------

### restartCamera()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Restart the camera session after it has been stopped.

```APIDOC
## restartCamera()

### Description
Restart the camera session after stopping it.

### Method
`Future<void> restartCamera()`
```

--------------------------------

### Initialize YOLO with Official Model ID

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/install.md

Initialize the YOLO plugin using an official model ID. Use YOLO.officialModels() to list available IDs.

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

--------------------------------

### setLens()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Switch to the physical lens whose zoom factor is nearest to the requested value.

```APIDOC
## setLens()

### Description
Switch to the physical lens whose zoom factor is nearest to the requested value.

### Method
`Future<void> setLens(double zoomFactor)`

### Parameters
#### Path Parameters
- `zoomFactor` (double) - Required - Target zoom factor; the nearest available lens is selected.
```

--------------------------------

### switchModel()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Switches the currently loaded YOLO model to a new model specified by its path. Optionally sets a new task type if metadata is missing.

```APIDOC
## switchModel()

### Description
Switch to a different model (requires viewId to be set).

### Method
```dart
Future<void> switchModel(String newModelPath, [YOLOTask? newTask])
```

### Parameters
#### Path Parameters
- `newModelPath` (String) - Path to the new model file
- `newTask` (YOLOTask?) - Task type for the new model when metadata is missing

### Throws
- `StateError` - If view not initialized
- `ModelLoadingException` - If model switch fails
```

--------------------------------

### Initialize YOLO with Explicit Task

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Instantiate the YOLO model with a custom TFLite model path and explicitly define the task if metadata is missing.

```dart
final yolo = YOLO(
  modelPath: 'assets/models/custom.tflite',
  task: YOLOTask.detect,
);
```

--------------------------------

### Monitor Model Download Progress

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Listen to the downloadProgress stream to track the progress of official model asset downloads. The stream emits DownloadProgress objects.

```dart
YOLOModelManager.downloadProgress.listen((progress) {
  print('Download: ${(progress.fraction * 100).toStringAsFixed(0)}%');
});
```

--------------------------------

### registerInstance

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Registers a YOLO instance with a unique identifier. This allows for managing multiple YOLO models or configurations simultaneously.

```APIDOC
## registerInstance

### Description
Registers a YOLO instance with a unique identifier.

### Method
`static void registerInstance(String instanceId, YOLO instance)`

### Parameters
- **instanceId** (String) - Required - The unique identifier for the YOLO instance.
- **instance** (YOLO) - Required - The YOLO instance to register.
```

--------------------------------

### Capture Photo with Overlays Option

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Capture a JPEG photo of the current camera frame. Optionally include native detection overlays.

```dart
Future<Uint8List?> capturePhoto({bool withOverlays = true})
```

--------------------------------

### getStoragePaths()

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/api.md

Retrieves the available storage paths on the application's platform, useful for determining where to save or load models.

```APIDOC
## getStoragePaths()

### Description
Get available storage paths for the app.

### Method
```dart
static Future<Map<String, String?>> getStoragePaths()
```

### Returns
Map of storage location names to paths
```

--------------------------------

### LiteRT GPU Accelerator Registration Log

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/performance.md

Log output indicating the LiteRT GPU accelerator is registered and compiling the TFLite graph for OpenCL delegate. This confirms GPU offloading for INT8 models.

```text
RegisterAccelerator: name=LiteRT GPU
Replacing 395 out of 395 node(s) with delegate (LITERT_CL)
ObjectDetector: LiteRT compiled on GPU; inputDims=[1, 640, 640, 3] outputDims=[[1, 84, 8400]]
```

--------------------------------

### Access OBB Results

Source: https://github.com/ultralytics/yolo-flutter-app/blob/main/doc/usage.md

Instantiate and load a YOLO model for Oriented Bounding Box (OBB) detection. Access class names and angles from the results.

```dart
final obbModel = YOLO(
  modelPath: 'assets/models/custom-obb.tflite',
  task: YOLOTask.obb,
);
await obbModel.loadModel();

final results = await obbModel.predict(imageBytes);
for (final detection in results['detections'] ?? <dynamic>[]) {
  final result = YOLOResult.fromMap(Map<String, dynamic>.from(detection));
  print('${result.className}: angle=${result.angle}');
}
```