Oznaczanie obrazów etykietami za pomocą modelu wytrenowanego przez AutoML na platformach Apple

Po wytrenowaniu własnego modelu za pomocą AutoML Vision Edge możesz go używać w aplikacji do oznaczania obrazów.

Modele wytrenowane za pomocą AutoML Vision Edge można integrować na 2 sposoby. Możesz zgrupować model, kopiując jego pliki do projektu Xcode, lub pobrać go dynamicznie z Firebase.

Zanim zaczniesz

1. Uwzględnij biblioteki ML Kit w pliku Podfile:

   Aby połączyć model z aplikacją:

   pod 'GoogleMLKit/ImageLabelingCustom'
   

   Aby dynamicznie pobierać model z Firebase, dodaj zależność LinkFirebase:

   pod 'GoogleMLKit/ImageLabelingCustom'
   pod 'GoogleMLKit/LinkFirebase'
   

2. Po zainstalowaniu lub zaktualizowaniu pakietów projektu otwórz projekt Xcode za pomocą .xcworkspace. ML Kit jest obsługiwany w Xcode w wersji 12.2 lub nowszej.

3. Jeśli chcesz pobrać model, dodaj Firebase do projektu na Androida, jeśli nie zostało to jeszcze zrobione. Nie jest to wymagane, gdy model jest w pakiecie.

1. Wczytaj model

Konfigurowanie źródła lokalnego modelu

Aby połączyć model z aplikacją:

1. Wyodrębnij model i jego metadane z archiwum ZIP pobranego z konsoli Firebase do folderu:

   your_model_directory
     |____dict.txt
     |____manifest.json
     |____model.tflite
   

   Wszystkie 3 pliki muszą znajdować się w tym samym folderze. Zalecamy używanie plików w postaci pobranej, bez wprowadzania zmian (w tym nazw plików).

2. Skopiuj folder do projektu Xcode, pamiętając o zaznaczeniu opcji Utwórz odwołania do folderu. Plik modelu i metadane zostaną uwzględnione w pakiecie aplikacji i będą dostępne dla ML Kit.

3. Utwórz obiekt LocalModel, podając ścieżkę do pliku manifestu modelu:

   Swift

   guard let manifestPath = Bundle.main.path(
       forResource: "manifest",
       ofType: "json",
       inDirectory: "your_model_directory"
   ) else { return true }
   let localModel = LocalModel(manifestPath: manifestPath)
   

   Objective-C

   NSString *manifestPath =
       [NSBundle.mainBundle pathForResource:@"manifest"
                                     ofType:@"json"
                                inDirectory:@"your_model_directory"];
   MLKLocalModel *localModel =
       [[MLKLocalModel alloc] initWithManifestPath:manifestPath];
   

Konfigurowanie źródła modelu hostowanego w Firebase

Aby użyć modelu hostowanego zdalnie, utwórz obiekt CustomRemoteModel, podając nazwę przypisaną do modelu podczas jego publikowania:

// Initialize the model source with the name you assigned in
// the Firebase console.
let remoteModelSource = FirebaseModelSource(name: "your_remote_model")
let remoteModel = CustomRemoteModel(remoteModelSource: remoteModelSource)

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

Następnie uruchom zadanie pobierania modelu, określając warunki, na jakich chcesz zezwolić na pobieranie. Jeśli model nie jest dostępny na urządzeniu lub jest dostępna nowsza wersja modelu, zadanie pobiera go asynchronicznie z Firebase:

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

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

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

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

Wiele aplikacji inicjuje zadanie pobierania w kodzie inicjującym, ale możesz to zrobić w dowolnym momencie, zanim zaczniesz używać modelu.

Tworzenie etykiet obrazów na podstawie modelu

Po skonfigurowaniu źródeł modelu utwórz obiekt ImageLabeler na podstawie jednego z nich.

Jeśli masz tylko model zainstalowany lokalnie, utwórz etykietownik na podstawie obiektu LocalModel i skonfiguruj próg poziomu ufności, który chcesz wymagać (patrz Ocenianie modelu):

let options = CustomImageLabelerOptions(localModel: localModel)
options.confidenceThreshold = NSNumber(value: 0.0)  // Evaluate your model in the Cloud console
                                                    // to determine an appropriate value.
let imageLabeler = ImageLabeler.imageLabeler(options)

CustomImageLabelerOptions *options =
    [[CustomImageLabelerOptions alloc] initWithLocalModel:localModel];
options.confidenceThreshold = @(0.0f);  // Evaluate your model in the Cloud console
                                        // to determine an appropriate value.
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

Jeśli model jest hostowany zdalnie, przed jego uruchomieniem musisz sprawdzić, czy został pobrany. Stan zadania pobierania modelu możesz sprawdzić, korzystając z metody isModelDownloaded(remoteModel:) menedżera modeli.

Musisz to potwierdzić tylko przed uruchomieniem etykietowania, ale jeśli masz model hostowany zdalnie i model w pakiecie lokalnym, warto wykonać tę weryfikację podczas tworzenia instancji ImageLabeler: utwórz etykietowanie z modelu zdalnego, jeśli został pobrany, a w przeciwnym razie z modelu lokalnego.

var options: CustomImageLabelerOptions
if (ModelManager.modelManager().isModelDownloaded(remoteModel)) {
  options = CustomImageLabelerOptions(remoteModel: remoteModel)
} else {
  options = CustomImageLabelerOptions(localModel: localModel)
}
options.confidenceThreshold = NSNumber(value: 0.0)  // Evaluate your model in the Firebase console
                                                    // to determine an appropriate value.
let imageLabeler = ImageLabeler.imageLabeler(options: options)

MLKCustomImageLabelerOptions *options;
if ([[MLKModelManager modelManager] isModelDownloaded:remoteModel]) {
  options = [[MLKCustomImageLabelerOptions alloc] initWithRemoteModel:remoteModel];
} else {
  options = [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
}
options.confidenceThreshold = @(0.0f);  // Evaluate your model in the Firebase console
                                        // to determine an appropriate value.
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

Jeśli masz tylko model hostowany zdalnie, wyłącz funkcje związane z modelem (np. wygaszaj lub ukryj część interfejsu użytkownika), dopóki nie potwierdzisz, że model został pobrany.

Stan pobierania modelu możesz uzyskać, dołączając obserwatorów do domyślnego Centrum powiadomień. W bloku obserwatora używaj słabego odwołania do self, ponieważ pobieranie może zająć trochę czasu, a obiekt źródłowy może zostać zwolniony przed zakończeniem pobierania. Przykład:

NotificationCenter.default.addObserver(
    forName: .mlkitMLModelDownloadDidSucceed,
    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: .mlkitMLModelDownloadDidFail,
    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]
    // ...
}

__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. Przygotuj obraz wejściowy

Utwórz obiekt VisionImage za pomocą obiektu UIImage lub CMSampleBufferRef.

Jeśli używasz UIImage, wykonaj te czynności:

• Utwórz obiekt VisionImage za pomocą funkcji UIImage. Pamiętaj, aby podać prawidłowy adres .orientation.

  Swift

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

  Objective-C

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

Jeśli używasz CMSampleBufferRef, wykonaj te czynności:

• Określ orientację danych obrazu zawartych w buforze CMSampleBufferRef.

  Aby uzyskać orientację obrazu:

  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 position == AVCaptureDevicePositionFront ? UIImageOrientationLeftMirrored
                                                        : UIImageOrientationRight;
  
      case UIDeviceOrientationLandscapeLeft:
        return position == AVCaptureDevicePositionFront ? UIImageOrientationDownMirrored
                                                        : UIImageOrientationUp;
      case UIDeviceOrientationPortraitUpsideDown:
        return position == AVCaptureDevicePositionFront ? UIImageOrientationRightMirrored
                                                        : UIImageOrientationLeft;
      case UIDeviceOrientationLandscapeRight:
        return position == AVCaptureDevicePositionFront ? UIImageOrientationUpMirrored
                                                        : UIImageOrientationDown;
      case UIDeviceOrientationUnknown:
      case UIDeviceOrientationFaceUp:
      case UIDeviceOrientationFaceDown:
        return UIImageOrientationUp;
    }
  }
        

• Utwórz obiekt VisionImage, używając obiektu CMSampleBufferRef i jego orientacji:

  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. Uruchom narzędzie do etykietowania obrazów

Asynchronicznie:

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

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

Synchronicznie:

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

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

4. Uzyskiwanie informacji o oznaczonych obiektach

Jeśli operacja etykietowania obrazu się powiedzie, zwróci tablicę ImageLabel. Każdy element ImageLabel reprezentuje coś, co zostało opisane na obrazie. Możesz uzyskać opis tekstowy każdej etykiety (jeśli jest dostępny w metadanych pliku modelu TensorFlow Lite), wskaźnik ufności i indeks. Przykład:

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

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

Wskazówki dotyczące zwiększania skuteczności w czasie rzeczywistym

Jeśli chcesz oznaczać obrazy w aplikacji w czasie rzeczywistym, postępuj zgodnie z tymi wskazówkami, aby uzyskać najlepszą liczbę klatek na sekundę:

• ograniczać wywołania do tego detektora. Jeśli podczas działania detektora pojawi się nowa klatka wideo, odrzuć ją.
• Jeśli używasz danych wyjściowych z detektora do nakładania grafiki na obraz wejściowy, najpierw uzyskaj wynik, a potem renderuj obraz i nakładaj w jednym kroku. W ten sposób renderujesz na powierzchni wyświetlacza tylko raz w przypadku każdej ramki wejściowej. Przykładem są klasy previewOverlayView i FIRDetectionOverlayView w przykładowej aplikacji z galerii.