واجهة برمجة تطبيقات كاميرات متعددة

ملاحظة: تشير هذه الصفحة إلى حزمة Camera2. ننصحك باستخدام CameraX، ما لم يتطلّب تطبيقك ميزات محدّدة منخفضة المستوى من Camera2. تتوافق كل من CameraX وCamera2 مع الإصدار 5.0 من نظام التشغيل Android (المستوى 21 من واجهة برمجة التطبيقات) والإصدارات الأحدث.

تم طرح ميزة "الكاميرات المتعدّدة" في الإصدار Android 9 (المستوى 28 من واجهة برمجة التطبيقات). منذ إطلاقها، تم طرح أجهزة في السوق متوافقة مع واجهة برمجة التطبيقات. ترتبط العديد من حالات استخدام الكاميرات المتعدّدة ارتباطًا وثيقًا بإعدادات أجهزة معيّنة. بعبارة أخرى، لا تتوافق جميع حالات الاستخدام مع كل جهاز،  ما يجعل ميزات الكاميرات المتعددة مرشّحًا جيدًا لـ عرض الميزات في Play.

تشمل بعض حالات الاستخدام النموذجية ما يلي:

  • التكبير/التصغير: التبديل بين الكاميرات حسب منطقة الاقتصاص أو البُعد البؤري الذي تم اختياره
  • العمق: استخدام كاميرات متعدّدة لإنشاء خريطة عمق
  • الخلفية الضبابية: استخدام معلومات العمق المستنتَجة لمحاكاة نطاق تركيز ضيق يشبه نطاق التركيز في كاميرات DSLR

الفرق بين الكاميرات المنطقية والكاميرات المادية

يتطلب فهم واجهة برمجة التطبيقات للكاميرات المتعددة فهم الفرق بين الكاميرات المنطقية والكاميرات المادية. كمرجع، لنفترض أنّ لدينا جهازًا مزوّدًا بثلاث كاميرات خلفية. في هذا المثال، تُعدّ كل كاميرا من الكاميرات الخلفية الثلاث كاميرا مادية. أما الكاميرا المنطقية، فهي مجموعة من كاميرتين أو أكثر من تلك الكاميرات المادية. يمكن أن يكون ناتج الكاميرا المنطقية عبارة عن بث يأتي من إحدى الكاميرات المادية الأساسية، أو بث مدمج يأتي من أكثر من كاميرا مادية أساسية في الوقت نفسه. وفي كلتا الحالتين، تتم معالجة البث من خلال طبقة تجريد الأجهزة (HAL) للكاميرا.

تطوّر العديد من الشركات المصنّعة للهواتف تطبيقات كاميرا تابعة لها، وعادةً ما تكون مثبّتة مسبقًا على أجهزتها. ولاستخدام جميع إمكانات الأجهزة، قد تستخدم واجهات برمجة تطبيقات خاصة أو مخفية أو تتلقّى معاملة خاصة من تنفيذ برنامج التشغيل لا يمكن للتطبيقات الأخرى الوصول إليها. تنفّذ بعض الأجهزة مفهوم الكاميرات المنطقية من خلال توفير بث مدمج من الإطارات من الكاميرات المادية المختلفة، ولكن فقط لبعض التطبيقات المميّزة. غالبًا ما يتم عرض كاميرا واحدة فقط من الكاميرات المادية لإطار العمل. يوضّح المخطّط البياني التالي الوضع بالنسبة إلى المطوّرين الخارجيين قبل الإصدار 9 من Android:

إمكانات الكاميرا التي لا تتوفّر عادةً إلا للتطبيقات المميّزة
الشكل 1: إمكانات الكاميرا التي لا تتوفّر عادةً إلا للتطبيقات المميّزة

اعتبارًا من الإصدار Android 9، لم يعُد مسموحًا باستخدام واجهات برمجة التطبيقات الخاصة في تطبيقات Android. مع تضمين ميزة دعم الكاميرات المتعددة في إطار العمل، تنصح أفضل ممارسات Android بشدة بأن توفّر الشركات المصنّعة للهواتف كاميرا منطقية لجميع الكاميرات المادية التي تواجه الاتجاه نفسه. في ما يلي ما يجب أن يتوقّع مطوّرو التطبيقات التابعة لجهات خارجية رؤيته على الأجهزة التي تعمل بنظام التشغيل Android 9 والإصدارات الأحدث:

إمكانية وصول المطوّرين الكاملة إلى جميع أجهزة الكاميرا بدءًا من الإصدار Android 9
الشكل 2: إمكانية وصول المطوّرين الكاملة إلى جميع أجهزة الكاميرا بدءًا من الإصدار Android 9

يعتمد ما توفّره الكاميرا المنطقية كليًا على تنفيذ المصنّع الأصلي للجهاز لطبقة تجريد الأجهزة (HAL) للكاميرا. على سبيل المثال، يطبّق جهاز مثل Pixel 3 الكاميرا المنطقية بطريقة تختار إحدى الكاميرات المادية بناءً على البُعد البؤري المطلوب ومنطقة الاقتصاص.

واجهة برمجة التطبيقات للكاميرات المتعددة

تضيف واجهة برمجة التطبيقات الجديدة الثوابت والفئات والطرق الجديدة التالية:

بسبب التغييرات التي طرأت على مستند تعريف معايير التوافق (CDD) في Android، فإنّ واجهة برمجة التطبيقات للكاميرات المتعددة تأتي أيضًا مع توقعات معيّنة من المطوّرين. كانت الأجهزة المزوّدة بكاميرات مزدوجة متوفّرة قبل إصدار Android 9، ولكن فتح أكثر من كاميرا واحدة في الوقت نفسه كان يتطلّب التجربة والخطأ. في الإصدار Android 9 والإصدارات الأحدث، توفّر ميزة "الكاميرات المتعددة" مجموعة من القواعد لتحديد الحالات التي يمكن فيها فتح زوج من الكاميرات المادية التي تشكّل جزءًا من الكاميرا المنطقية نفسها.

في معظم الحالات، تعرض الأجهزة التي تعمل بنظام التشغيل Android 9 والإصدارات الأحدث جميع الكاميرات المادية (باستثناء أنواع أدوات الاستشعار الأقل شيوعًا مثل الأشعة تحت الحمراء) بالإضافة إلى كاميرا منطقية أسهل في الاستخدام. بالنسبة إلى كل مجموعة من أحداث البث التي من المضمون أن تعمل، يمكن استبدال بث واحد ينتمي إلى كاميرا منطقية بحدثَي بث من الكاميرات الفعلية الأساسية.

أحداث بث متعددة في الوقت نفسه

يتناول القسم استخدام عدة عمليات بث كاميرا في الوقت نفسه قواعد استخدام عدة عمليات بث في الوقت نفسه في كاميرا واحدة. مع إضافة واحدة ملحوظة، تنطبق نفس القواعد على الكاميرات المتعددة. CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA توضّح كيفية استبدال بث منطقي YUV_420_888 أو بث أولي ببثين فعليين. وهذا يعني أنّه يمكن استبدال كل بث من النوع YUV أو RAW ببثَّين من النوع والحجم نفسهما. يمكنك البدء ببث كاميرا بالإعدادات المضمونة التالية للأجهزة ذات الكاميرا الواحدة:

  • البث 1: نوع YUV، حجم MAXIMUM من الكاميرا المنطقية id = 0

بعد ذلك، يتيح لك جهاز يتضمّن ميزة "دعم الكاميرات المتعددة" إنشاء جلسة لاستبدال بث YUV المنطقي ببثَّين فعليَّين:

  • البث 1: نوع YUV، حجم MAXIMUM من الكاميرا الفعلية id = 1
  • البث 2: نوع YUV، حجم MAXIMUM من الكاميرا الفعلية id = 2

يمكنك استبدال بث YUV أو RAW ببثَّين مكافئَين إذا كانت هاتان الكاميرتان جزءًا من مجموعة كاميرات منطقية،  والمُدرَجة ضمن CameraCharacteristics.getPhysicalCameraIds().

إنّ الضمانات التي يوفّرها إطار العمل هي الحد الأدنى المطلوب للحصول على لقطات من أكثر من كاميرا فعلية في الوقت نفسه. تتوفّر عمليات بث إضافية في معظم الأجهزة، ما يسمح أحيانًا بفتح عدة أجهزة كاميرا مادية بشكل مستقل. بما أنّ إطار العمل لا يضمن ذلك، يتطلّب الأمر إجراء اختبارات وضبط لكل جهاز على حدة من خلال التجربة والخطأ.

إنشاء جلسة باستخدام عدة كاميرات فعلية

عند استخدام كاميرات فعلية على جهاز مزوّد بكاميرات متعدّدة، افتح كاميرا واحدة CameraDevice (الكاميرا المنطقية) وتفاعَل معها في جلسة واحدة. أنشئ الجلسة الواحدة باستخدام واجهة برمجة التطبيقات CameraDevice.createCaptureSession(SessionConfiguration config) التي تمت إضافتها في المستوى 28 من واجهة برمجة التطبيقات. تحتوي إعدادات الجلسة على عدد من إعدادات الإخراج، ولكل منها مجموعة من أهداف الإخراج، ويمكن اختياريًا تحديد معرّف الكاميرا المادية.

نموذج SessionConfiguration وOutputConfiguration
الشكل 3: نموذج SessionConfiguration وOutputConfiguration

تتضمّن طلبات الالتقاط هدفًا مرتبطًا بها. يحدّد إطار العمل الكاميرا المادية (أو المنطقية) التي يتم إرسال الطلبات إليها استنادًا إلى هدف الإخراج المرفق. إذا كان هدف الإخراج يتوافق مع أحد أهداف الإخراج التي تم إرسالها كإعدادات إخراج مع معرّف كاميرا مادية، تتلقّى هذه الكاميرا المادية الطلب وتعالجه.

استخدام كاميرتَين فعليتَين

من الإضافات الأخرى إلى واجهات برمجة التطبيقات الخاصة بالكاميرا المتعددة هي إمكانية تحديد الكاميرات المنطقية والعثور على الكاميرات المادية التي تقف وراءها. يمكنك تحديد دالة للمساعدة في تحديد الأزواج المحتملة من الكاميرات المادية التي يمكنك استخدامها لاستبدال أحد بث الكاميرا المنطقية:

/**
 * Helper class used to encapsulate a logical camera and two underlying
 * physical cameras
 */
data class DualCamera(val logicalId: String, val physicalId1: String, val physicalId2: String)

fun findDualCameras(manager: CameraManager, facing: Int? = null): List<DualCamera> {
    val dualCameras = mutableListOf<DualCamera>()

    // Iterate over all the available camera characteristics.
    manager.cameraIdList.map {
        Pair(manager.getCameraCharacteristics(it), it)
    }.filter {
        // Filter by cameras facing the requested direction.
        facing == null || it.first.get(CameraCharacteristics.LENS_FACING) == facing
    }.filter {
        // Filter by logical cameras.
        // CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA requires API >= 28.
        it.first.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)?.contains(
            CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
        ) ?: false
    }.forEach {
        // All possible pairs from the list of physical cameras are valid results.
        // NOTE: There could be N physical cameras as part of a logical camera grouping.
        // getPhysicalCameraIds() requires API >= 28.
        val physicalCameras = it.first.physicalCameraIds.toTypedArray()
        for (idx1 in 0 until physicalCameras.size) {
            for (idx2 in (idx1 + 1) until physicalCameras.size) {
                dualCameras.add(
                    DualCamera(
                        it.second, physicalCameras[idx1], physicalCameras[idx2]
                    )
                )
            }
        }
    }

    return dualCameras
}

وتتحكّم الكاميرا المنطقية في معالجة حالة الكاميرات المادية. لفتح "كاميرا مزدوجة"، افتح الكاميرا المنطقية المقابلة للكاميرات الفعلية:

fun openDualCamera(
    cameraManager: CameraManager,
    dualCamera: DualCamera,
    executor: Executor,
    callback: (CameraDevice) -> Unit
) {

    // openCamera() requires API >= 28.
    cameraManager.openCamera(
        dualCamera.logicalId, executor,
        object : CameraDevice.StateCallback() {
            override fun onOpened(device: CameraDevice) = callback(device)
            // Omitting for brevity...
            override fun onError(device: CameraDevice, error: Int) = onDisconnected(device)
            override fun onDisconnected(device: CameraDevice) = device.close()
        }
    )
}

بالإضافة إلى اختيار الكاميرا التي تريد فتحها، فإن العملية هي نفسها فتح الكاميرا في إصدارات Android السابقة. يؤدي إنشاء جلسة التقاط باستخدام واجهة برمجة التطبيقات الجديدة لإعداد الجلسات إلى توجيه إطار العمل لربط أهداف معيّنة بمعرّفات كاميرات مادية محدّدة:

/**
 * Helper type definition that encapsulates 3 sets of output targets:
 *
 * 1. Logical camera
 * 2. First physical camera
 * 3. Second physical camera
 */
typealias DualCameraOutputs =
    Triple<MutableList<Surface>?, MutableList<Surface>?, MutableList<Surface>?>

fun createDualCameraSession(
    cameraManager: CameraManager,
    dualCamera: DualCamera,
    targets: DualCameraOutputs,
    executor: Executor,
    callback: (CameraCaptureSession) -> Unit
) {

    // Create 3 sets of output configurations: one for the logical camera, and
    // one for each of the physical cameras.
    val outputConfigsLogical = targets.first?.map { OutputConfiguration(it) }
    val outputConfigsPhysical1 = targets.second?.map {
        OutputConfiguration(it).apply { setPhysicalCameraId(dualCamera.physicalId1) }
    }
    val outputConfigsPhysical2 = targets.third?.map {
        OutputConfiguration(it).apply { setPhysicalCameraId(dualCamera.physicalId2) }
    }

    // Put all the output configurations into a single flat array.
    val outputConfigsAll = arrayOf(
        outputConfigsLogical, outputConfigsPhysical1, outputConfigsPhysical2
    )
        .filterNotNull().flatMap { it }

    // Instantiate a session configuration that can be used to create a session.
    val sessionConfiguration = SessionConfiguration(
        SessionConfiguration.SESSION_REGULAR,
        outputConfigsAll, executor,
        object : CameraCaptureSession.StateCallback() {
            override fun onConfigured(session: CameraCaptureSession) = callback(session)
            // Omitting for brevity...
            override fun onConfigureFailed(session: CameraCaptureSession) = session.device.close()
        }
    )

    // Open the logical camera using the previously defined function.
    openDualCamera(cameraManager, dualCamera, executor = executor) {

        // Finally create the session and return using the callback.
        it.createCaptureSession(sessionConfiguration)
    }
}

يمكنك الاطّلاع على createCaptureSession للحصول على معلومات حول مجموعات مصادر البيانات المتوافقة. يتم دمج أحداث البث لأحداث بث متعددة على كاميرا منطقية واحدة. يمتد التوافق إلى استخدام الإعدادات نفسها واستبدال أحد هذه التدفقات بتدفقين من كاميرتين فعليتين تشكّلان جزءًا من الكاميرا المنطقية نفسها.

بعد تجهيز جلسة الكاميرا، أرسِل طلبات الالتقاط التي اخترتها. يتلقّى كل هدف من طلب الالتقاط بياناته من الكاميرا المادية المرتبطة به، في حال استخدام أي منها، أو يعود إلى الكاميرا المنطقية.

مثال على حالة استخدام Zoom

يمكن دمج الكاميرات المادية في بث واحد لكي يتمكّن المستخدمون من التبديل بين الكاميرات المادية المختلفة لتجربة مجال رؤية مختلف، ما يتيح التقاط "مستوى تكبير" مختلف بشكل فعّال.

مثال على تبديل الكاميرات لحالة استخدام مستوى التكبير
الشكل 4: مثال على تبديل الكاميرات لحالة استخدام مستوى التكبير (من إعلان Pixel 3)

ابدأ باختيار زوج من الكاميرات المادية للسماح للمستخدمين بالتبديل بينهما. للحصول على أقصى تأثير، يمكنك اختيار زوج الكاميرات الذي يوفّر الحد الأدنى والحد الأقصى للبعد البؤري المتاح.

fun findShortLongCameraPair(manager: CameraManager, facing: Int? = null): DualCamera? {

    return findDualCameras(manager, facing).map {
        val characteristics1 = manager.getCameraCharacteristics(it.physicalId1)
        val characteristics2 = manager.getCameraCharacteristics(it.physicalId2)

        // Query the focal lengths advertised by each physical camera.
        val focalLengths1 = characteristics1.get(
            CameraCharacteristics.LENS_INFO_AVAILABLE_FOCAL_LENGTHS
        ) ?: floatArrayOf(0F)
        val focalLengths2 = characteristics2.get(
            CameraCharacteristics.LENS_INFO_AVAILABLE_FOCAL_LENGTHS
        ) ?: floatArrayOf(0F)

        // Compute the largest difference between min and max focal lengths between cameras.
        val focalLengthsDiff1 = (focalLengths2.maxOrNull() ?: 0f) - (focalLengths1.minOrNull() ?: 0f)
        val focalLengthsDiff2 = (focalLengths1.maxOrNull() ?: 0f) - (focalLengths2.minOrNull() ?: 0f)

        // Return the pair of camera IDs and the difference between min and max focal lengths.
        if (focalLengthsDiff1 < focalLengthsDiff2) {
            Pair(DualCamera(it.logicalId, it.physicalId1, it.physicalId2), focalLengthsDiff1)
        } else {
            Pair(DualCamera(it.logicalId, it.physicalId2, it.physicalId1), focalLengthsDiff2)
        }

        // Return only the pair with the largest difference, or null if no pairs are found.
    }.maxByOrNull { it.second }?.first
}

من المنطقي في هذه الحالة استخدام SurfaceViews، واحد لكل مصدر بيانات. يتم تبديل SurfaceViews هذه استنادًا إلى تفاعل المستخدم بحيث يظهر واحد فقط في أي وقت.

يوضّح الرمز التالي كيفية فتح الكاميرا المنطقية وضبط مخرجاتها وإنشاء جلسة كاميرا وبدء بثَّي معاينة:

val cameraManager: CameraManager = ...
val cameraExecutor: Executor = ...  // owned by your activity / fragment

// Get the two output targets from the activity / fragment.
val surface1 = ...  // from SurfaceView
val surface2 = ...  // from SurfaceView

val dualCamera = findShortLongCameraPair(cameraManager) ?: return
val outputTargets = DualCameraOutputs(
    null, mutableListOf(surface1), mutableListOf(surface2)
)

// Here you open the logical camera, configure the outputs and create a session.
createDualCameraSession(
    cameraManager, dualCamera, targets = outputTargets, executor = cameraExecutor
) { session ->

    // Create a single request which has one target for each physical camera.
    // NOTE: Each target receive frames from only its associated physical camera.
    val requestTemplate = CameraDevice.TEMPLATE_PREVIEW
    val captureRequest = session.device.createCaptureRequest(requestTemplate).apply {
        arrayOf(surface1, surface2).forEach { addTarget(it) }
    }.build()

    // Set the sticky request for the session and you are done.
    session.setRepeatingRequest(captureRequest, null, null)
}

كل ما عليك فعله هو توفير واجهة مستخدم تتيح للمستخدم التبديل بين السطحَين، مثل زر أو النقر مرّتين على SurfaceView. يمكنك أيضًا إجراء شكل من أشكال تحليل المشهد والتبديل بين البثَّين تلقائيًا.

تشويه العدسة

تُنتج جميع العدسات قدرًا معينًا من التشويه. في Android، يمكنك الاستعلام عن التشويه الذي تسببه العدسات باستخدام CameraCharacteristics.LENS_DISTORTION، الذي يحل محل CameraCharacteristics.LENS_RADIAL_DISTORTION الذي تم إيقافه نهائيًا. بالنسبة إلى الكاميرات المنطقية، يكون التشويش ضئيلاً ويمكن لتطبيقك استخدام اللقطات كما هي تقريبًا من الكاميرا. بالنسبة للكاميرات المادية، هناك إعدادات عدسة مختلفة جدًا، خاصة على العدسات العريضة.

قد تستخدم بعض الأجهزة ميزة "تصحيح التشوّه" التلقائي من خلال CaptureRequest.DISTORTION_CORRECTION_MODE. يتم تفعيل ميزة "تصحيح التشوّه" تلقائيًا في معظم الأجهزة.

val cameraSession: CameraCaptureSession = ...

// Use still capture template to build the capture request.
val captureRequest = cameraSession.device.createCaptureRequest(
    CameraDevice.TEMPLATE_STILL_CAPTURE
)

// Determine if this device supports distortion correction.
val characteristics: CameraCharacteristics = ...
val supportsDistortionCorrection = characteristics.get(
    CameraCharacteristics.DISTORTION_CORRECTION_AVAILABLE_MODES
)?.contains(
    CameraMetadata.DISTORTION_CORRECTION_MODE_HIGH_QUALITY
) ?: false

if (supportsDistortionCorrection) {
    captureRequest.set(
        CaptureRequest.DISTORTION_CORRECTION_MODE,
        CameraMetadata.DISTORTION_CORRECTION_MODE_HIGH_QUALITY
    )
}

// Add output target, set other capture request parameters...

// Dispatch the capture request.
cameraSession.capture(captureRequest.build(), ...)

يمكن أن يؤثر ضبط طلب التقاط في هذا الوضع على عدد اللقطات في الثانية التي يمكن أن تنتجها الكاميرا. يمكنك اختيار ضبط تصحيح التشوّه على التقاط الصور الثابتة فقط.