Guia de detecção de pontos de referência na mão para iOS

Com a tarefa MediaPipe Hand Pointser, você pode detectar os pontos de referência dos mãos em uma imagem. Estas instruções mostram como usar o ponto de referência de mão com aplicativos iOS. O exemplo de código descrito nestas instruções está disponível no GitHub.

Para mais informações sobre os recursos, modelos e opções de configuração dessa 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 Hand Markdown para iOS. No exemplo, a câmera de um dispositivo iOS físico é usada para detectar pontos de referência manuais em um stream de vídeo contínuo. O app também pode detectar pontos de referência em imagens e vídeos na galeria de dispositivos.

Use o app como ponto de partida para seu próprio app iOS ou consulte-o ao modificar um app atual. O código de exemplo do Hand extras está hospedado no GitHub (em inglês).

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 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 da compra esparsa para que você tenha apenas os arquivos do app de exemplo Hand Markdown:

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

Depois de criar uma versão local do código de exemplo, você poderá 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 essencial para o aplicativo de exemplo Hand Markdown (em inglês):

• HandLandmarkerService.swift (em inglês): inicializa o Hand Pointser, 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 do feed da câmera em tempo real e visualiza os resultados.
• MediaLibraryViewController.swift: implementa a IU para o modo de entrada de arquivo de imagem estática e vídeo e visualiza os resultados.

Configuração

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

Dependências

O Hand Markdown usa a biblioteca MediaPipeTasksVision, que precisa ser instalada usando CocoaPods. A biblioteca é compatível com apps Swift e Objective-C e não requer nenhuma configuração específica 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 o aplicativo, consulte Como usar o CocoaPods.

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

target 'MyHandLandmarkerApp' 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 Hand Pointser requer um modelo treinado compatível com ela. Para mais informações sobre os modelos treinados disponíveis para o Hand Pointser, consulte a seção Modelos de 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 do Xcode, consulte Gerenciar arquivos e pastas no projeto do Xcode.

Use a propriedade BaseOptions.modelAssetPath para especificar o caminho para o modelo no seu pacote de apps. Confira um exemplo de código na próxima seção.

Criar a tarefa

É possível criar a tarefa Hand Markdown chamando um dos inicializadores dela. O inicializador HandLandmarker(options:) aceita valores para as opções de configuração.

Se você não precisa de um ponto de referência manual inicializado com opções de configuração personalizadas, é possível usar o inicializador HandLandmarker(modelPath:) para criar um marcador de mão 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 "Ponto de referência" oferece suporte a três tipos de dados de entrada: imagens estáticas, arquivos de vídeo e streams de vídeo ao vivo. Por padrão, HandLandmarker(modelPath:) inicializa uma tarefa para imagens estáticas. Se você quiser que sua tarefa seja inicializada para processar arquivos de vídeo ou streams de vídeo ao vivo, use HandLandmarker(options:) para especificar o modo de execução de vídeo ou transmissão ao vivo. O modo de transmissão ao vivo também requer a opção de configuração handLandmarkerLiveStreamDelegate extra, que permite que o Marcador de mão envie resultados do ponto de referência manual para o delegado de forma assíncrona.

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

Swift

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "hand_landmarker",
                                      ofType: "task")

let options = HandLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let handLandmarker = try HandLandmarker(options: options)
    

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "hand_landmarker",
                                      ofType: "task")

let options = HandLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let handLandmarker = try HandLandmarker(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `HandLandmarkerLiveStreamDelegate` protocol and
// implements the method that the hand landmarker calls once it finishes
// performing landmarks detection in each input frame.
class HandLandmarkerResultProcessor: NSObject, HandLandmarkerLiveStreamDelegate {

  func handLandmarker(
    _ handLandmarker: HandLandmarker,
    didFinishDetection result: HandLandmarkerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the hand landmarker result or errors here.

  }
}

let modelPath = Bundle.main.path(
  forResource: "hand_landmarker",
  ofType: "task")

let options = HandLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

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

let handLandmarker = try HandLandmarker(options: options)
    

Objective-C

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"hand_landmarker"
                                                      ofType:@"task"];

MPPHandLandmarkerOptions *options = [[MPPHandLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minHandDetectionConfidence = minHandDetectionConfidence;
options.minHandPresenceConfidence = minHandPresenceConfidence;
options.minTrackingConfidence = minHandTrackingConfidence;
options.numHands = numHands;

MPPHandLandmarker *handLandmarker =
  [[MPPHandLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"hand_landmarker"
                                                      ofType:@"task"];

MPPHandLandmarkerOptions *options = [[MPPHandLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minHandDetectionConfidence = minHandDetectionConfidence;
options.minHandPresenceConfidence = minHandPresenceConfidence;
options.minTrackingConfidence = minHandTrackingConfidence;
options.numHands = numHands;

MPPHandLandmarker *handLandmarker =
  [[MPPHandLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPHandLandmarkerLiveStreamDelegate` protocol
// and implements the method that the hand landmarker calls once it finishes
// performing landmarks detection in each input frame.

@interface APPHandLandmarkerResultProcessor : NSObject 

@end

@implementation APPHandLandmarkerResultProcessor

-   (void)handLandmarker:(MPPHandLandmarker *)handLandmarker
    didFinishDetectionWithResult:(MPPHandLandmarkerResult *)handLandmarkerResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the hand landmarker result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"hand_landmarker"
                                                      ofType:@"task"];

MPPHandLandmarkerOptions *options = [[MPPHandLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minHandDetectionConfidence = minHandDetectionConfidence;
options.minHandPresenceConfidence = minHandPresenceConfidence;
options.minTrackingConfidence = minHandTrackingConfidence;
options.numHands = numHands;

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

MPPHandLandmarker *handLandmarker =
  [[MPPHandLandmarker alloc] initWithOptions:options error:nil];
    

Opções de configuração

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

Quando o modo de execução está definido para transmissão ao vivo, o Hand Markdown requer a opção extra de configuração handLandmarkerLiveStreamDelegate, que permite que ele forneça resultados de detecção de pontos de referência de forma assíncrona. O delegado precisa implementar o método handLandmarker(_:didFinishDetection:timestampInMilliseconds:error:), que o ponto de referência da mão chama depois de processar os resultados da detecção de pontos de referência de ponteiro para cada frame.

preparar dados

É necessário converter a imagem de entrada ou o frame em um objeto MPImage antes de transmiti-lo ao ponto de referência da mão. O MPImage é compatível com 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: imagens de um pacote de apps, da galeria do usuário ou do sistema de arquivos formatadas como imagens UIImage podem ser convertidas em um objeto MPImage.

• Vídeos: use o AVAssetImageGenerator para extrair frames de vídeo para o formato CGImage e convertê-los 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 um MPImage com a orientação UIImage.Orientation.Up padrão. É possível inicializar um MPImage com qualquer um dos valores UIImage.Orientation compatíveis. O ponto de referência de mão não oferece suporte a orientações espelhadas, como .upMirrored, .downMirrored, .leftMirrored e .rightMirrored.

Para mais informações sobre o UIImage, consulte a documentação do desenvolvedor da Apple UIImage.

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 Hand Markdown no modo de execução de imagens.

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

• transmissão ao vivo: os apps que usam a câmera do iOS para gerar frames podem ser convertidos no formato CVPixelBuffer para processamento antes de serem enviados ao Marcador de mão 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 o CVPixelBuffer, consulte a Documentação do desenvolvedor da Apple CVPixelBuffer (em inglês).

CMSampleBuffer

O formato CMSampleBuffer armazena amostras de mídia de um tipo uniforme e é adequado para o modo de execução de transmissão ao vivo. Os frames ativos de 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 do desenvolvedor da Apple CMSampleBuffer (em inglês).

Executar a tarefa

Para executar o ponto de referência de mão, use o método detect() específico do modo de corrida atribuído:

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

Swift

let result = try handLandmarker.detect(image: image)
    

let result = try handLandmarker.detect(
    videoFrame: image,
    timestampInMilliseconds: timestamp)
    

try handLandmarker.detectAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

MPPHandLandmarkerResult *result =
  [handLandmarker detectInImage:image error:nil];
    

MPPHandLandmarkerResult *result =
  [handLandmarker detectInVideoFrame:image
             timestampInMilliseconds:timestamp
                               error:nil];
    

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

O exemplo de código do Hand Markdown mostra as implementações de cada um desses modos com mais detalhes. 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, você também precisa fornecer o carimbo de data/hora do frame de entrada para a tarefa "Hand Markdowner".

• Quando executada no modo de imagem ou vídeo, a tarefa "Ponto de referência manual" bloqueia a linha de execução atual até terminar 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 a tarefa é executada no modo de transmissão ao vivo, a tarefa "hand Markdowner" é retornada imediatamente e não bloqueia a linha de execução atual. Ele invoca o método handLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) com o resultado do ponto de referência da mão após o processamento de cada frame de entrada. O Hand extras invoca esse método de forma assíncrona em uma fila de envio em série 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 manual estiver ocupada processando outro frame, o ponto de referência vai ignorar o novo frame de entrada.

Gerenciar e mostrar resultados

Ao executar a inferência, a tarefa "Handário do ponto de referência" retorna um HandLandmarkerResult que contém pontos de referência de mão em coordenadas de imagem, pontos de referência em coordenadas mundiais e mão direita(esquerda/direita) das mãos detectadas.

Veja a seguir um exemplo dos dados de saída dessa tarefa:

A saída HandLandmarkerResult contém três componentes. Cada componente é uma matriz, em que cada elemento contém os seguintes resultados para um único ponteiro detectado:

• Mão

  A mão dominante representa se as mãos detectadas são esquerdas ou direitas.

• Pontos de referência

  Há 21 pontos de referência, cada um composto pelas coordenadas x, y e z. As coordenadas x e y são normalizadas para [0.0, 1.0] de acordo com a largura e a altura da imagem, respectivamente. A coordenada z representa a profundidade do ponto de referência, sendo a profundidade no pulso a origem. Quanto menor o valor, mais perto o ponto de referência estará da câmera. A magnitude de z usa aproximadamente a mesma escala de x.

• Marcos mundiais

  Os pontos de referência de 21 ponteiros também são apresentados em coordenadas mundiais. Cada ponto de referência é composto por x, y e z, representando coordenadas 3D reais em metros, com a origem no centro geométrico do ponteiro.

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

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