Objekte mit einem benutzerdefinierten Klassifizierungsmodell unter iOS erkennen, verfolgen und klassifizieren

Mit ML Kit können Sie Objekte in aufeinanderfolgenden Videoframes erkennen und verfolgen.

Wenn Sie ein Bild an ML Kit übergeben, werden bis zu fünf Objekte sowie die Position jedes Objekts im Bild erkannt. Bei der Objekterkennung in Videostreams hat jedes Objekt eine eindeutige ID, mit der Sie das Objekt von Frame zu Frame verfolgen können.

Sie können ein benutzerdefiniertes Bildklassifizierungsmodell verwenden, um die erkannten Objekte zu klassifizieren. Unter Benutzerdefinierte Modelle mit ML Kit finden Sie Informationen zu den Anforderungen an die Modellkompatibilität. Dort finden Sie auch vortrainierte Modelle und erfahren, wie Sie Ihre eigenen Modelle trainieren.

Es gibt zwei Möglichkeiten, ein benutzerdefiniertes Modell zu integrieren. Sie können das Modell bündeln, indem Sie es im Asset-Ordner Ihrer App ablegen, oder Sie können es dynamisch von Firebase herunterladen. In der folgenden Tabelle werden die beiden Optionen verglichen.

Gebündeltes Modell Gehostetes Modell
Das Modell ist Teil der Datei .ipa Ihrer Anwendung, die sich vergrößert. Das Modell ist nicht Teil der .ipa-Datei deiner App. Sie wird durch Hochladen in Firebase Machine Learning gehostet.
Das Modell ist sofort verfügbar, auch wenn das Android-Gerät offline ist Das Modell wird bei Bedarf heruntergeladen
Kein Firebase-Projekt erforderlich Erfordert ein Firebase-Projekt
Du musst deine App neu veröffentlichen, um das Modell zu aktualisieren Modellaktualisierungen übertragen, ohne die App noch einmal zu veröffentlichen
Keine integrierten A/B-Tests Einfache A/B-Tests mit Firebase Remote Config

Ausprobieren

Hinweis

  1. Fügen Sie die ML Kit-Bibliotheken in Ihre Podfile-Datei ein:

    So bündeln Sie ein Modell mit Ihrer App:

    pod 'GoogleMLKit/ObjectDetectionCustom', '3.2.0'

    Fügen Sie zum dynamischen Herunterladen eines Modells aus Firebase die Abhängigkeit LinkFirebase hinzu:

    pod 'GoogleMLKit/ObjectDetectionCustom', '3.2.0'
pod 'GoogleMLKit/LinkFirebase', '3.2.0'

  2. Nachdem Sie die Pods Ihres Projekts installiert oder aktualisiert haben, öffnen Sie Ihr Xcode-Projekt mit dessen .xcworkspace. ML Kit wird in Xcode ab Version 13.2.1 unterstützt.

  3. Wenn Sie ein Modell herunterladen möchten, müssen Sie Firebase zu Ihrem iOS-Projekt hinzufügen, falls Sie dies noch nicht getan haben. Dies ist beim Bündeln des Modells nicht erforderlich.

1. Modell laden

Lokale Modellquelle konfigurieren

So bündeln Sie das Modell mit Ihrer App:

  1. Kopieren Sie die Modelldatei (in der Regel mit der Endung .tflite oder .lite) in Ihr Xcode-Projekt und wählen Sie dabei Copy bundle resources aus. Die Modelldatei ist im App Bundle enthalten und steht für ML Kit zur Verfügung.

  2. Erstellen Sie ein LocalModel-Objekt und geben Sie den Pfad zur Modelldatei an:

    Swift

    let localModel = LocalModel(path: localModelFilePath)

    Objective-C

    MLKLocalModel *localModel =
    [[MLKLocalModel alloc] initWithPath:localModelFilePath];

Firebase-gehostete Modellquelle konfigurieren

Wenn Sie das ferngehostete Modell verwenden möchten, erstellen Sie ein CustomRemoteModel-Objekt. Geben Sie dabei den Namen an, den Sie dem Modell bei der Veröffentlichung zugewiesen haben:

Swift

let firebaseModelSource = FirebaseModelSource(
    name: "your_remote_model") // The name you assigned in
                               // the Firebase console.
let remoteModel = CustomRemoteModel(remoteModelSource: firebaseModelSource)

Objective-C

MLKFirebaseModelSource *firebaseModelSource =
    [[MLKFirebaseModelSource alloc]
        initWithName:@"your_remote_model"]; // The name you assigned in
                                            // the Firebase console.
MLKCustomRemoteModel *remoteModel =
    [[MLKCustomRemoteModel alloc]
        initWithRemoteModelSource:firebaseModelSource];

Starten Sie dann die Aufgabe zum Herunterladen des Modells und geben Sie die Bedingungen an, unter denen Sie den Download zulassen möchten. Wenn sich das Modell nicht auf dem Gerät befindet oder eine neuere Version des Modells verfügbar ist, wird es von der Aufgabe asynchron von Firebase heruntergeladen:

Swift

let downloadConditions = ModelDownloadConditions(
  allowsCellularAccess: true,
  allowsBackgroundDownloading: true
)

let downloadProgress = ModelManager.modelManager().download(
  remoteModel,
  conditions: downloadConditions
)

Objective-C

MLKModelDownloadConditions *downloadConditions =
    [[MLKModelDownloadConditions alloc] initWithAllowsCellularAccess:YES
                                         allowsBackgroundDownloading:YES];

NSProgress *downloadProgress =
    [[MLKModelManager modelManager] downloadModel:remoteModel
                                       conditions:downloadConditions];

Viele Anwendungen starten die Downloadaufgabe im Initialisierungscode, Sie können dies jedoch jederzeit tun, bevor Sie das Modell verwenden müssen.

2. Objektdetektor konfigurieren

Nachdem Sie die Modellquellen konfiguriert haben, konfigurieren Sie den Objektdetektor für Ihren Anwendungsfall mit einem CustomObjectDetectorOptions-Objekt. Sie können die folgenden Einstellungen ändern:

Einstellungen für Objektdetektor
Erkennungsmodus STREAM_MODE (Standard) | SINGLE_IMAGE_MODE

In STREAM_MODE (Standardeinstellung) wird der Objektdetektor mit niedriger Latenz ausgeführt. Bei den ersten Aufrufen des Detektors kann es jedoch zu unvollständigen Ergebnissen kommen (z. B. nicht angegebene Begrenzungsrahmen oder Kategorielabels). Außerdem weist der Detektor in STREAM_MODE Objekten Tracking-IDs zu, mit denen Sie Objekte über Frames hinweg verfolgen können. Verwenden Sie diesen Modus, wenn Sie Objekte verfolgen möchten oder eine niedrige Latenz wichtig ist, z. B. bei der Verarbeitung von Videostreams in Echtzeit.

In SINGLE_IMAGE_MODE gibt der Objektdetektor das Ergebnis zurück, nachdem der Begrenzungsrahmen des Objekts bestimmt wurde. Wenn Sie auch die Klassifizierung aktivieren, wird das Ergebnis zurückgegeben, nachdem der Begrenzungsrahmen und das Kategorielabel verfügbar sind. Infolgedessen ist die Latenz bei der Erkennung potenziell höher. Außerdem werden in SINGLE_IMAGE_MODE keine Tracking-IDs zugewiesen. Verwenden Sie diesen Modus, wenn die Latenz nicht kritisch ist und Sie sich nicht mit Teilergebnissen befassen möchten.
Mehrere Objekte erkennen und verfolgen false (Standard) | true

Gibt an, ob bis zu fünf Objekte oder nur das auffälligste Objekt erkannt und verfolgt werden soll (Standardeinstellung).
Objekte klassifizieren false (Standard) | true

Gibt an, ob erkannte Objekte mithilfe des bereitgestellten benutzerdefinierten Klassifikatormodells klassifiziert werden sollen. Wenn Sie Ihr benutzerdefiniertes Klassifizierungsmodell verwenden möchten, müssen Sie dieses Feld auf true festlegen.

Konfidenzgrenzwert für die Klassifizierung

Minimaler Konfidenzwert erkannter Labels. Wenn nichts anderes festgelegt ist, wird jeder durch die Metadaten des Modells angegebene Klassifikatorgrenzwert verwendet. Wenn das Modell keine Metadaten enthält oder die Metadaten keinen Klassifikatorschwellenwert angeben, wird ein Standardschwellenwert von 0,0 verwendet.
Maximale Anzahl von Labels pro Objekt

Maximale Anzahl der Labels pro Objekt, die der Detektor zurückgibt. Wenn die Richtlinie nicht konfiguriert ist, wird der Standardwert 10 verwendet.

Wenn Sie nur ein lokal gebündeltes Modell haben, erstellen Sie einfach einen Objektdetektor aus Ihrem LocalModel-Objekt:

Swift

let options = CustomObjectDetectorOptions(localModel: localModel)
options.detectorMode = .singleImage
options.shouldEnableClassification = true
options.shouldEnableMultipleObjects = true
options.classificationConfidenceThreshold = NSNumber(value: 0.5)
options.maxPerObjectLabelCount = 3

Objective-C

MLKCustomObjectDetectorOptions *options =
    [[MLKCustomObjectDetectorOptions alloc] initWithLocalModel:localModel];
options.detectorMode = MLKObjectDetectorModeSingleImage;
options.shouldEnableClassification = YES;
options.shouldEnableMultipleObjects = YES;
options.classificationConfidenceThreshold = @(0.5);
options.maxPerObjectLabelCount = 3;

Bei einem remote gehosteten Modell müssen Sie prüfen, ob es heruntergeladen wurde, bevor Sie es ausführen. Sie können den Status der Modelldownloadaufgabe mit der Methode isModelDownloaded(remoteModel:) des Modellmanagers prüfen.

Sie müssen dies nur vor dem Ausführen des Objektdetektors bestätigen. Wenn Sie sowohl ein extern gehostetes Modell als auch ein lokal gebündeltes Modell haben, kann es jedoch sinnvoll sein, diese Prüfung beim Instanziieren von ObjectDetector durchzuführen: Erstellen Sie einen Detektor aus dem Remote-Modell, wenn es heruntergeladen wurde, und ansonsten aus dem lokalen Modell.

Swift

var options: CustomObjectDetectorOptions!
if (ModelManager.modelManager().isModelDownloaded(remoteModel)) {
  options = CustomObjectDetectorOptions(remoteModel: remoteModel)
} else {
  options = CustomObjectDetectorOptions(localModel: localModel)
}
options.detectorMode = .singleImage
options.shouldEnableClassification = true
options.shouldEnableMultipleObjects = true
options.classificationConfidenceThreshold = NSNumber(value: 0.5)
options.maxPerObjectLabelCount = 3

Objective-C

MLKCustomObjectDetectorOptions *options;
if ([[MLKModelManager modelManager] isModelDownloaded:remoteModel]) {
  options = [[MLKCustomObjectDetectorOptions alloc] initWithRemoteModel:remoteModel];
} else {
  options = [[MLKCustomObjectDetectorOptions alloc] initWithLocalModel:localModel];
}
options.detectorMode = MLKObjectDetectorModeSingleImage;
options.shouldEnableClassification = YES;
options.shouldEnableMultipleObjects = YES;
options.classificationConfidenceThreshold = @(0.5);
options.maxPerObjectLabelCount = 3;

Wenn Sie nur ein extern gehostetes Modell haben, sollten Sie die modellbezogenen Funktionen deaktivieren, z. B. einen Teil Ihrer UI ausblenden oder ausblenden, bis Sie bestätigen, dass das Modell heruntergeladen wurde.

Sie können den Status des Modelldownloads abrufen, indem Sie dem standardmäßigen Benachrichtigungscenter Beobachter hinzufügen. Verwenden Sie im Beobachterblock unbedingt einen schwachen Verweis auf self, da Downloads einige Zeit dauern können und das ursprüngliche Objekt bis zum Abschluss des Downloads freigegeben werden kann. Beispiel:

Swift

NotificationCenter.default.addObserver(
    forName: .mlkitModelDownloadDidSucceed,
    object: nil,
    queue: nil
) { [weak self] notification in
    guard let strongSelf = self,
        let userInfo = notification.userInfo,
        let model = userInfo[ModelDownloadUserInfoKey.remoteModel.rawValue]
            as? RemoteModel,
        model.name == "your_remote_model"
        else { return }
    // The model was downloaded and is available on the device
}

NotificationCenter.default.addObserver(
    forName: .mlkitModelDownloadDidFail,
    object: nil,
    queue: nil
) { [weak self] notification in
    guard let strongSelf = self,
        let userInfo = notification.userInfo,
        let model = userInfo[ModelDownloadUserInfoKey.remoteModel.rawValue]
            as? RemoteModel
        else { return }
    let error = userInfo[ModelDownloadUserInfoKey.error.rawValue]
    // ...
}

Objective-C

__weak typeof(self) weakSelf = self;

[NSNotificationCenter.defaultCenter
    addObserverForName:MLKModelDownloadDidSucceedNotification
                object:nil
                 queue:nil
            usingBlock:^(NSNotification *_Nonnull note) {
              if (weakSelf == nil | note.userInfo == nil) {
                return;
              }
              __strong typeof(self) strongSelf = weakSelf;

              MLKRemoteModel *model = note.userInfo[MLKModelDownloadUserInfoKeyRemoteModel];
              if ([model.name isEqualToString:@"your_remote_model"]) {
                // The model was downloaded and is available on the device
              }
            }];

[NSNotificationCenter.defaultCenter
    addObserverForName:MLKModelDownloadDidFailNotification
                object:nil
                 queue:nil
            usingBlock:^(NSNotification *_Nonnull note) {
              if (weakSelf == nil | note.userInfo == nil) {
                return;
              }
              __strong typeof(self) strongSelf = weakSelf;

              NSError *error = note.userInfo[MLKModelDownloadUserInfoKeyError];
            }];

Die Objekterkennungs- und -Tracking-API ist für die folgenden beiden Hauptanwendungsfälle optimiert:

  • Live-Erkennung und Nachverfolgung des auffälligsten Objekts im Kamerasucher
  • Erkennung mehrerer Objekte in einem statischen Bild.

So konfigurieren Sie die API für diese Anwendungsfälle:

Swift

// Live detection and tracking
let options = CustomObjectDetectorOptions(localModel: localModel)
options.shouldEnableClassification = true
options.maxPerObjectLabelCount = 3

// Multiple object detection in static images
let options = CustomObjectDetectorOptions(localModel: localModel)
options.detectorMode = .singleImage
options.shouldEnableMultipleObjects = true
options.shouldEnableClassification = true
options.maxPerObjectLabelCount = 3

Objective-C

// Live detection and tracking
MLKCustomObjectDetectorOptions *options =
    [[MLKCustomObjectDetectorOptions alloc] initWithLocalModel:localModel];
options.shouldEnableClassification = YES;
options.maxPerObjectLabelCount = 3;

// Multiple object detection in static images
MLKCustomObjectDetectorOptions *options =
    [[MLKCustomObjectDetectorOptions alloc] initWithLocalModel:localModel];
options.detectorMode = MLKObjectDetectorModeSingleImage;
options.shouldEnableMultipleObjects = YES;
options.shouldEnableClassification = YES;
options.maxPerObjectLabelCount = 3;

3. Eingabebild vorbereiten

Erstellen Sie mit UIImage oder CMSampleBuffer ein VisionImage-Objekt.

Wenn Sie ein UIImage verwenden, gehen Sie so vor:

  • Erstellen Sie mit UIImage ein VisionImage-Objekt. Achten Sie darauf, den richtigen .orientation anzugeben.

    Swift

    let image = VisionImage(image: UIImage)
visionImage.orientation = image.imageOrientation

    Objective-C

    MLKVisionImage *visionImage = [[MLKVisionImage alloc] initWithImage:image];
visionImage.orientation = image.imageOrientation;

Wenn Sie ein CMSampleBuffer verwenden, gehen Sie so vor:

  • Gibt die Ausrichtung der Bilddaten an, die in CMSampleBuffer enthalten sind.

    So rufen Sie die Bildausrichtung ab:

    Swift

    func imageOrientation(
  deviceOrientation: UIDeviceOrientation,
  cameraPosition: AVCaptureDevice.Position
) -> UIImage.Orientation {
  switch deviceOrientation {
  case .portrait:
    return cameraPosition == .front ? .leftMirrored : .right
  case .landscapeLeft:
    return cameraPosition == .front ? .downMirrored : .up
  case .portraitUpsideDown:
    return cameraPosition == .front ? .rightMirrored : .left
  case .landscapeRight:
    return cameraPosition == .front ? .upMirrored : .down
  case .faceDown, .faceUp, .unknown:
    return .up
  }
}

    Objective-C

    - (UIImageOrientation)
  imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                         cameraPosition:(AVCaptureDevicePosition)cameraPosition {
  switch (deviceOrientation) {
    case UIDeviceOrientationPortrait:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationLeftMirrored
                                                            : UIImageOrientationRight;

    case UIDeviceOrientationLandscapeLeft:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationDownMirrored
                                                            : UIImageOrientationUp;
    case UIDeviceOrientationPortraitUpsideDown:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationRightMirrored
                                                            : UIImageOrientationLeft;
    case UIDeviceOrientationLandscapeRight:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationUpMirrored
                                                            : UIImageOrientationDown;
    case UIDeviceOrientationUnknown:
    case UIDeviceOrientationFaceUp:
    case UIDeviceOrientationFaceDown:
      return UIImageOrientationUp;
  }
}
  • Erstelle ein VisionImage-Objekt mit dem Objekt CMSampleBuffer und der Ausrichtung:

    Swift

    let image = VisionImage(buffer: sampleBuffer)
image.orientation = imageOrientation(
  deviceOrientation: UIDevice.current.orientation,
  cameraPosition: cameraPosition)

    Objective-C

     MLKVisionImage *image = [[MLKVisionImage alloc] initWithBuffer:sampleBuffer];
 image.orientation =
   [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                cameraPosition:cameraPosition];

4. Objektdetektor erstellen und ausführen

  1. Erstellen Sie einen neuen Objektdetektor:

    Swift

    let objectDetector = ObjectDetector.objectDetector(options: options)

    Objective-C

    MLKObjectDetector *objectDetector = [MLKObjectDetector objectDetectorWithOptions:options];

  2. Verwenden Sie dann den Detektor:

    Asynchron:

    Swift

    objectDetector.process(image) { objects, error in
    guard error == nil, let objects = objects, !objects.isEmpty else {
        // Handle the error.
        return
    }
    // Show results.
}

    Objective-C

    [objectDetector
    processImage:image
      completion:^(NSArray *_Nullable objects,
                   NSError *_Nullable error) {
        if (objects.count == 0) {
            // Handle the error.
            return;
        }
        // Show results.
     }];

    Synchron:

    Swift

    var objects: [Object]
do {
    objects = try objectDetector.results(in: image)
} catch let error {
    // Handle the error.
    return
}
// Show results.

    Objective-C

    NSError *error;
NSArray *objects =
    [objectDetector resultsInImage:image error:&error];
// Show results or handle the error.

5. Informationen zu Objekten mit Labels abrufen

Wenn der Aufruf an den Bildprozessor erfolgreich ist, übergibt dieser entweder eine Liste von Object-Werten an den Abschluss-Handler oder gibt die Liste zurück, je nachdem, ob Sie die asynchrone oder synchrone Methode aufgerufen haben.

Jeder Object enthält die folgenden Attribute:

frame Ein CGRect, das die Position des Objekts im Bild angibt.
trackingID Eine Ganzzahl, die das Objekt in Bildern identifiziert, oder "nil" in SINGLE_IMAGE_MODE.
labels
label.text Die Beschreibung des Labeltexts. Wird nur zurückgegeben, wenn die Metadaten des TensorFlow Lite-Modells Labelbeschreibungen enthalten.
label.index Index des Labels unter allen vom Klassifikator unterstützten Labels.
label.confidence Der Konfidenzwert der Objektklassifizierung.

Swift

// objects contains one item if multiple object detection wasn't enabled.
for object in objects {
  let frame = object.frame
  let trackingID = object.trackingID
  let description = object.labels.enumerated().map { (index, label) in
    "Label \(index): \(label.text), \(label.confidence), \(label.index)"
  }.joined(separator: "\n")
}

Objective-C

// The list of detected objects contains one item if multiple object detection
// wasn't enabled.
for (MLKObject *object in objects) {
  CGRect frame = object.frame;
  NSNumber *trackingID = object.trackingID;
  for (MLKObjectLabel *label in object.labels) {
    NSString *labelString =
        [NSString stringWithFormat:@"%@, %f, %lu",
                                   label.text,
                                   label.confidence,
                                   (unsigned long)label.index];
  }
}

Sicherstellen einer großartigen User Experience

Beachten Sie für eine optimale Nutzererfahrung die folgenden Richtlinien in Ihrer App:

  • Die erfolgreiche Objekterkennung hängt von der visuellen Komplexität des Objekts ab. Damit Objekte mit wenigen visuellen Merkmalen erkannt werden, müssen sie möglicherweise einen größeren Teil des Bildes einnehmen. Sie sollten Nutzern Hinweise zur Erfassung von Eingaben geben, die gut für die Art von Objekten funktionieren, die Sie erkennen möchten.
  • Wenn Sie bei der Klassifizierung Objekte erkennen möchten, die nicht ordnungsgemäß in die unterstützten Kategorien fallen, implementieren Sie eine spezielle Behandlung für unbekannte Objekte.

Sehen Sie sich auch die [Showcase-App „ML Kit Material Design“][showcase-link]{: .external } und die Sammlung Muster für durch maschinelles Lernen unterstützte Funktionen in Material Design an.

Leistung erhöhen

Wenn Sie die Objekterkennung in einer Echtzeitanwendung verwenden möchten, beachten Sie die folgenden Richtlinien, um die besten Framerates zu erzielen:

  • Wenn Sie den Streamingmodus in einer Echtzeitanwendung verwenden, sollten Sie die Erkennung mehrerer Objekte nicht verwenden, da die meisten Geräte keine angemessenen Framerates erzeugen können.

  • Verwenden Sie zum Verarbeiten von Videobildern die synchrone results(in:)-API des Detektors. Rufen Sie diese Methode über die captureOutput(_, didOutput:from:)-Funktion von AVCaptureVideoDataOutputSampleBufferDelegate auf, um synchron Ergebnisse aus dem angegebenen Videoframe zu erhalten. Behalten Sie die alwaysDiscardsLateVideoFrames von AVCaptureVideoDataOutput als true bei, um Aufrufe an den Detektor zu drosseln. Wenn ein neuer Videoframe verfügbar wird, während der Detektor ausgeführt wird, wird er gelöscht.
  • Wenn Sie die Ausgabe des Detektors verwenden, um Grafiken über das Eingabebild einzublenden, rufen Sie zuerst das Ergebnis aus ML Kit ab und rendern Sie dann das Bild und Overlay in einem einzigen Schritt. Dadurch wird für jeden verarbeiteten Eingabeframe nur einmal ein Rendering auf der Anzeigeoberfläche ausgeführt. Ein Beispiel finden Sie unter updatePreviewOverlayViewWithLastFrame im ML Kit-Schnellstartbeispiel.