تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

بنية CameraX

تتناول هذه الصفحة بنية CameraX، بما في ذلك هيكلها، وكيفية التعامل مع واجهة برمجة التطبيقات، وكيفية التعامل مع مراحل النشاط، وكيفية دمج حالات الاستخدام.

بنية CameraX

يمكنك استخدام CameraX للتفاعل مع كاميرا الجهاز من خلال تجريد يُسمى حالة الاستخدام. تتوفّر حالات الاستخدام التالية:

Preview: تقبل مساحة عرض لمعاينة، مثل PreviewView.
تحليل الصور: يوفّر مخازن مؤقتة يمكن لوحدة المعالجة المركزية الوصول إليها لإجراء التحليل، مثل تحليل تعلُّم الآلة.
التقاط صورة: لالتقاط صورة وحفظها
التقاط الفيديو: التقاط الفيديو والصوت باستخدام VideoCapture

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

نموذج واجهة برمجة التطبيقات

للعمل مع المكتبة، عليك تحديد ما يلي:

حالة الاستخدام المطلوبة مع خيارات الضبط
ما يجب فعله ببيانات الإخراج من خلال إرفاق المستمعين.
التدفق المقصود، مثل وقت تفعيل الكاميرات ووقت إنتاج البيانات، من خلال ربط حالة الاستخدام بدورات حياة بنية Android.

هناك طريقتان لكتابة تطبيق CameraX: CameraController (رائعة إذا كنت تريد أبسط طريقة لاستخدام CameraX) أو CameraProvider (رائعة إذا كنت بحاجة إلى مزيد من المرونة).

CameraController

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

val previewView: PreviewView = viewBinding.previewView
var cameraController = LifecycleCameraController(baseContext)
cameraController.bindToLifecycle(this)
cameraController.cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
previewView.controller = cameraController

إنّ UseCase التلقائية لـ CameraController هي Preview وImageCapture وImageAnalysis. لإيقاف ImageCapture أو ImageAnalysis، أو لتفعيل VideoCapture، استخدِم طريقة setEnabledUseCases().

لمزيد من استخدامات CameraController، يُرجى الاطّلاع على نموذج الماسح الضوئي لرمز الاستجابة السريعة أو فيديو أساسيات CameraController.

CameraProvider

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

يمكنك ضبط حالات الاستخدام باستخدام إجراءات set() وإنهائها باستخدام الإجراء build(). يوفّر كل عنصر من عناصر حالات الاستخدام مجموعة من واجهات برمجة التطبيقات الخاصة بحالة الاستخدام. على سبيل المثال، توفّر حالة استخدام التقاط الصور طلب إجراء takePicture().

بدلاً من أن يضع التطبيق طلبات إجراءات بدء وإيقاف محدّدة في onResume() وonPause()، يحدّد التطبيق مراحل النشاط لربط الكاميرا بها، باستخدام cameraProvider.bindToLifecycle(). بعد ذلك، تُعلم دورة الحياة هذه CameraX بموعد ضبط جلسة التقاط الكاميرا وتضمن تغيير حالة الكاميرا بشكل مناسب لتتطابق مع انتقالات دورة الحياة.

للاطّلاع على خطوات التنفيذ لكل حالة استخدام، يُرجى مراجعة تنفيذ معاينة وتحليل الصور والتقاط الصور وتسجيل الفيديو

تتفاعل حالة استخدام المعاينة مع Surface للعرض. إنشاء حالة الاستخدام مع خيارات الضبط باستخدام الرمز التالي:

val preview = Preview.Builder().build()
val viewFinder: PreviewView = findViewById(R.id.previewView)

// The use case is bound to an Android Lifecycle with the following code.
val camera = cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview)

// PreviewView creates a surface provider and is the recommended provider.
preview.setSurfaceProvider(viewFinder.getSurfaceProvider())Architecture.kt

لمزيد من الأمثلة على الرموز البرمجية، يمكنك الاطّلاع على نموذج تطبيق CameraX الرسمي.

مراحل النشاط في CameraX

تراقب واجهة CameraX دورة حياة لتحديد وقت فتح الكاميرا ووقت إنشاء جلسة التقاط ووقت الإيقاف والإغلاق. توفّر واجهات برمجة التطبيقات لحالات الاستخدام طلبات إجراء وعمليات استدعاء لمراقبة مستوى التقدّم.

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

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

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

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

‫LifecycleOwners المخصّصة

في الحالات المتقدّمة، يمكنك إنشاء LifecycleOwner مخصّص للسماح لتطبيقك بالتحكّم صراحةً في مراحل نشاط جلسة CameraX بدلاً من ربطها بـ LifecycleOwner عادي في Android.

توضح عينة التعليمات البرمجية التالية كيفية إنشاء LifecycleOwner مخصص بسيط:

class CustomLifecycle : LifecycleOwner {
    private val lifecycleRegistry: LifecycleRegistry

    init {
        lifecycleRegistry = LifecycleRegistry(this)
        lifecycleRegistry.currentState = Lifecycle.State.CREATED
    }
    // ...
    fun doOnResume() {
        lifecycleRegistry.currentState = State.RESUMED
    }
    // ...
    override val lifecycle: Lifecycle
        get() = lifecycleRegistry
}Architecture.kt

باستخدام LifecycleOwner، يمكن لتطبيقك وضع عمليات انتقال الحالة في النقاط المطلوبة في الرمز البرمجي. لمزيد من المعلومات حول تنفيذ هذه الوظيفة في تطبيقك، يُرجى الاطّلاع على تنفيذ LifecycleOwner مخصّص.

حالات الاستخدام المتزامن

يمكن تشغيل حالات الاستخدام في الوقت نفسه. على الرغم من إمكانية ربط حالات الاستخدام بشكل تسلسلي بدورة حياة، من الأفضل ربط جميع حالات الاستخدام باستدعاء واحد لـ CameraProcessProvider.bindToLifecycle(). لمزيد من المعلومات حول أفضل الممارسات المتعلّقة بتغييرات الإعدادات، يُرجى الاطّلاع على مقالة التعامل مع تغييرات الإعدادات.

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

private lateinit var imageCapture: ImageCapture

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    val cameraProviderFuture = ProcessCameraProvider.getInstance(this)

    cameraProviderFuture.addListener(
        Runnable {
            // Camera provider is now guaranteed to be available.
            val cameraProvider = cameraProviderFuture.get()

            // Set up the preview use case to display camera preview.
            val preview = Preview.Builder().build()

            // Set up the capture use case to allow users to take photos.
            imageCapture = ImageCapture.Builder()
                .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
                .build()

            // Choose the camera by requiring a lens facing.
            val cameraSelector = CameraSelector.Builder()
                .requireLensFacing(CameraSelector.LENS_FACING_FRONT)
                .build()

            // Attach use cases to the camera with the same lifecycle owner.
            val camera = cameraProvider.bindToLifecycle(
                this as LifecycleOwner, cameraSelector, preview, imageCapture
            )

            // Connect the preview use case to the previewView.
            preview.setSurfaceProvider(
                previewView.getSurfaceProvider()
            )
        },
        ContextCompat.getMainExecutor(this)
    )
}Architecture.kt

تتيح مكتبة CameraX الاستخدام المتزامن لنسخة واحدة من كل من Preview وVideoCapture وImageAnalysis وImageCapture. بالإضافة إلى ذلك،

يمكن أن تعمل كل حالة استخدام بمفردها. على سبيل المثال، يمكن لأحد التطبيقات تسجيل فيديو بدون استخدام المعاينة.
عند تفعيل الإضافات، لا يمكن ضمان عمل سوى مجموعة ImageCapture وPreview. استنادًا إلى عملية التنفيذ التي يجريها المصنّع الأصلي للجهاز، قد لا يكون من الممكن أيضًا إضافة ImageAnalysis، ولا يمكن تفعيل الإضافات لحالة استخدام VideoCapture. يُرجى الاطّلاع على مستند مرجع الإضافة لمزيد من التفاصيل.
بناءً على إمكانات الكاميرا، قد تتيح بعض الكاميرات استخدام هذه المجموعة في أوضاع الدقة المنخفضة، ولكن لا يمكنها استخدام المجموعة نفسها في بعض أوضاع الدقة الأعلى.
على الأجهزة التي تتضمّن مستوى جهاز الكاميرا FULL أو أقل، قد يؤدي الجمع بين Preview وVideoCapture وImageCapture أو ImageAnalysis إلى فرض CameraX لتكرار بث PRIV للكاميرا لكل من Preview وVideoCapture. تتيح هذه العملية، التي تُعرف باسم "مشاركة البث"، استخدام هذه الميزات في الوقت نفسه، ولكنها تتطلب معالجة إضافية. وقد يؤدي ذلك إلى زيادة وقت الاستجابة قليلاً وتقليل عمر البطارية.

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

@androidx.annotation.OptIn(ExperimentalCamera2Interop::class)
fun isBackCameraLevel3Device(cameraProvider: ProcessCameraProvider): Boolean {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
        return CameraSelector.DEFAULT_BACK_CAMERA
            .filter(cameraProvider.availableCameraInfos)
            .firstOrNull()
            ?.let { Camera2CameraInfo.from(it) }
            ?.getCameraCharacteristic(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL) ==
            CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3
    }
    return false
}Architecture.kt

الأذونات

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

لمزيد من المعلومات حول ضبط أذونات تطبيقك، يُرجى الاطّلاع على مقالة طلب أذونات التطبيق.

المتطلبات

في ما يلي الحدّ الأدنى من متطلبات إصدار CameraX:

مستوى واجهة برمجة التطبيقات 21 لنظام التشغيل Android
الإصدار 1.1.1 من مكوِّنات الهندسة المتوافقة مع Android

بالنسبة إلى الأنشطة التي تراعي مراحل النشاط، استخدِم FragmentActivity أو AppCompatActivity.

تحديد الاعتماديات

لإضافة اعتمادية على CameraX، يجب تضمين مستودع Google Maven في مشروعك.

افتح ملف settings.gradle لمشروعك وأضِف مستودع google() كما هو موضّح في ما يلي:

أنيق

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

Kotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

أضِف ما يلي إلى نهاية مجموعة Android:

أنيق

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

أضِف ما يلي إلى ملف build.gradle لكل وحدة في التطبيق:

Groovy

dependencies {
  // CameraX core library using the camera2 implementation
  def camerax_version = "1.7.0-rc01"
  // The following line is optional, as the core library is included indirectly by camera-camera2
  implementation "androidx.camera:camera-core:${camerax_version}"
  implementation "androidx.camera:camera-camera2:${camerax_version}"
  // If you want to additionally use the CameraX Lifecycle library
  implementation "androidx.camera:camera-lifecycle:${camerax_version}"
  // If you want to additionally use the CameraX VideoCapture library
  implementation "androidx.camera:camera-video:${camerax_version}"
  // If you want to additionally use the CameraX View class
  implementation "androidx.camera:camera-view:${camerax_version}"
  // If you want to additionally add CameraX ML Kit Vision Integration
  implementation "androidx.camera:camera-mlkit-vision:${camerax_version}"
  // If you want to additionally use the CameraX Extensions library
  implementation "androidx.camera:camera-extensions:${camerax_version}"
}

Kotlin

dependencies {
    // CameraX core library using the camera2 implementation
    val camerax_version = "1.7.0-rc01"
    // The following line is optional, as the core library is included indirectly by camera-camera2
    implementation("androidx.camera:camera-core:${camerax_version}")
    implementation("androidx.camera:camera-camera2:${camerax_version}")
    // If you want to additionally use the CameraX Lifecycle library
    implementation("androidx.camera:camera-lifecycle:${camerax_version}")
    // If you want to additionally use the CameraX VideoCapture library
    implementation("androidx.camera:camera-video:${camerax_version}")
    // If you want to additionally use the CameraX View class
    implementation("androidx.camera:camera-view:${camerax_version}")
    // If you want to additionally add CameraX ML Kit Vision Integration
    implementation("androidx.camera:camera-mlkit-vision:${camerax_version}")
    // If you want to additionally use the CameraX Extensions library
    implementation("androidx.camera:camera-extensions:${camerax_version}")
}

لمزيد من المعلومات حول ضبط تطبيقك ليتوافق مع هذه المتطلبات، يُرجى الاطّلاع على مقالة تعريف التبعيات.

إمكانية التشغيل التفاعلي بين CameraX وCamera2

تستند CameraX إلى Camera2، وتوفّر CameraX طرقًا لقراءة السمات وحتى كتابتها في عملية تنفيذ Camera2. للاطّلاع على التفاصيل الكاملة، يُرجى مراجعة حزمة إمكانية التشغيل التفاعلي.

لمزيد من المعلومات حول كيفية ضبط CameraX لخصائص Camera2، استخدِم Camera2CameraInfo لقراءة CameraCharacteristics الأساسية. يمكنك أيضًا اختيار كتابة خصائص Camera2 الأساسية بإحدى الطريقتَين التاليتَين:

استخدِم Camera2CameraControl، الذي يتيح لك ضبط السمات في CaptureRequest الأساسي، مثل وضع التركيز التلقائي.
يمكنك توسيع نطاق CameraX UseCase باستخدام Camera2Interop.Extender. يتيح لك ذلك ضبط السمات في CaptureRequest، تمامًا مثل Camera2CameraControl. وتوفّر لك أيضًا بعض عناصر التحكّم الإضافية، مثل ضبط حالة استخدام البث لتحسين الكاميرا بما يتناسب مع سيناريو الاستخدام. لمزيد من المعلومات، يُرجى الاطّلاع على استخدام حالات استخدام البث لتحسين الأداء.

تستخدم عينة التعليمات البرمجية التالية حالات استخدام البث لتحسين جودة مكالمة فيديو. استخدِم Camera2CameraInfo لمعرفة ما إذا كانت حالة استخدام بث مكالمات الفيديو متاحة. بعد ذلك، استخدِم Camera2Interop.Extender لضبط حالة استخدام البث الأساسي.

// Set underlying Camera2 stream use case to optimize for video calls.

val videoCallStreamId =
    CameraMetadata.SCALER_AVAILABLE_STREAM_USE_CASES_VIDEO_CALL.toLong()

// Check available CameraInfos to find the first one that supports
// the video call stream use case.
val frontCameraInfo = cameraProvider.getAvailableCameraInfos()
    .first { cameraInfo ->
        val isVideoCallStreamingSupported = Camera2CameraInfo.from(cameraInfo)
            .getCameraCharacteristic(
                CameraCharacteristics.SCALER_AVAILABLE_STREAM_USE_CASES
            )?.contains(videoCallStreamId)
        val isFrontFacing = (cameraInfo.getLensFacing() == 
                             CameraSelector.LENS_FACING_FRONT)
        (isVideoCallStreamingSupported == true) && isFrontFacing
    }

val cameraSelector = frontCameraInfo.cameraSelector

// Start with a Preview Builder.
val previewBuilder = Preview.Builder()
    .setTargetAspectRatio(screenAspectRatio)
    .setTargetRotation(rotation)

// Use Camera2Interop.Extender to set the video call stream use case.
Camera2Interop.Extender(previewBuilder).setStreamUseCase(videoCallStreamId)

// Bind the Preview UseCase and the corresponding CameraSelector.
val preview = previewBuilder.build()
camera = cameraProvider.bindToLifecycle(this, cameraSelector, preview)

مراجع إضافية

لمزيد من المعلومات حول CameraX، يُرجى الاطّلاع على المراجع الإضافية التالية.

درس تطبيقي حول الترميز

بدء استخدام CameraX

عيّنة تعليمات برمجية

نماذج تطبيقات CameraX

بنية CameraX تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.