Configuration options

You configure each CameraX use case using a configuration interface class to control different aspects of the use case's operations.

For example, with the image capture use-case, you can set which lens to use, a target aspect ratio, and how threading should be done. The following code shows one example:

Kotlin

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

Java

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

For information on configuration that is specific to the individual use cases, see Implement a preview, Analyze images, and Take a photo.

Automatic selection

CameraX automatically provides functionality that is specific to the device that your app is running on. For example, CameraX will automatically determine the best resolution to use if you don't specify a resolution, or if the resolution you specify is unsupported. All of this is handled behind the scenes, eliminating the need for you to write device-specific code.

Rotation

By default, the camera rotation is set to match the default display's rotation during the creation of the use case. In this default case, CameraX produces outputs to allow the app to easily match what you would expect to see in the preview. You can change the rotation to a custom value to support multi-display devices by passing in the current display orientation when configuring use case objects or dynamically after they have been created.

Your app can configure the target rotation using the configuration builders. Your app can also update rotation settings by using the methods from the use case APIs (for example ImageAnalysis.setTargetRotation()), even while the lifecycle is in a running state. You might use this when the app is locked to portrait mode—and so no reconfiguration occurs on rotation—but the photo or analysis use case needs to be aware of the current rotation of the device. For example, rotation awareness may be needed so faces are oriented correctly for face detection, or photos are set to landscape or portrait.

Although data for captured images is stored without rotating it, the Exif data contains rotation information so that gallery applications can show the image in the correct orientation after saving.

To display preview data with the correct orientation, you can use the metadata output from Preview.PreviewOutput() to create transforms for GLSurfaceView display.

The following code sample shows how to set the rotation through the configuration APIs:

Kotlin

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

Java

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

Based on the set rotation, each use case will either rotate the image data directly or provide rotation metadata to the consumers of the non-rotated image data.

  • Preview: Metadata output is provided to create the right transforms for a GLSurfaceView display using Preview.PreviewOutput.getRotationDegrees().
  • ImageAnalysis: Metadata output is provided so that image buffer coordinates are known relative to display coordinates. The analyze() method provides a rotationDegrees parameter representing the rotation that needs to be applied to the image analysis data to match the viewfinder.
  • ImageCapture: The image Exif metadata will be altered to note the rotation setting.

Camera resolution

You can choose to allow CameraX to set image resolution based on a combination of the device capabilities, device’s supported hardware level, use case, and provided aspect ratio. Alternatively, you can set a specific target resolution with a corresponding aspect ratio in use cases that support that configuration. Resolutions matching the target aspect ratio will be prioritized over the specific target resolution.

Automatic resolution

CameraX can automatically determine the best resolution settings based on the use cases specified in CameraX.bindToLifecycle(). Whenever possible, specify all the use cases needed to run concurrently in a single session in a single CameraX.bindToLifecycle() call. CameraX will determine resolutions based on the set of use cases bound by considering the device’s supported hardware level and by accounting for device-specific variance (where a device may exceed or not meet the stream configurations available). The intent is to allow the application to run on a wide variety of devices while minimizing device-specific code paths.

The default aspect ratio for image capture and image analysis use cases is 4:3.

Use cases have a configurable aspect ratio to allow the application to specify the desired aspect ratio based on UI design. CameraX output will be produced to match the aspect ratios requested as closely as the device supports. If there is no exact-match resolution supported, the one that fulfills the most conditions is selected. Thus the application dictates how the camera should appear in the app, and CameraX determines the best camera resolution settings to satisfy that on different devices.

For example an app may do any of the following:

  • Configure the layout to use 4:3 for image capture.
  • Specify a full screen layout. Given variation in screen resolutions and accounting for system UI bar, this is a ratio that varies per device.
  • Specify a square layout.

CameraX will choose the internal Camera2 surface resolutions automatically. The following table shows the resolutions:

Use case Internal surface resolution Output data resolution
Preview Aspect Ratio: The resolution that best fits the target to the setting. Internal surface resolution. Metadata is provided to allow a View to crop, scale, and rotate for the target aspect ratio.
Default resolution: Highest preview resolution, or highest device-preferred resolution that matches aspect ratio above.
Max resolution: Preview size, which refers to the best size match to the device's screen resolution, or to 1080p (1920x1080), whichever is smaller.
Image analysis Aspect ratio: The resolution that best fits the target to the setting. Internal surface resolution.
Default resolution: The default target resolution setting is 640x480. Adjusting both target resolution and corresponding aspect ratio will result in a best-supported resolution under 1080p.
Max resolution: This is limited by CameraX to 1080p. The target resolution is set as 640x480 by default, so if you want a resolution larger than 640x480, you must use setTargetResolution and setTargetAspectRatio to get the closest one from the supported resolutions.
Image capture Aspect ratio: Aspect ratio that best fits the setting. Internal surface resolution.
Default resolution: Highest resolution available, or highest device-preferred resolution that matches aspect ratio above.
Max resolution: The camera device's maximum output resolution for JPEG format from StreamConfigurationMap#getOutputSizes

Specify a resolution

You can set specific resolutions when building use case configurations using the setTargetResolution(Size resolution) method, as shown in the following code sample:

Kotlin

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

Java

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

You can set a specific target aspect ratio based on the resolution specified. The target aspect ratio will affect which resolution is chosen. Set the target aspect ratio to match the target resolution to get the chosen resolution. The resulting resolution takes into account the device capability and other attached used cases.

If the exact resolution and aspect ratio requested cannot be accommodated, the closest higher, bounding resolution is chosen, falling back to 640x480 if none is available.

CameraX will apply the best suitable resolution based on the requests. If the primary need is to satisfy aspect ratio, specify only setTargetAspectRatio, and CameraX will determine a specific resolution suitable based on the device. If the primary need of the app is to specify a resolution in order to make image processing more efficient (for example a small or mid-sized image based on device processing capability), use setTargetResolution(Size resolution).

If your app requires an exact resolution, see the table within createCaptureSession to determine what maximum resolutions are supported by each hardware level. To check for the specific resolutions supported by the current device, see StreamConfigurationMap.getOutputSize(int).

Additional resources

To learn more about CameraX, consult the following additional resources.

Codelab

  • Getting Started with CameraX
  • Code sample

  • Official CameraX sample app