Bilder mit einem benutzerdefinierten Modell unter iOS mit Labels versehen

Mit ML Kit können Sie Entitäten in einem Bild erkennen und mit Labels versehen. Diese API unterstützt eine Vielzahl von benutzerdefinierten Bildklassifizierungsmodellen. Unter Benutzerdefinierte Modelle mit ML Kit finden Sie Informationen zu den Anforderungen an die Modellkompatibilität sowie dazu, wo Sie vortrainierte Modelle finden und 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 des APK deiner App, das dessen Größe erhöht. Das Modell gehört nicht zu Ihrem APK. 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/ImageLabelingCustom', '3.2.0'

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

    pod 'GoogleMLKit/ImageLabelingCustom', '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 RemoteModel-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.

Labelersteller für Bilder konfigurieren

Nachdem Sie die Modellquellen konfiguriert haben, erstellen Sie ein ImageLabeler-Objekt aus einer davon.

Folgende Optionen sind verfügbar:

Optionen
confidenceThreshold

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.
maxResultCount

Maximale Anzahl der zurückzugebenden Labels. Wenn die Richtlinie nicht konfiguriert ist, wird der Standardwert 10 verwendet.

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

Swift

let options = CustomImageLabelerOptions(localModel: localModel)
options.confidenceThreshold = NSNumber(value: 0.0)
let imageLabeler = ImageLabeler.imageLabeler(options: options)

Objective-C

MLKCustomImageLabelerOptions *options =
    [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
options.confidenceThreshold = @(0.0);
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

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 Labelerstellers 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 ImageLabeler durchzuführen: Erstellen Sie einen Labelersteller aus dem Remote-Modell, wenn es heruntergeladen wurde, und ansonsten aus dem lokalen Modell.

Swift

var options: CustomImageLabelerOptions!
if (ModelManager.modelManager().isModelDownloaded(remoteModel)) {
  options = CustomImageLabelerOptions(remoteModel: remoteModel)
} else {
  options = CustomImageLabelerOptions(localModel: localModel)
}
options.confidenceThreshold = NSNumber(value: 0.0)
let imageLabeler = ImageLabeler.imageLabeler(options: options)

Objective-C

MLKCustomImageLabelerOptions *options;
if ([[MLKModelManager modelManager] isModelDownloaded:remoteModel]) {
  options = [[MLKCustomImageLabelerOptions alloc] initWithRemoteModel:remoteModel];
} else {
  options = [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
}
options.confidenceThreshold = @(0.0);
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

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];
            }];

2. 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];

3. Labelersteller für Bilder ausführen

Übergeben Sie das Objekt image an die Methode process() der ImageLabeler, um Objekte in einem Bild mit einem Label zu versehen.

Asynchron:

Swift

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

Objective-C

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

Synchron:

Swift

var labels: [ImageLabel]
do {
    labels = try imageLabeler.results(in: image)
} catch let error {
    // Handle the error.
    return
}
// Show results.

Objective-C

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

4. Informationen zu Elementen mit Labels abrufen

Wenn der Vorgang zum Beschriften von Bildern erfolgreich ist, wird ein Array von ImageLabel zurückgegeben. Jede ImageLabel steht für etwas, das im Bild mit einem Label versehen war. Sie können für jedes Label die Textbeschreibung (sofern in den Metadaten der TensorFlow Lite-Modelldatei verfügbar), den Konfidenzwert und den Index abrufen. Beispiel:

Swift

for label in labels {
  let labelText = label.text
  let confidence = label.confidence
  let index = label.index
}

Objective-C

for (MLKImageLabel *label in labels) {
  NSString *labelText = label.text;
  float confidence = label.confidence;
  NSInteger index = label.index;
}

Tipps zur Verbesserung der Echtzeitleistung

Wenn du Bilder in einer Echtzeitanwendung mit Labels versehen möchtest, beachte die folgenden Richtlinien, um die besten Framerates zu erzielen:

  • 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.