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:
val config = ImageCaptureConfig.Builder() .setLensFacing(...) .setFlashMode(...) .setTargetAspectRatio(...) .build()
ImageCaptureConfig config = new ImageCaptureConfig.Builder() .setLensFacing(...) .setFlashMode(...) .setTargetAspectRatio(...) .build();
In addition to configuration options, some use cases expose APIs to dynamically alter settings after the use case has been created. For information on configuration that is specific to the individual use cases, see Implement a preview, Analyze images, and Take a photo.
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.
CameraX's goal is to successfully initialize a camera session. This means CameraX compromises on resolution and aspect ratios based on device capability. The compromise may happen because:
- The device does not support the requested resolution.
- The device has compatibility issues, such as legacy devices that require certain resolutions to operate correctly.
- On some devices, certain formats are only available at certain aspect ratios.
- The device has a preference for a "nearest mod16" for JPEG or video encoding. See SCALER_STREAM_CONFIGURATION_MAP for more information.
Although CameraX creates and manages the session, you should always check the returned image sizes on the use case output in your code and adjust accordingly.
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
The following code sample shows how to set the rotation through the configuration APIs:
val previewConfig = PreviewConfig.Builder() .setTargetRotation(windowManager.defaultDisplay.rotation) .build()
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
- ImageAnalysis: Metadata output is provided so that image buffer
coordinates are known relative to display coordinates. The
analyze()method provides a
rotationDegreesparameter 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.
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.
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
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
val imageAnalysisConfig = ImageAnalysisConfig.Builder() .setTargetResolution(Size(1280, 720)) .build()
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
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
To learn more about CameraX, consult the following additional resources.