Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Opções de configuração

Configure cada caso de uso do CameraX usando uma classe de interface de configuração para controlar diferentes aspectos das operações do caso de uso.

Por exemplo, com o caso de uso de captura de imagem, é possível configurar qual lente será usada, a proporção desejada e como a linha de execução precisa ser feita. O código a seguir mostra um exemplo:

Kotlin

    val config = ImageCaptureConfig.Builder()
        .setLensFacing(...)
        .setFlashMode(...)
        .setTargetAspectRatio(...)
        .build()
    

Java

    ImageCaptureConfig config =
        new ImageCaptureConfig.Builder()
            .setLensFacing(...)
            .setFlashMode(...)
            .setTargetAspectRatio(...)
            .build();
    

Além das opções de configuração, alguns casos de uso expõem APIs para alterar as configurações de forma dinâmica após a criação deles. Para saber mais sobre configurações específicas de casos de uso individuais, consulte Implementar uma visualização, Analisar imagens e Tirar uma foto.

Seleção automática

O CameraX fornece automaticamente uma funcionalidade específica do dispositivo em que seu app está sendo executado. Por exemplo, o CameraX determinará automaticamente a melhor resolução a ser usada se você não especificar nenhuma ou se a resolução especificada não for compatível. Tudo isso é feito em segundo plano, eliminando a necessidade de criar códigos específicos para o dispositivo.

O objetivo do CameraX é inicializar uma sessão de câmera. Isso significa que o CameraX compromete a resolução e a proporção com base na capacidade do dispositivo. Isso pode acontecer pelos seguintes motivos:

  • O dispositivo não é compatível com a resolução solicitada.
  • O dispositivo tem problemas de compatibilidade, como dispositivos herdados que precisam de determinadas resoluções para funcionar corretamente.
  • Em alguns dispositivos, determinados formatos estão disponíveis apenas em algumas proporções.
  • O dispositivo prefere um "mod16 mais próximo" para codificação JPEG ou de vídeo. Consulte SCALER_STREAM_CONFIGURATION_MAP para mais informações.

Embora o CameraX crie e gerencie a sessão, é recomendado sempre verificar o tamanho das imagens retornadas na saída do caso de uso no seu código e fazer os ajustes necessários.

Rotação

Por padrão, a rotação da câmera é definida para corresponder à rotação da tela padrão durante a criação do caso de uso. Nesse caso padrão, o CameraX produz saídas para permitir que o app corresponda facilmente ao que você espera da visualização. É possível alterar a rotação para um valor personalizado que seja compatível com dispositivos de várias telas transmitindo a orientação atual da tela ao configurar os objetos de caso de uso ou dinamicamente, depois de terem sido criados.

É possível fazer com que seu app configure a rotação desejada usando os criadores de configuração. Você também pode atualizar as configurações de rotação usando os métodos das APIs de caso de uso, como ImageAnalysis.setTargetRotation(), mesmo enquanto o ciclo de vida estiver em um estado de execução. Você poderá usar isso quando o app estiver fixo no modo retrato para que nenhuma reconfiguração ocorra na rotação, mas o caso de uso de foto ou de análise precisará ter a informação sobre a rotação atual do dispositivo. Por exemplo, os dados de rotação podem ser necessários para que os rostos fiquem na orientação correta para o reconhecimento ou as fotos sejam definidas como paisagem ou retrato.

Embora os dados das imagens capturadas sejam armazenados sem a rotação, os dados Exif contêm informações de rotação para que os aplicativos da galeria possam mostrar a imagem na orientação correta depois de salvá-la.

Para exibir dados de visualização na orientação correta, é possível usar os metadados de Preview.PreviewOutput() para criar transformações na exibição de GLSurfaceView.

Veja na amostra de código a seguir como configurar a rotação por meio das APIs de configuração:

Kotlin

    val previewConfig = PreviewConfig.Builder()
            .setTargetRotation(windowManager.defaultDisplay.rotation)
            .build()
    

Java

    PreviewConfig previewConfig =
      new PreviewConfig.Builder()
          .setTargetRotation(getWindowManager().getDefaultDisplay().getRotation())
          .build();
    

Com base na rotação definida, cada caso de uso fará a rotação dos dados da imagem diretamente ou fornecerá metadados de rotação aos consumidores dos dados de imagem não alterados.

  • Preview: a saída de metadados é apresentada para criar as transformações certas para uma tela GLSurfaceView usando Preview.PreviewOutput.getRotationDegrees().
  • ImageAnalysis: a saída de metadados é apresentada para que as coordenadas do buffer de imagem sejam conhecidas em relação às coordenadas de exibição. O método analyze() fornece um parâmetro rotationDegrees, que representa a rotação que precisa ser aplicada aos dados de análise da imagem para corresponder ao visor.
  • ImageCapture: os metadados Exif da imagem serão alterados para observar a configuração de rotação.

Resolução da câmera

Você pode permitir que o CameraX defina uma resolução de imagem com base em uma combinação dos recursos do dispositivo, nível de hardware compatível com o dispositivo, caso de uso e proporção. Também é possível definir uma resolução específica com uma proporção correspondente em casos de uso compatíveis com essa configuração. As resoluções correspondentes à proporção escolhida terão prioridade sobre a resolução especificada.

Resolução automática

O CameraX pode determinar automaticamente as melhores configurações de resolução com base nos casos de uso especificados em CameraX.bindToLifecycle(). Sempre que possível, especifique todos os casos de uso necessários para serem executados simultaneamente em uma única sessão em uma única chamada CameraX.bindToLifecycle(). O CameraX determinará resoluções com base no conjunto de casos de uso vinculados considerando o nível de hardware compatível com o dispositivo e contabilizando a variação específica do dispositivo, em que um dispositivo pode exceder ou não cumprir as configurações de fluxo disponíveis. A intenção é permitir que o aplicativo seja executado em uma ampla variedade de dispositivos, minimizando os caminhos de código específicos do dispositivo.

A proporção padrão para os casos de uso de captura e análise de imagens é de 4:3.

Os casos de uso têm uma proporção configurável para permitir que o aplicativo especifique a proporção desejada com base no design da IU. A saída do CameraX será produzida para corresponder às proporções solicitadas tanto quanto possível. Se não houver uma correspondência exata à resolução compatível, aquela que atender à maioria das condições será selecionada. Assim, o aplicativo determina como a câmera aparecerá no app, e o CameraX define as melhores configurações de resolução para diferentes dispositivos.

Por exemplo, um app pode:

  • configurar o layout para usar 4:3 em capturas de imagem;
  • especificar um layout de tela cheia. Dada a variação de resoluções de tela e a contabilização da barra de IU do sistema, essa é uma proporção que varia de acordo com o dispositivo;
  • especificar um layout quadrado.

O CameraX escolherá automaticamente as resoluções de superfície internas do Camera2. A tabela a seguir mostra as resoluções:

Caso de uso Resolução de superfície interna Resolução de dados de saída
Visualização Proporção: a resolução que melhor se ajusta à configuração desejada. Resolução de superfície interna. Os metadados são fornecidos para permitir uma visualização para cortar, redimensionar e girar até chegar à proporção desejada.
Resolução padrão: a resolução de visualização mais alta ou a resolução preferencial por dispositivo mais alta correspondente à proporção acima.
Resolução máxima: o tamanho de visualização, referente ao melhor tamanho correspondente à resolução de tela do dispositivo ou a 1080p (1920x1080), o que for menor.
Análise de imagem Proporção: a resolução que melhor se ajusta à configuração desejada. Resolução de superfície interna.
Resolução padrão: a configuração de resolução padrão é de 640x480. O ajuste da resolução e da proporção correspondente resultará em uma resolução mais compatível de menos de 1080p.
Resolução máxima: limitada pelo CameraX para 1080p. A resolução é definida como 640x480 por padrão. Portanto, se você quiser uma resolução maior que essa, precisará usar setTargetResolution e setTargetAspectRatio para chegar o mais perto possível das resoluções compatíveis.
Captura de imagem Proporção: a proporção que melhor se adapta à configuração. Resolução de superfície interna.
Resolução padrão: a resolução mais alta disponível ou a resolução preferencial por dispositivo mais alta correspondente à proporção acima.
Resolução máxima: a resolução máxima de saída da câmera para o formato JPEG de StreamConfigurationMap#getOutputSizes.

Especificar uma resolução

É possível definir resoluções específicas ao criar configurações de casos de uso por meio do método setTargetResolution(Size resolution), conforme exibido na amostra de código a seguir:

Kotlin

    val imageAnalysisConfig = ImageAnalysisConfig.Builder()
        .setTargetResolution(Size(1280, 720))
        .build()
    

Java

    ImageAnalysisConfig config =
      new ImageAnalysisConfig.Builder()
        .setTargetResolution(new Size(1280, 720))
        .build();
    

É possível definir uma proporção específica com base na resolução determinada. A proporção definida afetará a escolha da resolução. Defina uma proporção que corresponda à resolução, para chegar à resolução escolhida. A resolução resultante usará a capacidade do dispositivo e de outros casos de uso anexados.

Se a resolução e a proporção exatas não puderem ser acomodadas, a resolução mais alta mais próxima será escolhida, caindo para 640x480 se nenhuma outra estiver disponível.

O CameraX aplicará a melhor resolução adequada com base nas solicitações. Se a necessidade principal for a proporção, especifique apenas setTargetAspectRatio, e o CameraX determinará uma resolução específica com base no dispositivo. Use setTargetResolution(Size resolution) se a necessidade principal do app for especificar uma resolução para deixar o processamento de imagens mais eficiente, por exemplo, em uma imagem de tamanho pequeno ou médio com base na capacidade de processamento do dispositivo.

Se seu app precisar de uma resolução exata, consulte a tabela em createCaptureSession para determinar as resoluções máximas compatíveis com cada nível de hardware. Para verificar as resoluções específicas compatíveis com o dispositivo atual, consulte StreamConfigurationMap.getOutputSize(int).

Se seu app estiver sendo executado no Android 10, use isSessionConfigurationSupported para verificar uma SessionConfiguration específica.

Foco de controle

A API CameraControl oferece recursos "Toque para focar". Receba um CameraControl especificando "lens facing":

Kotlin

    CameraX.getCameraControl(LensFacing lensFacing)
    

Java

    CameraX.getCameraControl(LensFacing lensFacing);
    

Use MeteringPointFactory, MeteringPoint, MeteringMode e FocusMeteringAction para usar o recurso "Toque para focar":

Kotlin

    val factory = SensorOrientedMeteringPointFactory(width, height)
    val point = factory.createPoint(x, y)
    val action = FocusMeteringAction.Builder.from(point,
        FocusMeteringAction.MeteringMode.AF_ONLY)
        .addPoint(point2, FocusMeteringAction.MeteringMode.AE_ONLY) // could have many
        .setAutoFocusCallback { }
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build()
    

Java

    MeteringPointFactory factory = new SensorOrientedMeteringPointFactory(width, height);
    MeteringPoint point = factory.createPoint(x, y);
    FocusMeteringAction action = FocusMeteringAction.Builder.from(point,
                                     MeteringMode.AF_ONLY)
        .addPoint(point2, MeteringMode.AE_ONLY) // could have many
        .setAutoFocusCallback(new OnAutoFocusListener(){
            public void onFocusCompleted(boolean isSuccess) {
            }
        })
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build();
    

Outros recursos

Para saber mais sobre o CameraX, consulte os seguintes recursos adicionais.

Codelab

  • Primeiros passos com o CameraX (link em inglês)
  • Amostra de código

  • App de amostra oficial do CameraX (link em inglês)
  • Comunidade de desenvolvedores

    Grupo de discussão do CameraX do Android