構成オプション

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

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

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

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

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

CameraXConfig

簡便化のために、CameraX には、ほとんどの使用シナリオに適した内部エグゼキュータやハンドラなどのデフォルト構成が用意されています。ただし、アプリに特別な要件がある場合や、デフォルト構成をカスタマイズする場合のためのインターフェースとして CameraXConfig もあります。

CameraXConfig を使用すると、アプリで次のことができます。

• setAvailableCameraLimiter() を使用して、起動レイテンシを最適化する。
• setCameraExecutor() を使用して、アプリのエグゼキュータを CameraX に提供する。
• setSchedulerHandler() を使用して、デフォルトのスケジューラ ハンドラを置き換える。
• setMinimumLoggingLevel() を使用して、ロギングレベルを変更する。

使用モデル

CameraXConfig を使用する手順は次のとおりです。

1. カスタマイズした構成を使用して、CameraXConfig オブジェクトを作成します。
2. Application に CameraXConfig.Provider インターフェースを実装し、getCameraXConfig() で CameraXConfig オブジェクトを返します。
3. こちらに記載されている手順に沿って、Application クラスを AndroidManifest.xml ファイルに追加します。

たとえば、次のコードサンプルでは、CameraX のロギングの対象をエラー メッセージに限定しています。

class CameraApplication : Application(), CameraXConfig.Provider {
   override fun getCameraXConfig(): CameraXConfig {
       return CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
           .setMinimumLoggingLevel(Log.ERROR).build()
   }
}

CameraX の構成を設定した後でアプリがその構成を認識する必要がある場合は、CameraXConfig オブジェクトのローカルコピーを保持します。

カメラ リミッター

ProcessCameraProvider.getInstance() の初回呼び出しの際に、CameraX はデバイスで使用できるカメラの特性を列挙および照会します。CameraX はハードウェア コンポーネントと通信する必要があるため、特にローエンドのデバイスでは、カメラごとに行われるこのプロセスにかなりの時間がかかることがあります。アプリがデバイスの特定のカメラ（デフォルトの前面カメラなど）のみを使用する場合は、他のカメラを無視するよう CameraX を設定することで、アプリが使用するカメラの起動レイテンシを短縮できます。

CameraXConfig.Builder.setAvailableCamerasLimiter() に渡される CameraSelector によってカメラが除外された場合、CameraX はそのカメラが存在しないかのように動作します。たとえば、次のコードは、アプリが使用するカメラをデバイスのデフォルトの背面カメラに限定しています。

class MainApplication : Application(), CameraXConfig.Provider {
   override fun getCameraXConfig(): CameraXConfig {
       return CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
              .setAvailableCamerasLimiter(CameraSelector.DEFAULT_BACK_CAMERA)
              .build()
   }
}

スレッド

CameraX が構築されるたいていのプラットフォーム API では、ハードウェアとのプロセス間通信（IPC）のブロックが必要です。この処理には、応答まで数百ミリ秒かかる場合があります。このため、CameraX はそれらの API をバックグラウンド スレッドからのみ呼び出します。これにより、メインスレッドがブロックされず、滑らかな UI を維持できます。この動作が透過的に見えるように、CameraX はこれらのバックグラウンド スレッドを内部的に管理します。ただし、アプリの中にはスレッドの厳密な制御を必要とするものもあります。CameraXConfig を使用すると、アプリは CameraXConfig.Builder.setCameraExecutor() と CameraXConfig.Builder.setSchedulerHandler() を通じて使用されるバックグラウンド スレッドを設定できます。

カメラ エグゼキュータ

カメラ エグゼキュータは、すべての内部的な Camera プラットフォーム API 呼び出しと、これらの API からのコールバックに使用されます。CameraX は、このタスクを実行するために内部 Executor を割り当てて管理します。ただし、アプリがスレッドのより厳密な制御を必要とする場合は、CameraXConfig.Builder.setCameraExecutor() を使用してください。

スケジューラ ハンドラ

スケジューラ ハンドラは、カメラが使用できない場合にカメラを開く処理を再試行するなどの内部タスクを一定の間隔でスケジュールするために使用されます。このハンドラはジョブを実行せず、カメラ エグゼキュータにジョブをディスパッチするだけです。コールバック用に Handler を必要とする従来の API プラットフォームで使用される場合もあります。その場合も、コールバックはカメラ エグゼキュータに直接ディスパッチされるだけです。CameraX はこのタスクを実行するために内部 HandlerThread を割り当てて管理しますが、これは CameraXConfig.Builder.setSchedulerHandler() でオーバーライドできます。

ロギング

CameraX のロギングを使用すると、アプリは logcat メッセージをフィルタできます。これは、本番環境のコードで冗長なメッセージを回避するためのおすすめの方法です。CameraX は、最も詳細なレベルから最も重大なレベルまでの 4 段階のロギングレベルをサポートしています。

• Log.DEBUG（デフォルト）
• Log.INFO
• Log.WARN
• Log.ERROR

これらのログレベルについて詳しくは、Android の Log のドキュメントをご覧ください。アプリに適切なロギングレベルを設定するには、CameraXConfig.Builder.setMinimumLoggingLevel(int) を使用します。

自動選択

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 は、アプリケーションの要件とユースケースに最適なカメラデバイスを自動的に選択します。選択されたデバイスとは異なるデバイスを使用する場合は、いくつかの方法があります。

• デフォルトの前面カメラをリクエストするには、CameraSelector.DEFAULT_FRONT_CAMERA を使用します。
• デフォルトの背面カメラをリクエストするには、CameraSelector.DEFAULT_BACK_CAMERA を使用します。
• 利用可能なデバイスのリストを CameraCharacteristics でフィルタするには、CameraSelector.Builder.addCameraFilter() を使用します。

次のコードサンプルは、デバイスの選択に影響を与える CameraSelector を作成する方法を示しています。

fun selectExternalOrBestCamera(provider: ProcessCameraProvider):CameraSelector? {
   val cam2Infos = provider.availableCameraInfos.map {
       Camera2CameraInfo.from(it)
   }.sortedByDescending {
       // HARDWARE_LEVEL is Int type, with the order of:
       // LEGACY < LIMITED < FULL < LEVEL_3 < EXTERNAL
       it.getCameraCharacteristic(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL)
   }

   return when {
       cam2Infos.isNotEmpty() -> {
           CameraSelector.Builder()
               .addCameraFilter {
                   it.filter { camInfo ->
                       // cam2Infos[0] is either EXTERNAL or best built-in camera
                       val thisCamId = Camera2CameraInfo.from(camInfo).cameraId
                       thisCamId == cam2Infos[0].cameraId
                   }
               }.build()
       }
       else -> null
    }
}

// create a CameraSelector for the USB camera (or highest level internal camera)
val selector = selectExternalOrBestCamera(processCameraProvider)
processCameraProvider.bindToLifecycle(this, selector, preview, analysis)

カメラの解像度

デバイスの機能、デバイスがサポートするハードウェア レベル、ユースケース、指定されたアスペクト比の組み合わせに基づいて 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 を指定します。

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

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

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

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

カメラ出力の制御

CameraX では、個々のユースケースごとに必要に応じてカメラ出力を構成できるだけでなく、バインドされたすべてのユースケースに共通するカメラ処理をサポートする以下のインターフェースも実装されています。

• CameraControl: 一般的なカメラ機能を設定できます。
• CameraInfo: 上記の一般的なカメラ機能の状態を確認できます。

CameraControl は以下のカメラ機能に対応しています。

• ズーム
• トーチ
• フォーカスと測光（タップしてフォーカス）
• 露出補正

CameraControl と CameraInfo のインスタンスを取得する

ProcessCameraProvider.bindToLifecyle() から返された Camera オブジェクトを使って、CameraControl と CameraInfo のインスタンスを取得します。次のコードに、例を示します。

val camera = processCameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview)

// For performing operations that affect all outputs.
val cameraControl = camera.cameraControl
// For querying information and states.
val cameraInfo = camera.cameraInfo

Camera camera = processCameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview)

// For performing operations that affect all outputs.
CameraControl cameraControl = camera.getCameraControl()
// For querying information and states.
CameraInfo cameraInfo = camera.getCameraInfo()

たとえば、bindToLifecycle() を呼び出した後にズームなどの CameraControl 処理を送信できます。カメラ インスタンスをバインドするために使用されるアクティビティを停止または破棄すると、CameraControl は処理を実行できなくなり、エラーの ListenableFuture を返します。

ズーム

CameraControl には、ズームレベルを変更する 2 つのメソッドが用意されています。

• setZoomRatio() は、ズーム倍率でズームを設定します。

  倍率は CameraInfo.getZoomState().getValue().getMinZoomRatio() から CameraInfo.getZoomState().getValue().getMaxZoomRatio() までの範囲内にする必要があります。そうでない場合、関数はエラーの ListenableFuture を返します。

• setLinearZoom() は、現在のズームを 0～1.0 の線形ズーム値で設定します。

  線形ズームの利点は、ズームの変化に応じて視野（FOV）が拡大縮小することです。そのため、Slider ビューでの使用に最適です。

CameraInfo.getZoomState() は、現在のズーム状態の LiveData を返します。この値は、カメラの初期化時や、setZoomRatio() または setLinearZoom() を使ってズームレベルが設定されたときに変化します。どちらのメソッドを呼び出しても、ZoomState.getZoomRatio() と ZoomState.getLinearZoom() の背後にある値が設定されます。これは、スライダーとともにズーム倍率をテキスト表示する場合に適しています。ZoomState LiveData を監視するだけで、変換を必要とせずに両方を更新できます。

両方の API から返される ListenableFuture を使用すると、ズーム値が指定されたリクエストが繰り返されたとき、それぞれが完了したことをアプリケーションに通知させることができます。また、前の処理の実行中に新しいズーム値を設定すると、前のズーム処理の ListenableFuture は即座にエラーで終了します。

トーチ

CameraControl.enableTorch(boolean) は、トーチ（フラッシュライト）を有効または無効にします。

CameraInfo.getTorchState() を使用すると、現在のトーチの状態を確認できます。トーチが使用できるかどうかは、CameraInfo.hasFlashUnit() から返される値で確認できます。使用できない場合、CameraControl.enableTorch(boolean) を呼び出すと、返された ListenableFuture は即座にエラーで終了し、トーチの状態は TorchState.OFF に設定されます。

トーチを有効にすると、flashMode 設定に関係なく、写真や動画のキャプチャ中もオンになります。ImageCapture の flashMode は、トーチが無効になっている場合にのみ機能します。

フォーカスと測光

CameraControl.startFocusAndMetering() は、指定された FocusMeteringAction に基づいて AF/AE/AWB 測光領域を設定することで、オートフォーカスと露出測定をトリガーします。これは、多くのカメラアプリで「タップしてフォーカス」機能を実装する際によく使用されます。

MeteringPoint

まず、MeteringPointFactory.createPoint(float x, float y, float size) を使用して MeteringPoint を作成します。MeteringPoint は、カメラ Surface 上の一点を表します。正規化された形式で保存されるため、AF/AE/AWB 領域を指定するためのセンサー座標に簡単に変換できます。

MeteringPoint のサイズは 0～1 で、デフォルト サイズは 0.15f です。MeteringPointFactory.createPoint(float x, float y, float size) を呼び出すと、size で指定されたサイズで (x, y) を中心とする長方形の領域が作成されます。

次のコードは、MeteringPoint の作成方法を示しています。

// Use PreviewView.getMeteringPointFactory if PreviewView is used for preview.
previewView.setOnTouchListener((view, motionEvent) ->  {
val meteringPoint = previewView.meteringPointFactory
    .createPoint(motionEvent.x, motionEvent.y)
…
}

// Use DisplayOrientedMeteringPointFactory if SurfaceView / TextureView is used for
// preview. Please note that if the preview is scaled or cropped in the View,
// it’s the application's responsibility to transform the coordinates properly
// so that the width and height of this factory represents the full Preview FOV.
// And the (x,y) passed to create MeteringPoint may need to be adjusted with
// the offsets.
val meteringPointFactory = DisplayOrientedMeteringPointFactory(
     surfaceView.display,
     camera.cameraInfo,
     surfaceView.width,
     surfaceView.height
)

// Use SurfaceOrientedMeteringPointFactory if the point is specified in
// ImageAnalysis ImageProxy.
val meteringPointFactory = SurfaceOrientedMeteringPointFactory(
     imageWidth,
     imageHeight,
     imageAnalysis)

startFocusAndMetering と FocusMeteringAction

startFocusAndMetering() を呼び出すには、アプリで FocusMeteringAction を作成する必要があります。これは、1 つ以上の MeteringPoints と、省略可能な FLAG_AF、FLAG_AE、FLAG_AWB を組み合わせた測光モードから構成されます。使用方法を次のコードで示します。

val meteringPoint1 = meteringPointFactory.createPoint(x1, x1)
val meteringPoint2 = meteringPointFactory.createPoint(x2, y2)
val action = FocusMeteringAction.Builder(meteringPoint1) // default AF|AE|AWB
      // Optionally add meteringPoint2 for AF/AE.
      .addPoint(meteringPoint2, FLAG_AF | FLAG_AE)
      // The action will be canceled in 3 seconds (if not set, default is 5s).
      .setAutoCancelDuration(3, TimeUnit.SECONDS)
      .build()

val result = cameraControl.startFocusAndMetering(action)
// Adds listener to the ListenableFuture if you need to know the focusMetering result.
result.addListener({
   // result.get().isFocusSuccessful returns if the auto focus is successful or not.
}, ContextCompat.getMainExecutor(this)

上記のコードでは、startFocusAndMetering() に渡す FocusMeteringAction は、AF/AE/AWB 測光領域用の 1 つの MeteringPoint と、AF と AE 用のみの別の MeteringPoint で構成されます。

内部的には、CameraX が Camera2 MeteringRectangles に変換し、対応する CONTROL_AF_REGIONS / CONTROL_AE_REGIONS / CONTROL_AWB_REGIONS パラメータをキャプチャ リクエストに設定します。

すべてのデバイスが AF/AE/AWB と複数領域をサポートしているわけではないため、CameraX はベスト エフォートで FocusMeteringAction を実行します。CameraX は、サポートされている MeteringPoint の最大数を、追加された順に使用します。最大数を超えて追加された MeteringPoint はすべて無視されます。たとえば、FocusMeteringAction が 3 つの MeteringPoint を、2 つしかサポートしていないプラットフォームに与えた場合、初めの 2 つの MeteringPoint のみが使用されます。最後の MeteringPoint は無視されます。

露出補正

露出補正は、自動露出（AE）の出力結果から、さらに露出値（EV）をアプリで微調整する必要がある場合に便利です。露出補正値は次のように使用されて、現在の画像の状態に必要な露出が決定されます。

Exposure = ExposureCompensationIndex * ExposureCompensationStep

CameraX には、露出補正をインデックス値として設定する Camera.CameraControl.setExposureCompensationIndex() 関数が用意されています。

正の値を指定すると画像が明るくなり、負の値を指定すると画像が暗くなります。次のセクションで説明する CameraInfo.ExposureState.exposureCompensationRange() で、サポートされている範囲を確認できます。値がサポートされている場合、キャプチャ リクエストでその値が正常に有効になると、返された ListenableFuture は正常終了します。指定したインデックスがサポート範囲外の場合、setExposureCompensationIndex() は、返された ListenableFuture は直ちにエラーで終了します。

CameraX では、最新の setExposureCompensationIndex() リクエストのみが保持され、前のリクエストが実行される前にこの関数が複数回呼び出されると、キャンセルされます。

次のスニペットは、露出補正インデックスを設定し、露出の変更リクエストが実行されたときに呼び出されるコールバックを登録します。

camera.cameraControl.setExposureCompensationIndex(exposureCompensationIndex)
   .addListener({
      // Get the current exposure compensation index, it may be
      // different from the asked value in case this request was
      // canceled by a newer setting request.
      val currentExposureIndex = camera.cameraInfo.exposureState.exposureCompensationIndex
      …
   }, mainExecutor)

• Camera.CameraInfo.getExposureState() は、以下を含む現在の ExposureState を取得します。

  • 露出補正制御のサポート状況
  • 現在の露出補正インデックス
  • 露出補正インデックスの範囲
  • 露出補正値の計算に使用される露出補正ステップ

たとえば、次のコードは、露出の SeekBar の設定を現在の ExposureState 値で初期化します。

val exposureState = camera.cameraInfo.exposureState
binding.seekBar.apply {
   isEnabled = exposureState.isExposureCompensationSupported
   max = exposureState.exposureCompensationRange.upper
   min = exposureState.exposureCompensationRange.lower
   progress = exposureState.exposureCompensationIndex
}

参考情報

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

Codelab

コードサンプル

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

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