2nd/10_Wiki/Topic_Programming/Coding/Android_CameraX_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
android-camerax-patterns	Android CameraX — 카메라 / 이미지 분석	Coding	draft	B	conceptual	2026-05-09	2026-05-09	android camera camerax vibe-coding	language applicable_to Kotlin / CameraX 1.4+ Android		Camera2 ImageCapture ImageAnalysis Preview lifecycle camera

Android CameraX

Camera2 의 lifecycle-aware wrapper. Preview / ImageCapture / ImageAnalysis / VideoCapture 4종 use case. 디바이스 호환성 자동 처리.

📖 핵심 개념

• ProcessCameraProvider: 부팅.
• UseCase: Preview / ImageCapture / ImageAnalysis / VideoCapture.
• bindToLifecycle: lifecycle 에 묶어 자동 시작/정지.

💻 코드 패턴

의존성

implementation("androidx.camera:camera-core:1.4.0")
implementation("androidx.camera:camera-camera2:1.4.0")
implementation("androidx.camera:camera-lifecycle:1.4.0")
implementation("androidx.camera:camera-view:1.4.0")

Preview + Capture (Compose)

@Composable
fun CameraScreen() {
    val ctx = LocalContext.current
    val lifecycleOwner = LocalLifecycleOwner.current
    val previewView = remember { PreviewView(ctx) }
    var imageCapture by remember { mutableStateOf<ImageCapture?>(null) }

    LaunchedEffect(Unit) {
        val provider = ProcessCameraProvider.getInstance(ctx).get()

        val preview = Preview.Builder().build().also {
            it.setSurfaceProvider(previewView.surfaceProvider)
        }
        val capture = ImageCapture.Builder()
            .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
            .build()
        imageCapture = capture

        try {
            provider.unbindAll()
            provider.bindToLifecycle(
                lifecycleOwner,
                CameraSelector.DEFAULT_BACK_CAMERA,
                preview, capture
            )
        } catch (e: Exception) { log.error("camera bind failed", e) }
    }

    Box {
        AndroidView(factory = { previewView })
        Button(onClick = { imageCapture?.takePictureToDisk(ctx) }) { Text("촬영") }
    }
}

fun ImageCapture.takePictureToDisk(ctx: Context) {
    val file = File(ctx.cacheDir, "shot_${System.currentTimeMillis()}.jpg")
    val output = ImageCapture.OutputFileOptions.Builder(file).build()
    takePicture(output, ContextCompat.getMainExecutor(ctx),
        object : ImageCapture.OnImageSavedCallback {
            override fun onImageSaved(o: ImageCapture.OutputFileResults) { /* file ready */ }
            override fun onError(e: ImageCaptureException) { log.error("capture failed", e) }
        })
}

ImageAnalysis — ML / barcode

val analyzer = ImageAnalysis.Builder()
    .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
    .build()
    .also {
        it.setAnalyzer(Executors.newSingleThreadExecutor()) { imageProxy ->
            val mediaImage = imageProxy.image ?: return@setAnalyzer
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            barcodeScanner.process(image)
                .addOnSuccessListener { codes -> codes.forEach { onScan(it.rawValue) } }
                .addOnCompleteListener { imageProxy.close() } // 반드시 close
        }
    }

provider.bindToLifecycle(lifecycleOwner, CameraSelector.DEFAULT_BACK_CAMERA, preview, analyzer)

Permission

val permission = rememberPermissionState(Manifest.permission.CAMERA)
LaunchedEffect(Unit) { permission.launchPermissionRequest() }
if (!permission.status.isGranted) return // PermissionRationale UI

Video capture

val recorder = Recorder.Builder()
    .setQualitySelector(QualitySelector.from(Quality.HD))
    .build()
val videoCapture = VideoCapture.withOutput(recorder)
provider.bindToLifecycle(lifecycleOwner, selector, preview, videoCapture)

val output = MediaStoreOutputOptions.Builder(...).build()
recording = videoCapture.output.prepareRecording(ctx, output)
    .start(ContextCompat.getMainExecutor(ctx)) { event -> ... }
// 종료
recording?.stop()

🤔 의사결정 기준

사용	UseCase 조합
단순 사진	Preview + ImageCapture
QR / barcode 스캔	Preview + ImageAnalysis
ML 분석 (얼굴, OCR)	Preview + ImageAnalysis
비디오 녹화	Preview + VideoCapture
사진 + 비디오 동시	Preview + ImageCapture + VideoCapture (제한 있음)

❌ 안티패턴

• imageProxy.close() 누락: backpressure → analyzer 멈춤.
• lifecycle 안 묶음: 백그라운드에서 카메라 점유 → 배터리.
• 메인 스레드에서 ML 처리: UI 멈춤. 별도 executor.
• 여러 use case 가 디바이스 한계 초과: bind 실패. 한 번에 적게.
• Preview rotation 안 처리: 회전 시 이상.
• 권한 거부 후 silent: 가이드 UI.

🤖 LLM 활용 힌트

• CameraX + lifecycle bind + 단일 executor analyzer 패턴 표준.
• ML Kit 결합 자주.

🔗 관련 문서

• Android_Lifecycle_Aware_Components
• iOS_Background_Tasks