رصد معلومات تداخل الوجه باستخدام أدوات تعلّم الآلة على Android

يتم توفير واجهة برمجة التطبيقات هذه في إصدار تجريبي، ولا تخضع لأي سياسة إيقاف أو اتفاقية مستوى الخدمة. يمكن إجراء تغييرات على واجهة برمجة التطبيقات هذه تؤدي إلى إلغاء التوافق مع الأنظمة القديمة.

يمكنك استخدام مجموعة أدوات تعلّم الآلة لرصد الوجوه في الصور والفيديوهات التي تشبه السيلفي.

تستخدم واجهة برمجة التطبيقات هذه مكتبة مجمَّعة لزيادة حجم تطبيقك. يمكنك الاطّلاع على هذا الدليل للحصول على مزيد من المعلومات.

واجهة برمجة التطبيقات لاكتشاف شبكات الوجه
اسم حزمة SDK	face-mesh-detection
التنفيذ	يتم ربط الرمز ومواد العرض بشكلٍ ثابت بتطبيقك في وقت الإصدار.
تأثير حجم التطبيق	6.4 ميغابايت تقريبًا
عروض أداء	عرض الوقت الفعلي على معظم الأجهزة

التجربة الآن

• يمكنك تجربة نموذج التطبيق للاطّلاع على مثال على استخدام واجهة برمجة التطبيقات هذه.

قبل البدء

تتطلّب واجهة برمجة التطبيقات هذه المستوى 21 أو أعلى من واجهة برمجة تطبيقات Android. تأكَّد من أنّ ملف إصدار تطبيقك يستخدم القيمة 21 أو قيمة أعلى من minSdkVersion.

1. في ملف build.gradle على مستوى المشروع، تأكَّد من تضمين مستودع Maven من Google في قسمَي "النص البرمجي" و"جميع المشاريع".

2. أضِف الاعتمادية لمكتبة اكتشاف شبكات الوجوه في أدوات تعلُّم الآلة إلى ملف Gradle على مستوى التطبيق الخاص بالوحدة، والذي يكون عادةً app/build.gradle:

   dependencies {
    // ...
   
    implementation 'com.google.mlkit:face-mesh-detection:16.0.0-beta1'
   }
   

إرشادات إدخال الصور

1. يجب التقاط الصور على بُعد مترين تقريبًا من كاميرا الجهاز، لتكون الوجوه كبيرة بما يكفي للتعرّف على أفضل شبكات للوجه. بشكل عام، كلما زاد حجم الوجه، كانت ميزة التعرف على الشبكة المتداخلة أفضل.

2. يجب أن يكون الوجه مواجهًا للكاميرا مع إظهار نصف الوجه على الأقل. قد يؤدي وجود أي جسم كبير بين الوجه والكاميرا إلى انخفاض الدقة.

إذا كنت ترغب في اكتشاف الوجوه في تطبيق الوقت الفعلي، فينبغي عليك أيضًا مراعاة الأبعاد العامة للصورة التي تم إدخالها. يمكن معالجة الصور الأصغر بشكلٍ أسرع، وبالتالي فإن التقاط الصور بدرجات دقة أقل يقلل من وقت الاستجابة. ومع ذلك، ضع في اعتبارك متطلبات الدقة الواردة أعلاه وتأكد من أن وجه الشخص يشغل أكبر قدر ممكن من الصورة.

ضبط أداة رصد شبكات الوجه

إذا أردت تغيير أي من الإعدادات التلقائية لأداة رصد الشبكات المتداخلة للوجه، حدِّد هذه الإعدادات باستخدام كائن FaceMeshDetectorOptions. يمكنك تغيير الإعدادات التالية:

1. setUseCase

   • BOUNDING_BOX_ONLY: لا يقدّم سوى مربّع حدود لشبكة وجه تم رصدها. هذا هو أسرع جهاز كشف للوجه، ولكن مع حدود النطاق(يجب أن تكون الوجوه في نطاق مترين تقريبًا أو حوالي 7 أقدام من الكاميرا).

   • FACE_MESH (الخيار التلقائي): يوفِّر هذا الخيار مربّع حدود ومعلومات إضافية عن شبكة الوجوه (معلومات عن 468 نقطة ثلاثية الأبعاد ومثلثات). عند المقارنة بحالة استخدام BOUNDING_BOX_ONLY، يزيد وقت الاستجابة بنسبة %15 تقريبًا وفقًا لما تم قياسه على Pixel 3.

مثلاً:

Kotlin

val defaultDetector = FaceMeshDetection.getClient(
  FaceMeshDetectorOptions.DEFAULT_OPTIONS)

val boundingBoxDetector = FaceMeshDetection.getClient(
  FaceMeshDetectorOptions.Builder()
    .setUseCase(UseCase.BOUNDING_BOX_ONLY)
    .build()
)

Java

FaceMeshDetector defaultDetector =
        FaceMeshDetection.getClient(
                FaceMeshDetectorOptions.DEFAULT_OPTIONS);

FaceMeshDetector boundingBoxDetector = FaceMeshDetection.getClient(
        new FaceMeshDetectorOptions.Builder()
                .setUseCase(UseCase.BOUNDING_BOX_ONLY)
                .build()
        );

تحضير صورة الإدخال

لرصد الوجوه في إحدى الصور، أنشِئ عنصر InputImage من Bitmap أو media.Image أو ByteBuffer أو مصفوفة بايت أو ملف على الجهاز. وبعد ذلك، مرِّر الكائن InputImage إلى طريقة process في FaceDetector.

لاكتشاف شبكات الوجه المتداخلة، يجب استخدام صورة بأبعاد لا تقل عن 480×360 بكسل. إذا كنت تستكشف الوجوه في الوقت الفعلي، يمكن أن يساعد التقاط الإطارات بدرجة الدقة الأدنى هذه في تقليل وقت الاستجابة.

يمكنك إنشاء كائن 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 لتطلب من المستخدم اختيار صورة من تطبيق معرض الصور.

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 مع درجات التدوير.

معالجة الصورة

تمرير الصورة إلى طريقة process:

Kotlin

val result = detector.process(image)
        .addOnSuccessListener { result ->
            // Task completed successfully
            // …
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // …
        }

Java

Task<List<FaceMesh>> result = detector.process(image)
        .addOnSuccessListener(
                new OnSuccessListener<List<FaceMesh>>() {
                    @Override
                    public void onSuccess(List<FaceMesh> result) {
                        // Task completed successfully
                        // …
                    }
                })
        .addOnFailureListener(
                new OnFailureListener() {
                    @Override
                    Public void onFailure(Exception e) {
                        // Task failed with an exception
                        // …
                    }
                });

الحصول على معلومات عن شبكة الوجه التي تم رصدها

إذا تم رصد أي وجه في الصورة، يتم تمرير قائمة بكائنات FaceMesh إلى مستمعي النجاح. تُمثِّل كل سمة FaceMesh وجهًا تم التعرّف عليه في الصورة. بالنسبة لكل شبكة وجه، يمكنك الحصول على إحداثيات الحدود في صورة الإدخال، بالإضافة إلى أي معلومات أخرى قمت بتهيئة أداة كشف شبكات الوجه للعثور عليها.

Kotlin

for (faceMesh in faceMeshs) {
    val bounds: Rect = faceMesh.boundingBox()

    // Gets all points
    val faceMeshpoints = faceMesh.allPoints
    for (faceMeshpoint in faceMeshpoints) {
      val index: Int = faceMeshpoints.index()
      val position = faceMeshpoint.position
    }

    // Gets triangle info
    val triangles: List<Triangle<FaceMeshPoint>> = faceMesh.allTriangles
    for (triangle in triangles) {
      // 3 Points connecting to each other and representing a triangle area.
      val connectedPoints = triangle.allPoints()
    }
}

Java

for (FaceMesh faceMesh : faceMeshs) {
    Rect bounds = faceMesh.getBoundingBox();

    // Gets all points
    List<FaceMeshPoint> faceMeshpoints = faceMesh.getAllPoints();
    for (FaceMeshPoint faceMeshpoint : faceMeshpoints) {
        int index = faceMeshpoints.getIndex();
        PointF3D position = faceMeshpoint.getPosition();
    }

    // Gets triangle info
    List<Triangle<FaceMeshPoint>> triangles = faceMesh.getAllTriangles();
    for (Triangle<FaceMeshPoint> triangle : triangles) {
        // 3 Points connecting to each other and representing a triangle area.
        List<FaceMeshPoint> connectedPoints = triangle.getAllPoints();
    }
}