CameraX: ما هو، API CameraX وكيف تعمل الكاميرا

ما هو CameraX؟

CameraX هي مكتبة من مجموعة Android Jetpack، أطلقتها Google لأول مرة في 2019 كبديل لـ Camera API القديمة وكبديل مبسط لـ Camera2 المعقدة. الفلسفة الأساسية لـ CameraX هي «اكتب مرة واحدة، يعمل على جميع الأجهزة». تتعامل المكتبة تلقائياً مع اختلافات الأجهزة: موقع الكاميرات، الدقة المدعومة، اتجاه المستشعر والتنسيقات المتاحة — لا يحتاج المطور إلى كتابة كود خاص بالجهاز.

هندسة CameraX مبنية على حالات الاستخدام: Preview (عرض بث الكاميرا في Viewfinder)، ImageCapture (التقاط الصور)، ImageAnalysis (تحليل تدفق الإطارات للتعلم الآلي) و VideoCapture (تسجيل الفيديو). كل حالة استخدام هي مكون مستقل يمكن دمجه: تشغيل Preview للعثرة و ImageAnalysis لمعالجة التعلم الآلي في وقت واحد. وفقاً لـ Google (2026)، CameraX مدعومة على 99% من أجهزة Android مع API 21+.

الميزات الرئيسية

CameraX توفر التبديل التلقائي بين الكاميرا الأمامية والخلفية، ودعم دوران الشاشة دون إعادة إنشاء الجلسة، ومعالجة مدمجة لدورة الحياة عبر LifecycleOwner، وربط حالات الاستخدام بعملية Lifecycle واحدة، ودعم إضافات Camera2 للوضع الرأسي و HDR والوضع الليلي، و TestableCameraX لاختبار الوحدة دون جهاز حقيقي.

حالات استخدام CameraX

CameraX تُحدد أربع حالات استخدام قياسية، كل منها يحل مهمة محددة للكاميرا. يمكن دمج حالات الاستخدام: أشهر المجموعات هي Preview + ImageCapture لتطبيق الكاميرا و Preview + ImageAnalysis لماسح التعلم الآلي.

Preview

حالة استخدام Preview تعرض بث الفيديو من الكاميرا في PreviewView — عرض خاص من مكتبة CameraX. يتكيف PreviewView تلقائياً مع نسبة أبعاد الكاميرا، ويدعم ScaleType (FillCenter, FitCenter) ودوران الشاشة دون إعادة إنشاء حالة الاستخدام. يحتاج المطور فقط إلى ربط Preview بدورة الحياة عبر ProcessCameraProvider.

ImageAnalysis

حالة استخدام ImageAnalysis تُرسل كل إطار من الكاميرا إلى معالج للتحليل: التعرف على النص، اكتشاف الوجوه، مسح رموز QR. يستقبل المحلل الإطارات بتنسيق YUV_420_888 — مساحة الألوان العالمية في Android. وضع التشغيل (BLOCKING أو NON_BLOCKING) يتحكم في قائمة الإطارات: BLOCKING ينتظر اكتمال التحليل السابق، NON_BLOCKING يتخطى الإطارات أثناء التأخير.

ImageCapture

حالة استخدام ImageCapture تلتقط صوراً من الكاميرا مع إعدادات الفلاش والدقة والضغط. التنسيقات المدعومة هي JPEG و RAW (على الأجهزة المتوافقة). يحفظ ImageCapture اللقطة بشكل غير متزامن عبر OnImageCapturedCallback أو مباشرة إلى ملف عبر ImageCapture.OutputFileOptions.

VideoCapture — تسجيل الفيديو

حالة استخدام VideoCapture أُضيفت في CameraX 1.1.0 (beta) وتسمح بتسجيل الفيديو بدقة تصل إلى 4K بمعدل 30 إطاراً في الثانية. تتزامن حالة الاستخدام تلقائياً مع Preview: الصورة في العثرة تطابق ما يتم تسجيله في الملف. يستخدم VideoCapture MediaCodec و MediaMuxer داخلياً، مخفياً تعقيد إعداد برنامج ترميز الفيديو وحاوية MP4.

CameraX مقابل Camera2

CameraX و Camera2 هما نهجان للعمل مع الكاميرا في Android. Camera2 هي واجهة برمجة تطبيقات منخفضة المستوى تمنح تحكماً كاملاً في الجهاز. CameraX هي تجريد عالي المستوى يؤتمت السيناريوهات النموذجية. الاختيار بينهما يعتمد على متطلبات المشروع.

استخدم CameraX للمهام القياسية: كاميرا داخل التطبيق، ماسح QR، معالجة تدفق التعلم الآلي. استخدم Camera2 عندما يكون التحكم اليدوي في التعريض، التصوير RAW مع تحكم كامل بالمعايير، أو العمل بعدة كاميرات في وقت واحد مطلوباً.

أمثلة كود بلغة Kotlin

لنراجع إعداداً كاملاً لـ CameraX في تطبيق Android باستخدام حالات الاستخدام الرئيسية الثلاث: Preview و ImageCapture و ImageAnalysis.

إعداد ProcessCameraProvider

الكود يربط CameraX بدورة حياة النشاط عبر ProcessCameraProvider. أولاً يتم طلب مثيل للمزود، ثم يتم إنشاء حالات الاستخدام وتنفيذ الربط.

val cameraProviderFuture =
    ProcessCameraProvider.getInstance(this)

cameraProviderFuture.addListener({
    val cameraProvider = cameraProviderFuture.get()

    // إنشاء Preview
    val preview = Preview.Builder()
        .build()
        .also {
            it.setSurfaceProvider(
                binding.viewFinder.surfaceProvider
            )
        }

    // إنشاء ImageCapture
    val imageCapture = ImageCapture.Builder()
        .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
        .build()

    // الربط بدورة الحياة
    cameraProvider.unbindAll()
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}, ContextCompact.getMainExecutor(this))

كود Kotlin يحصل على ProcessCameraProvider عبر future، وينشئ حالتي استخدام Preview و ImageCapture، ويربطهما بدورة حياة النشاط الحالي. تتعامل CameraX تلقائياً مع دوران الشاشة وتبديل الكاميرا وتحرير الموارد عند إغلاق النشاط.

ImageAnalysis لمعالجة التعلم الآلي

لنضف حالة استخدام ImageAnalysis لمعالجة كل إطار من تدفق الكاميرا، مثلاً للتكامل مع ML Kit.

val imageAnalysis = ImageAnalysis.Builder()
    .setBackpressureStrategy(
        ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
    )
    .build()

imageAnalysis.setAnalyzer(
    ContextCompact.getMainExecutor(this)
) { imageProxy ->
    // تحويل YUV إلى Bitmap لـ ML Kit
    val bitmap = ImageUtils.yuvToBitmap(imageProxy)
    val inputImage = InputImage.fromBitmap(bitmap)

    // بدء التعرف على النص في ML Kit
    recognizer.process(inputImage)
        .addOnSuccessListener { result ->
            // معالجة النتيجة
            processTextResult(result)
        }
        .addOnCompleteListener {
            imageProxy.close()
        }
}

ImageAnalysis باستخدام استراتيجية KEEP_ONLY_LATEST يعالج فقط آخر إطار متاح، متجاوزاً الإطارات القديمة إذا كان المحلل لا يواكب. كل إطار يُحول من YUV إلى Bitmap لـ ML Kit، وبعد ذلك يبدأ التعرف على النص. استدعاء imageProxy.close() إلزامي — وإلا ستتوقف CameraX عن تسليم إطارات جديدة.

إضافات CameraX

إضافات CameraX هي وحدة تُضيف أوضاع تصوير متقدمة: الوضع الرأسي (طمس الخلفية)، HDR (نطاق ديناميكي موسع)، الوضع الليلي (تصوير في الإضاءة المنخفضة)، التعديل التلقائي (تصحيح البشرة) ووضع التجميل. تُفعّل الإضافات فقط على الأجهزة حيث قدمت الشركة المصنعة للكاميرا تنفيذ OEM.

التحقق من الإضافات وتفعيلها

قبل استخدام إضافات CameraX، يجب التحقق مما إذا كانت الإضافة متوفرة على الجهاز الحالي. توصي Google بالتحقق عبر ExtensionsManager.isExtensionAvailable.

val extensionsManager =
    ExtensionsManager.getInstance(this)

if (extensionsManager.isExtensionAvailable(
    cameraProvider,
    CameraSelector.DEFAULT_BACK_CAMERA,
    ExtensionMode.BOKEH
)) {
    // تفعيل الوضع الرأسي
    cameraProvider.bindToLifecycle(
        this,
        CameraSelector.DEFAULT_BACK_CAMERA,
        preview,
        imageCapture
    )
}

الكود يتحقق من دعم إضافة BOKEH (الوضع الرأسي) عبر ExtensionsManager ويُفعّلها إذا كان تنفيذ OEM متاحاً. تقوم CameraX تلقائياً بتبديل إعدادات الكاميرا للوضع الرأسي. إذا كانت الإضافة غير متوفرة، يستمر التطبيق في العمل بالوضع القياسي دون تعطل.

إضافات CameraX تحل واحدة من أهم مشكلات تطوير Android: تجزئة الكاميرات. على الأجهزة المختلفة، يُنفّذ الوضع الرأسي بطرق مختلفة — بعضها يستخدم عدستين، والبعض الآخر يستخدم طمساً برمجياً. CameraX تجرد هذا الاختلاف: المطور يُفعّل وضع BOKEH، والمكتبة نفسها تحدد كيفية تنفيذه على جهاز معين. تحتفظ Google بقائمة شركاء OEM موثوقين: Samsung, Xiaomi, OPPO, vivo, Google Pixel.

عند العمل مع CameraX، من المهم مراعاة القيود على عدد حالات الاستخدام المتزامنة: على معظم الأجهزة، يمكن تشغيل 3 حالات استخدام كحد أقصى في وقت واحد. على سبيل المثال، Preview + ImageCapture + ImageAnalysis تعمل على جميع الأجهزة الحديثة، لكن Preview + ImageCapture + VideoCapture قد لا تكون مدعومة على الموديلات الاقتصادية. توفر CameraX طريقة ProcessCameraProvider.checkAvailability() التي تتحقق من توافق مجموعة حالات الاستخدام قبل الربط، مما يساعد على تجنب الأعطال في وقت التشغيل.

تتكامل CameraX مع Jetpack Navigation عبر CameraXFragment أو PreviewView المتوافق مع Compose. بالنسبة لـ Compose، يُستخدم عنصر AndroidView الذي يُدمج فيه PreviewView. تتعامل CameraX بشكل صحيح مع دوران الشاشة وتغييرات التكوين دون فقدان حالة جلسة الكاميرا — فقط حدد LifecycleOwner، وستقوم المكتبة تلقائياً بإعادة إنشاء روابط حالات الاستخدام عند دوران الجهاز.

لاختبار CameraX بدون جهاز حقيقي، توفر Google TestableCameraX — مكتبة تحاكي سلوك الكاميرا في اختبارات الوحدة. تسمح TestableCameraX بمحاكاة إطارات الكاميرا واختبار عمل ImageAnalysis وصحة ImageCapture بدون جهاز مادي. هذا يُسرّع بشكل كبير خط أنابيب CI/CD للمشاريع التي تعمل مع الكاميرا.