Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Обнаружение, отслеживание и классификация объектов с помощью собственной модели классификации на iOS

С помощью ML Kit можно обнаруживать и отслеживать объекты в последовательных кадрах видео.

Когда вы передаете изображение в ML Kit, он обнаруживает на нем до пяти объектов и определяет их положение. При обнаружении объектов в видеопотоках каждому объекту присваивается уникальный идентификатор, который можно использовать для отслеживания объекта от кадра к кадру.

Вы можете использовать пользовательскую модель классификации изображений, чтобы классифицировать обнаруженные объекты. Информацию о требованиях к совместимости моделей, о том, где найти предварительно обученные модели и как обучить собственные модели, можно найти в разделе Специальные модели с ML Kit.

Интегрировать специальную модель можно двумя способами. Вы можете упаковать модель, поместив ее в папку ресурсов приложения, или динамически загрузить ее из Cloud Storage. В таблице ниже сравниваются эти два варианта.

Пакетная модель	Размещенная модель
Модель является частью файла `.ipa` вашего приложения, что увеличивает его размер.	Модель не входит в файл `.ipa` вашего приложения. Для этого его нужно загрузить в Cloud Storage. Мы рекомендуем использовать Cloud Storage for Firebase.
Модель доступна сразу, даже если устройство Android не подключено к интернету.	В приложении должен быть код для скачивания модели по запросу.
Проект Firebase не требуется	Проект Firebase (если вы используете Cloud Storage for Firebase).
Чтобы обновить модель, опубликуйте приложение повторно.	Обновляйте модели, не публикуя приложение заново
Нет встроенного A/B-тестирования	A/B-тестирование с помощью Firebase Remote Config

Попробовать

Пример использования встроенной модели можно найти в приложении для быстрого начала работы с Vision API, а размещенной – в приложении для быстрого начала работы с AutoML API.
Пример полной реализации этого API можно посмотреть в приложении Material Design.

Подготовка

Включите библиотеки ML Kit в свой Podfile:
```
pod 'GoogleMLKit/ObjectDetectionCustom', '8.0.0'
```
После установки или обновления Pods проекта откройте проект Xcode, используя файл .xcworkspace. ML Kit поддерживается в Xcode версии 13.2.1 или более поздней.
Если вы хотите скачать модель с помощью Cloud Storage для Firebase, убедитесь, что вы добавили Firebase в проект iOS, если ещё этого не сделали. Это не требуется, если вы объединяете модель.

1. Загрузка модели

Как настроить источник локальной модели

Чтобы встроить модель в приложение:

Скопируйте файл модели (обычно с расширением .tflite или .lite) в проект Xcode, выбрав Copy bundle resources. Файл модели будет включен в пакет приложения и доступен для ML Kit.

Создайте объект LocalModel, указав путь к файлу модели:

Swift

let localModel = LocalModel(path: localModelFilePath)

Objective-C

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

Как настроить удаленный источник модели

Чтобы использовать модель, размещенную на удаленном сервере, вам нужно скачать ее в локальное хранилище устройства с помощью логики приложения, а затем загрузить как локальную модель. Для размещения модели рекомендуется использовать Cloud Storage for Firebase. Подробные инструкции по реализации приведены в руководстве по переходу с Firebase ML на Cloud Storage.

2. Настройте детектор объектов

После настройки источников моделей настройте детектор объектов для вашего варианта использования с помощью объекта CustomObjectDetectorOptions. Вы можете изменить следующие настройки:

Настройки детектора объектов
Режим обнаружения	`STREAM_MODE` (по умолчанию) \| `SINGLE_IMAGE_MODE` В режиме `STREAM_MODE` (по умолчанию) детектор объектов работает с низкой задержкой, но при первых нескольких вызовах может выдавать неполные результаты (например, не указывать ограничивающие рамки или ярлыки категорий). Кроме того, в `STREAM_MODE` детектор присваивает объектам идентификаторы отслеживания, которые можно использовать для отслеживания объектов в кадрах. Используйте этот режим, если вам нужно отслеживать объекты или важна низкая задержка, например при обработке видеопотоков в реальном времени. В режиме `SINGLE_IMAGE_MODE` детектор обнаружения объектов возвращает результат после определения граничной рамки объекта. Если вы также включите классификацию, то результат будет возвращен после того, как станут доступны и граничная рамка, и ярлык категории. В результате этого может увеличиться задержка обнаружения. Кроме того, в `SINGLE_IMAGE_MODE` идентификаторы отслеживания не назначаются. Используйте этот режим, если задержка не критична и вы не хотите иметь дело с частичными результатами.
Обнаружение и отслеживание нескольких объектов	`false` (по умолчанию) \| `true` Определяет, нужно ли обнаруживать и отслеживать до пяти объектов или только самый заметный (по умолчанию).
Классификация объектов	`false` (по умолчанию) \| `true` Нужно ли классифицировать обнаруженные объекты с помощью предоставленной модели собственного классификатора. Чтобы использовать собственную модель классификации, задайте значение `true`.
Порог достоверности классификации	Минимальный уровень достоверности обнаруженных ярлыков. Если не задано, будет использоваться пороговое значение классификатора, указанное в метаданных модели. Если модель не содержит метаданных или в них не указан порог классификатора, будет использоваться порог по умолчанию, равный 0.0.
Максимальное количество ярлыков на объект	Максимальное количество ярлыков на объект, которое будет возвращать детектор. Если значение не задано, по умолчанию используется 10.

Если у вас есть только локальная модель, просто создайте детектор обнаружения объектов на основе объекта LocalModel:

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;

Если вы используете модель, размещенную удаленно, перед запуском убедитесь, что она скачана.

Хотя подтверждать это нужно только перед запуском обнаружения объектов, если у вас есть и удаленно размещенная, и локально встроенная модель, имеет смысл выполнять эту проверку при создании экземпляра ObjectDetector: создать детектор на основе удаленной модели, если она скачана, и на основе локальной модели в противном случае.

Swift

// Path where your download logic saves the model
let documentDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
let localModelURL = documentDirectory.appendingPathComponent("my_remote_model.tflite")

let model: LocalModel
if FileManager.default.fileExists(atPath: localModelURL.path) {
  // Use the downloaded model
  model = LocalModel(path: localModelURL.path)
} else {
  // Fall back to bundled model
  guard let bundledModelPath = Bundle.main.path(forResource: "model", ofType: "tflite") else { return }
  model = LocalModel(path: bundledModelPath)
}

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

Objective-C

NSString *documentsDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *localModelPath = [documentsDirectory stringByAppendingPathComponent:@"my_remote_model.tflite"];

MLKLocalModel *model;
if ([NSFileManager.defaultManager fileExistsAtPath:localModelPath]) {
  // Use the downloaded model
  model = [[MLKLocalModel alloc] initWithPath:localModelPath];
} else {
  // Fall back to bundled model
  NSString *bundledModelPath = [NSBundle.mainBundle pathForResource:@"model" ofType:@"tflite"];
  model = [[MLKLocalModel alloc] initWithPath:bundledModelPath];
}

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

Если у вас есть только модель, размещенная на удаленном сервере, вам следует отключить связанные с ней функции, например заблокировать или скрыть часть интерфейса, пока модель не будет скачана.

Swift

let documentDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
let localModelURL = documentDirectory.appendingPathComponent("my_remote_model.tflite")
if FileManager.default.fileExists(atPath: localModelURL.path) {
  // Model is already cached, initialize immediately
  self.initializeDetector(with: localModelURL)
} else {
  // Model is not yet available, show loading UI and start download
  self.showLoadingUI()
  let storage = Storage.storage()
  let modelRef = storage.reference(forURL: "gs://YOUR_BUCKET/path/to/model.tflite")
  modelRef.write(toFile: localModelURL) { url, error in
    self.hideLoadingUI()
    if let error = error {
      // Handle download error
      self.showErrorUI()
    } else if let modelURL = url {
      // Download success, initialize detector
      self.initializeDetector(with: modelURL)
    }
  }
}

func initializeDetector(with modelURL: URL) {
  let localModel = LocalModel(path: modelURL.path)
  let options = CustomObjectDetectorOptions(localModel: localModel)
  options.detectorMode = .singleImage
  options.shouldEnableClassification = true
  options.shouldEnableMultipleObjects = true
  self.objectDetector = ObjectDetector.objectDetector(options: options)
  // Enable ML features in UI
  self.enableMLFeatures()
}

Objective-C

NSString *documentsDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *localModelPath = [documentsDirectory stringByAppendingPathComponent:@"my_remote_model.tflite"];
NSURL *localModelURL = [NSURL fileURLWithPath:localModelPath];

if ([NSFileManager.defaultManager fileExistsAtPath:localModelPath]) {
  // Model is already cached, initialize immediately
  [self initializeDetectorWithURL:localModelURL];
} else {
  // Model is not yet available, show loading UI and start download
  [self showLoadingUI];

  FIRStorage *storage = [FIRStorage storage];
  FIRStorageReference *modelRef = [storage referenceForURL:@"gs://YOUR_BUCKET/path/to/model.tflite"];

  [modelRef writeToFile:localModelURL
             completion:^(NSURL * _Nullable URL, NSError * _Nullable error) {
               [self hideLoadingUI];
               if (error != nil) {
                 // Handle download error
                 [self showErrorUI];
               } else {
                 // Download success, initialize detector
                 [self initializeDetectorWithURL:URL];
               }
             }];
}

- (void)initializeDetectorWithURL:(NSURL *)modelURL {
  MLKLocalModel *localModel = [[MLKLocalModel alloc] initWithPath:modelURL.path];
  MLKCustomObjectDetectorOptions *options = [[MLKCustomObjectDetectorOptions alloc] initWithLocalModel:localModel];
  options.detectorMode = MLKObjectDetectorModeSingleImage;
  options.shouldEnableClassification = YES;
  options.shouldEnableMultipleObjects = YES;
  self.objectDetector = [MLKObjectDetector objectDetectorWithOptions:options];

  // Enable ML features in UI
  [self enableMLFeatures];
}

API обнаружения и отслеживания объектов оптимизирован для этих двух основных вариантов использования:

Обнаружение и отслеживание наиболее заметного объекта в видоискателе камеры в реальном времени.
Распознавание нескольких объектов на статичном изображении.

Чтобы настроить API для этих вариантов использования, выполните следующие действия:

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. Как подготовить входное изображение

Создайте объект VisionImage, используя UIImage или CMSampleBuffer.

Если вы используете UIImage, выполните следующие действия:

Создайте объект VisionImage с UIImage. Убедитесь, что вы указали правильный .orientation.

Swift

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

Objective-C

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

Если вы используете CMSampleBuffer, выполните следующие действия:

Укажите ориентацию изображения, содержащегося в CMSampleBuffer.

Чтобы узнать ориентацию изображения:

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

Создайте объект VisionImage, используя объект CMSampleBuffer и ориентацию:

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. Создайте и запустите детектор объектов

Создайте детектор объектов.

Swift

let objectDetector = ObjectDetector.objectDetector(options: options)

Objective-C

MLKObjectDetector *objectDetector = [MLKObjectDetector objectDetectorWithOptions:options];

Затем используйте детектор:

Асинхронно:

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

Синхронно:

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. Как получить информацию об объектах с ярлыками

Если вызов процессора обработки изображений выполнен успешно, он передает список объектов Object обработчику завершения или возвращает список в зависимости от того, какой метод вы вызвали – асинхронный или синхронный.

Каждый объект Object содержит следующие свойства:

frame CGRect, указывающий положение объекта на изображении.

trackingID Целое число, которое идентифицирует объект на изображениях, или `nil` в режиме SINGLE_IMAGE_MODE.

labels

`label.text`	Текстовое описание ярлыка. Возвращается, только если метаданные модели LiteRT содержат описания ярлыков.
`label.index`	Индекс ярлыка среди всех ярлыков, поддерживаемых классификатором.
`label.confidence`	Уровень достоверности классификации объекта.

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

Как обеспечить удобство для пользователей

Чтобы обеспечить удобство пользователей, следуйте этим рекомендациям:

Успешное обнаружение объектов зависит от их визуальной сложности. Чтобы объекты с небольшим количеством визуальных признаков были обнаружены, они должны занимать большую часть изображения. Вы должны предоставить пользователям рекомендации по захват входных данных, которые хорошо работают с типами объектов, которые вы хотите обнаружить.
Если вы используете классификацию и хотите обнаруживать объекты, которые не попадают ни в одну из поддерживаемых категорий, реализуйте специальную обработку для неизвестных объектов.

Также ознакомьтесь с приложением ML Kit Material Design и коллекцией шаблонов Material Design для функций на основе машинного обучения.

Повышение эффективности

Если вы хотите использовать обнаружение объектов в приложении, работающем в реальном времени, следуйте приведенным ниже рекомендациям, чтобы добиться оптимальной частоты кадров.

При использовании режима потоковой передачи в приложении реального времени не используйте обнаружение нескольких объектов, так как большинство устройств не смогут обеспечить адекватную частоту кадров.
Для обработки кадров видео используйте синхронный API детектора results(in:). Вызовите этот метод из функции captureOutput(_, didOutput:from:) объекта AVCaptureVideoDataOutputSampleBufferDelegate, чтобы синхронно получить результаты для заданного кадра видео. Оставьте для параметра alwaysDiscardsLateVideoFrames в AVCaptureVideoDataOutput значение true, чтобы ограничить количество вызовов детектора. Если во время работы детектора станет доступен новый кадр видео, он будет пропущен.
Если вы используете результаты работы детектора для наложения графики на входное изображение, сначала получите результат от ML Kit, а затем отрисуйте изображение и наложите графику за один шаг. В этом случае отрисовка на поверхности экрана выполняется только один раз для каждого обработанного входного кадра. Пример можно найти в функции updatePreviewOverlayViewWithLastFrame в образце быстрого запуска ML Kit.