A tarefa "Detector de objetos" permite detectar a presença e a localização de vários classes de objetos. Por exemplo, um Detector de Objetos pode localizar cães em uma imagem. Estas instruções mostram como usar a tarefa Detector de objetos no iOS. A descrito nestas instruções está disponível no GitHub.
Para saber como essa tarefa funciona, acesse este site demonstração. Para mais informações sobre os recursos, modelos e opções de configuração do para essa tarefa, consulte Visão geral.
Exemplo de código
O código de exemplo do MediaPipe Tasks é uma implementação básica de um objeto App de detector para iOS. O exemplo usa a câmera de um dispositivo iOS físico para detectar objetos continuamente e também pode usar imagens e vídeos do dispositivo para detectar objetos estaticamente.
Você pode usar o app como ponto de partida para seu próprio app iOS ou consultá-lo ao modificar um aplicativo existente. O exemplo de código do Object Detector está hospedado em GitHub.
Fazer o download do código
As instruções a seguir mostram como criar uma cópia local do exemplo. usando a ferramenta de linha de comando git.
Para fazer o download do código de exemplo:
Clone o repositório git usando o seguinte comando:
git clone https://github.com/google-ai-edge/mediapipe-samples
Opcionalmente, configure sua instância git para usar a finalização esparsa. Assim, você terá somente os arquivos do app de exemplo do Object Detector:
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, você pode instalar o MediaPipe, abrir o projeto usando Xcode e executar o app. Para instruções, consulte o Guia de configuração do iOS.
Principais componentes
Os arquivos a seguir contêm o código crucial para o exemplo do Object Detector aplicativo:
- 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 para o modo de entrada de transmissão da câmera em tempo real e as visualizações os resultados da detecção.
- MediaLibraryViewController.swift: Implementa a interface para o modo de entrada de arquivo de vídeo e imagem estática e visualiza os resultados da detecção.
Configuração
Esta seção descreve 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 sua ambiente de desenvolvimento para usar tarefas do MediaPipe, incluindo a 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
usando o CocoaPods. A biblioteca é compatível com aplicativos Swift e Objective-C
e não requer configuração específica do idioma.
Para instruções sobre como instalar o CocoaPods no macOS, consulte a documentação do CocoaPods
guia de instalação (em inglês).
Para instruções sobre como criar um Podfile
com os pods necessários para
aplicativo, consulte Usar
CocoaPods.
Adicione o pod do 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 do
iOS para mais informações sobre a configuração
seu Podfile
.
Modelo
A tarefa MediaPipe Object Detector requer um modelo treinado que seja compatível a essa tarefa. Para mais informações sobre os modelos treinados disponíveis para Detector de objetos, consulte a visão geral da tarefa Modelos .
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 seu projeto Xcode, consulte Como gerenciar arquivos e pastas no seu Xcode projeto.
Use a propriedade BaseOptions.modelAssetPath
para especificar o caminho para o modelo.
no seu pacote de apps. Para conferir um exemplo de código, consulte a próxima seção.
Criar a tarefa
É possível criar a tarefa "Detector de objetos" chamando um dos inicializadores dele. A
O inicializador ObjectDetector(options:)
define valores para as opções de configuração.
incluindo modo de execução, nome de exibição, localidade, número máximo de resultados, confiança
limite, lista de permissões de categorias e lista de bloqueio.
Se você não precisa que um detector de objetos seja inicializado com configuração personalizada
você pode usar o inicializador ObjectDetector(modelPath:)
para criar um
Object Detector com as opções padrão. Para mais informações sobre configurações
opções, consulte Visão geral da configuração.
A tarefa Detector de objetos é compatível com três tipos de dados de entrada: imagens estáticas e arquivos de vídeo.
e transmissões de vídeo ao vivo. Por padrão, ObjectDetector(modelPath:)
inicializa uma
para imagens estáticas. Se você quiser que sua tarefa seja inicializada para processar vídeos
arquivos ou streams de vídeo ao vivo, use ObjectDetector(options:)
para especificar o
ou no modo de corrida ao vivo. O modo de transmissão ao vivo também requer
objectDetectorLiveStreamDelegate
, que ativa
O Object Detector deve entregar resultados de detecção ao delegado de maneira assíncrona.
Escolha a guia correspondente ao modo de corrida para saber como criar a tarefa e executar inferência.
Swift
Imagem
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)
Vídeo
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)
transmissão ao vivo
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
Imagem
@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];
Vídeo
@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];
transmissão ao vivo
@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:
Nome da opção | Descrição | Intervalo de valor | Valor padrão |
---|---|---|---|
runningMode |
Define o modo de execução da tarefa. Existem três
modos: IMAGEM: o modo para entradas de imagem única. VÍDEO: o modo para frames decodificados de um vídeo. LIVE_STREAM: o modo de transmissão ao vivo da entrada dados de uma câmera, por exemplo. Neste modo, resultListener deve ser chamado para configurar um listener e receber resultados de forma assíncrona. |
{RunningMode.image, RunningMode.video, RunningMode.liveStream } |
RunningMode.image |
displayNamesLocales |
Define o idioma dos rótulos a serem usados para nomes de exibição fornecidos no
metadados do modelo da tarefa, se disponíveis. O padrão é en para
inglês. É possível adicionar rótulos localizados aos metadados de um modelo personalizado
usando a API Metadata Writer do TensorFlow Lite;
|
Código da localidade | en |
maxResults |
Define o número máximo opcional de resultados de detecção com maior pontuação como voltar. | Qualquer número positivo | -1 (todos os resultados são retornados) |
scoreThreshold |
Define o limite de pontuação da previsão que substitui o fornecido no os metadados do modelo (se houver). Resultados abaixo desse valor são rejeitados. | Qualquer flutuação | Não definido |
categoryAllowlist |
Define a lista opcional de nomes de categorias permitidos. Se não estiver vazio,
resultados de detecção cujo nome de categoria não esteja neste conjunto serão
que foram filtradas. Nomes de categorias duplicados ou desconhecidos são ignorados.
Essa opção é mutuamente exclusiva com categoryDenylist e usando
os dois resultarão em erro. |
Qualquer string | Não definido |
categoryDenylist |
Define a lista opcional de nomes de categorias que não são permitidos. Se
não vazio, os resultados de detecção cujo nome de categoria estiver neste conjunto serão filtrados
para fora. Nomes de categorias duplicados ou desconhecidos são ignorados. Essa opção é mutuamente
exclusivo com categoryAllowlist e usar ambos resulta em um erro. |
Qualquer string | Não definido |
Configuração da transmissão ao vivo
Quando o modo de execução é definido como transmissão ao vivo, o Detector de objetos exige o
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
objectDetector(_objectDetector:didFinishDetection:timestampInMilliseconds:error:)
que o Detector de objetos chama depois de processar o resultado da detecção para
cada frame.
Nome da opção | Descrição | Intervalo de valor | Valor padrão |
---|---|---|---|
objectDetectorLiveStreamDelegate |
Permite que o Object Detector receba resultados de detecção de forma assíncrona em
modo de transmissão ao vivo. A classe cuja instância é definida para essa propriedade deve
implementar
objectDetector(_:didFinishDetection:timestampInMilliseconds:error:)
. |
Não relevante | Não definido |
Preparar dados
É necessário converter a imagem ou o frame de entrada em um objeto MPImage
antes
e passá-lo para o detector de objetos. MPImage
oferece suporte a diferentes tipos de imagens do iOS
formatos e pode usá-los em qualquer modo em execução para inferência. Para mais
informações sobre MPImage
, consulte
API MPImage
Escolha um formato de imagem iOS com base no seu caso de uso e no modo de execução que seu
exigido pelo aplicativo.MPImage
aceita UIImage
, CVPixelBuffer
e
CMSampleBuffer
formatos de imagem do iOS.
UIImage
O formato UIImage
é adequado para os seguintes modos de execução:
Imagens: imagens de um pacote de apps, galeria do usuário ou sistema de arquivos formatados como
UIImage
imagens podem ser convertidas em um objetoMPImage
.Vídeos: use AVAssetImageGenerator para extrair frames de vídeo CGImage formato e converta-as em imagens
UIImage
.
Swift
// 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)
Objective-C
// 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 um MPImage
com o
UIImage.Orientation.Up
orientação. É possível inicializar um MPImage
com qualquer um dos
UIImage.Orientation
e a distribuição dos valores dos dados. O Object Detector não oferece suporte a orientações espelhadas como .upMirrored
,
.downMirrored
, .leftMirrored
e .rightMirrored
.
Para mais informações sobre o UIImage
, consulte a página do desenvolvedor de imagens de usuário
Documentação.
CVPixelBuffer
O formato CVPixelBuffer
é adequado para aplicativos que geram frames
e usar a interface CoreImage do iOS
para processamento.
O formato CVPixelBuffer
é adequado para os seguintes modos de execução:
Imagens: apps que geram imagens de
CVPixelBuffer
após algum processamento. usando o frameworkCoreImage
do iOS podem ser enviadas ao Object Detector na modo de execução de imagem.Vídeos: os quadros podem ser convertidos para o formato
CVPixelBuffer
para e enviados ao Detector de Objetos no modo de Vídeo.Transmissão ao vivo: apps que usam a câmera do iOS para gerar frames podem ser convertidos no formato
CVPixelBuffer
para processamento antes de ser enviado ao Detector de objetos no modo de transmissão ao vivo.
Swift
// 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)
Objective-C
// 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 o CVPixelBuffer
, consulte a documentação da Apple CVPixelBuffer
Desenvolvedor
Documentação.
CMSampleBuffer
O formato CMSampleBuffer
armazena amostras de mídia de um tipo uniforme de mídia e é
adequado para o modo de transmissão ao vivo. Os frames ao vivo das câmeras do iOS são
enviados de forma assíncrona no formato CMSampleBuffer
pelo iOS
AVCaptureVideoDataOutput.
Swift
// 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)
Objective-C
// 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 o CMSampleBuffer
, consulte a documentação da Apple do CMSampleBuffer
Desenvolvedor
Documentação.
Executar a tarefa
Para executar o Detector de objetos, use o método detect()
específico do
modo de corrida:
- 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 Object Detector na estes diferentes modos de execução:
Swift
Imagem
let objectDetector.detect(image:image)
Vídeo
let objectDetector.detect(videoFrame:image)
transmissão ao vivo
let objectDetector.detectAsync(image:image)
Objective-C
Imagem
MPPObjectDetectorResult *result = [objectDetector detectInImage:image error:nil];
Vídeo
MPPObjectDetectorResult *result = [objectDetector detectInVideoFrame:image timestampInMilliseconds:timestamp error:nil];
transmissão ao vivo
BOOL success = [objectDetector detectAsyncInImage:image timestampInMilliseconds:timestamp error:nil];
O exemplo de código do Object Detector mostra as implementações de cada um desses modos.
em mais detalhes detect(image:)
, detect(videoFrame:)
e
detectAsync(image:)
O código de exemplo permite que o usuário alterne entre
de processamento que podem não ser necessários para seu caso de uso.
Observe o seguinte:
Ao executar no modo de vídeo ou de transmissão ao vivo, você também precisa 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 Detector de objetos bloqueia linha de execução atual até terminar de processar a imagem ou frame de entrada. Para evite o bloqueio da linha de execução atual, execute o processamento em segundo plano conversa usando iOS Dispatch ou NSOperation frameworks.
Quando executada no modo de transmissão ao vivo, a tarefa "Detector de objetos" retorna imediatamente e não bloqueia a linha de execução atual. Ele invoca
objectDetector(_objectDetector:didFinishDetection:timestampInMilliseconds:error:)
com o resultado da detecção após o processamento de cada frame de entrada. A O Object Detector invoca esse método de forma assíncrona em um número de série dedicado fila de despacho. Para exibir resultados na interface do usuário, envie para a fila principal após o processamento dos resultados. Se odetectAsync
é chamada quando a tarefa "Detector de objetos" está ocupada processando outro o objeto Detector ignorará o novo frame de entrada.
Gerenciar e exibir resultados
Ao executar a inferência, a tarefa do detector de objetos retorna um ObjectDetectorResult
.
que descreve os objetos encontrados na imagem de entrada.
Confira abaixo 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 abaixo mostra uma visualização da saída da tarefa:
O código de exemplo do Object Detector demonstra como exibir os resultados da detecção retornados da tarefa, consulte o exemplo de código para saber mais detalhes.