Opsi konfigurasi

Konfigurasi setiap kasus penggunaan CameraX menggunakan class antarmuka konfigurasi untuk mengontrol berbagai aspek operasi pada kasus penggunaan tersebut.

Misalnya, pada kasus penggunaan pengambilan gambar, Anda dapat menentukan lensa mana yang akan digunakan, rasio tinggi lebar target, dan cara menjalankan threading. Kode berikut menampilkan satu contoh:

Kotlin

    val config = ImageCaptureConfig.Builder()
        .setLensFacing(...)
        .setFlashMode(...)
        .setTargetAspectRatio(...)
        .build()
    

Java

    ImageCaptureConfig config =
        new ImageCaptureConfig.Builder()
            .setLensFacing(...)
            .setFlashMode(...)
            .setTargetAspectRatio(...)
            .build();
    

Selain opsi konfigurasi, beberapa kasus penggunaan mengekspos API untuk secara dinamis mengubah setelan setelah kasus penggunaan dibuat. Untuk informasi konfigurasi yang berlaku khusus pada setiap kasus penggunaan, lihat Mengimplementasikan pratinjau, Menganalisis gambar, dan Mengambil foto.

Pemilihan otomatis

CameraX otomatis menyediakan fungsionalitas yang berlaku khusus untuk perangkat yang menjalankan aplikasi Anda. Misalnya, CameraX akan otomatis menentukan resolusi terbaik yang akan digunakan jika Anda tidak menentukan resolusi, atau jika resolusi yang Anda tentukan tidak didukung. Semuanya ini ditangani di balik layar, sehingga Anda tidak perlu menulis kode khusus untuk perangkat tertentu.

Sasaran CameraX adalah menginisialisasi sesi kamera dengan sukses. Ini berarti CameraX mengorbankan resolusi dan rasio tinggi lebar berdasarkan kemampuan perangkat. Kompromi ini terjadi karena:

  • Perangkat tidak mendukung resolusi yang diminta.
  • Perangkat memiliki masalah kompatibilitas, seperti perangkat lama yang memerlukan resolusi tertentu agar dapat beroperasi dengan benar.
  • Pada beberapa perangkat, format tertentu hanya tersedia pada rasio tinggi lebar tertentu.
  • Perangkat memiliki preferensi "nearest mod16" untuk JPEG atau encoding video. Lihat SCALER_STREAM_CONFIGURATION_MAP untuk informasi lebih lanjut.

Meskipun CameraX membuat dan mengelola sesi, Anda harus selalu memeriksa ukuran gambar yang ditampilkan pada output kasus penggunaan dalam kode Anda dan menyesuaikannya.

Rotasi

Secara default, rotasi kamera disetel agar mengikuti rotasi tampilan default selama pembuatan kasus penggunaan. Dalam kasus default ini, CameraX menghasilkan output yang memungkinkan aplikasi mencocokkan dengan mudah objek yang ingin Anda lihat di pratinjau. Anda dapat mengubah rotasi ke nilai kustom untuk mendukung perangkat multi-tampilan dengan meneruskan orientasi tampilan saat ini saat mengonfigurasi objek kasus penggunaan, atau secara dinamis setelah objek selesai dibuat.

Aplikasi Anda dapat mengonfigurasi rotasi target menggunakan builder konfigurasi. Aplikasi Anda juga dapat memperbarui setelan rotasi dengan menggunakan metode dari API kasus penggunaan (misalnya ImageAnalysis.setTargetRotation()), bahkan saat siklus proses dalam status berjalan. Anda dapat menggunakan cara ini saat aplikasi terkunci ke mode potret—sehingga konfigurasi ulang tidak diperlukan saat rotasi terjadi—tetapi kasus penggunaan pengambilan foto atau analisis gambar perlu memperhatikan rotasi saat ini dari perangkat. Misalnya, kemampuan mendeteksi rotasi mungkin diperlukan sehingga wajah diorientasikan dengan tepat untuk deteksi wajah, atau foto disetel ke mode lanskap atau potret.

Meskipun data untuk gambar yang diambil disimpan tanpa merotasi gambar tersebut, data Exif memuat informasi rotasi sehingga aplikasi galeri dapat menampilkan gambar dalam orientasi yang benar setelah disimpan.

Untuk menampilkan data pratinjau dengan orientasi yang benar, Anda dapat menggunakan output metadata dari Preview.PreviewOutput() guna membuat transformasi untuk tampilan GLSurfaceView.

Contoh kode berikut menampilkan cara menyetel rotasi melalui API konfigurasi:

Kotlin

    val previewConfig = PreviewConfig.Builder()
            .setTargetRotation(windowManager.defaultDisplay.rotation)
            .build()
    

Java

    PreviewConfig previewConfig =
      new PreviewConfig.Builder()
          .setTargetRotation(getWindowManager().getDefaultDisplay().getRotation())
          .build();
    

Berdasarkan rotasi yang ditetapkan, setiap kasus penggunaan akan merotasi data gambar secara langsung atau memberikan metadata rotasi kepada pemakai data gambar yang tidak dirotasi.

  • Preview: Output metadata disediakan guna membuat transformasi yang tepat untuk tampilan GLSurfaceView menggunakan Preview.PreviewOutput.getRotationDegrees().
  • ImageAnalysis: Output metadata disediakan sehingga koordinat buffer gambar diketahui relatif terhadap koordinat tampilan. Metode analyze() menyediakan parameter rotationDegrees yang menunjukkan rotasi yang perlu diterapkan pada data analisis gambar agar sesuai dengan jendela bidik.
  • ImageCapture: Metadata Exif gambar akan diubah untuk mencatat setelan rotasi.

Resolusi kamera

Anda dapat mengizinkan CameraX menyetel resolusi gambar berdasarkan kombinasi kapabilitas perangkat, tingkat hardware yang didukung perangkat, kasus penggunaan, dan rasio tinggi lebar yang tersedia. Atau, Anda dapat menetapkan resolusi target spesifik dengan rasio tinggi lebar yang sesuai dalam kasus penggunaan yang mendukung konfigurasi tersebut. Resolusi yang cocok dengan rasio tinggi lebar target akan lebih diprioritaskan daripada resolusi target spesifik.

Resolusi otomatis

CameraX dapat otomatis menentukan setelan resolusi terbaik berdasarkan kasus penggunaan yang ditentukan dalam CameraX.bindToLifecycle(). Jika memungkinkan, tentukan semua kasus penggunaan yang diperlukan agar berjalan secara bersamaan dalam satu sesi dan dalam satu panggilan CameraX.bindToLifecycle(). CameraX akan menentukan resolusi berdasarkan kumpulan kasus penggunaan dengan mempertimbangkan tingkat hardware yang didukung perangkat dan dengan memperhitungkan varian khusus perangkat (di mana perangkat mungkin melebihi atau tidak memenuhi konfigurasi aliran yang tersedia). Tujuannya adalah agar aplikasi dapat berjalan pada aneka jenis perangkat sambil meminimalkan jalur kode khusus perangkat.

Rasio tinggi lebar default untuk kasus penggunaan pengambilan gambar dan analisis gambar adalah 4:3.

Kasus penggunaan memiliki rasio tinggi lebar yang dapat dikonfigurasi yang memungkinkan aplikasi untuk menentukan rasio tinggi lebar yang diinginkan berdasarkan desain UI. Output CameraX akan dihasilkan untuk mengimbangi rasio tinggi lebar yang diminta, yang sedekat mungkin dengan yang didukung perangkat. Jika tidak ada resolusi yang sama persis dengan yang didukung, resolusi yang memenuhi sebagian besar kondisi akan dipilih. Dengan begitu, aplikasi menentukan bagaimana kamera ditampilkan pada aplikasi, dan CameraX menentukan setelan resolusi kamera terbaik untuk memenuhi kondisi itu di perangkat berbeda.

Misalnya, sebuah aplikasi mungkin melakukan salah satu dari berikut ini:

  • Mengonfigurasi tata letak untuk menggunakan rasio 4:3 untuk pengambilan gambar.
  • Menentukan tata letak layar penuh. Mengingat variasi resolusi layar dan dengan memperhitungkan menu UI sistem, ini adalah rasio yang akan bervariasi dari satu perangkat ke perangkat yang lain.
  • Menentukan tata letak persegi.

CameraX akan memilih resolusi permukaan Camera2 internal secara otomatis. Tabel berikut menampilkan berbagai resolusi:

Kasus penggunaan Resolusi permukaan internal Resolusi data output
Pratinjau Rasio Tinggi Lebar: Resolusi yang paling sesuai untuk target berdasarkan setelan. Resolusi permukaan internal. Metadata disediakan agar Tampilan dapat di-crop, diskala, dan dirotasi sesuai rasio tinggi lebar target.
Resolusi default: Resolusi pratinjau tertinggi, atau resolusi tertinggi pilihan perangkat yang cocok dengan rasio tinggi lebar di atas.
Resolusi maksimal: Ukuran pratinjau, menunjukkan ukuran yang paling cocok dengan resolusi layar perangkat, atau dengan 1080p (1920x1080), salah satu yang lebih kecil.
Analisis gambar Rasio tinggi lebar: Resolusi yang paling sesuai untuk target berdasarkan setelan. Resolusi permukaan internal.
Resolusi default: Setelan resolusi target default adalah 640x480. Menyesuaikan resolusi target dan rasio tinggi lebar yang terkait akan menghasilkan resolusi terbaik yang didukung di bawah 1080p.
Resolusi maksimal: Dibatasi oleh CameraX ke 1080p. Resolusi target secara default ditetapkan ke 640x480, sehingga jika menginginkan resolusi di atas 640x480, Anda harus menggunakan setTargetResolution dan setTargetAspectRatio untuk mendapatkan resolusi yang paling mendekati resolusi yang didukung.
Pengambilan gambar Rasio tinggi lebar: Rasio tinggi lebar yang paling sesuai dengan setelan. Resolusi permukaan internal.
Resolusi default: Resolusi tertinggi yang tersedia, atau resolusi tertinggi pilihan perangkat yang cocok dengan rasio tinggi lebar di atas.
Resolusi maksimal: Resolusi output maksimum kamera perangkat untuk format JPEG dari StreamConfigurationMap#getOutputSizes

Menentukan resolusi

Anda dapat menetapkan resolusi tertentu saat membuat konfigurasi kasus penggunaan menggunakan metode setTargetResolution(Size resolution), seperti yang ditampilkan dalam contoh kode berikut:

Kotlin

    val imageAnalysisConfig = ImageAnalysisConfig.Builder()
        .setTargetResolution(Size(1280, 720))
        .build()
    

Java

    ImageAnalysisConfig config =
      new ImageAnalysisConfig.Builder()
        .setTargetResolution(new Size(1280, 720))
        .build();
    

Anda dapat menetapkan rasio tinggi lebar target tertentu berdasarkan resolusi yang ditetapkan. Rasio tinggi lebar target akan memengaruhi resolusi mana yang akan dipilih. Tetapkan rasio tinggi lebar target agar cocok dengan resolusi target untuk mendapatkan resolusi yang dipilih. Resolusi yang dihasilkan akan memperhitungkan kapabilitas perangkat dan kasus penggunaan lainnya yang disertakan.

Jika resolusi dan rasio tinggi lebar yang sama persis dengan permintaan tidak dapat dipenuhi, resolusi pembatas yang lebih tinggi dan paling mendekati akan dipilih. Resolusi akan kembalikan ke 640x480 jika tidak ada pilihan yang tersedia.

CameraX akan menerapkan resolusi terbaik yang sesuai berdasarkan permintaan. Jika kebutuhan utamanya adalah memenuhi rasio tinggi lebar, cukup tentukan setTargetAspectRatio, dan CameraX akan menentukan resolusi spesifik yang sesuai berdasarkan perangkatnya. Jika kebutuhan utama aplikasi Anda adalah menentukan resolusi agar pemrosesan gambar berjalan lebih efisien (misalnya gambar berukuran kecil atau sedang berdasarkan kemampuan pemrosesan perangkat), gunakan setTargetResolution(Size resolution).

Jika aplikasi Anda membutuhkan resolusi yang sama persis, lihat tabel dalam createCaptureSession untuk menentukan resolusi maksimum yang didukung oleh setiap tingkat hardware. Untuk memeriksa resolusi spesifik yang didukung perangkat saat ini, lihat StreamConfigurationMap.getOutputSize(int).

Jika aplikasi Anda berjalan pada Android 10, Anda dapat menggunakan isSessionConfigurationSupported untuk memverifikasi SessionConfiguration tertentu.

Mengontrol fokus

CameraControl API menawarkan kapabilitas Tap-to-Focus. Anda mendapatkan CameraControl dengan menentukan arah hadap lensa:

Kotlin

    CameraX.getCameraControl(LensFacing lensFacing)
    

Java

    CameraX.getCameraControl(LensFacing lensFacing);
    

Gunakan MeteringPointFactory, MeteringPoint, MeteringMode, dan FocusMeteringAction untuk menjalankan Tap-to-Focus:

Kotlin

    val factory = SensorOrientedMeteringPointFactory(width, height)
    val point = factory.createPoint(x, y)
    val action = FocusMeteringAction.Builder.from(point,
        FocusMeteringAction.MeteringMode.AF_ONLY)
        .addPoint(point2, FocusMeteringAction.MeteringMode.AE_ONLY) // could have many
        .setAutoFocusCallback { }
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build()
    

Java

    MeteringPointFactory factory = new SensorOrientedMeteringPointFactory(width, height);
    MeteringPoint point = factory.createPoint(x, y);
    FocusMeteringAction action = FocusMeteringAction.Builder.from(point,
                                     MeteringMode.AF_ONLY)
        .addPoint(point2, MeteringMode.AE_ONLY) // could have many
        .setAutoFocusCallback(new OnAutoFocusListener(){
            public void onFocusCompleted(boolean isSuccess) {
            }
        })
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build();
    

Referensi lainnya

Untuk mempelajari CameraX lebih lanjut, lihat referensi tambahan berikut.

Codelab

  • Memulai CameraX
  • Contoh kode

  • Contoh aplikasi CameraX resmi
  • Komunitas developer

    Grup Diskusi Android CameraX