Обнаруживайте и отслеживайте объекты с помощью ML Kit на iOS

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

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

Прежде чем вы начнете

1. Если вы еще не добавили Firebase в свое приложение, сделайте это, выполнив действия, описанные в руководстве по началу работы .
2. Включите библиотеки ML Kit в свой подфайл:

   pod 'Firebase/MLVision', '6.25.0'
   pod 'Firebase/MLVisionObjectDetection', '6.25.0'
   

   После установки или обновления модулей вашего проекта обязательно откройте проект Xcode, используя его .xcworkspace .
3. Импортируйте Firebase в свое приложение:

   Быстрый

   import Firebase

   Цель-C

   @import Firebase;

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

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

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

   Настройки детектора объектов
   Режим обнаружения	.stream (по умолчанию) | .singleImage В потоковом режиме (по умолчанию) детектор объектов работает с очень низкой задержкой, но может давать неполные результаты (например, неуказанные ограничивающие рамки или категорию) при первых нескольких вызовах детектора. Кроме того, в потоковом режиме детектор присваивает объектам идентификаторы отслеживания, которые можно использовать для отслеживания объектов между кадрами. Используйте этот режим, если вы хотите отслеживать объекты или когда важна низкая задержка, например, при обработке видеопотоков в реальном времени. В режиме одного изображения детектор объектов ждет, пока не станут доступны ограничивающая рамка обнаруженного объекта и категория (если вы включили классификацию), прежде чем возвращать результат. Как следствие, задержка обнаружения потенциально выше. Кроме того, в режиме одного изображения идентификаторы отслеживания не назначаются. Используйте этот режим, если задержка не критична и вы не хотите иметь дело с частичными результатами.
   Обнаружение и отслеживание нескольких объектов	false (по умолчанию) | true Следует ли обнаруживать и отслеживать до пяти объектов или только самый заметный объект (по умолчанию).
   Классифицировать объекты	false (по умолчанию) | true Классифицировать обнаруженные объекты по грубым категориям или нет. При включении детектор объектов классифицирует объекты по следующим категориям: модные товары, продукты питания, товары для дома, места, растения и неизвестное.

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

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

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

   Быстрый

   // Live detection and tracking
   let options = VisionObjectDetectorOptions()
   options.detectorMode = .stream
   options.shouldEnableMultipleObjects = false
   options.shouldEnableClassification = true  // Optional
   
   // Multiple object detection in static images
   let options = VisionObjectDetectorOptions()
   options.detectorMode = .singleImage
   options.shouldEnableMultipleObjects = true
   options.shouldEnableClassification = true  // Optional
   

   Цель-C

   // Live detection and tracking
   FIRVisionObjectDetectorOptions *options = [[FIRVisionObjectDetectorOptions alloc] init];
   options.detectorMode = FIRVisionObjectDetectorModeStream;
   options.shouldEnableMultipleObjects = NO;
   options.shouldEnableClassification = YES;  // Optional
   
   // Multiple object detection in static images
   FIRVisionObjectDetectorOptions *options = [[FIRVisionObjectDetectorOptions alloc] init];
   options.detectorMode = FIRVisionObjectDetectorModeSingleImage;
   options.shouldEnableMultipleObjects = YES;
   options.shouldEnableClassification = YES;  // Optional
   

2. Получите экземпляр FirebaseVisionObjectDetector :

   Быстрый

   let objectDetector = Vision.vision().objectDetector()
   
   // Or, to change the default settings:
   let objectDetector = Vision.vision().objectDetector(options: options)
   

   Цель-C

   FIRVisionObjectDetector *objectDetector = [[FIRVision vision] objectDetector];
   
   // Or, to change the default settings:
   FIRVisionObjectDetector *objectDetector = [[FIRVision vision] objectDetectorWithOptions:options];
   

2. Запустите детектор объектов

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

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

   Чтобы использовать UIImage :

   1. При необходимости поверните изображение так, чтобы его свойство imageOrientation имело значение .up .
   2. Создайте объект VisionImage , используя правильно повернутый UIImage . Не указывайте метаданные вращения — необходимо использовать значение по умолчанию .topLeft .

      Быстрый

      let image = VisionImage(image: uiImage)

      Цель-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithImage:uiImage];

   Чтобы использовать CMSampleBufferRef :

   1. Создайте объект VisionImageMetadata , который задает ориентацию данных изображения, содержащихся в буфере CMSampleBufferRef .

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

      Быстрый

      func imageOrientation(
          deviceOrientation: UIDeviceOrientation,
          cameraPosition: AVCaptureDevice.Position
          ) -> VisionDetectorImageOrientation {
          switch deviceOrientation {
          case .portrait:
              return cameraPosition == .front ? .leftTop : .rightTop
          case .landscapeLeft:
              return cameraPosition == .front ? .bottomLeft : .topLeft
          case .portraitUpsideDown:
              return cameraPosition == .front ? .rightBottom : .leftBottom
          case .landscapeRight:
              return cameraPosition == .front ? .topRight : .bottomRight
          case .faceDown, .faceUp, .unknown:
              return .leftTop
          }
      }

      Цель-C

      - (FIRVisionDetectorImageOrientation)
          imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                                 cameraPosition:(AVCaptureDevicePosition)cameraPosition {
        switch (deviceOrientation) {
          case UIDeviceOrientationPortrait:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationLeftTop;
            } else {
              return FIRVisionDetectorImageOrientationRightTop;
            }
          case UIDeviceOrientationLandscapeLeft:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationBottomLeft;
            } else {
              return FIRVisionDetectorImageOrientationTopLeft;
            }
          case UIDeviceOrientationPortraitUpsideDown:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationRightBottom;
            } else {
              return FIRVisionDetectorImageOrientationLeftBottom;
            }
          case UIDeviceOrientationLandscapeRight:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationTopRight;
            } else {
              return FIRVisionDetectorImageOrientationBottomRight;
            }
          default:
            return FIRVisionDetectorImageOrientationTopLeft;
        }
      }

      Затем создайте объект метаданных:

      Быстрый

      let cameraPosition = AVCaptureDevice.Position.back  // Set to the capture device you used.
      let metadata = VisionImageMetadata()
      metadata.orientation = imageOrientation(
          deviceOrientation: UIDevice.current.orientation,
          cameraPosition: cameraPosition
      )

      Цель-C

      FIRVisionImageMetadata *metadata = [[FIRVisionImageMetadata alloc] init];
      AVCaptureDevicePosition cameraPosition =
          AVCaptureDevicePositionBack;  // Set to the capture device you used.
      metadata.orientation =
          [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                       cameraPosition:cameraPosition];

   2. Создайте объект VisionImage , используя объект CMSampleBufferRef и метаданные вращения:

      Быстрый

      let image = VisionImage(buffer: sampleBuffer)
      image.metadata = metadata

      Цель-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithBuffer:sampleBuffer];
      image.metadata = metadata;

2. Передайте VisionImage одному из методов обработки изображений детектора объектов. Вы можете использовать либо метод асинхронного process(image:) либо метод синхронных results() .

   Чтобы обнаружить объекты асинхронно:

   Быстрый

   objectDetector.process(image) { detectedObjects, error in
     guard error == nil else {
       // Error.
       return
     }
     guard let detectedObjects = detectedObjects, !detectedObjects.isEmpty else {
       // No objects detected.
       return
     }
   
     // Success. Get object info here.
     // ...
   }
   

   Цель-C

   [objectDetector processImage:image
                     completion:^(NSArray<FIRVisionObject *> * _Nullable objects,
                                  NSError * _Nullable error) {
                       if (error == nil) {
                         return;
                       }
                       if (objects == nil | objects.count == 0) {
                         // No objects detected.
                         return;
                       }
   
                       // Success. Get object info here.
                       // ...
                     }];
   

   Чтобы обнаружить объекты синхронно:

   Быстрый

   var results: [VisionObject]? = nil
   do {
     results = try objectDetector.results(in: image)
   } catch let error {
     print("Failed to detect object with error: \(error.localizedDescription).")
     return
   }
   guard let detectedObjects = results, !detectedObjects.isEmpty else {
     print("Object detector returned no results.")
     return
   }
   
   // ...
   

   Цель-C

   NSError *error;
   NSArray<FIRVisionObject *> *objects = [objectDetector resultsInImage:image
                                                                  error:&error];
   if (error == nil) {
     return;
   }
   if (objects == nil | objects.count == 0) {
     // No objects detected.
     return;
   }
   
   // Success. Get object info here.
   // ...
   

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

   Каждый VisionObject содержит следующие свойства:

   frame	CGRect , указывающий положение объекта на изображении.
   trackingID	Целое число, которое идентифицирует объект на изображениях. Ноль в режиме одного изображения.
   classificationCategory	Грубая категория объекта. Если в детекторе объектов не включена классификация, это всегда .unknown .
   confidence	Доверительная ценность классификации объектов. Если в детекторе объектов не включена классификация или объект классифицируется как неизвестный, это значение равно nil .

   Быстрый

   // detectedObjects contains one item if multiple object detection wasn't enabled.
   for obj in detectedObjects {
     let bounds = obj.frame
     let id = obj.trackingID
   
     // If classification was enabled:
     let category = obj.classificationCategory
     let confidence = obj.confidence
   }
   

   Цель-C

   // The list of detected objects contains one item if multiple
   // object detection wasn't enabled.
   for (FIRVisionObject *obj in objects) {
     CGRect bounds = obj.frame;
     if (obj.trackingID) {
       NSInteger id = obj.trackingID.integerValue;
     }
   
     // If classification was enabled:
     FIRVisionObjectCategory category = obj.classificationCategory;
     float confidence = obj.confidence.floatValue;
   }
   

Улучшение удобства использования и производительности

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

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

Также ознакомьтесь с [демонстрационным приложением ML Kit Material Design][showcase-link]{: .external } и коллекцией шаблонов Material Design для функций машинного обучения .

При использовании режима потоковой передачи в приложении реального времени следуйте этим рекомендациям для достижения наилучшей частоты кадров:

• Не используйте обнаружение нескольких объектов в режиме потоковой передачи, так как большинство устройств не смогут обеспечить достаточную частоту кадров.

• Отключите классификацию, если она вам не нужна.

• Дроссель вызывает детектор. Если новый видеокадр становится доступным во время работы детектора, удалите этот кадр.
• Если вы используете выходные данные детектора для наложения графики на входное изображение, сначала получите результат из ML Kit, затем визуализируйте изображение и наложите его за один шаг. При этом вы выполняете рендеринг на поверхность дисплея только один раз для каждого входного кадра. Пример см. в классах PreviewOverlayView и FIRDetectionOverlayView в демонстрационном примере приложения.