android camera 参数

Android 相机系统非常灵活，但同时也比较复杂，参数可以分为几个层面：

1. Camera2 API (推荐): 这是现代 Android (API Level 21+) 的官方推荐相机 API，功能强大，控制粒度细，是专业相机应用开发的基础。
2. CameraX (推荐): 这是一个 Jetpack 库，它封装了复杂的 Camera2 API，并提供了兼容性支持（回退到 Camera1），大大简化了开发，它基于 Camera2，所以参数本质上是相通的。
3. Camera1 API (已废弃): 旧版 API，控制能力有限，不推荐新项目使用，但可能在维护旧应用时遇到。

下面我将主要围绕 Camera2 API 来详细介绍参数，并说明如何在 CameraX 中使用它们。

核心参数分类

我们可以将相机参数想象成一个物理相机的各种旋钮和设置,它们主要分为以下几类：

曝光相关参数

控制进光量,决定照片的亮度。

对焦相关参数

控制相机的清晰度。

白平衡相关参数

控制画面的色彩,使其在不同光源下看起来真实。

闪光灯与测光相关参数

图像输出与格式相关参数

拍摄控制参数

如何在 Camera2 API 中使用这些参数

使用 Camera2 API 的标准流程是 打开相机 -> 配置输出 -> 捕捉图像 -> 关闭相机。

获取相机参数

你需要获取 CameraCharacteristics 对象，它包含了相机硬件的静态信息（只读）。

// 打开相机
CameraManager manager = (CameraManager) getSystemService(Context.CAMERA_SERVICE);
String cameraId = manager.getCameraIdList()[0]; // 获取后置摄像头ID
CameraCharacteristics characteristics = manager.getCameraCharacteristics(cameraId);
// 获取支持的参数范围
Range<Integer> isoRange = characteristics.get(CameraCharacteristics.SENSOR_INFO_SENSITIVITY_RANGE);
Range<Long> exposureTimeRange = characteristics.get(CameraCharacteristics.SENSOR_INFO_EXPOSURE_TIME_RANGE);
float[] apertures = characteristics.get(CameraCharacteristics.LENS_INFO_AVAILABLE_APERTURES);

配置并设置参数

创建一个 CaptureRequest.Builder，然后通过 set() 方法设置你想要的参数。

// 创建一个用于拍照的CaptureRequest.Builder
CameraCaptureRequest.Builder captureRequestBuilder = cameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_STILL_CAPTURE);
// --- 设置参数 ---
// 1. 曝光
captureRequestBuilder.set(CaptureRequest.CONTROL_AE_MODE, CaptureRequest.CONTROL_AE_MODE_ON_AUTO_FLASH);
captureRequestBuilder.set(CaptureRequest.SENSOR_SENSITIVITY, 800); // 设置ISO为800
captureRequestBuilder.set(CaptureRequest.SENSOR_EXPOSURE_TIME, 1000000L / 30); // 设置快门为1/30秒
// 2. 对焦
captureRequestBuilder.set(CaptureRequest.CONTROL_AF_MODE, CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE);
// 设置对焦区域 (一个矩形区域，归一化坐标 0.0f - 1.0f)
Rect afRegion = new Rect(100, 100, 300, 300); // 示例区域
captureRequestBuilder.set(CaptureRequest.CONTROL_AF_REGIONS, new MeteringRectangle[]{new MeteringRectangle(afRegion, MeteringRectangle.METERING_WEIGHT_MAX)});
// 3. 白平衡
captureRequestBuilder.set(CaptureRequest.CONTROL_AWB_MODE, CaptureRequest.CONTROL_AWB_MODE_CLOUDY_DAYLIGHT);
// 4. 闪光灯
captureRequestBuilder.set(CaptureRequest.FLASH_MODE, CaptureRequest.FLASH_MODE_AUTO);
// 5. 图像旋转 (非常重要！)
int rotation = getWindowManager().getDefaultDisplay().getRotation();
int sensorOrientation = characteristics.get(CameraCharacteristics.SENSOR_ORIENTATION);
int jpegOrientation = (sensorOrientation + rotation * 90) % 360;
captureRequestBuilder.set(CaptureRequest.JPEG_ORIENTATION, jpegOrientation);
// 6. 将预览Surface加入请求
captureRequestBuilder.addTarget(surface);
// 构建最终的CaptureRequest
CaptureRequest captureRequest = captureRequestBuilder.build();

执行捕获

将配置好的 CaptureRequest 发送给相机设备进行拍照。

// cameraDevice是之前打开的CameraDevice实例
// captureSession是之前创建的CameraCaptureSession实例
cameraCaptureSession.capture(captureRequest, null, null);

如何在 CameraX 中使用这些参数

CameraX 的设计哲学是“声明式”的，你通过构建器 Preview.Builder, ImageCapture.Builder 等来声明你想要什么，而不是去操作底层的 CaptureRequest。

基础设置

// 1. 定义UseCase
val preview = Preview.Builder().build()
val imageCapture = ImageCapture.Builder().build()
// 2. 绑定到生命周期
val cameraProviderFuture = ProcessCameraProvider.getInstance(context)
cameraProviderFuture.addListener({
    val cameraProvider = cameraProviderFuture.get()
    val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
    cameraProvider.unbindAll()
    cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview, imageCapture)
}, ContextCompat.getMainExecutor(context))
// 3. 将Preview连接到PreviewView
preview.setSurfaceProvider(previewView.surfaceProvider)

设置 ImageCapture 参数

ImageCapture.Builder 提供了链式调用来配置参数，这些参数最终会映射到底层的 Camera2 参数。

val imageCapture = ImageCapture.Builder()
    // 设置捕捉模式 (单张/HDR)
    .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY) // 或 CAPTURE_MODE_MAXIMIZE_QUALITY
    // 设置闪光灯模式
    .setFlashMode(ImageCapture.FLASH_MODE_AUTO) // FLASH_MODE_ON, FLASH_MODE_OFF, FLASH_MODE_SCREEN
    // 设置图像分析器 (可选)
    .setAnalyzer(Executors.newSingleThreadExecutor(), imageAnalyzer)
    // 设置拍照时的缩放比例
    .setZoomRatio(1.5f)
    // 设置目标旋转
    .setTargetRotation(previewView.display.rotation)
    // 设置拍照质量/分辨率
    .setTargetResolution(Size(4032, 3024)) // 设置目标尺寸，CameraX会自动选择最接近的
    .build()

动态修改参数 (对焦、曝光)

对于需要动态调整的参数（如点击对焦），CameraX 提供了 CameraControl。

// 从 Preview 或 ImageCapture 获取 CameraControl
val cameraControl = previewView.cameraControl
// 在 PreviewView 上点击时，进行对焦
previewView.setOnTouchListener { view, event ->
    if (event.action == MotionEvent.ACTION_UP) {
        val meteringPointFactory = PreviewViewMeteringPointFactory(view)
        val action = FocusMeteringAction.Builder(meteringPointFactory.createPoint(event.x, event.y)).build()
        // 执行对焦和测光操作
        cameraControl.startFocusAndMetering(action)
            .addListener({
                // 对焦成功
            }, ContextCompat.getMainExecutor(context))
    }
    true
}

CameraX 的 FocusMeteringAction 会自动帮你设置 CONTROL_AF_MODE, CONTROL_AF_REGIONS, CONTROL_AE_REGIONS 等复杂的 Camera2 参数，非常方便。

重要注意事项

1. 异步操作: Camera2 API 几乎所有核心操作都是异步的（打开相机、创建会话、捕获图像等），必须使用 CameraDevice.StateCallback, CameraCaptureSession.CaptureCallback 等回调来处理结果。
2. 生命周期管理: 必须正确管理相机的生命周期，在 Activity/Fragment 的 onResume 中打开相机，在 onPause 中关闭，CameraX 通过 bindToLifecycle 自动处理了这一点，极大简化了开发。
3. 线程: 相机操作必须在后台线程执行，但结果需要返回到主线程更新 UI，Camera2 需要手动处理线程切换，CameraX 则在内部封装好了。
4. 性能: 高分辨率预览、连续对焦、人脸检测等操作会消耗大量 CPU/GPU 资源，要注意性能优化，避免内存泄漏和 ANR。
5. 权限: 从 Android 6.0 (API 23) 开始，必须动态申请 CAMERA 和 WRITE_EXTERNAL_STORAGE (如果需要保存照片) 权限。

对于新项目,强烈推荐使用 CameraX，它能让你专注于业务逻辑而不是复杂的相机细节，如果你需要 CameraX 没有提供的某些特殊功能，你仍然可以通过 Camera2Extender 来访问底层的 Camera2 API。