構成オプション

CameraX ユースケースを個別に構成すると、ユースケースのさまざまな処理を制御できます。

たとえば、画像キャプチャ ユースケースでは、ターゲット アスペクト比とフラッシュ モードを設定できます。次のコードはその一例を示しています。

val imageCapture = ImageCapture.Builder()
    .setFlashMode(...)
    .setTargetAspectRatio(...)
    .build()

ImageCapture imageCapture =
    new ImageCapture.Builder()
        .setFlashMode(...)
        .setTargetAspectRatio(...)
        .build();

一部のユースケースでは、構成オプションに加えて、ユースケースの作成後に設定を動的に変更する API も公開されています。 個々のユースケースに固有の構成については、プレビューを実装する、画像を解析する、画像キャプチャをご覧ください。

自動選択

CameraX は、アプリが実行されているデバイスに固有の機能を自動的に提供します。たとえば、解像度が指定されていない場合や、指定された解像度がサポートされていない場合、使用する最適な解像度を自動的に決定します。これらはすべてライブラリによって処理されるため、デバイス固有のコードを記述する必要はありません。

CameraX の目標は、カメラ セッションを正常に初期化することです。そのために、CameraX はデバイス機能に基づいて解像度とアスペクト比を低下させることがあります。これは、次の理由で発生する可能性があります。

• デバイスが、リクエストされた解像度に対応していない。
• デバイスに互換性の問題がある。たとえば、古いデバイスの中には、正常に動作するために特定の解像度を必要とするものがあります。
• 一部のデバイスで、特定のアスペクト比でのみ使用可能な特定の形式がある。
• デバイスで、JPEG または動画エンコードについて「mod16 に最も近い」値が優先される。 詳しくは、SCALER_STREAM_CONFIGURATION_MAP をご覧ください。

CameraX はセッションを作成し管理しますが、コードのユースケース出力で返される画像サイズを常に確認し、それに応じて調整する必要があります。

回転

カメラの回転はデフォルトでは、ユースケースの作成時にデフォルトのディスプレイの回転と一致するように設定されます。このデフォルトのケースでは、CameraX は、ユーザーが期待する画像をアプリのプレビューで簡単に作成できるように出力を生成します。マルチディスプレイ デバイスに対応するため、回転をカスタム値に変更できます。そのためには、ユースケース オブジェクトの構成時に、またはユースケース オブジェクトの作成後に動的に、現在のディスプレイの向きを渡します。

アプリは、構成設定を使用してターゲットの回転を設定できます。その後、ライフサイクルが実行状態であっても、ユースケース API のメソッド（ImageAnalysis.setTargetRotation() など）を使用して回転設定を更新できます。この方法は、アプリが縦向きにロックされている（そのため、回転時に再構成が行われない）場合に使用できます。ただし、写真または解析ユースケースがデバイスの現在の回転を認識できることが必要です。たとえば、顔の向きを正しく検出する場合や、写真を横向きまたは縦向きに設定する場合は、回転の認識が必要になります。

キャプチャした画像のデータは、回転情報なしで保存されることがあります。EXIF データには回転情報が含まれるため、保存後にギャラリー アプリは画像を正しい向きで表示できます。

プレビュー データを正しい向きで表示するには、Preview.PreviewOutput() のメタデータ出力を使用して変換を作成します。

次のコードサンプルは、向きのイベントで回転を設定する方法を示しています。

override fun onCreate() {
    val imageCapture = ImageCapture.Builder().build()

    val orientationEventListener = object : OrientationEventListener(this as Context) {
        override fun onOrientationChanged(orientation : Int) {
            // Monitors orientation values to determine the target rotation value
            val rotation : Int = when (orientation) {
                in 45..134 -> Surface.ROTATION_270
                in 135..224 -> Surface.ROTATION_180
                in 225..314 -> Surface.ROTATION_90
                else -> Surface.ROTATION_0
            }

            imageCapture.targetRotation = rotation
        }
    }
    orientationEventListener.enable()
}

@Override
public void onCreate() {
    ImageCapture imageCapture = new ImageCapture.Builder().build();

    OrientationEventListener orientationEventListener = new OrientationEventListener((Context)this) {
       @Override
       public void onOrientationChanged(int orientation) {
           int rotation;

           // Monitors orientation values to determine the target rotation value
           if (orientation >= 45 && orientation < 135) {
               rotation = Surface.ROTATION_270;
           } else if (orientation >= 135 && orientation < 225) {
               rotation = Surface.ROTATION_180;
           } else if (orientation >= 225 && orientation < 315) {
               rotation = Surface.ROTATION_90;
           } else {
               rotation = Surface.ROTATION_0;
           }

           imageCapture.setTargetRotation(rotation);
       }
    };

    orientationEventListener.enable();
}

以下の各ユースケースは、設定された回転に基づいて、画像データを直接回転させるか、または回転されていない画像データの回転メタデータをコンシューマに提供します。

• Preview: Preview.getTargetRotation() によりターゲット解像度の回転を認識できるようなメタデータ出力が提供されます。
• ImageAnalysis: 画像バッファ座標と表示座標の相対関係を認識できるようなメタデータ出力が提供されます。
• ImageCapture: 画像の EXIF メタデータまたはバッファ、あるいはメタデータとバッファの両方が変更され、回転設定が記録されます。変更される値は HAL 実装によって異なります。

切り抜き範囲

デフォルトでは、切り抜き範囲はバッファ範囲と一致します。切り抜き範囲は ViewPort と UseCaseGroup を使ってカスタマイズできます。ユースケースをグループ化してビューポートを設定すると、CameraX でグループ内のすべてのユースケースの切り抜き範囲がカメラセンサーの同じ領域をポイントするようになります。

次のコード スニペットは、これら 2 つのクラスの使用方法を示しています。

val viewPort =  ViewPort.Builder(Rational(width, height), display.rotation).build()
val useCaseGroup = UseCaseGroup.Builder()
    .addUseCase(preview)
    .addUseCase(imageAnalysis)
    .addUseCase(imageCapture)
    .setViewPort(viewPort)
    .build()
cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, useCaseGroup)

ViewPort viewPort = new ViewPort.Builder(
         new Rational(width, height),
         getDisplay().getRotation()).build();
UseCaseGroup useCaseGroup = new UseCaseGroup.Builder()
    .addUseCase(preview)
    .addUseCase(imageAnalysis)
    .addUseCase(imageCapture)
    .setViewPort(viewPort)
    .build();
cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, useCaseGroup);

ViewPort は、エンドユーザーに表示されるバッファ範囲を定義します。CameraX は、ビューポートのプロパティと接続されたユースケースに基づいて、最大切り抜き範囲を計算します。通常、WYSIWYG 効果を実現するには、プレビューのユースケースに基づいてビューポートを構成する必要があります。ビューポートを簡単に取得するには、PreviewView を使用します。

次のコード スニペットの例は、ViewPort オブジェクトを取得する方法を示しています。

val viewport = findViewById<PreviewView>(R.id.preview_view).viewPort

ViewPort viewPort = ((PreviewView)findViewById(R.id.preview_view)).getViewPort();

上記の例では、PreviewView のスケールタイプがデフォルトの FILL_CENTER に設定されている場合、アプリが ImageAnalysis と ImageCapture から取得する範囲と PreviewView でエンドユーザーに表示される範囲とが一致します。切り抜き範囲と回転を出力バッファに適用すると、すべてのユースケースの画像は解像度の違いはあるものの、同じになります。変換情報の適用方法について詳しくは、出力を変換するをご覧ください。

カメラの解像度

デバイスの機能、デバイスがサポートするハードウェア レベル、ユースケース、指定されたアスペクト比の組み合わせに基づいて CameraX が画像解像度を設定するように選択できます。または、特定のターゲット解像度または特定のアスペクト比を、その構成をサポートするユースケースに設定することもできます。

自動解像度

CameraX は、cameraProcessProvider.bindToLifecycle() で指定されたユースケースに基づいて最適な解像度設定を自動的に決定します。可能な限り、1 回の bindToLifecycle() 呼び出しで、同一のセッションで同時に実行する必要のあるユースケースをすべて指定してください。CameraX は、デバイスがサポートするハードウェア レベルや、デバイスの特徴（デバイスが使用可能なストリーム設定の限度を超えている、あるいはその設定に対応していないことがある）を考慮して、バインドされているユースケースのセットに基づいて解像度を決定します。これは、デバイス固有のコードパスを最小限に抑えつつ、アプリをさまざまなデバイスで実行できるようにするためです。

画像キャプチャ ユースケースと画像解析ユースケースのデフォルトのアスペクト比は 4:3 です。

UI の設計に基づいてアプリで目的のアスペクト比を指定できるようにするために、ユースケースでアスペクト比を設定できるようになっています。CameraX の出力は、リクエストされたアスペクト比とデバイスがサポートするアスペクト比ができる限り一致するように生成されます。完全に一致する解像度がサポートされていない場合、条件に最も近い解像度が選択されます。このようにして、アプリは、アプリ内におけるカメラのアスペクト比を決定し、CameraX は、各デバイスでそのアスペクト比に適合する最適なカメラ解像度設定を決定します。

たとえば、アプリは以下の操作をいずれも実行できます。

• ユースケースのターゲット解像度を 4:3 または 16:9 に指定する
• カスタム解像度を指定する（CameraX はこれに最も近い解像度を探します）
• ImageCapture の切り抜きのアスペクト比を指定する

CameraX は内部の Camera2 サーフェス解像度を自動的に選択します。次の表にその解像度を示します。

解像度を指定する

次のコードサンプルに示すように、ユースケースを作成する際に setTargetResolution(Size resolution) メソッドを使用して特定の解像度を設定できます。

val imageAnalysis = ImageAnalysis.Builder()
    .setTargetResolution(Size(1280, 720))
    .build()

ImageAnalysis imageAnalysis =
  new ImageAnalysis.Builder()
    .setTargetResolution(new Size(1280, 720))
    .build();

同じユースケースに、ターゲット アスペクト比とターゲット解像度の両方を設定することはできません。これを行うと、構成オブジェクトの作成時に IllegalArgumentException がスローされます。

解像度 Size を、サポートされているサイズをターゲットの回転で回転させた後の座標フレームで表してください。たとえば、自然な向きが縦向きであるデバイスがあるとします。ターゲットの回転が自然な縦向きになっているときに、縦向きの画像のリクエストに対して 480x640 を指定したら、同じデバイスを 90 度回転して横向きをターゲットにした場合は 640x480 を指定します。

ImageAnalysis で選択できる最大解像度は 1080p です。ImageAnalysis の 1080p という制限は、十分な品質とスムーズな出力ストリームが得られるように、パフォーマンスと品質の両方の要因を考慮したものです。

ターゲット解像度を使用して、画像解像度の最小値を確立することが試みられます。実際の画像解像度は、ターゲット解像度以上で最も近い解像度になります。これは Camera の実装によって決定されます。ただし、ターゲット解像度以上の解像度が存在しない場合は、ターゲット解像度よりも小さく最も近い解像度が選択されます。指定された Size と同じアスペクト比の解像度は、異なるアスペクト比の解像度よりも優先されます。

CameraX はリクエストに基づいて最適な解像度を適用します。アスペクト比の要件を満たすことが最も重要である場合は、setTargetAspectRatio のみを指定します。CameraX は、デバイスに応じた適切な解像度を決定します。アプリの画像処理を効率化することが最も重要で、そのために解像度を指定する必要がある場合（たとえば、デバイスの処理能力に応じて小規模または中規模サイズの画像を使用する場合）は、setTargetResolution(Size resolution) を使用します。

アプリで正確な解像度が必要な場合は、createCaptureSession() の表で、各ハードウェア レベルでサポートされている最大解像度を確認してください。現行のデバイスでサポートされている解像度を確認するには、StreamConfigurationMap.getOutputSizes(int) をご覧ください。

Android 10 以上でアプリを実行している場合は、isSessionConfigurationSupported() を使用して特定の SessionConfiguration を確認できます。

フォーカスの制御

CameraControl API は「タップしてフォーカス」機能を提供します。まず、次のコードに示すように、CameraControl オブジェクトを取得します。

val camera = processCameraProvider.bindToLifecycle(...)
val cameraControl = camera.getCameraControl()

Camera camera = processCameraProvider.bindToLifecycle(...);
CameraControl cameraControl = camera.getCameraControl();

タップしてフォーカスを実行するには、MeteringPointFactory、MeteringPoint、MeteringMode、FocusMeteringAction を次のように使用します。

val factory = SurfaceOrientedMeteringPointFactory(width, height)
val point = factory.createPoint(x, y)
val action = FocusMeteringAction.Builder(point, FocusMeteringAction.FLAG_AF)
    .addPoint(point2, FocusMeteringAction.FLAG_AE) // could have many
    // auto calling cancelFocusAndMetering in 5 seconds
    .setAutoCancelDuration(5, TimeUnit.SECONDS)
    .build()

val future = cameraControl.startFocusAndMetering(action)
future.addListener( Runnable {
    val result = future.get()
    // process the result
} , executor)

MeteringPointFactory factory = new SurfaceOrientedMeteringPointFactory(width, height);
MeteringPoint point = factory.createPoint(x, y);
FocusMeteringAction action = new FocusMeteringAction.Builder(point, FocusMeteringAction.FLAG_AF)
        .addPoint(point2, FocusMeteringAction.FLAG_AE) // could have many
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build();

ListenableFuture future = cameraControl.startFocusAndMetering(action)
future.addListener( () -> {
    try {
        FocusMeteringResult result = future.get();
        // process the result
    } catch (Exception e) {
    }
} , executor);

参考情報

CameraX について詳しくは、以下の参考情報をご確認ください。

Codelab

コードサンプル

デベロッパー コミュニティ

Android CameraX ディスカッション グループ