ตรวจจับและติดตามวัตถุด้วย ML Kit บน Android

คุณใช้ ML Kit เพื่อตรวจจับและติดตามออบเจ็กต์ในเฟรมวิดีโอที่ต่อเนื่องกันได้

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

API นี้ใช้ไลบรารีที่ไม่ได้รวมไว้ ซึ่งต้องดาวน์โหลดก่อนใช้งาน ดูข้อมูลเพิ่มเติมได้ที่คู่มือนี้

ลองเลย

• ลองใช้แอปตัวอย่างเพื่อดูตัวอย่างการใช้งาน API นี้
• ดูการใช้งาน API นี้ตั้งแต่ต้นจนจบได้ในแอป Material Design Showcase

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

API นี้ต้องใช้ Android API ระดับ 21 ขึ้นไป ตรวจสอบว่าไฟล์บิลด์ของแอป ใช้ค่า minSdkVersion ตั้งแต่ 21 ขึ้นไป

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

   dependencies {
     // ...
   
     implementation 'com.google.mlkit:object-detection:17.0.2'
   
   }

1. กำหนดค่าเครื่องตรวจจับออบเจ็กต์

หากต้องการตรวจหาและติดตามออบเจ็กต์ ให้สร้างอินสแตนซ์ของ ObjectDetector ก่อน และระบุการตั้งค่าเครื่องตรวจจับที่ต้องการเปลี่ยนจากค่าเริ่มต้น (ไม่บังคับ)

1. กำหนดค่าเครื่องตรวจจับออบเจ็กต์สำหรับ Use Case ของคุณด้วยออบเจ็กต์ ObjectDetectorOptions คุณเปลี่ยนการตั้งค่าต่อไปนี้ได้

   การตั้งค่าเครื่องตรวจจับออบเจ็กต์
   โหมดการตรวจหา	STREAM_MODE (ค่าเริ่มต้น) | SINGLE_IMAGE_MODE ใน STREAM_MODE (ค่าเริ่มต้น) เครื่องตรวจจับออบเจ็กต์จะทำงาน โดยมีความหน่วงต่ำ แต่อาจให้ผลลัพธ์ที่ไม่สมบูรณ์ (เช่น กรอบล้อมรอบหรือป้ายกำกับหมวดหมู่ที่ไม่ได้ระบุ) ในการเรียกใช้ เครื่องตรวจจับ 2-3 ครั้งแรก นอกจากนี้ ใน STREAM_MODE เครื่องตรวจจับจะกำหนดรหัสการติดตามให้กับออบเจ็กต์ ซึ่งคุณสามารถใช้เพื่อ ติดตามออบเจ็กต์ในเฟรมต่างๆ ได้ ใช้โหมดนี้เมื่อต้องการติดตามออบเจ็กต์ หรือเมื่อเวลาในการตอบสนองต่ำมีความสำคัญ เช่น เมื่อประมวลผลสตรีมวิดีโอแบบเรียลไทม์ ใน SINGLE_IMAGE_MODE เครื่องตรวจหาออบเจ็กต์จะแสดงผลลัพธ์หลังจากกำหนดกรอบล้อมรอบของออบเจ็กต์แล้ว หากคุณเปิดใช้การแยกประเภทด้วย ระบบจะแสดงผลลัพธ์หลังจากที่ทั้งกรอบล้อมรอบและป้ายกำกับหมวดหมู่พร้อมใช้งาน ด้วยเหตุนี้ เวลาในการตอบสนองของการตรวจจับจึงอาจสูงขึ้น นอกจากนี้ ใน SINGLE_IMAGE_MODE ระบบจะไม่กำหนดรหัสติดตาม ใช้ โหมดนี้หากเวลาในการตอบสนองไม่ใช่เรื่องสำคัญและคุณไม่ต้องการจัดการกับ ผลลัพธ์บางส่วน
   ตรวจจับและติดตามวัตถุหลายรายการ	false (ค่าเริ่มต้น) | true เลือกว่าจะตรวจหาและติดตามวัตถุสูงสุด 5 รายการหรือเฉพาะวัตถุที่โดดเด่นที่สุด (ค่าเริ่มต้น)
   จัดประเภทออบเจ็กต์	false (ค่าเริ่มต้น) | true จะจัดประเภทออบเจ็กต์ที่ตรวจพบเป็นหมวดหมู่คร่าวๆ หรือไม่ เมื่อเปิดใช้ เครื่องตรวจจับออบเจ็กต์จะจัดประเภทออบเจ็กต์เป็นหมวดหมู่ต่อไปนี้ สินค้าแฟชั่น อาหาร ของใช้ในบ้าน สถานที่ และพืช

   API การตรวจจับและติดตามวัตถุได้รับการเพิ่มประสิทธิภาพสำหรับกรณีการใช้งานหลัก 2 กรณีต่อไปนี้

   • การตรวจจับและติดตามวัตถุที่โดดเด่นที่สุดในช่องมองภาพของกล้องแบบเรียลไทม์
   • การตรวจจับวัตถุหลายรายการจากภาพนิ่ง

   วิธีกำหนดค่า API สำหรับกรณีการใช้งานเหล่านี้

   Kotlin

   // Live detection and tracking
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
           .enableClassification()  // Optional
           .build()
   
   // Multiple object detection in static images
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
           .enableMultipleObjects()
           .enableClassification()  // Optional
           .build()

   Java

   // Live detection and tracking
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
                   .enableClassification()  // Optional
                   .build();
   
   // Multiple object detection in static images
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
                   .enableMultipleObjects()
                   .enableClassification()  // Optional
                   .build();

2. รับอินสแตนซ์ของ ObjectDetector

   Kotlin

   val objectDetector = ObjectDetection.getClient(options)

   Java

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

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

หากต้องการตรวจหาและติดตามออบเจ็กต์ ให้ส่งรูปภาพไปยังเมธอด process() ของObjectDetectorอินสแตนซ์

เครื่องตรวจจับออบเจ็กต์จะทำงานโดยตรงจาก Bitmap, NV21 ByteBuffer หรือ YUV_420_888 media.Image ขอแนะนำให้สร้าง InputImage จากแหล่งที่มาเหล่านั้น หากคุณมีสิทธิ์เข้าถึงแหล่งที่มาใดแหล่งที่มาหนึ่งโดยตรง หากคุณสร้าง InputImage จากแหล่งที่มาอื่นๆ เราจะจัดการ Conversion ภายในให้คุณ ซึ่งอาจมีประสิทธิภาพน้อยกว่า

สำหรับแต่ละเฟรมของวิดีโอหรือรูปภาพในลำดับ ให้ทำดังนี้

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

การใช้ media.Image

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

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

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

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

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

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

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

Kotlin

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

Java

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

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

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

Kotlin

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

Java

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

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

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

Kotlin

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

Java

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 ให้ประกาศดังนี้

Kotlin

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

Java

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

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

3. ประมวลผลรูปภาพ

ส่งรูปภาพไปยังเมธอด process()

Kotlin

objectDetector.process(image)
    .addOnSuccessListener { detectedObjects ->
        // Task completed successfully
        // ...
    }
    .addOnFailureListener { e ->
        // Task failed with an exception
        // ...
    }

Java

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

หมายเหตุ: หากคุณใช้ CameraX API อย่าลืมปิด ImageProxy เมื่อใช้งานเสร็จแล้ว เช่น โดยการเพิ่ม OnCompleteListener ลงใน Task ที่ส่งคืนจาก เมธอด process ดูตัวอย่างได้ที่คลาส VisionProcessorBase ในแอปตัวอย่างฉบับเริ่มต้น

4. ดูข้อมูลเกี่ยวกับออบเจ็กต์ที่ตรวจพบ

หากการเรียก process() สำเร็จ ระบบจะส่งรายการ DetectedObject ไปยัง เครื่องมือฟังที่สำเร็จ

หมายเหตุ: ในโหมดสตรีมมิง ตัวตรวจหาวัตถุอาจต้องประมวลผลเฟรม 30 เฟรมขึ้นไป ทั้งนี้ขึ้นอยู่กับประสิทธิภาพของอุปกรณ์ ก่อนที่จะตรวจหาวัตถุแรก

DetectedObject แต่ละรายการมีพร็อพเพอร์ตี้ต่อไปนี้

กรอบล้อมรอบ	Rect ที่ระบุตำแหน่งของออบเจ็กต์ใน รูปภาพ
รหัสติดตาม	จำนวนเต็มที่ระบุออบเจ็กต์ในรูปภาพ Null ใน SINGLE_IMAGE_MODE
ป้ายกำกับ	คำอธิบายป้ายกำกับ ข้อความอธิบายป้ายกำกับ ซึ่งจะเป็นค่าคงที่ String ค่าใดค่าหนึ่งที่กำหนดไว้ใน PredefinedCategory ดัชนีป้ายกำกับ ดัชนีของป้ายกำกับในบรรดาป้ายกำกับทั้งหมดที่ตัวแยกประเภท รองรับ ซึ่งจะเป็นค่าคงที่จำนวนเต็มค่าใดค่าหนึ่งที่กำหนดไว้ ใน PredefinedCategory ความน่าเชื่อถือของป้ายกำกับ ค่าความเชื่อมั่นของการจัดประเภทออบเจ็กต์

Kotlin

for (detectedObject in detectedObjects) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
        val text = label.text
        if (PredefinedCategory.FOOD == text) {
            ...
        }
        val index = label.index
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        val confidence = label.confidence
    }
}

Java

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : detectedObjects) {
    Rect boundingBox = detectedObject.getBoundingBox();
    Integer trackingId = detectedObject.getTrackingId();
    for (Label label : detectedObject.getLabels()) {
        String text = label.getText();
        if (PredefinedCategory.FOOD.equals(text)) {
            ...
        }
        int index = label.getIndex();
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        float confidence = label.getConfidence();
    }
}

การรับประกันประสบการณ์ของผู้ใช้ที่ยอดเยี่ยม

โปรดปฏิบัติตามหลักเกณฑ์ต่อไปนี้ในแอปเพื่อให้ผู้ใช้ได้รับประสบการณ์ที่ดีที่สุด

• การตรวจจับวัตถุที่สำเร็จจะขึ้นอยู่กับความซับซ้อนของภาพของวัตถุ ใน การตรวจหา วัตถุที่มีฟีเจอร์ภาพจำนวนน้อยอาจต้อง ใช้พื้นที่ส่วนใหญ่ของรูปภาพ คุณควรให้คำแนะนำแก่ผู้ใช้เกี่ยวกับ การบันทึกอินพุตที่ทำงานได้ดีกับออบเจ็กต์ประเภทที่คุณต้องการตรวจหา
• เมื่อใช้การแยกประเภท หากต้องการตรวจจับออบเจ็กต์ที่ไม่ได้อยู่ในหมวดหมู่ที่รองรับอย่างชัดเจน ให้ใช้การจัดการพิเศษสำหรับออบเจ็กต์ที่ไม่รู้จัก

นอกจากนี้ โปรดดู แอปสาธิต Material Design ของ ML Kit และคอลเล็กชัน Material Design รูปแบบสำหรับฟีเจอร์ที่ทำงานด้วยแมชชีนเลิร์นนิง

Improving performance

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

• เมื่อใช้โหมดการสตรีมในแอปพลิเคชันแบบเรียลไทม์ อย่าใช้การตรวจหาออบเจ็กต์หลายรายการ เนื่องจากอุปกรณ์ส่วนใหญ่ไม่สามารถสร้างอัตราเฟรมที่เพียงพอได้

• ปิดใช้การแยกประเภทหากไม่ต้องการ

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