ติดป้ายกำกับรูปภาพด้วยโมเดลที่กำหนดเองใน Android

คุณสามารถผสานรวมการติดป้ายกำกับรูปภาพกับโมเดลที่กำหนดเองได้ 2 วิธี ได้แก่ การรวมไปป์ไลน์เป็นส่วนหนึ่งของแอป หรือใช้ไปป์ไลน์ที่แยกออกมาซึ่งขึ้นอยู่กับบริการ Google Play หากเลือกไปป์ไลน์ที่แยกออกมา แอปจะมีขนาดเล็กลง ดูรายละเอียดในตารางต่อไปนี้

คุณสามารถผสานรวมโมเดลที่กำหนดเองได้ 2 วิธี ได้แก่ การรวมโมเดลโดยใส่ไว้ในโฟลเดอร์ชิ้นงานของแอป หรือดาวน์โหลดแบบไดนามิกจาก Firebase ตารางต่อไปนี้เปรียบเทียบ 2 ตัวเลือกนี้

ลองเลย

• ดูตัวอย่างการใช้งานโมเดลที่รวมกลุ่มได้ที่แอปเริ่มต้นใช้งานวิชันซิสเต็ม และดูตัวอย่างการใช้งานโมเดลที่โฮสต์ได้ที่แอปเริ่มต้นใช้งาน AutoML

ก่อนเริ่มต้น

1. ในไฟล์ build.gradle.kts ระดับโปรเจ็กต์ ให้ตรวจสอบว่าได้รวมที่เก็บ Maven ของ Google ไว้ในส่วน buildscript และ allprojects

2. เพิ่มทรัพยากร Dependency สำหรับไลบรารี ML Kit สำหรับ Android ลงในไฟล์ Gradle ระดับแอปของโมดูล ซึ่งโดยปกติจะเป็นไฟล์ app/build.gradle.kts เลือกทรัพยากร Dependency รายการใดรายการหนึ่งต่อไปนี้ตามความต้องการ

   สำหรับการรวมไปป์ไลน์กับแอป

   dependencies {
     // ...
     // Use this dependency to bundle the pipeline with your app
     implementation("com.google.mlkit:image-labeling-custom:17.0.3")
   }
   

   สำหรับการใช้ไปป์ไลน์ในบริการ Google Play

   dependencies {
     // ...
     // Use this dependency to use the dynamically downloaded pipeline in Google Play services
     implementation("com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5")
   }
   

3. หากเลือกใช้ไปป์ไลน์ในบริการ Google Play คุณสามารถ กำหนดค่าแอปให้ดาวน์โหลดไปป์ไลน์ลงในอุปกรณ์โดยอัตโนมัติ หลังจากติดตั้งแอปจาก Play Store หากต้องการทำเช่นนั้น ให้เพิ่มการประกาศต่อไปนี้ลงในไฟล์ AndroidManifest.xml ของแอป

   <application ...>
       ...
       <meta-data
           android:name="com.google.mlkit.vision.DEPENDENCIES"
           android:value="custom_ica" />
       <!-- To use multiple downloads: android:value="custom_ica,download2,download3" -->
   </application>
   

   นอกจากนี้ คุณยังตรวจสอบความพร้อมใช้งานของไปป์ไลน์และขอให้ดาวน์โหลด ผ่าน บริการ Google Play ModuleInstallClient API ได้ด้วย

   หากคุณไม่ได้เปิดใช้การดาวน์โหลดไปป์ไลน์ในระหว่างการติดตั้งหรือขอให้ดาวน์โหลดอย่างชัดเจน ระบบจะดาวน์โหลดไปป์ไลน์เมื่อคุณเรียกใช้ตัวติดป้ายกำกับเป็นครั้งแรก คำขอที่คุณส่งก่อนที่การดาวน์โหลดจะเสร็จสมบูรณ์จะไม่แสดงผลลัพธ์

4. หากต้องการดาวน์โหลดโมเดลโดยใช้ Cloud Storage สำหรับ Firebase ให้ ตรวจสอบว่าคุณ ได้เพิ่ม Firebase ลงในโปรเจ็กต์ Android แล้ว หากยังไม่ได้ดำเนินการ การดำเนินการนี้ไม่จำเป็นเมื่อคุณรวม โมเดล

1. โหลดโมเดล

คุณสามารถโหลดโมเดลจากแหล่งที่มาที่รวมกลุ่มไว้ในเครื่องหรือแหล่งที่มาที่โฮสต์จากระยะไกล

กำหนดค่าแหล่งที่มาของโมเดลในเครื่อง

วิธีรวมโมเดลกับแอป

1. คัดลอกไฟล์โมเดล (โดยปกติจะลงท้ายด้วย .tflite หรือ .lite) ไปยังโฟลเดอร์ assets/ ของแอป (คุณอาจต้องสร้างโฟลเดอร์ก่อนโดยคลิกขวาที่โฟลเดอร์ app/ แล้วคลิกใหม่ > โฟลเดอร์ > โฟลเดอร์ชิ้นงาน)

2. สร้างออบเจ็กต์ LocalModel โดยระบุเส้นทางไปยังไฟล์โมเดล

   Kotlin

   val localModel = LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute path to model file)
           // or .setUri(URI to model file)
           .build()

   Java

   LocalModel localModel =
       new LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute path to model file)
           // or .setUri(URI to model file)
           .build();

กำหนดค่าแหล่งที่มาของโมเดลที่โฮสต์จากระยะไกล

หากต้องการใช้โมเดลที่โฮสต์จากระยะไกล คุณต้องดาวน์โหลดไฟล์โมเดลลงในพื้นที่เก็บข้อมูลในเครื่องของอุปกรณ์โดยใช้ตรรกะของแอปเอง แล้วโหลดเป็นโมเดลในเครื่อง เราขอแนะนำให้ใช้ Cloud Storage for Firebase เพื่อโฮสต์โมเดล ดูรายละเอียดการใช้งานได้ที่ คู่มือการย้ายข้อมูลจาก Firebase ML ไปยัง Cloud Storage

กำหนดค่าตัวติดป้ายกำกับรูปภาพ

หลังจากกำหนดค่าแหล่งที่มาของโมเดลแล้ว ให้สร้างออบเจ็กต์ ImageLabeler จากแหล่งที่มาใดแหล่งที่มาหนึ่ง

โดยมีตัวเลือกดังต่อไปนี้

หากมีเพียงโมเดลที่รวมกลุ่มไว้ในเครื่อง ให้สร้างตัวติดป้ายกำกับจากออบเจ็กต์ LocalModel ดังนี้

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

CustomImageLabelerOptions customImageLabelerOptions =
        new CustomImageLabelerOptions.Builder(localModel)
            .setConfidenceThreshold(0.5f)
            .setMaxResultCount(5)
            .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

หากมีโมเดลที่โฮสต์จากระยะไกล คุณจะต้องตรวจสอบว่าได้ดาวน์โหลดโมเดลแล้วก่อนที่จะดำเนินการ

แม้ว่าคุณจะต้องยืนยันการดาวน์โหลดโมเดลที่โฮสต์จากระยะไกลก่อนเรียกใช้ตัวติดป้ายกำกับเท่านั้น แต่หากมีทั้งโมเดลที่โฮสต์จากระยะไกลและโมเดลที่รวมกลุ่มไว้ในเครื่อง การตรวจสอบนี้เมื่อสร้างอินสแตนซ์ตัวติดป้ายกำกับรูปภาพอาจเป็นเรื่องสมเหตุสมผล กล่าวคือ สร้างตัวติดป้ายกำกับจากโมเดลระยะไกลหากดาวน์โหลดแล้ว และสร้างจากโมเดลในเครื่องหากยังไม่ได้ดาวน์โหลด

val modelFile = File(context.cacheDir, "my_downloaded_model.tflite")
val model = if (modelFile.exists()) {
    // Use the downloaded model if available
    LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
} else {
    // Fall back to the bundled model
    LocalModel.Builder().setAssetFilePath("model.tflite").build()
}
val options = CustomImageLabelerOptions.Builder(model)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(options)

File modelFile = new File(context.getCacheDir(), "my_downloaded_model.tflite");
LocalModel model;
if (modelFile.exists()) {
    // Use the downloaded model if available
    model = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
} else {
    // Fall back to the bundled model
    model = new LocalModel.Builder().setAssetFilePath("model.tflite").build();
}
CustomImageLabelerOptions options = new CustomImageLabelerOptions.Builder(model)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build();
ImageLabeler labeler = ImageLabeling.getClient(options);

หากมีเพียงโมเดลที่โฮสต์จากระยะไกล คุณควรปิดใช้ฟังก์ชันการทำงานที่เกี่ยวข้องกับโมเดล เช่น ทำให้ส่วนหนึ่งของ UI เป็นสีเทาหรือซ่อนไว้ จนกว่าจะยืนยันว่าได้ดาวน์โหลดโมเดลแล้ว

val localFile = File(context.cacheDir, "my_remote_model.tflite")
if (localFile.exists()) {
    initializeLabeler(localFile)
} else {
    showLoadingUI()
    val storage = Firebase.storage
    val modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite")
    modelRef.getFile(localFile)
        .addOnSuccessListener {
            hideLoadingUI()
            initializeLabeler(localFile)
        }
        .addOnFailureListener {
            showErrorUI()
        }
}

private fun initializeLabeler(modelFile: File) {
    val localModel = LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
    val options = CustomImageLabelerOptions.Builder(localModel).build()
    val labeler = ImageLabeling.getClient(options)
    enableMLFeatures(labeler)
}

File localFile = new File(context.getCacheDir(), "my_remote_model.tflite");
if (localFile.exists()) {
    initializeLabeler(localFile);
} else {
    showLoadingUI();
    FirebaseStorage storage = FirebaseStorage.getInstance();
    StorageReference modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite");
    modelRef.getFile(localFile)
        .addOnSuccessListener(new OnSuccessListener<FileDownloadTask.TaskSnapshot>() {
            @Override
            public void onSuccess(FileDownloadTask.TaskSnapshot taskSnapshot) {
                hideLoadingUI();
                initializeLabeler(localFile);
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                showErrorUI();
            }
        });
}

private void initializeLabeler(File modelFile) {
    LocalModel localModel = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
    CustomImageLabelerOptions options = new CustomImageLabelerOptions.Builder(localModel).build();
    ImageLabeler labeler = ImageLabeling.getClient(options);
    enableMLFeatures(labeler);
}

2. เตรียมรูปภาพอินพุต

คุณสามารถสร้าง InputImage ออบเจ็กต์จากแหล่งที่มาต่างๆ ซึ่งเราจะอธิบายแต่ละแหล่งที่มาด้านล่าง

การใช้ media.Image

หากต้องการสร้างออบเจ็กต์ InputImage จากออบเจ็กต์ media.Image เช่น เมื่อคุณถ่ายรูปจากกล้องของอุปกรณ์ ให้ส่งออบเจ็กต์ media.Image และการหมุนของรูปภาพไปยัง InputImage.fromMediaImage()

หากคุณใช้ไลบรารี CameraX คลาส OnImageCapturedListener และ ImageAnalysis.Analyzer จะคำนวณค่าการหมุน ให้คุณ

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
            // ...
        }
    }
}

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
          // ...
        }
    }
}

หากคุณไม่ได้ใช้ไลบรารีกล้องที่แสดงองศาการหมุนของรูปภาพ คุณ สามารถคำนวณองศาการหมุนได้จากองศาการหมุนของอุปกรณ์และการวางแนวของเซ็นเซอร์กล้องในอุปกรณ์ ดังนี้

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
}
MLKitVisionImage.kt

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;
}

จากนั้นส่งออบเจ็กต์ media.Image และค่าองศาการหมุนไปยัง InputImage.fromMediaImage() ดังนี้

val image = InputImage.fromMediaImage(mediaImage, rotation)
MLKitVisionImage.kt

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

การใช้ URI ของไฟล์

หากต้องการสร้างออบเจ็กต์ InputImage จาก URI ของไฟล์ ให้ส่งบริบทของแอปและ URI ของไฟล์ไปยัง InputImage.fromFilePath() วิธีนี้มีประโยชน์เมื่อคุณ ใช้ Intent ACTION_GET_CONTENT เพื่อแจ้งให้ผู้ใช้เลือก รูปภาพจากแอปแกลเลอรี

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
MLKitVisionImage.kt

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

การใช้ ByteBuffer หรือ ByteArray

หากต้องการสร้างออบเจ็กต์ InputImage จาก ByteBuffer หรือ ByteArray ให้คำนวณองศาการหมุนของรูปภาพ ก่อนตามที่อธิบายไว้ก่อนหน้านี้สำหรับอินพุต media.Image จากนั้นสร้างออบเจ็กต์ InputImage ด้วยบัฟเฟอร์หรืออาร์เรย์ รวมถึงความสูง ความกว้าง รูปแบบการเข้ารหัสสี และองศาการหมุนของรูปภาพ ดังนี้

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java

การใช้ Bitmap

หากต้องการสร้างออบเจ็กต์ InputImage จากออบเจ็กต์ Bitmap ให้ประกาศดังนี้

val image = InputImage.fromBitmap(bitmap, 0)
MLKitVisionImage.kt

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
MLKitVisionImage.java

รูปภาพจะแสดงด้วยออบเจ็กต์ Bitmap พร้อมองศาการหมุน

3. เรียกใช้ตัวติดป้ายกำกับรูปภาพ

หากต้องการติดป้ายกำกับออบเจ็กต์ในรูปภาพ ให้ส่งออบเจ็กต์ image ไปยังเมธอด process() ของ ImageLabeler

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
ImageLabelingActivity.kt

labeler.process(image)
        .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() {
            @Override
            public void onSuccess(List<ImageLabel> labels) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });
ImageLabelingActivity.java

4. ดูข้อมูลเกี่ยวกับเอนทิตีที่ติดป้ายกำกับ

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}
ImageLabelingActivity.kt

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}
ImageLabelingActivity.java

เคล็ดลับในการปรับปรุงประสิทธิภาพแบบเรียลไทม์

หากต้องการติดป้ายกำกับรูปภาพในแอปพลิเคชันแบบเรียลไทม์ ให้ทำตามหลักเกณฑ์ต่อไปนี้ เพื่อให้ได้อัตราเฟรมที่ดีที่สุด

• หากใช้ Camera หรือ camera2 API ให้ควบคุมการเรียกตัวติดป้ายกำกับรูปภาพ หากเฟรมวิดีโอใหม่ พร้อมใช้งานขณะที่ตัวติดป้ายกำกับรูปภาพกำลังทำงานอยู่ ให้ทิ้งเฟรมนั้น ดูตัวอย่างได้ที่คลาส VisionProcessorBase ในแอปตัวอย่างเริ่มต้นใช้งาน
• หากใช้ CameraX API ให้ตรวจสอบว่าได้ตั้งค่ากลยุทธ์การควบคุมปริมาณข้อมูลย้อนกลับเป็นค่าเริ่มต้น ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST ซึ่งจะรับประกันว่าระบบจะส่งรูปภาพเพียงรูปเดียวสำหรับการวิเคราะห์ในแต่ละครั้ง หากมีการสร้างรูปภาพเพิ่มเติมเมื่อตัววิเคราะห์ไม่ว่าง ระบบจะทิ้งรูปภาพเหล่านั้นโดยอัตโนมัติและไม่จัดคิวเพื่อส่ง เมื่อปิดรูปภาพที่กำลังวิเคราะห์โดยการเรียกใช้ ImageProxy.close() ระบบจะส่งรูปภาพล่าสุดถัดไป
• หากคุณใช้เอาต์พุตของตัวติดป้ายกำกับรูปภาพเพื่อซ้อนทับกราฟิกบน รูปภาพอินพุต ให้รับผลลัพธ์จาก ML Kit ก่อน จากนั้นแสดงรูปภาพ และซ้อนทับในขั้นตอนเดียว ซึ่งจะแสดงบนพื้นผิวการแสดงผล เพียงครั้งเดียวสำหรับแต่ละเฟรมอินพุต ดูตัวอย่างได้ที่คลาส CameraSourcePreview และ GraphicOverlay ในแอปตัวอย่างเริ่มต้นใช้งาน
• หากใช้ Camera2 API ให้ถ่ายรูปในรูปแบบ ImageFormat.YUV_420_888 หากใช้ Camera API รุ่นเก่า ให้ถ่ายรูปใน ImageFormat.NV21 รูปแบบ