Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Opsi konfigurasi

Anda mengonfigurasi setiap kasus penggunaan CameraX untuk mengontrol berbagai aspek operasi kasus penggunaan.

Misalnya, pada kasus penggunaan pengambilan gambar, Anda dapat menentukan rasio tinggi lebar target dan mode flash. Kode berikut menampilkan satu contoh:

Kotlin

val imageCapture = ImageCapture.Builder()
    .setFlashMode(...)
    .setTargetAspectRatio(...)
    .build()

Java

ImageCapture imageCapture =
    new ImageCapture.Builder()
        .setFlashMode(...)
        .setTargetAspectRatio(...)
        .build();

Selain opsi konfigurasi, beberapa kasus penggunaan mengekspos API untuk secara dinamis mengubah setelan setelah kasus penggunaan dibuat. Untuk informasi tentang konfigurasi yang berlaku khusus untuk kasus penggunaan tertentu, 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. Semua ini ditangani oleh library, sehingga Anda tidak perlu menuliskan kode khusus perangkat.

Sasaran CameraX adalah menginisialisasi sesi kamera dengan sukses. Ini berarti CameraX menerima 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 mengetahui informasi selengkapnya.

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 menetapkan rotasi target menggunakan setelan konfigurasi. Kemudian, perangkat dapat memperbarui setelan rotasi menggunakan metode dari API kasus penggunaan (seperti ImageAnalysis.setTargetRotation()), bahkan saat siklus proses sedang 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 informasi 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.

Data untuk gambar yang diambil dapat disimpan tanpa informasi rotasi. Data Exif berisi 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() untuk membuat transformasi.

Contoh kode berikut menunjukkan cara menentukan rotasi pada peristiwa orientasi:

Kotlin

override fun onCreate() {
    val imageCapture = ImageCapture.Builder().build()

    val orientationEventListener = object : OrientationEventListener(this as Context) {
        override fun onOrientationChanged(orientation : Int) {
            // Monitors orientation values to determine the target rotation value
            val rotation : Int = when (orientation) {
                in 45..134 -> Surface.ROTATION_270
                in 135..224 -> Surface.ROTATION_180
                in 225..314 -> Surface.ROTATION_90
                else -> Surface.ROTATION_0
            }

            imageCapture.targetRotation = rotation
        }
    }
    orientationEventListener.enable()
}

Java

@Override
public void onCreate() {
    ImageCapture imageCapture = new ImageCapture.Builder().build();

    OrientationEventListener orientationEventListener = new OrientationEventListener((Context)this) {
       @Override
       public void onOrientationChanged(int orientation) {
           int rotation;

           // Monitors orientation values to determine the target rotation value
           if (orientation >= 45 && orientation < 135) {
               rotation = Surface.ROTATION_270;
           } else if (orientation >= 135 && orientation < 225) {
               rotation = Surface.ROTATION_180;
           } else if (orientation >= 225 && orientation < 315) {
               rotation = Surface.ROTATION_90;
           } else {
               rotation = Surface.ROTATION_0;
           }

           imageCapture.setTargetRotation(rotation);
       }
    };

    orientationEventListener.enable();
}

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 sehingga rotasi resolusi target diketahui menggunakan Preview.getTargetRotation().
  • ImageAnalysis: Output metadata disediakan sehingga koordinat buffer gambar diketahui relatif terhadap koordinat tampilan.
  • ImageCapture: Metadata Exif gambar, buffering, atau buffering beserta metadata akan diubah untuk mencatat setelan rotasi. Nilai yang diubah bergantung pada implementasi HAL.

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 atau rasio tinggi lebar spesifik dalam kasus penggunaan yang mendukung konfigurasi tersebut.

Resolusi otomatis

CameraX dapat menentukan setelan resolusi terbaik secara otomatis berdasarkan kasus penggunaan yang ditentukan di cameraProcessProvider.bindToLifecycle(). Jika memungkinkan, tentukan semua kasus penggunaan yang diperlukan untuk dijalankan secara bersamaan dalam satu sesi dalam satu panggilan 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 berbagai jenis perangkat sembari 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, aplikasi dapat melakukan salah satu hal berikut:

  • Menentukan resolusi target sebesar 4:3 atau 16:9 untuk kasus penggunaan
  • Menentukan resolusi khusus yang akan digunakan CameraX untuk menemukan kecocokan terdekat
  • Menentukan rasio tinggi lebar pemangkasan untuk ImageCapture

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 View dapat dipangkas, 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 maksimum: Ukuran pratinjau, menunjukkan ukuran yang paling cocok dengan resolusi layar perangkat, atau dengan 1080p (1920x1080), mana pun 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 maksimum: Dibatasi oleh CameraX ke 1080p. Resolusi target disetel ke 640x480 secara default, sehingga jika ingin resolusi lebih besar dari 640x480, Anda harus menggunakan setTargetResolution dan setTargetAspectRatio untuk mendapatkan yang terdekat dari resolusi yang didukung.
Mengambil 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 maksimum: Resolusi output maksimum perangkat kamera untuk format JPEG dari StreamConfigurationMap.getOutputSizes

Menentukan resolusi

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

Kotlin

val imageAnalysis = ImageAnalysis.Builder()
    .setTargetResolution(Size(1280, 720))
    .build()

Java

ImageAnalysis imageAnalysis =
  new ImageAnalysis.Builder()
    .setTargetResolution(new Size(1280, 720))
    .build();

Anda tidak dapat menetapkan rasio tinggi lebar target dan resolusi target pada kasus penggunaan yang sama. Melakukannya akan memunculkan IllegalArgumentException saat membuat objek konfigurasi.

Nyatakan Size resolusi dalam bingkai koordinat setelah memutar ukuran yang didukung oleh rotasi target. Misalnya, perangkat yang memiliki orientasi alami potret dengan rotasi target alami yang meminta gambar potret dapat menetapkan 480x640, dan perangkat yang sama, diputar 90 derajat serta menargetkan orientasi lanskap dapat menetapkan 640x480.

Resolusi maksimum yang tersedia yang dapat Anda pilih untuk ImageAnalysis adalah 1080p. Batasan 1080p untuk ImageAnalysis mempertimbangkan faktor performa dan kualitas sehingga pengguna dapat memperoleh kualitas yang wajar dan streaming output yang lancar.

Resolusi target berupaya menetapkan batas minimum untuk resolusi gambar. Resolusi gambar sebenarnya akan menjadi resolusi terdekat yang tersedia dalam ukuran yang tidak lebih kecil dari resolusi target, seperti yang ditentukan oleh implementasi Kamera. Namun, jika tidak ada resolusi yang sama dengan atau lebih besar dari resolusi target, resolusi terdekat yang tersedia yang lebih kecil dari resolusi target akan dipilih. Resolusi dengan rasio tinggi lebar yang sama dengan Size yang disediakan akan diberi prioritas lebih tinggi daripada resolusi rasio tinggi lebar yang berbeda.

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 adalah menentukan resolusi agar pemrosesan gambar lebih efisien (misalnya gambar kecil atau sedang berdasarkan kemampuan pemrosesan perangkat), gunakan setTargetResolution(Size resolution).

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

Jika aplikasi Anda berjalan di Android 10 atau versi yang lebih tinggi, Anda dapat menggunakan isSessionConfigurationSupported untuk memverifikasi SessionConfiguration spesifik.

Mengontrol fokus

CameraControl API menawarkan kemampuan Tap-to-Focus. Mulai dengan mendapatkan objek CameraControl, seperti yang ditunjukkan pada kode berikut:

Kotlin

val camera = processCameraProvider.bindToLifecycle(...)
val cameraControl = camera.getCameraControl()

Java

Camera camera = processCameraProvider.bindToLifecycle(...);
CameraControl cameraControl = camera.getCameraControl();

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

Kotlin

val factory = SurfaceOrientedMeteringPointFactory(width, height)
val point = factory.createPoint(x, y)
val action = FocusMeteringAction.Builder(point, FocusMeteringAction.FLAG_AF)
    .addPoint(point2, FocusMeteringAction.FLAG_AE) // could have many
    // auto calling cancelFocusAndMetering in 5 seconds
    .setAutoCancelDuration(5, TimeUnit.SECONDS)
    .build()

val future = cameraControl.startFocusAndMetering(action)
future.addListener( Runnable {
    val result = future.get()
    // process the result
} , executor)

Java

MeteringPointFactory factory = new SurfaceOrientedMeteringPointFactory(width, height);
MeteringPoint point = factory.createPoint(x, y);
FocusMeteringAction action = new FocusMeteringAction.Builder(point, FocusMeteringAction.FLAG_AF)
        .addPoint(point2, FocusMeteringAction.FLAG_AE) // could have many
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build();

ListenableFuture future = cameraControl.startFocusAndMetering(action)
future.addListener( () -> {
    try {
        FocusMeteringResult result = future.get();
        // process the result
    } catch (Exception e) {
    }
} , executor);

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