Detecte, rastreie e classifique objetos com um modelo de classificação personalizado no iOS

É possível usar o Kit de ML para detectar e rastrear objetos em frames de vídeo sucessivos.

Quando você transmite uma imagem para o Kit de ML, ele detecta até cinco objetos na imagem, com a posição de cada objeto na imagem. Ao detectar objetos em streams de vídeo, cada objeto tem um ID exclusivo que pode ser usado para rastrear o objeto de frame a frame.

É possível usar um modelo de classificação de imagem personalizado para classificar os objetos detectados. Consulte Modelos personalizados com o kit de ML para orientações sobre os requisitos de compatibilidade de modelos, onde encontrar modelos pré-treinados e como treinar seus próprios modelos.

Há duas maneiras de integrar um modelo personalizado. Coloque o modelo na pasta de recursos do app para agrupar o modelo ou faça o download dele dinamicamente do Firebase. A tabela a seguir compara as duas opções.

Modelo em pacote Modelo hospedado
O modelo faz parte do arquivo .ipa do app, que aumenta o tamanho dele. O modelo não faz parte do arquivo .ipa do app. Ele é hospedado ao fazer upload para o Firebase Machine Learning.
O modelo estará disponível imediatamente, mesmo quando o dispositivo Android estiver off-line O download do modelo é feito sob demanda
Não é necessário ter um projeto do Firebase Requer um projeto do Firebase
É preciso republicar seu app para atualizar o modelo Enviar atualizações do modelo sem republicar o app
Sem testes A/B integrados Teste A/B fácil com a Configuração remota do Firebase

Testar

Antes de começar

  1. Inclua as bibliotecas do Kit de ML no seu Podfile:

    Para agrupar um modelo e seu app:

    pod 'GoogleMLKit/ObjectDetectionCustom', '3.2.0'

    Para fazer o download dinâmico de um modelo do Firebase, adicione a dependência LinkFirebase:

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

  2. Depois de instalar ou atualizar os pods do projeto, abra o projeto Xcode usando o .xcworkspace. O Kit de ML é compatível com a versão 13.2.1 ou posterior do Xcode.

  3. Se você quiser fazer o download de um modelo, adicione o Firebase ao seu projeto do iOS, caso ainda não tenha feito isso. Essa etapa não é necessária para empacotar o modelo.

1. Carregar o modelo

Configurar uma fonte de modelo local

Para agrupar o modelo e o aplicativo, siga estas etapas:

  1. Copie o arquivo de modelo (que geralmente termina em .tflite ou .lite) para o projeto do Xcode. Selecione Copy bundle resources ao fazer isso. O arquivo de modelo será incluído no pacote de apps e estará disponível para o Kit de ML.

  2. Crie o objeto LocalModel, especificando o caminho para o arquivo de modelo:

    Swift

    let localModel = LocalModel(path: localModelFilePath)

    Objective-C

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

Configurar uma fonte de modelo hospedada no Firebase

Para usar o modelo hospedado remotamente, crie um objeto CustomRemoteModel, especificando o nome que você atribuiu ao modelo quando o publicou:

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

Em seguida, inicie a tarefa de download do modelo, especificando as condições sob as quais você quer permitir o download. Se o modelo não estiver no dispositivo ou se uma versão mais recente do modelo estiver disponível, a tarefa fará o download do modelo de forma assíncrona do Firebase:

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

Muitos apps iniciam a tarefa de download no código de inicialização, mas você pode fazer isso a qualquer momento antes de precisar usar o modelo.

2. Configurar o detector de objetos

Depois de configurar as origens do modelo, configure o detector de objetos para seu caso de uso com um objeto CustomObjectDetectorOptions. É possível alterar as seguintes configurações:

Configurações do detector de objetos
Modo de detecção STREAM_MODE (padrão) | SINGLE_IMAGE_MODE

Em STREAM_MODE (padrão), o detector de objetos é executado com baixa latência, mas pode produzir resultados incompletos (como caixas delimitadoras ou rótulos de categoria não especificados) nas primeiras invocações do detector. Além disso, no STREAM_MODE, o detector atribui IDs de rastreamento a objetos, que podem ser usados para rastrear objetos em frames. Use esse modo quando quiser rastrear objetos ou quando a baixa latência for importante, como ao processar streams de vídeo em tempo real.

Em SINGLE_IMAGE_MODE, o detector de objetos retorna o resultado depois que a caixa delimitadora do objeto é determinada. Se você também ativar a classificação, ela retornará o resultado depois que a caixa delimitadora e o rótulo da categoria estiverem disponíveis. Como consequência, a latência de detecção é potencialmente maior. Além disso, no SINGLE_IMAGE_MODE, os IDs de acompanhamento não são atribuídos. Use esse modo se a latência não for crítica e você não quiser lidar com resultados parciais.
Detectar e rastrear vários objetos false (padrão) | true

Define se é preciso detectar e rastrear até cinco objetos ou apenas o objeto mais proeminente (padrão).
Classificar objetos false (padrão) | true

Se os objetos detectados serão classificados ou não usando o modelo de classificador personalizado fornecido. Para usar seu modelo de classificação personalizado, é necessário defini-lo como true.

Limite de confiança da classificação

Pontuação de confiança mínima dos rótulos detectados. Se não for definido, qualquer limite do classificador especificado pelos metadados do modelo será usado. Se o modelo não contiver metadados ou os metadados não especificarem um limite de classificador, um limite padrão de 0,0 será usado.
Máximo de rótulos por objeto

Número máximo de rótulos por objeto que o detector vai retornar. Se não for definido, o valor padrão 10 será usado.

Se você tiver apenas um modelo empacotado localmente, basta criar um detector de objetos usando o objeto 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;

Se você tiver um modelo hospedado remotamente, será necessário verificar se foi feito o download dele antes de executá-lo. É possível verificar o status da tarefa de download do modelo usando o método isModelDownloaded(remoteModel:) do gerenciador de modelos.

Embora isso só precise ser confirmado antes de executar o detector de objetos, se você tiver um modelo hospedado remotamente e um modelo agrupado localmente, pode fazer sentido fazer essa verificação ao instanciar o ObjectDetector: crie um detector usando o modelo remoto se ele tiver sido transferido por download. Caso contrário, use o modelo local.

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;

Se você tiver apenas um modelo hospedado remotamente, desative o recurso relacionado ao modelo (por exemplo, ocultando ou esmaecendo parte da interface) até confirmar que o download do modelo foi concluído.

Para receber o status de download do modelo, anexe observadores à Central de Notificações padrão. Certifique-se de usar uma referência fraca a self no bloco de observadores, já que os downloads podem levar algum tempo e o objeto de origem poderá ser liberado quando o download for concluído. Exemplo:

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

A API de detecção e rastreamento de objetos é otimizada para estes dois casos de uso principais:

  • Detecção ao vivo e rastreamento do objeto mais proeminente no visor da câmera.
  • A detecção de vários objetos usando uma imagem estática.

Se quiser configurar a API para esses casos de uso:

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. Preparar a imagem de entrada

Crie um objeto VisionImage usando um UIImage ou um CMSampleBuffer.

Se você usa um UIImage, siga estas etapas:

  • Crie um objeto VisionImage com o UIImage. Especifique o .orientation correto.

    Swift

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

    Objective-C

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

Se você usa um CMSampleBuffer, siga estas etapas:

  • Especifique a orientação dos dados da imagem contidos em CMSampleBuffer.

    Para ver a orientação da imagem:

    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;
  }
}
  • Crie um objeto VisionImage usando o objeto CMSampleBuffer e a orientação:

    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. Criar e executar o detector de objetos

  1. Crie um novo detector de objetos:

    Swift

    let objectDetector = ObjectDetector.objectDetector(options: options)

    Objective-C

    MLKObjectDetector *objectDetector = [MLKObjectDetector objectDetectorWithOptions:options];

  2. Em seguida, use o detector:

    De forma assíncrona:

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

    De forma síncrona:

    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. Conseguir informações sobre os objetos rotulados

Se a chamada para o processador de imagem for bem-sucedida, ela transmite uma lista de Objects para o gerenciador de conclusão ou retorna a lista, dependendo se você chamou o método assíncrono ou síncrono.

Cada Object contém as seguintes propriedades:

frame Um CGRect que indica a posição do objeto na imagem.
trackingID Um número inteiro que identifica o objeto nas imagens ou "nil" no SINGLE_IMAGE_MODE.
labels
label.text A descrição do texto do rótulo. Retornado somente se os metadados do modelo do TensorFlow Lite contiverem descrições de rótulos.
label.index O índice do rótulo entre todos os rótulos compatíveis com o classificador.
label.confidence O nível de confiança da classificação do objeto.

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

Como garantir uma ótima experiência do usuário

Para ter a melhor experiência do usuário, siga estas diretrizes no seu app:

  • A detecção bem-sucedida de objetos depende da complexidade visual do objeto. Para serem detectados, objetos com um pequeno número de recursos visuais podem precisar ocupar uma parte maior da imagem. Forneça aos usuários orientações sobre como capturar entradas que funcionem bem com o tipo de objeto que você quer detectar.
  • Ao usar a classificação, se você quiser detectar objetos que não se enquadrem nas categorias compatíveis, implemente o tratamento especial para objetos desconhecidos.

Além disso, confira o [app de demonstração do Material Design do Kit de ML][showcase-link]{: .external } e a coleção Padrões para recursos com tecnologia de machine learning do Material Design.

Melhoria de performance

Caso você queira usar a detecção de objetos em um aplicativo em tempo real, siga estas diretrizes para ter as melhores taxas de frames:

  • Ao usar o modo de streaming em um aplicativo em tempo real, não use a detecção de vários objetos, porque a maioria dos dispositivos não será capaz de produzir taxas de frames adequadas.

  • Para processar frames de vídeo, use a API síncrona results(in:) do detector. Chame esse método na função captureOutput(_, didOutput:from:) de AVCaptureVideoDataOutputSampleBufferDelegate para receber resultados de forma síncrona do frame de vídeo especificado. Mantenha o alwaysDiscardsLateVideoFrames de AVCaptureVideoDataOutput como true para limitar as chamadas ao detector. Se um novo frame de vídeo ficar disponível enquanto o detector estiver em execução, ele será descartado.
  • Se você usar a saída do detector para sobrepor elementos gráficos na imagem de entrada, primeiro acesse o resultado do Kit de ML e, em seguida, renderize a imagem e a sobreposição em uma única etapa. Ao fazer isso, você renderiza a superfície de exibição apenas uma vez para cada frame de entrada processado. Consulte updatePreviewOverlayViewWithLastFrame no exemplo do guia de início rápido do Kit de ML.