Detectar poses com o Kit de ML no iOS

O kit de ML oferece dois SDKs otimizados para detecção de postura.

Faça um teste

• Teste o app de exemplo para ver um exemplo de uso dessa API.

Antes de começar

1. Inclua os seguintes pods do ML Kit no seu Podfile:

   # If you want to use the base implementation:
   pod 'GoogleMLKit/PoseDetection', '8.0.0'
   
   # If you want to use the accurate implementation:
   pod 'GoogleMLKit/PoseDetectionAccurate', '8.0.0'
   

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

1. Criar uma instância de PoseDetector

Para detectar uma pose em uma imagem, primeiro crie uma instância de PoseDetector e especifique as configurações do detector, se quiser.

PoseDetector opções

Modo de detecção

O PoseDetector opera em dois modos de detecção. Escolha a opção que corresponde ao seu caso de uso.

stream (padrão)

O detector de postura primeiro detecta a pessoa mais proeminente na imagem e depois executa a detecção de postura. Nos frames subsequentes, a etapa de detecção de pessoas não será realizada, a menos que a pessoa fique obscurecida ou não seja mais detectada com alta confiança. O detector de postura tentará rastrear a pessoa mais proeminente e retornar a postura dela em cada inferência. Isso reduz a latência e facilita a detecção. Use esse modo quando quiser detectar poses em um stream de vídeo.

singleImage

O detector de postura detecta uma pessoa e executa a detecção de postura. A etapa de detecção de pessoas será executada para todas as imagens, então a latência será maior, e não haverá rastreamento de pessoas. Use esse modo quando usar a detecção de postura em imagens estáticas ou quando não quiser fazer o rastreamento.

Especifique as opções do detector de postura:

// Base pose detector with streaming, when depending on the PoseDetection SDK
let options = PoseDetectorOptions()
options.detectorMode = .stream

// Accurate pose detector on static images, when depending on the
// PoseDetectionAccurate SDK
let options = AccuratePoseDetectorOptions()
options.detectorMode = .singleImage

// Base pose detector with streaming, when depending on the PoseDetection SDK
MLKPoseDetectorOptions *options = [[MLKPoseDetectorOptions alloc] init];
options.detectorMode = MLKPoseDetectorModeStream;

// Accurate pose detector on static images, when depending on the
// PoseDetectionAccurate SDK
MLKAccuratePoseDetectorOptions *options =
    [[MLKAccuratePoseDetectorOptions alloc] init];
options.detectorMode = MLKPoseDetectorModeSingleImage;

Por fim, receba uma instância de PoseDetector. Transmita as opções especificadas:

let poseDetector = PoseDetector.poseDetector(options: options)

MLKPoseDetector *poseDetector =
    [MLKPoseDetector poseDetectorWithOptions:options];

2. Preparar a imagem de entrada

Para detectar poses, siga as etapas abaixo para cada imagem ou frame de vídeo. Se você tiver ativado o modo de stream, precisará criar objetos VisionImage a partir de CMSampleBuffer.

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 a .orientation correta.

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

3. Processar a imagem

Transmita o VisionImage para um dos métodos de processamento de imagem do detector de postura. É possível usar o método process(image:) assíncrono ou o método results() síncrono.

Para detectar objetos de modo síncrono:

var results: [Pose]
do {
  results = try poseDetector.results(in: image)
} catch let error {
  print("Failed to detect pose with error: \(error.localizedDescription).")
  return
}
guard let detectedPoses = results, !detectedPoses.isEmpty else {
  print("Pose detector returned no results.")
  return
}

// Success. Get pose landmarks here.

NSError *error;
NSArray *poses = [poseDetector resultsInImage:image error:&error];
if (error != nil) {
  // Error.
  return;
}
if (poses.count == 0) {
  // No pose detected.
  return;
}

// Success. Get pose landmarks here.

Para detectar objetos de modo assíncrono:

poseDetector.process(image) { detectedPoses, error in
  guard error == nil else {
    // Error.
    return
  }
  guard !detectedPoses.isEmpty else {
    // No pose detected.
    return
  }

  // Success. Get pose landmarks here.
}

[poseDetector processImage:image
                completion:^(NSArray * _Nullable poses,
                             NSError * _Nullable error) {
                    if (error != nil) {
                      // Error.
                      return;
                    }
                    if (poses.count == 0) {
                      // No pose detected.
                      return;
                    }

                    // Success. Get pose landmarks here.
                  }];

4. Receber informações sobre a postura detectada

Se uma pessoa for detectada na imagem, a API de detecção de postura vai transmitir uma matriz de objetos Pose para o gerenciador de conclusão ou retornar a matriz, dependendo se você chamou o método assíncrono ou síncrono.

Se a pessoa não estiver completamente dentro da imagem, o modelo vai atribuir as coordenadas dos pontos de referência ausentes fora do frame e dar a elas valores baixos de InFrameConfidence.

Se nenhuma pessoa for detectada, a matriz ficará vazia.

for pose in detectedPoses {
  let leftAnkleLandmark = pose.landmark(ofType: .leftAnkle)
  if leftAnkleLandmark.inFrameLikelihood > 0.5 {
    let position = leftAnkleLandmark.position
  }
}

for (MLKPose *pose in detectedPoses) {
  MLKPoseLandmark *leftAnkleLandmark =
      [pose landmarkOfType:MLKPoseLandmarkTypeLeftAnkle];
  if (leftAnkleLandmark.inFrameLikelihood > 0.5) {
    MLKVision3DPoint *position = leftAnkleLandmark.position;
  }
}

Dicas para melhorar a performance

A qualidade dos resultados depende da qualidade da imagem de entrada:

• Para que o Kit de ML detecte a postura com precisão, a pessoa na imagem precisa ser representada por dados de pixel suficientes. Para ter o melhor desempenho, o assunto precisa ter pelo menos 256 x 256 pixels.
• Se você estiver detectando poses em um aplicativo em tempo real, considere as dimensões gerais das imagens de entrada. Imagens menores podem ser processadas mais rapidamente. Para reduzir a latência, capture imagens em resoluções mais baixas, mas tenha em mente os requisitos de resolução acima e faça o assunto ocupar o máximo possível da imagem.
• Uma imagem com foco inadequado também pode prejudicar a precisão. Se os resultados não forem aceitáveis, peça para o usuário recapturar a imagem.

Se você quiser usar a detecção de postura em um aplicativo em tempo real, siga estas diretrizes para conseguir as melhores taxas de frames:

• Use o SDK PoseDetection básico e o modo de detecção stream.
• Capture imagens em uma resolução menor. No entanto, lembre-se também dos requisitos de dimensão de imagem da API.
• Para processar frames de vídeo, use a API síncrona results(in:) do detector. Chame esse método da função captureOutput(_, didOutput:from:) do AVCaptureVideoDataOutputSampleBufferDelegate para receber de forma síncrona os resultados do frame de vídeo especificado. Mantenha alwaysDiscardsLateVideoFrames de AVCaptureVideoDataOutput como "true" para limitar as chamadas ao detector. Se um novo frame de vídeo ficar disponível durante a execução do detector, 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. Em seguida, renderize a imagem e faça a sobreposição de uma só vez. Ao fazer isso, você renderiza a superfície de exibição apenas uma vez para cada frame de entrada processado. Consulte as classes previewOverlayView e MLKDetectionOverlayView no app de exemplo da demonstração.

Próximas etapas

• Para saber como usar pontos de referência de postura para classificar poses, consulte Dicas de classificação de postura.
• Consulte a amostra do guia de início rápido do Kit de ML no GitHub para ver um exemplo desta API em uso.