Bir görüntüyü ML Kit'e ilettiğinizde bu cihaz, görüntüdeki her nesnenin konumuyla birlikte görüntüde beşe kadar nesne algılar. Video akışlarında nesneleri algılarken her nesnenin benzersiz bir kimliği vardır. Bu kimliği, nesneyi kareden kareye izlemek için kullanabilirsiniz.
Algılanan nesneleri sınıflandırmak için özel bir görüntü sınıflandırma modeli kullanabilirsiniz. Model uyumluluğu gereksinimleri, önceden eğitilmiş modellerin nerede bulunduğu ve kendi modellerinizi nasıl eğiteceğiniz hakkında yardım almak için lütfen ML Kit ile özel modeller bölümüne bakın.
Özel bir modeli iki şekilde entegre edebilirsiniz. Modeli uygulamanızın öğe klasörüne yerleştirerek paketleyebilir veya Firebase'den dinamik olarak indirebilirsiniz. Aşağıdaki tabloda iki seçenek karşılaştırılmaktadır.
Gruplandırılmış Model | Barındırılan Model |
---|---|
Model, uygulamanızın APK'sının bir parçası olduğundan boyutunu artırır. | Model, APK'nızın bir parçası değil. Firebase Makine Öğrenimi'ne yüklenerek barındırılır. |
Model, Android cihaz çevrimdışı olsa bile hemen kullanılabilir | Model istek üzerine indirilir |
Firebase projesine gerek yoktur | Firebase projesi gereklidir |
Modeli güncellemek için uygulamanızı yeniden yayınlamanız gerekir | Uygulamanızı yeniden yayınlamadan model güncellemelerini aktarın |
Yerleşik A/B testi yok | Firebase Remote Config ile kolay A/B testi |
Deneyin
- Paketlenmiş modelin örnek kullanımı için vision hızlı başlangıç uygulamasına ve barındırılan modelin örnek kullanımı için automl hızlı başlangıç uygulamasına göz atın.
- Bu API'nin uçtan uca uygulanması için Materyal Tasarım vitrin uygulamasına bakın.
Başlamadan önce
Proje düzeyindeki
build.gradle
dosyanıza hembuildscript
hem deallprojects
bölümlerinize Google'ın Maven deposunu eklediğinizden emin olun.ML Kit Android kitaplıklarının bağımlılıklarını, modülünüzün uygulama düzeyindeki Gradle dosyasına ekleyin. Bu dosya genellikle
app/build.gradle
olur:Uygulamanızla bir model paketi sunmak için:
dependencies { // ... // Object detection & tracking feature with custom bundled model implementation 'com.google.mlkit:object-detection-custom:17.0.2' }
Firebase'den dinamik olarak bir model indirmek için
linkFirebase
bağımlılığını ekleyin:dependencies { // ... // Object detection & tracking feature with model downloaded // from firebase implementation 'com.google.mlkit:object-detection-custom:17.0.2' implementation 'com.google.mlkit:linkfirebase:17.0.0' }
Bir model indirmek istiyorsanız henüz yapmadıysanız Firebase'i Android projenize eklediğinizden emin olun. Modeli paketlediğinizde bu gerekli değildir.
1. Modeli yükleme
Yerel model kaynağını yapılandırma
Modeli uygulamanızla birlikte gruplandırmak için:
Model dosyasını (genellikle
.tflite
veya.lite
ile biter) uygulamanızınassets/
klasörüne kopyalayın. (Önceapp/
klasörünü sağ tıklayıp ardından Yeni > Klasör > Öğeler Klasörü'nü tıklayarak klasörü oluşturmanız gerekebilir.)Ardından, Gradle'ın uygulamayı oluştururken model dosyasını sıkıştırmadığından emin olmak için aşağıdakileri uygulamanızın
build.gradle
dosyasına ekleyin:android { // ... aaptOptions { noCompress "tflite" // or noCompress "lite" } }
Model dosyası, uygulama paketine dahil edilir ve ML Kit'in kullanımına ham öğe olarak eklenir.
Model dosyasının yolunu belirterek
LocalModel
nesnesi oluşturun:Kotlin
val localModel = LocalModel.Builder() .setAssetFilePath("model.tflite") // or .setAbsoluteFilePath(absolute file path to model file) // or .setUri(URI to model file) .build()
Java
LocalModel localModel = new LocalModel.Builder() .setAssetFilePath("model.tflite") // or .setAbsoluteFilePath(absolute file path to model file) // or .setUri(URI to model file) .build();
Firebase tarafından barındırılan bir model kaynağını yapılandırma
Uzaktan barındırılan modeli kullanmak için FirebaseModelSource
ile bir CustomRemoteModel
nesnesi oluşturun ve modeli yayınlarken atadığınız adı belirtin:
Kotlin
// Specify the name you assigned in the Firebase console. val remoteModel = CustomRemoteModel .Builder(FirebaseModelSource.Builder("your_model_name").build()) .build()
Java
// Specify the name you assigned in the Firebase console. CustomRemoteModel remoteModel = new CustomRemoteModel .Builder(new FirebaseModelSource.Builder("your_model_name").build()) .build();
Ardından, indirme işlemine izin vermek istediğiniz koşulları belirterek model indirme görevini başlatın. Model cihazda yoksa veya modelin daha yeni bir sürümü varsa görev, modeli Firebase'den eşzamansız olarak indirir:
Kotlin
val downloadConditions = DownloadConditions.Builder() .requireWifi() .build() RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener { // Success. }
Java
DownloadConditions downloadConditions = new DownloadConditions.Builder() .requireWifi() .build(); RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(@NonNull Task task) { // Success. } });
Birçok uygulama, indirme görevini başlatma kodunda başlatır ancak modeli kullanmanız gerekmeden istediğiniz zaman bu işlemi gerçekleştirebilirsiniz.
2. Nesne algılayıcısını yapılandırın
Model kaynaklarınızı yapılandırdıktan sonra, bir CustomObjectDetectorOptions
nesnesi kullanarak kullanım alanınız için nesne algılayıcıyı yapılandırın. Aşağıdaki ayarları değiştirebilirsiniz:
Nesne Algılayıcı Ayarları | |
---|---|
Algılama modu |
STREAM_MODE (varsayılan) | SINGLE_IMAGE_MODE
Nesne algılayıcı,
|
Birden fazla nesneyi algılama ve izleme |
false (varsayılan) | true
En fazla beş nesnenin mı yoksa yalnızca en belirgin nesnenin mı (varsayılan) algılanacağını ve izleneceğini belirtir. |
Nesneleri sınıflandırma |
false (varsayılan) | true
Sağlanan özel sınıflandırıcı modeli kullanılarak algılanan nesnelerin sınıflandırılıp sınıflandırılmayacağı. Özel sınıflandırma modelinizi kullanmak için bunu |
Sınıflandırma güven eşiği |
Algılanan etiketlerin minimum güven puanı. Ayarlanmazsa modelin meta verileri tarafından belirtilen herhangi bir sınıflandırıcı eşiği kullanılır. Model herhangi bir meta veri içermiyorsa veya meta veriler bir sınıflandırıcı eşiği belirtmiyorsa varsayılan eşik olan 0, 0 kullanılır. |
Nesne başına maksimum etiket sayısı |
Algılayıcının döndüreceği nesne başına maksimum etiket sayısı. Politika ayarlanmazsa 10 olan varsayılan değer kullanılır. |
Nesne algılama ve izleme API'si aşağıdaki iki temel kullanım alanı için optimize edilmiştir:
- Kamera vizöründeki en belirgin nesnenin canlı olarak algılanması ve izlenmesi.
- Statik bir görüntüden birden fazla nesnenin algılanması.
API'yi bu kullanım alanları için yerel olarak paket haline getirilmiş bir modelle yapılandırmak için:
Kotlin
// Live detection and tracking val customObjectDetectorOptions = CustomObjectDetectorOptions.Builder(localModel) .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE) .enableClassification() .setClassificationConfidenceThreshold(0.5f) .setMaxPerObjectLabelCount(3) .build() // Multiple object detection in static images val customObjectDetectorOptions = CustomObjectDetectorOptions.Builder(localModel) .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE) .enableMultipleObjects() .enableClassification() .setClassificationConfidenceThreshold(0.5f) .setMaxPerObjectLabelCount(3) .build() val objectDetector = ObjectDetection.getClient(customObjectDetectorOptions)
Java
// Live detection and tracking CustomObjectDetectorOptions customObjectDetectorOptions = new CustomObjectDetectorOptions.Builder(localModel) .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE) .enableClassification() .setClassificationConfidenceThreshold(0.5f) .setMaxPerObjectLabelCount(3) .build(); // Multiple object detection in static images CustomObjectDetectorOptions customObjectDetectorOptions = new CustomObjectDetectorOptions.Builder(localModel) .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE) .enableMultipleObjects() .enableClassification() .setClassificationConfidenceThreshold(0.5f) .setMaxPerObjectLabelCount(3) .build(); ObjectDetector objectDetector = ObjectDetection.getClient(customObjectDetectorOptions);
Uzaktan barındırılan bir modeliniz varsa çalıştırmadan önce modelin indirilip indirilmediğini kontrol etmeniz gerekir. Model yöneticisinin isModelDownloaded()
yöntemini kullanarak model indirme görevinin durumunu kontrol edebilirsiniz.
Algılayıcıyı çalıştırmadan önce bunu doğrulamanız gerekse de hem uzaktan barındırılan bir modeliniz hem de yerel olarak paketlenmiş bir modeliniz varsa görüntü algılayıcıyı örneklendirmek için bu kontrolün yapılması mantıklı olabilir: İndirilmişse uzak modelden, aksi takdirde yerel modelden bir algılayıcı oluşturun.
Kotlin
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener { isDownloaded -> val optionsBuilder = if (isDownloaded) { CustomObjectDetectorOptions.Builder(remoteModel) } else { CustomObjectDetectorOptions.Builder(localModel) } val customObjectDetectorOptions = optionsBuilder .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE) .enableClassification() .setClassificationConfidenceThreshold(0.5f) .setMaxPerObjectLabelCount(3) .build() val objectDetector = ObjectDetection.getClient(customObjectDetectorOptions) }
Java
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Boolean isDownloaded) { CustomObjectDetectorOptions.Builder optionsBuilder; if (isDownloaded) { optionsBuilder = new CustomObjectDetectorOptions.Builder(remoteModel); } else { optionsBuilder = new CustomObjectDetectorOptions.Builder(localModel); } CustomObjectDetectorOptions customObjectDetectorOptions = optionsBuilder .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE) .enableClassification() .setClassificationConfidenceThreshold(0.5f) .setMaxPerObjectLabelCount(3) .build(); ObjectDetector objectDetector = ObjectDetection.getClient(customObjectDetectorOptions); } });
Yalnızca uzaktan barındırılan bir modeliniz varsa modelin indirildiğini onaylayana kadar modelle ilgili işlevleri (örneğin, devre dışı bırakma veya kullanıcı arayüzünüzün bir bölümünü gizleme) devre dışı bırakmanız gerekir. Bunu, model yöneticisinin download()
yöntemine işleyici ekleyerek yapabilirsiniz:
Kotlin
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener { // Download complete. Depending on your app, you could enable the ML // feature, or switch from the local model to the remote model, etc. }
Java
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Void v) { // Download complete. Depending on your app, you could enable // the ML feature, or switch from the local model to the remote // model, etc. } });
3. Giriş görüntüsünü hazırlama
Resminizden birInputImage
nesnesi oluşturun.
Nesne algılayıcı, doğrudan bir Bitmap
, NV21 ByteBuffer
veya YUV_420_888 media.Image
kaynağından çalışır. Bu kaynaklardan birine doğrudan erişiminiz varsa bu kaynaklardan bir InputImage
oluşturmanız önerilir. Diğer kaynaklardan bir InputImage
oluşturursanız dönüşümü sizin için dahili olarak gerçekleştiririz ve bu daha az verimli olabilir.
Farklı kaynaklardan bir InputImage
nesnesi oluşturabilirsiniz. Her biri aşağıda açıklanmıştır.
media.Image
kullanma
media.Image
nesnesinden InputImage
nesnesi oluşturmak için (örneğin, bir cihazın kamerasından görüntü yakaladığınızda) media.Image
nesnesini ve resmin dönüşünü InputImage.fromMediaImage()
parametresine geçirin.
KameraX kitaplığını kullanırsanız OnImageCapturedListener
ve ImageAnalysis.Analyzer
sınıfları, rotasyon değerini sizin için hesaplar.
Kotlin
private class YourImageAnalyzer : ImageAnalysis.Analyzer { override fun analyze(imageProxy: ImageProxy) { val mediaImage = imageProxy.image if (mediaImage != null) { val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees) // Pass image to an ML Kit Vision API // ... } } }
Java
private class YourAnalyzer implements ImageAnalysis.Analyzer { @Override public void analyze(ImageProxy imageProxy) { Image mediaImage = imageProxy.getImage(); if (mediaImage != null) { InputImage image = InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees()); // Pass image to an ML Kit Vision API // ... } } }
Resmin dönüş derecesini veren bir kamera kitaplığı kullanmıyorsanız bunu cihazın dönüş derecesinden ve cihazdaki kamera sensörünün yönüne göre hesaplayabilirsiniz:
Kotlin
private val ORIENTATIONS = SparseIntArray() init { ORIENTATIONS.append(Surface.ROTATION_0, 0) ORIENTATIONS.append(Surface.ROTATION_90, 90) ORIENTATIONS.append(Surface.ROTATION_180, 180) ORIENTATIONS.append(Surface.ROTATION_270, 270) } /** * Get the angle by which an image must be rotated given the device's current * orientation. */ @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) @Throws(CameraAccessException::class) private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int { // Get the device's current rotation relative to its "native" orientation. // Then, from the ORIENTATIONS table, look up the angle the image must be // rotated to compensate for the device's rotation. val deviceRotation = activity.windowManager.defaultDisplay.rotation var rotationCompensation = ORIENTATIONS.get(deviceRotation) // Get the device's sensor orientation. val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager val sensorOrientation = cameraManager .getCameraCharacteristics(cameraId) .get(CameraCharacteristics.SENSOR_ORIENTATION)!! if (isFrontFacing) { rotationCompensation = (sensorOrientation + rotationCompensation) % 360 } else { // back-facing rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360 } return rotationCompensation }
Java
private static final SparseIntArray ORIENTATIONS = new SparseIntArray(); static { ORIENTATIONS.append(Surface.ROTATION_0, 0); ORIENTATIONS.append(Surface.ROTATION_90, 90); ORIENTATIONS.append(Surface.ROTATION_180, 180); ORIENTATIONS.append(Surface.ROTATION_270, 270); } /** * Get the angle by which an image must be rotated given the device's current * orientation. */ @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing) throws CameraAccessException { // Get the device's current rotation relative to its "native" orientation. // Then, from the ORIENTATIONS table, look up the angle the image must be // rotated to compensate for the device's rotation. int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation(); int rotationCompensation = ORIENTATIONS.get(deviceRotation); // Get the device's sensor orientation. CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE); int sensorOrientation = cameraManager .getCameraCharacteristics(cameraId) .get(CameraCharacteristics.SENSOR_ORIENTATION); if (isFrontFacing) { rotationCompensation = (sensorOrientation + rotationCompensation) % 360; } else { // back-facing rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360; } return rotationCompensation; }
Daha sonra, media.Image
nesnesini ve döndürme derecesi değerini InputImage.fromMediaImage()
öğesine geçirin:
Kotlin
val image = InputImage.fromMediaImage(mediaImage, rotation)
Java
InputImage image = InputImage.fromMediaImage(mediaImage, rotation);
Dosya URI'si kullanma
Dosya URI'sinden bir InputImage
nesnesi oluşturmak için uygulama bağlamını ve dosya URI'sini InputImage.fromFilePath()
öğesine iletin. Bu, kullanıcıdan galeri uygulamasından bir resim seçmesini istemek için bir ACTION_GET_CONTENT
amacı kullandığınızda faydalıdır.
Kotlin
val image: InputImage try { image = InputImage.fromFilePath(context, uri) } catch (e: IOException) { e.printStackTrace() }
Java
InputImage image; try { image = InputImage.fromFilePath(context, uri); } catch (IOException e) { e.printStackTrace(); }
ByteBuffer
veya ByteArray
kullanma
ByteBuffer
veya ByteArray
kaynağından InputImage
nesnesi oluşturmak için önce resim döndürme derecesini, daha önce media.Image
girişi için açıklandığı gibi hesaplayın.
Ardından, resmin yüksekliği, genişliği, renk kodlama biçimi ve döndürme derecesiyle birlikte arabellek veya diziyi içeren InputImage
nesnesini oluşturun:
Kotlin
val image = InputImage.fromByteBuffer( byteBuffer, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 ) // Or: val image = InputImage.fromByteArray( byteArray, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 )
Java
InputImage image = InputImage.fromByteBuffer(byteBuffer, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 ); // Or: InputImage image = InputImage.fromByteArray( byteArray, /* image width */480, /* image height */360, rotation, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 );
Bitmap
kullanma
Bitmap
nesnesinden InputImage
nesnesi oluşturmak için aşağıdaki beyanı yapın:
Kotlin
val image = InputImage.fromBitmap(bitmap, 0)
Java
InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
Resim, döndürme dereceleriyle birlikte bir Bitmap
nesnesiyle temsil edilir.
4. Nesne algılayıcıyı çalıştırın
Kotlin
objectDetector .process(image) .addOnFailureListener(e -> {...}) .addOnSuccessListener(results -> { for (detectedObject in results) { // ... } });
Java
objectDetector .process(image) .addOnFailureListener(e -> {...}) .addOnSuccessListener(results -> { for (DetectedObject detectedObject : results) { // ... } });
5. Etiketli nesneler hakkında bilgi alma
process()
çağrısı başarılı olursa başarılı dinleyiciye bir DetectedObject
listesi iletilir.
Her DetectedObject
aşağıdaki özellikleri içerir:
Sınırlayıcı kutu | Resimdeki nesnenin konumunu belirten bir Rect . |
||||||
İzleme Kimliği | Nesneyi görüntüler arasında tanımlayan bir tam sayı. SINGLE_IMAGE_MODE boş. | ||||||
Etiketler |
|
Kotlin
// The list of detected objects contains one item if multiple // object detection wasn't enabled. for (detectedObject in results) { val boundingBox = detectedObject.boundingBox val trackingId = detectedObject.trackingId for (label in detectedObject.labels) { val text = label.text val index = label.index val confidence = label.confidence } }
Java
// The list of detected objects contains one item if multiple // object detection wasn't enabled. for (DetectedObject detectedObject : results) { Rect boundingBox = detectedObject.getBoundingBox(); Integer trackingId = detectedObject.getTrackingId(); for (Label label : detectedObject.getLabels()) { String text = label.getText(); int index = label.getIndex(); float confidence = label.getConfidence(); } }
Mükemmel bir kullanıcı deneyimi sağlama
En iyi kullanıcı deneyimi için uygulamanızda aşağıdaki yönergeleri uygulayın:
- Nesnenin başarılı bir şekilde algılanması, nesnenin görsel karmaşıklığına bağlıdır. Az sayıda görsel özelliğe sahip nesnelerin algılanmaları için resmin daha büyük bir bölümünü kaplamaları gerekebilir. Kullanıcılara, algılamak istediğiniz nesne türlerinde iyi çalışan girdileri yakalama konusunda yol göstermeniz gerekir.
- Sınıflandırma kullanırken, desteklenen kategorilere düzgün bir şekilde girmeyen nesneleri algılamak isterseniz bilinmeyen nesneler için özel işlem uygulayın.
Ayrıca, ML Kiti Materyal Tasarım vitrin uygulamasına ve Materyal Tasarım Makine öğrenimi destekli özellikler için kalıplar koleksiyonuna göz atın.
Performansı artırma
Nesne algılamayı gerçek zamanlı bir uygulamada kullanmak istiyorsanız en iyi kare hızlarına ulaşmak için şu yönergeleri uygulayın:Çoğu cihaz yeterli kare hızı üretemeyeceğinden gerçek zamanlı bir uygulamada akış modunu kullanırken birden fazla nesne algılamayı kullanmayın.
Camera
veyacamera2
API kullanıyorsanız algılayıcıya yapılan çağrıları kısıtlayın. Algılayıcı çalışırken yeni bir video karesi kullanılabilir hale gelirse kareyi bırakın. Örnek için hızlı başlangıç örnek uygulamasındakiVisionProcessorBase
sınıfına bakın.CameraX
API'yi kullanıyorsanız geri basınç stratejisinin varsayılan değere (ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
) ayarlandığından emin olun. Bu, analiz için tek seferde yalnızca bir resmin teslim edileceğini garanti eder. Analiz aracı meşgulken daha fazla görüntü oluşturulursa bu resimler otomatik olarak bırakılır ve gönderim için sıraya alınmaz. Analiz edilen resim, ImageProxy.close() çağrısı yapılarak kapatıldıktan sonra bir sonraki en son resim gönderilir.- Algılayıcının çıkışını giriş görüntüsünün üzerine grafik yerleştirmek için kullanırsanız önce sonucu ML Kit'ten alın, ardından görüntüyü tek bir adımda oluşturun ve yer paylaşımlı yapın. Bu işlem, her giriş karesi için görüntü yüzeyinde yalnızca bir kez oluşturulur. Örnek için hızlı başlangıç örnek uygulamasındaki
CameraSourcePreview
veGraphicOverlay
sınıflarına bakın. - Camera2 API'yi kullanıyorsanız görüntüleri
ImageFormat.YUV_420_888
biçiminde yakalayın. Eski Camera API'yi kullanıyorsanız görüntüleriImageFormat.NV21
biçiminde yakalayın.