Guia de detecção de objetos para iOS

A tarefa do detector de objetos permite detectar a presença e a localização de várias classes de objetos. Por exemplo, um detector de objetos pode localizar cães em uma imagem. Estas instruções mostram como usar a tarefa do detector de objetos no iOS. O exemplo de código descrito nestas instruções está disponível no GitHub.

Confira esta demonstração na Web para ver essa tarefa em ação. Para mais informações sobre os recursos, modelos e opções de configuração desta tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo do MediaPipe Tasks é uma implementação básica de um app Object Detector para iOS. O exemplo usa a câmera em um dispositivo iOS físico para detectar objetos continuamente e também pode usar imagens e vídeos da galeria do dispositivo para detectar objetos de forma estática.

É possível usar o app como ponto de partida para seu próprio app iOS ou consultá-lo ao modificar um app atual. O código de exemplo do Object Detector está hospedado no GitHub.

Fazer o download do código

As instruções a seguir mostram como criar uma cópia local do código de exemplo usando a ferramenta de linha de comando git.

Para fazer o download do código de exemplo:

1. Clone o repositório do Git usando o seguinte comando:

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. Como opção, configure sua instância git para usar a finalização esparsa. Assim, você terá apenas os arquivos do aplicativo de exemplo do detector de objetos:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/object_detection/ios/
   

Depois de criar uma versão local do código de exemplo, é possível instalar a biblioteca de tarefas do MediaPipe, abrir o projeto usando o Xcode e executar o app. Para instruções, consulte o Guia de configuração para iOS.

Principais componentes

Os arquivos a seguir contêm o código crucial para o aplicativo de exemplo do Detector de objetos:

• ObjectDetectorService.swift: inicializa o detector, processa a seleção do modelo e executa a inferência nos dados de entrada.
• CameraViewController.swift: implementa a interface do modo de entrada de feed de câmera ao vivo e mostra os resultados da detecção.
• MediaLibraryViewController.swift: implementa a interface para o modo de entrada de imagem estática e arquivo de vídeo e visualiza os resultados da detecção.

Configuração

Nesta seção, descrevemos as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código para usar o Object Detector. Para informações gerais sobre como configurar seu ambiente de desenvolvimento para usar tarefas do MediaPipe, incluindo os requisitos de versão da plataforma, consulte o Guia de configuração para iOS.

Dependências

O Object Detector usa a biblioteca MediaPipeTasksVision, que precisa ser instalada com o CocoaPods. A biblioteca é compatível com apps Swift e Objective-C e não requer outras configurações específicas da linguagem.

Para instruções sobre como instalar o CocoaPods no macOS, consulte o Guia de instalação do CocoaPods. Para instruções sobre como criar um Podfile com os pods necessários para seu app, consulte Como usar o CocoaPods.

Adicione o pod MediaPipeTasksVision no Podfile usando o seguinte código:

target 'MyObjectDetectorApp' do
  use_frameworks!
  pod 'MediaPipeTasksVision'
end

Se o app incluir destinos de teste de unidade, consulte o Guia de configuração para iOS para mais informações sobre como configurar o Podfile.

Modelo

A tarefa do MediaPipe Object Detector requer um modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o Object Detector, consulte a seção "Modelos" da visão geral da tarefa.

Selecione e faça o download de um modelo e adicione-o ao diretório do projeto usando o Xcode. Para instruções sobre como adicionar arquivos ao projeto Xcode, consulte Como gerenciar arquivos e pastas no projeto do Xcode.

Use a propriedade BaseOptions.modelAssetPath para especificar o caminho para o modelo no app bundle. Para conferir um exemplo de código, consulte a próxima seção.

Criar a tarefa

É possível criar a tarefa do Detector de objetos chamando um dos inicializadores. O inicializador ObjectDetector(options:) define valores para opções de configuração, incluindo modo de execução, localidade de nomes de exibição, número máximo de resultados, limite de confiança, lista de permissões e de bloqueio de categorias.

Se você não precisa que um detector de objetos seja inicializado com opções de configuração personalizadas, use o inicializador ObjectDetector(modelPath:) para criar um detector de objetos com as opções padrão. Para mais informações sobre as opções de configuração, consulte Visão geral da configuração.

A tarefa do detector de objetos oferece suporte a três tipos de dados de entrada: imagens estáticas, arquivos de vídeo e transmissões de vídeo ao vivo. Por padrão, ObjectDetector(modelPath:) inicializa uma tarefa de imagens estáticas. Se você quiser que a tarefa seja inicializada para processar arquivos de vídeo ou transmissões de vídeo ao vivo, use ObjectDetector(options:) para especificar o modo de execução do vídeo ou da transmissão ao vivo. O modo de transmissão ao vivo também exige a opção de configuração objectDetectorLiveStreamDelegate, que permite que o Detector de objetos envie resultados de detecção para o delegado de forma assíncrona.

Escolha a guia correspondente ao modo de execução para saber como criar a tarefa e executar a inferência.

Swift

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = ObjectDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.maxResults = 5

let objectDetector = try ObjectDetector(options: options)
    

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = ObjectDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.maxResults = 5

let objectDetector = try ObjectDetector(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `ObjectDetectorLiveStreamDelegate` protocol and
// implements the method that the object detector calls once it
// finishes performing detection on each input frame.
class ObjectDetectorResultProcessor: NSObject, ObjectDetectorLiveStreamDelegate {

  func objectDetector(
    _ objectDetector: ObjectDetector,
    didFinishDetection objectDetectionResult: ObjectDetectorResult?,
    timestampInMilliseconds: Int,
    error: Error?) {
    // Process the detection result or errors here.
  }
}

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = ObjectDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.maxResults = 5

// Assign an object of the class to the `objectDetectorLiveStreamDelegate`
// property.
let processor = ObjectDetectorResultProcessor()
options.objectDetectorLiveStreamDelegate = processor

let objectDetector = try ObjectDetector(options: options)
    

Objective-C

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPObjectDetectorOptions *options = [[MPPObjectDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.maxResults = 5;

MPPObjectDetector *objectDetector =
      [[MPPObjectDetector alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPObjectDetectorOptions *options = [[MPPObjectDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.maxResults = 5;

MPPObjectDetector *objectDetector =
      [[MPPObjectDetector alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `ObjectDetectorLiveStreamDelegate` protocol and
// implements the method that the object detector calls once it
// finishes performing detection on each input frame.

@interface APPObjectDetectorResultProcessor : NSObject 

@end

@implementation MPPObjectDetectorResultProcessor

-   (void)objectDetector:(MPPObjectDetector *)objectDetector
    didFinishDetectionWithResult:(MPPObjectDetectorResult *)ObjectDetectorResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the detection result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPObjectDetectorOptions *options = [[MPPObjectDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.maxResults = 5;

// Assign an object of the class to the `objectDetectorLiveStreamDelegate`
// property.
APPObjectDetectorResultProcessor *processor = [APPObjectDetectorResultProcessor new];
options.objectDetectorLiveStreamDelegate = processor;

MPPObjectDetector *objectDetector =
      [[MPPObjectDetector alloc] initWithOptions:options error:nil];
    

Opções de configuração

Esta tarefa tem as seguintes opções de configuração para apps iOS:

Configuração de transmissão ao vivo

Quando o modo de execução é definido como transmissão ao vivo, o Detector de objetos exige a opção de configuração objectDetectorLiveStreamDelegate extra, que permite que o detector forneça resultados de detecção de forma assíncrona. O delegado implementa o método objectDetector(_objectDetector:didFinishDetection:timestampInMilliseconds:error:), que o Detector de objetos chama após processar o resultado da detecção para cada frame.

Preparar dados

É necessário converter a imagem ou o frame de entrada em um objeto MPImage antes de transmiti-lo ao detector de objetos. O MPImage oferece suporte a diferentes tipos de formatos de imagem do iOS e pode usá-los em qualquer modo de execução para inferência. Para mais informações sobre MPImage, consulte a API MPImage.

Escolha um formato de imagem do iOS com base no seu caso de uso e no modo de execução exigido pelo aplicativo.MPImage aceita os formatos de imagem UIImage, CVPixelBuffer e CMSampleBuffer do iOS.

UIImage

O formato UIImage é adequado para os seguintes modos de execução:

• Imagens: as imagens de um pacote de apps, galeria de usuários ou sistema de arquivos formatadas como UIImage podem ser convertidas em um objeto MPImage.

• Vídeos: use o AVAssetImageGenerator para extrair frames de vídeo para o formato CGImage e os converter em imagens UIImage.

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(uiImage: image)
    

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

O exemplo inicializa uma MPImage com a orientação UIImage.Orientation.Up padrão. É possível inicializar uma MPImage com qualquer um dos valores UIImage.Orientation compatíveis. O Object Detector não oferece suporte a orientações espelhadas como .upMirrored, .downMirrored, .leftMirrored, .rightMirrored.

Para mais informações sobre UIImage, consulte a documentação para desenvolvedores da Apple de UIImage (em inglês).

CVPixelBuffer

O formato CVPixelBuffer é adequado para aplicativos que geram frames e usam o framework CoreImage do iOS para processamento.

O formato CVPixelBuffer é adequado para os seguintes modos de execução:

• Imagens: apps que geram imagens CVPixelBuffer após algum processamento usando o framework CoreImage do iOS podem ser enviados ao detector de objetos no modo de execução de imagem.

• Vídeos: os frames de vídeo podem ser convertidos para o formato CVPixelBuffer para processamento e, em seguida, enviados ao Detector de objetos no modo de vídeo.

• transmissão ao vivo: os apps que usam uma câmera do iOS para gerar frames podem ser convertidos para o formato CVPixelBuffer para processamento antes de serem enviados ao detector de objetos no modo de transmissão ao vivo.

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(pixelBuffer: pixelBuffer)
    

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

Para mais informações sobre CVPixelBuffer, consulte a documentação para desenvolvedores da Apple CVPixelBuffer.

CMSampleBuffer

O formato CMSampleBuffer armazena amostras de mídia de um tipo uniforme e é adequado para o modo de execução de transmissões ao vivo. Os frames ao vivo das câmeras do iOS são enviados de forma assíncrona no formato CMSampleBuffer pelo AVCaptureVideoDataOutput do iOS.

// Obtain a CMSampleBuffer.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(sampleBuffer: sampleBuffer)
    

// Obtain a `CMSampleBuffer`.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithSampleBuffer:sampleBuffer error:nil];
    

Para mais informações sobre CMSampleBuffer, consulte a documentação para desenvolvedores da Apple CMSampleBuffer (em inglês).

Executar a tarefa

Para executar o Detector de objetos, use o método detect() específico do modo de execução atribuído:

• Imagem estática: detect(image:)
• Vídeo: detect(videoFrame:timestampInMilliseconds:)
• transmissão ao vivo: detectAsync(image:)

Os exemplos de código a seguir mostram exemplos básicos de como executar o Detector de objetos nesses modos de execução diferentes:

Swift

let objectDetector.detect(image:image)
    

let objectDetector.detect(videoFrame:image)
    

let objectDetector.detectAsync(image:image)
    

Objective-C

MPPObjectDetectorResult *result = [objectDetector detectInImage:image error:nil];
    

MPPObjectDetectorResult *result = [objectDetector detectInVideoFrame:image          timestampInMilliseconds:timestamp error:nil];
    

BOOL success = [objectDetector detectAsyncInImage:image
                          timestampInMilliseconds:timestamp
                                            error:nil];
    

O exemplo de código do Detector de objetos mostra as implementações de cada um desses modos com mais detalhes detect(image:), detect(videoFrame:) e detectAsync(image:). O código de exemplo permite que o usuário alterne entre os modos de processamento, o que pode não ser necessário para seu caso de uso.

Observe o seguinte:

• Ao executar no modo de vídeo ou de transmissão ao vivo, também é necessário fornecer o carimbo de data/hora do frame de entrada para a tarefa "Detector de objetos".

• Quando executada no modo de imagem ou vídeo, a tarefa do detector de objetos bloqueia a linha de execução atual até que ela termine de processar a imagem ou o frame de entrada. Para evitar o bloqueio da linha de execução atual, execute o processamento em uma linha de execução em segundo plano usando os frameworks Dispatch ou NSOperation do iOS.

• Quando executada no modo de transmissão ao vivo, a tarefa do detector de objetos é retornada imediatamente e não bloqueia a linha de execução atual. Ele invoca o método objectDetector(_objectDetector:didFinishDetection:timestampInMilliseconds:error:) com o resultado da detecção após o processamento de cada frame de entrada. O Detector de objetos invoca esse método de forma assíncrona em uma fila de despacho serial dedicada. Para exibir resultados na interface do usuário, envie os resultados para a fila principal depois de processá-los. Se a função detectAsync for chamada quando a tarefa do Detector de objetos estiver ocupada processando outro frame, o Detector de objetos vai ignorar o novo frame de entrada.

Processar e mostrar resultados

Ao executar a inferência, a tarefa do detector de objetos retorna um objeto ObjectDetectorResult que descreve os objetos encontrados na imagem de entrada.

Confira a seguir um exemplo dos dados de saída desta tarefa:

ObjectDetectorResult:
 Detection #0:
  Box: (x: 355, y: 133, w: 190, h: 206)
  Categories:
   index       : 17
   score       : 0.73828
   class name  : dog
 Detection #1:
  Box: (x: 103, y: 15, w: 138, h: 369)
  Categories:
   index       : 17
   score       : 0.73047
   class name  : dog

A imagem a seguir mostra uma visualização da saída da tarefa:

O código de exemplo do Detector de objetos demonstra como mostrar os resultados de detecção retornados pela tarefa. Consulte o exemplo de código para mais detalhes.