Esta página foi traduzida pela API Cloud Translation.

Detectar poses com o Kit de ML no Android

O Kit de ML fornece dois SDKs otimizados para detecção de poses.

Nome do SDK	detecção de pose	precisão de detecção de pose
Implementação	O código e os recursos são vinculados estaticamente ao app no tempo de build.	O código e os recursos são vinculados estaticamente ao app no tempo de build.
Impacto no tamanho do app (incluindo código e recursos)	Aprox.10,1 MB	Aprox.13,3 MB
Desempenho	Pixel 3XL: aproximadamente 30 QPS	Pixel 3XL: ~23 QPS com CPU e 30 QPS com GPU

Faça um teste

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

Antes de começar

Esta API requer o nível 21 da API do Android ou mais recente. Certifique-se de que o build do seu app arquivo usa um valor de minSdkVersion de 21 ou superior.

No arquivo build.gradle no nível do projeto, inclua o repositório Maven do Google nas seções buildscript e allprojects.

Adicione as dependências das bibliotecas do Android do Kit de ML ao arquivo Gradle do módulo no nível do app, que geralmente é app/build.gradle:

dependencies {
  // If you want to use the base sdk
  implementation 'com.google.mlkit:pose-detection:18.0.0-beta4'
  // If you want to use the accurate sdk
  implementation 'com.google.mlkit:pose-detection-accurate:18.0.0-beta4'
}

1. Criar uma instância de `PoseDetector`

`PoseDetector` opções

Para detectar uma pose em uma imagem, primeiro crie uma instância de PoseDetector e você pode especificar as configurações do detector.

Modo de detecção

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

STREAM_MODE (padrão): O detector de poses primeiro detectará as pessoa proeminente na imagem e, em seguida, executar a detecção de pose. Nos frames subsequentes, a etapa de detecção de pessoa não será realizada, a menos que a pessoa fique obscurecidas ou não são mais detectadas com alta confiança. O detector de poses tentam rastrear a pessoa mais proeminente e voltar a pose em cada a inferência. Isso reduz a latência e suaviza a detecção. Use esse modo quando quiser detectar a pose em um stream de vídeo.
SINGLE_IMAGE_MODE: O detector de poses detectará uma pessoa e executará a pose detecção de ameaças. A etapa de detecção de pessoa será executada para cada imagem, portanto, a latência ser maior e não há rastreamento de pessoas. Usar este modo ao usar a pose detecção em imagens estáticas ou em que o rastreamento não é desejado.

Configuração de hardware

O PoseDetector oferece suporte a várias configurações de hardware para otimização. desempenho:

CPU: executa o detector usando apenas CPU.
CPU_GPU: executa o detector usando CPU e GPU.

Ao criar as opções do detector, você pode usar a API setPreferredHardwareConfigs para controlar a seleção de hardware. Por padrão, todas as configurações de hardware são definidas como preferenciais.

O kit de ML vai considerar a disponibilidade, a estabilidade, a precisão e a latência de cada configuração em consideração e escolher a melhor opção dentre as configurações preferidas. Se nenhuma das as configurações preferenciais forem aplicáveis, a configuração CPU será usada automaticamente como substituto. o Kit de ML fará essas verificações e a preparação relacionada de uma sem bloqueios antes de ativar qualquer aceleração. na primeira vez que o usuário executar o detector, ele usará CPU. Depois de todos a preparação for concluída, a melhor configuração será usada nas execuções a seguir.

Exemplos de uso de setPreferredHardwareConfigs:

Para permitir que o Kit de ML escolha a melhor configuração, não chame essa API.
Se você não quiser ativar nenhuma aceleração, transmita apenas CPU.
Se quiser usar a GPU para descarregar a CPU mesmo que ela seja mais lenta, transmita em apenas CPU_GPU.

Especifique as opções do detector de poses:

Kotlin

// Base pose detector with streaming frames, when depending on the pose-detection sdk
val options = PoseDetectorOptions.Builder()
    .setDetectorMode(PoseDetectorOptions.STREAM_MODE)
    .build()

// Accurate pose detector on static images, when depending on the pose-detection-accurate sdk
val options = AccuratePoseDetectorOptions.Builder()
    .setDetectorMode(AccuratePoseDetectorOptions.SINGLE_IMAGE_MODE)
    .build()

Java

// Base pose detector with streaming frames, when depending on the pose-detection sdk
PoseDetectorOptions options =
   new PoseDetectorOptions.Builder()
       .setDetectorMode(PoseDetectorOptions.STREAM_MODE)
       .build();

// Accurate pose detector on static images, when depending on the pose-detection-accurate sdk
AccuratePoseDetectorOptions options =
   new AccuratePoseDetectorOptions.Builder()
       .setDetectorMode(AccuratePoseDetectorOptions.SINGLE_IMAGE_MODE)
       .build();

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

Kotlin

val poseDetector = PoseDetection.getClient(options)

Java

PoseDetector poseDetector = PoseDetection.getClient(options);

2. Preparar a imagem de entrada

Para detectar poses em uma imagem, crie um objeto InputImage de uma matriz de bytes Bitmap, media.Image, ByteBuffer, ou um arquivo na o dispositivo. Em seguida, transmita o objeto InputImage para a PoseDetector.

Para a detecção de pose, use uma imagem com dimensões de pelo menos 480x360 pixels. Se você detectar poses em tempo real, capturar frames nessa resolução mínima pode ajudar a reduzir a latência.

Você pode criar um InputImage de diferentes origens, cada uma explicada abaixo.

Como usar um `media.Image`

Para criar um InputImage de um objeto media.Image, como quando você captura uma imagem de um da câmera do dispositivo, transmita o objeto media.Image e o rotação para InputImage.fromMediaImage().

Se você usar o método CameraX, os recursos OnImageCapturedListener e As classes ImageAnalysis.Analyzer calculam o valor de rotação para você.

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {

    override fun analyze(imageProxy: ImageProxy) {
        val mediaImage = imageProxy.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

Se você não usar uma biblioteca de câmera que informe o grau de rotação da imagem, pode calculá-lo usando o grau de rotação do dispositivo e a orientação da câmera no dispositivo:

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

Em seguida, transmita o objeto media.Image e o grau de rotação para InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)MLKitVisionImage.kt

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

Usar um URI de arquivo

Para criar um InputImage de um URI de arquivo, transmita o contexto do aplicativo e o URI do arquivo para InputImage.fromFilePath(). Isso é útil quando você usar uma intent ACTION_GET_CONTENT para solicitar que o usuário selecione uma imagem do app Galeria.

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}MLKitVisionImage.kt

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

Como usar `ByteBuffer` ou `ByteArray`

Para criar um InputImage de uma ByteBuffer ou ByteArray, primeiro calcule a imagem grau de rotação conforme descrito anteriormente para a entrada media.Image. Depois, crie o objeto InputImage com o buffer ou a matriz, junto com o altura, largura, formato de codificação de cores e grau de rotação:

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java

Como usar um `Bitmap`

Para criar um InputImage de um objeto Bitmap, faça a seguinte declaração:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)MLKitVisionImage.kt

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);MLKitVisionImage.java

A imagem é representada por um objeto Bitmap com os graus de rotação.

3. Processar a imagem

Transmita o objeto InputImage preparado para o método process do PoseDetector.

Kotlin

Task<Pose> result = poseDetector.process(image)
       .addOnSuccessListener { results ->
           // Task completed successfully
           // ...
       }
       .addOnFailureListener { e ->
           // Task failed with an exception
           // ...
       }

Java

Task<Pose> result =
        poseDetector.process(image)
                .addOnSuccessListener(
                        new OnSuccessListener<Pose>() {
                            @Override
                            public void onSuccess(Pose pose) {
                                // Task completed successfully
                                // ...
                            }
                        })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });

Observação: se você estiver usando a classe CameraX, feche a ImageProxy quando terminar de usar. Por exemplo, adicionando um OnCompleteListener ao Task retornado do Método process. Consulte a VisionProcessorBase no app de amostra do guia de início rápido para conferir um exemplo.

4. Receber informações sobre a pose detectada

Se uma pessoa for detectada na imagem, a API de detecção de pose retornará um Pose com 33 PoseLandmarks.

Se a pessoa não estava totalmente dentro da imagem, o modelo atribui as coordenadas de pontos de referência ausentes fora do frame e a baixa InFrameConfidence.

Se nenhuma pessoa tiver sido detectada no enquadramento, o Pose O objeto não contém PoseLandmarks.

Kotlin

// Get all PoseLandmarks. If no person was detected, the list will be empty
val allPoseLandmarks = pose.getAllPoseLandmarks()

// Or get specific PoseLandmarks individually. These will all be null if no person
// was detected
val leftShoulder = pose.getPoseLandmark(PoseLandmark.LEFT_SHOULDER)
val rightShoulder = pose.getPoseLandmark(PoseLandmark.RIGHT_SHOULDER)
val leftElbow = pose.getPoseLandmark(PoseLandmark.LEFT_ELBOW)
val rightElbow = pose.getPoseLandmark(PoseLandmark.RIGHT_ELBOW)
val leftWrist = pose.getPoseLandmark(PoseLandmark.LEFT_WRIST)
val rightWrist = pose.getPoseLandmark(PoseLandmark.RIGHT_WRIST)
val leftHip = pose.getPoseLandmark(PoseLandmark.LEFT_HIP)
val rightHip = pose.getPoseLandmark(PoseLandmark.RIGHT_HIP)
val leftKnee = pose.getPoseLandmark(PoseLandmark.LEFT_KNEE)
val rightKnee = pose.getPoseLandmark(PoseLandmark.RIGHT_KNEE)
val leftAnkle = pose.getPoseLandmark(PoseLandmark.LEFT_ANKLE)
val rightAnkle = pose.getPoseLandmark(PoseLandmark.RIGHT_ANKLE)
val leftPinky = pose.getPoseLandmark(PoseLandmark.LEFT_PINKY)
val rightPinky = pose.getPoseLandmark(PoseLandmark.RIGHT_PINKY)
val leftIndex = pose.getPoseLandmark(PoseLandmark.LEFT_INDEX)
val rightIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_INDEX)
val leftThumb = pose.getPoseLandmark(PoseLandmark.LEFT_THUMB)
val rightThumb = pose.getPoseLandmark(PoseLandmark.RIGHT_THUMB)
val leftHeel = pose.getPoseLandmark(PoseLandmark.LEFT_HEEL)
val rightHeel = pose.getPoseLandmark(PoseLandmark.RIGHT_HEEL)
val leftFootIndex = pose.getPoseLandmark(PoseLandmark.LEFT_FOOT_INDEX)
val rightFootIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_FOOT_INDEX)
val nose = pose.getPoseLandmark(PoseLandmark.NOSE)
val leftEyeInner = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_INNER)
val leftEye = pose.getPoseLandmark(PoseLandmark.LEFT_EYE)
val leftEyeOuter = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_OUTER)
val rightEyeInner = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_INNER)
val rightEye = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE)
val rightEyeOuter = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_OUTER)
val leftEar = pose.getPoseLandmark(PoseLandmark.LEFT_EAR)
val rightEar = pose.getPoseLandmark(PoseLandmark.RIGHT_EAR)
val leftMouth = pose.getPoseLandmark(PoseLandmark.LEFT_MOUTH)
val rightMouth = pose.getPoseLandmark(PoseLandmark.RIGHT_MOUTH)

Java

// Get all PoseLandmarks. If no person was detected, the list will be empty
List<PoseLandmark> allPoseLandmarks = pose.getAllPoseLandmarks();

// Or get specific PoseLandmarks individually. These will all be null if no person
// was detected
PoseLandmark leftShoulder = pose.getPoseLandmark(PoseLandmark.LEFT_SHOULDER);
PoseLandmark rightShoulder = pose.getPoseLandmark(PoseLandmark.RIGHT_SHOULDER);
PoseLandmark leftElbow = pose.getPoseLandmark(PoseLandmark.LEFT_ELBOW);
PoseLandmark rightElbow = pose.getPoseLandmark(PoseLandmark.RIGHT_ELBOW);
PoseLandmark leftWrist = pose.getPoseLandmark(PoseLandmark.LEFT_WRIST);
PoseLandmark rightWrist = pose.getPoseLandmark(PoseLandmark.RIGHT_WRIST);
PoseLandmark leftHip = pose.getPoseLandmark(PoseLandmark.LEFT_HIP);
PoseLandmark rightHip = pose.getPoseLandmark(PoseLandmark.RIGHT_HIP);
PoseLandmark leftKnee = pose.getPoseLandmark(PoseLandmark.LEFT_KNEE);
PoseLandmark rightKnee = pose.getPoseLandmark(PoseLandmark.RIGHT_KNEE);
PoseLandmark leftAnkle = pose.getPoseLandmark(PoseLandmark.LEFT_ANKLE);
PoseLandmark rightAnkle = pose.getPoseLandmark(PoseLandmark.RIGHT_ANKLE);
PoseLandmark leftPinky = pose.getPoseLandmark(PoseLandmark.LEFT_PINKY);
PoseLandmark rightPinky = pose.getPoseLandmark(PoseLandmark.RIGHT_PINKY);
PoseLandmark leftIndex = pose.getPoseLandmark(PoseLandmark.LEFT_INDEX);
PoseLandmark rightIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_INDEX);
PoseLandmark leftThumb = pose.getPoseLandmark(PoseLandmark.LEFT_THUMB);
PoseLandmark rightThumb = pose.getPoseLandmark(PoseLandmark.RIGHT_THUMB);
PoseLandmark leftHeel = pose.getPoseLandmark(PoseLandmark.LEFT_HEEL);
PoseLandmark rightHeel = pose.getPoseLandmark(PoseLandmark.RIGHT_HEEL);
PoseLandmark leftFootIndex = pose.getPoseLandmark(PoseLandmark.LEFT_FOOT_INDEX);
PoseLandmark rightFootIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_FOOT_INDEX);
PoseLandmark nose = pose.getPoseLandmark(PoseLandmark.NOSE);
PoseLandmark leftEyeInner = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_INNER);
PoseLandmark leftEye = pose.getPoseLandmark(PoseLandmark.LEFT_EYE);
PoseLandmark leftEyeOuter = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_OUTER);
PoseLandmark rightEyeInner = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_INNER);
PoseLandmark rightEye = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE);
PoseLandmark rightEyeOuter = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_OUTER);
PoseLandmark leftEar = pose.getPoseLandmark(PoseLandmark.LEFT_EAR);
PoseLandmark rightEar = pose.getPoseLandmark(PoseLandmark.RIGHT_EAR);
PoseLandmark leftMouth = pose.getPoseLandmark(PoseLandmark.LEFT_MOUTH);
PoseLandmark rightMouth = pose.getPoseLandmark(PoseLandmark.RIGHT_MOUTH);

Dicas para melhorar o desempenho

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

Para que o Kit de ML detecte a pose com precisão, a pessoa na imagem deve ser representada por dados de pixel suficientes; para obter o melhor desempenho, o assunto deve ter pelo menos 256 x 256 pixels.
Se você detectar a pose em um aplicativo em tempo real, também pode considerar as dimensões gerais das imagens de entrada. Imagens menores podem ser processadas mais rápido, portanto, para reduzir a latência, capture imagens em resoluções mais baixas, mas mantenha os requisitos de resolução acima e garantir que o assunto ocupe o máximo o máximo possível da imagem.
Uma imagem com foco inadequado também pode afetar a precisão. Se você não receber resultados aceitáveis, peça ao usuário para recapturar a imagem.

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

Use o SDK básico de detecção de poses e o STREAM_MODE.
Capture imagens em uma resolução mais baixa. No entanto, lembre-se também dos requisitos de dimensão de imagem dessa API.
Se você usar o método Camera ou API camera2, limitar as chamadas ao detector. Se um novo vídeo fica disponível enquanto o detector está em execução, descarte esse frame. Consulte a VisionProcessorBase no app de amostra do guia de início rápido para conferir um exemplo.
Se você usa a API CameraX, verificar se a estratégia de pressão de retorno está definida para o valor padrão ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Isso garante que apenas uma imagem será enviada para análise por vez. Se mais imagens forem produzidas quando o analisador estiver ocupado, elas serão descartadas automaticamente e não serão enfileiradas entrega. Depois que a imagem que está sendo analisada é fechada, chamando ImageProxy.close(), a próxima imagem mais recente será entregue.
Se você usar a saída do detector para sobrepor elementos gráficos a imagem de entrada, primeiro acesse o resultado do Kit de ML e, em seguida, renderize a imagem e sobreposição em uma única etapa. Isso é renderizado na superfície da tela. apenas uma vez para cada frame de entrada. Consulte a CameraSourcePreview e GraphicOverlay no app de amostra do guia de início rápido para conferir um exemplo.
Se você usar a API Camera2, capture imagens no ImageFormat.YUV_420_888. Se você usar a API Camera mais antiga, capture imagens no ImageFormat.NV21.

Próximas etapas

Para aprender a usar pontos de referência de poses para classificar poses, consulte Dicas de classificação de posições.

Detectar poses com o Kit de ML no Android

Faça um teste

Antes de começar

1. Criar uma instância de PoseDetector

PoseDetector opções

Modo de detecção

Configuração de hardware

Kotlin

Java

Kotlin

Java

2. Preparar a imagem de entrada

Como usar um media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

Usar um URI de arquivo

Kotlin

Java

Como usar ByteBuffer ou ByteArray

Kotlin

Java

Como usar um Bitmap

Kotlin

Java

3. Processar a imagem

Kotlin

Java

4. Receber informações sobre a pose detectada

Kotlin

Java

Dicas para melhorar o desempenho

Próximas etapas

1. Criar uma instância de `PoseDetector`

`PoseDetector` opções

Como usar um `media.Image`

Como usar `ByteBuffer` ou `ByteArray`

Como usar um `Bitmap`