ViewPort

public final class ViewPort
extends Object

java.lang.Object
   ↳ androidx.camera.core.ViewPort


The field of view of one or many UseCases.

The ViewPort defines a FOV which is used by CameraX to calculate output crop rects. For use cases associated with the same ViewPort in a UseCaseGroup, the output crop rect will be mapped to the same camera sensor area. Usually ViewPort is configured to optimize for Preview so that ImageAnalysis and ImageCapture produce the same crop rect in a WYSIWYG way.

If the ViewPort is used with a ImageCapture and ImageCapture.takePicture(ImageCapture.OutputFileOptions, Executor, ImageCapture.OnImageSavedCallback) is called, the image may be cropped before saving to disk which introduces an additional latency. To avoid the latency and get the uncropped image, please use the in-memory method ImageCapture.takePicture(Executor, ImageCapture.OnImageCapturedCallback).

For ImageAnalysis and in-memory ImageCapture, the output crop rect is ImageProxy.getCropRect(); for on-disk ImageCapture, the image is cropped before saving; for Preview, the crop rect is SurfaceRequest.TransformationInfo.getCropRect(). Caller should transform the output in a way that only the area defined by the crop rect is visible to end users. Once the crop rect is applied, all the use cases will produce the same image with possibly different resolutions.

Summary

Nested classes

class ViewPort.Builder

Builder for ViewPort

Constants

int FILL_CENTER

Generate a crop rect that once applied, it scales the output while maintaining its aspect ratio, so it fills the entire ViewPort and center it.

int FILL_END

Generate a crop rect that once applied, it scales the output while maintaining its aspect ratio, so it fills the entire ViewPort, and align it to the end of the ViewPort, which is the bottom right corner in a left-to-right (LTR) layout, or the bottom left corner in a right-to-left (RTL) layout.

int FILL_START

Generate a crop rect that once applied, it scales the output while maintaining its aspect ratio, so it fills the entire ViewPort, and align it to the start of the ViewPort, which is the top left corner in a left-to-right (LTR) layout, or the top right corner in a right-to-left (RTL) layout.

int FIT

Generate the max possible crop rect ignoring the aspect ratio.

Public methods

Rational getAspectRatio()

Gets the aspect ratio of the ViewPort.

int getRotation()

Gets the rotation of the ViewPort.

int getScaleType()

Gets the scale type of the ViewPort.

Inherited methods

Constants

FILL_CENTER

public static final int FILL_CENTER

Generate a crop rect that once applied, it scales the output while maintaining its aspect ratio, so it fills the entire ViewPort and center it.

This may cause the output to be cropped if the output aspect ratio does not match that of the ViewPort.

Constant Value: 1 (0x00000001)

FILL_END

public static final int FILL_END

Generate a crop rect that once applied, it scales the output while maintaining its aspect ratio, so it fills the entire ViewPort, and align it to the end of the ViewPort, which is the bottom right corner in a left-to-right (LTR) layout, or the bottom left corner in a right-to-left (RTL) layout.

This may cause the output to be cropped if the output aspect ratio does not match that of the ViewPort.

Constant Value: 2 (0x00000002)

FILL_START

public static final int FILL_START

Generate a crop rect that once applied, it scales the output while maintaining its aspect ratio, so it fills the entire ViewPort, and align it to the start of the ViewPort, which is the top left corner in a left-to-right (LTR) layout, or the top right corner in a right-to-left (RTL) layout.

This may cause the output to be cropped if the output aspect ratio does not match that of the ViewPort.

Constant Value: 0 (0x00000000)

FIT

public static final int FIT

Generate the max possible crop rect ignoring the aspect ratio. For ImageAnalysis and ImageCapture, the output will be an image defined by the crop rect.

For Preview, further calculation is needed to to fit the crop rect into the viewfinder. Code sample below is a simplified version assuming Surface orientation is the same as the camera sensor orientation, the viewfinder is a SurfaceView and the viewfinder's pixel width/height is the same as the size request by CameraX in SurfaceRequest.getResolution(). For more complicated scenarios, please check out the source code of PreviewView in androidx.camera.view artifact.

First, calculate the transformation to fit the crop rect in the center of the viewfinder:

val transformation = Matrix()
   transformation.setRectToRect(
       cropRect, new RectF(0, 0, viewFinder.width, viewFinder.height, ScaleToFit.CENTER))
 

Then apply the transformation to the viewfinder:

val transformedRect = RectF(0, 0, viewFinder.width, viewFinder.height)
   transformation.mapRect(surfaceRect)
   viewFinder.pivotX = 0
   viewFinder.pivotY = 0
   viewFinder.translationX = transformedRect.left
   viewFinder.translationY = transformedRect.top
   viewFinder.scaleX = surfaceRect.width/transformedRect.width
   viewFinder.scaleY = surfaceRect.height/transformedRect.height
 

Constant Value: 3 (0x00000003)

Public methods

getAspectRatio

public Rational getAspectRatio ()

Gets the aspect ratio of the ViewPort.

Returns
Rational

getRotation

public int getRotation ()

Gets the rotation of the ViewPort.

Returns
int

getScaleType

public int getScaleType ()

Gets the scale type of the ViewPort.

Returns
int