Gdy przekazujesz obraz do narzędzia ML Kit, wykrywa on do 5 obiektów razem z pozycją każdego z nich. Przy wykrywaniu obiektów w strumieniach wideo każdy obiekt ma unikalny identyfikator, za pomocą którego można go śledzić od początku do klatki.
Do sklasyfikowania wykrytych obiektów możesz użyć niestandardowego modelu klasyfikacji obrazów. W artykule Modele niestandardowe z użyciem ML Kit dowiesz się, jakie są wymagania dotyczące zgodności modeli, gdzie znaleźć wytrenowane modele i jak trenować własne modele.
Model niestandardowy można zintegrować na 2 sposoby. Możesz połączyć model, umieszczając go w folderze zasobów aplikacji lub pobrać dynamicznie z Firebase. Tabela poniżej zawiera porównanie obu opcji.
Model w pakiecie | Model hostowany |
---|---|
Model jest częścią pliku APK aplikacji, co zwiększa swój rozmiar. | Ten model nie jest częścią Twojego pliku APK. Jest on hostowany przez przesłanie go do systemów uczących się Firebase. |
Model jest dostępny natychmiast, nawet jeśli urządzenie z Androidem jest offline. | Model jest pobierany na żądanie |
Nie potrzebujesz projektu Firebase | Wymaga projektu Firebase |
Aby zaktualizować model, musisz ponownie opublikować aplikację | Przesyłaj aktualizacje modelu bez ponownego publikowania aplikacji |
Brak wbudowanych testów A/B | łatwe testy A/B dzięki Zdalnej konfiguracji Firebase. |
Wypróbuj
- W krótkim wprowadzeniu do aplikacji Vision znajdziesz przykład użycia modelu w pakiecie, a w aplikacji z krótkim wprowadzeniem do Automl – przykład użycia hostowanego modelu.
- Pełną implementację tego interfejsu API znajdziesz w aplikacji Material Design z funkcją prezentacji.
Zanim zaczniesz
Pamiętaj, aby w sekcji
buildscript
iallprojects
w plikubuild.gradle
na poziomie projektu uwzględnić repozytorium Google Maven.Dodaj zależności dla bibliotek ML Kit na Androida do pliku Gradle na poziomie modułu. Ma on zwykle postać
app/build.gradle
:Aby dodać model do pakietu z aplikacją:
dependencies { // ... // Object detection & tracking feature with custom bundled model implementation 'com.google.mlkit:object-detection-custom:17.0.1' }
Aby dynamicznie pobierać model z Firebase, dodaj zależność
linkFirebase
:dependencies { // ... // Object detection & tracking feature with model downloaded // from firebase implementation 'com.google.mlkit:object-detection-custom:17.0.1' implementation 'com.google.mlkit:linkfirebase:17.0.0' }
Jeśli chcesz pobrać model, dodaj Firebase do swojego projektu na Androida, jeśli jeszcze tego nie zrobiłeś. Nie jest to wymagane podczas pakowania modelu.
1. Wczytywanie modelu
Skonfiguruj źródło modelu lokalnego
Aby połączyć model z aplikacją:
Skopiuj plik modelu (zwykle kończący się znakami
.tflite
lub.lite
) do folderuassets/
aplikacji. Być może najpierw trzeba będzie utworzyć folder. Aby to zrobić, kliknij prawym przyciskiem myszy folderapp/
, a następnie kliknij Nowy > Folder > Folder zasobów.Następnie dodaj do pliku
build.gradle
swojej aplikacji ten kod, aby Gradle nie kompresowała pliku modelu podczas tworzenia aplikacji:android { // ... aaptOptions { noCompress "tflite" // or noCompress "lite" } }
Plik modelu zostanie dołączony do pakietu aplikacji i będzie dostępny dla ML Kit jako nieprzetworzony zasób.
Utwórz obiekt
LocalModel
, podając ścieżkę do pliku modelu: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();
Skonfiguruj źródło modelu hostowane w Firebase
Aby użyć modelu hostowanego zdalnie, utwórz obiekt CustomRemoteModel
przez FirebaseModelSource
, podając nazwę przypisaną do modelu podczas jego publikowania:
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();
Następnie rozpocznij zadanie pobierania modelu, określając warunki, które mają mieć możliwość pobierania. Jeśli modelu nie ma na urządzeniu lub dostępna jest jego nowsza wersja, zadanie pobierze asynchronicznie model z Firebase:
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. } });
Wiele aplikacji rozpoczyna zadanie pobierania w kodzie inicjowania, ale możesz to zrobić w dowolnym momencie, zanim zajdzie potrzeba używania modelu.
2. Skonfiguruj detektor obiektów
Po skonfigurowaniu źródeł modelu skonfiguruj detektor obiektów na potrzeby danego przypadku użycia z użyciem obiektu CustomObjectDetectorOptions
. Możesz zmienić
te ustawienia:
Ustawienia funkcji wykrywania obiektów | |
---|---|
Tryb wykrywania |
STREAM_MODE (domyślnie) | SINGLE_IMAGE_MODE
W W |
Wykrywaj i śledź wiele obiektów |
false (domyślnie) | true
Określa, czy wykrywać i śledzić maksymalnie 5 obiektów, czy tylko najbardziej widoczny obiekt (domyślnie). |
Klasyfikowanie obiektów |
false (domyślnie) | true
Określa, czy klasyfikować wykryte obiekty przy użyciu dostarczonego modelu klasyfikatora niestandardowego. Aby użyć własnego modelu klasyfikacji, ustaw wartość |
Próg ufności klasyfikacji |
Minimalny wskaźnik ufności wykrytych etykiet. Jeśli nie skonfigurujesz tej zasady, zostanie użyty dowolny próg klasyfikatora określony przez metadane modelu. Jeśli model nie zawiera żadnych metadanych lub metadane nie określają progu klasyfikatora, zostanie użyty domyślny próg równy 0,0. |
Maksymalna liczba etykiet na obiekt |
Maksymalna liczba etykiet na obiekt, które może zwrócić detektor. Jeśli zasada nie jest skonfigurowana, używana jest wartość domyślna, czyli 10. |
Interfejs API wykrywania i śledzenia jest zoptymalizowany pod kątem tych 2 głównych przypadków użycia:
- Wykrywanie na żywo i śledzenie najbardziej widocznego obiektu w wizjerze kamery.
- Wykrywanie wielu obiektów na obrazie statycznym.
Aby skonfigurować interfejs API pod kątem tych przypadków użycia za pomocą modelu dołączonego lokalnie:
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);
Jeśli masz model hostowany zdalnie, przed jego uruchomieniem musisz sprawdzić, czy został on pobrany. Stan zadania pobierania modelu możesz sprawdzić za pomocą metody isModelDownloaded()
menedżera modeli.
Musisz to potwierdzić przed uruchomieniem wzorca, ale jeśli używasz zarówno modelu hostowanego zdalnie, jak i modelu dołączonego lokalnie, warto wykonać tę procedurę przy tworzeniu wystąpienia wzorca do wykrywania obrazów: utwórz detektor z modelu zdalnego (jeśli został pobrany, lub z modelu lokalnego).
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); } });
Jeśli masz tylko model hostowany zdalnie, wyłącz związane z nim funkcje – na przykład wyszarz lub ukryj część interfejsu użytkownika, dopóki nie potwierdzisz, że model został pobrany. Aby to zrobić, dołącz odbiornik do metody download()
menedżera modeli:
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. Przygotuj obraz wejściowy
Utwórz obiektInputImage
z obrazu.
Detektor obiektów działa bezpośrednio z interfejsów Bitmap
, NV21 ByteBuffer
lub YUV_420_888 media.Image
. Zalecamy utworzenie obiektu InputImage
z tych źródeł, jeśli masz do niego bezpośredni dostęp. Jeśli utworzysz InputImage
na podstawie innych źródeł, zrobimy to wewnętrznie za Ciebie, co może być mniej efektywne.
Obiekt InputImage
możesz utworzyć z różnych źródeł. Poniżej objaśniamy każde z nich.
Przy użyciu: media.Image
Aby utworzyć obiekt InputImage
z obiektu media.Image
, na przykład podczas przechwytywania obrazu aparatem urządzenia, przekaż obiekt media.Image
i ustaw obrót obrazu do wartości InputImage.fromMediaImage()
.
Jeśli używasz biblioteki
CameraX, klasy OnImageCapturedListener
i ImageAnalysis.Analyzer
obliczają za Ciebie wartość rotacji.
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 // ... } } }
Jeśli nie używasz biblioteki aparatu, która określa kąt obrotu obrazu, możesz go obliczyć na podstawie obrotów urządzenia i orientacji czujnika aparatu:
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; }
Następnie przekaż obiekt media.Image
i wartość stopnia obrotu do wartości InputImage.fromMediaImage()
:
Kotlin
val image = InputImage.fromMediaImage(mediaImage, rotation)
Java
InputImage image = InputImage.fromMediaImage(mediaImage, rotation);
Przy użyciu identyfikatora URI pliku
Aby utworzyć obiekt InputImage
na podstawie identyfikatora URI pliku, przekaż kontekst aplikacji i identyfikator URI pliku do InputImage.fromFilePath()
. Jest to przydatne, gdy używasz intencji ACTION_GET_CONTENT
, aby prosić użytkownika o wybranie obrazu z galerii.
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(); }
Przy użyciu: ByteBuffer
lub ByteArray
Aby utworzyć obiekt InputImage
na podstawie ByteBuffer
lub ByteArray
, najpierw oblicz stopień obrotu obrazu w sposób opisany wcześniej dla danych wejściowych media.Image
.
Następnie utwórz obiekt InputImage
z buforem lub tablicą oraz podaj wysokość, szerokość, format kodowania kolorów i stopień obrotu obrazu:
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 );
Przy użyciu: Bitmap
Aby utworzyć obiekt InputImage
z obiektu Bitmap
, złóż tę deklarację:
Kotlin
val image = InputImage.fromBitmap(bitmap, 0)
Java
InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
Obraz jest reprezentowany przez obiekt Bitmap
wraz z stopniami obrotu.
4. Uruchom detektor obiektów
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. Pobieranie informacji o obiektach z etykietami
Jeśli wywołanie process()
zakończy się powodzeniem, lista DetectedObject
zostanie przekazana do detektora sukcesu.
Każdy element DetectedObject
zawiera te właściwości:
Ramka ograniczająca | Rect wskazująca pozycję obiektu na obrazie. |
||||||
Identyfikator śledzenia | Liczba całkowita identyfikująca obiekt na zdjęciach. Wartość null w SINGLE_IMAGE_MODE. | ||||||
Etykiety |
|
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(); } }
Dbanie o wygodę użytkowników
Aby zadbać o wygodę użytkowników, przestrzegaj tych wytycznych:
- Pomyślne wykrywanie obiektów zależy od złożoności wizualnej obiektu. Aby można było wykryć obiekty o niewielkiej liczbie funkcji wizualnych, może być konieczne zajmowanie większej części obrazu. Musisz udostępnić użytkownikom wskazówki dotyczące przechwytywania danych wejściowych, które sprawdzają się w przypadku danego rodzaju obiektów, które chcesz wykrywać.
- Jeśli używasz klasyfikacji i chcesz wykrywać obiekty, które nie należą do poszczególnych kategorii, musisz wdrożyć specjalną obsługę nieznanych obiektów.
Zapoznaj się też z aplikacją do prezentowania w ramach ML Kit Material Design i z kolekcją Wzorców funkcji opartych na systemach uczących się Material Design.
Improving performance
Jeśli chcesz używać wykrywania obiektów w aplikacji w czasie rzeczywistym, postępuj zgodnie z tymi wskazówkami, aby uzyskać najlepszą liczbę klatek na sekundę:W przypadku korzystania z trybu strumieniowego przesyłania danych w aplikacji w czasie rzeczywistym nie używaj wykrywania wielu obiektów. Większość urządzeń nie jest w stanie uzyskać odpowiedniej liczby klatek.
- Jeśli używasz interfejsu API
Camera
lubcamera2
, ograniczaj wywołania wzorca. Jeśli podczas działania wzorca pojawi się nowa ramka wideo, upuść ją. Przykład znajdziesz w klasieVisionProcessorBase
w przykładowej aplikacji z krótkim wprowadzeniem. - Jeśli używasz interfejsu API
CameraX
, sprawdź, czy strategia dotycząca wstecznego obciążenia jest ustawiona na wartość domyślnąImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
. Gwarantuje to, że w danym momencie do analizy będzie przesyłany tylko 1 obraz. Jeśli wtedy, gdy analizator jest zajęty, zostanie utworzonych więcej obrazów, zostaną one automatycznie usunięte i nie zostaną dodane do kolejki do dostarczenia. Po zamknięciu analizowanego obrazu za pomocą wywołania ImageProxy.close() dostarczany jest następny najnowszy obraz. - Jeśli używasz danych wyjściowych wzorca do nakładania grafiki na obraz wejściowy, najpierw pobierz wynik z ML Kit, a następnie wyrenderuj obraz i nakładkę w jednym kroku. Wyświetla się ona tylko raz na każdą klatkę wejściową. Przykład znajdziesz w klasach
CameraSourcePreview
iGraphicOverlay
w przykładowej aplikacji krótkiego wprowadzenia. - Jeśli korzystasz z interfejsu Camera2 API, rób zdjęcia w formacie
ImageFormat.YUV_420_888
. Jeśli używasz starszej wersji interfejsu Camera API, zrób zdjęcia w formacieImageFormat.NV21
.