Face search

Use cases

Intelligent security monitoring

Using facial recognition, you can monitor crowded places such as factories, schools, shopping malls, and restaurants. This allows you to automatically count, identify, and track people, flag potentially unsafe behaviors and areas, and issue alerts. This improves security management and reduces costs for manual supervision.

Factory production safety

This feature provides an integrated software and hardware solution for production safety monitoring. Using images captured by cameras in plants and workshops, the system can identify unauthorized individuals to reduce security risks.

Face-based gate access

Integrating facial recognition into turnstiles allows you to quickly enroll faces and build a secure face library. Users gain entry by scanning their faces, which helps prevent issues like forgotten or spoofed badges. This enables access control for enterprise, commercial, and residential scenarios.

Smart face attendance

This feature offers three types of attendance solutions: mobile attendance, camera-based contactless attendance, and all-in-one device attendance. The system finds a user's most similar face in under one second, ensuring accurate check-ins, preventing fraudulent activities like buddy punching, and enhancing corporate security management.

Prerequisites

• You have indexed the images to be compared into a dataset. You can index images by binding a bucket (Create a binding task) or by actively indexing file metadata (IndexFileMeta or BatchIndexFileMeta).

• The dataset must contain at least two high-definition face images of the same person that meet the following requirements:

  • The face size is greater than 75 × 75 pixels.

  • The absolute values of the three HeadPose components must all be less than 30°.

  • FaceQuality is greater than 0.8.

• You have created an SMQ queue. For more information, see Manage queues.

  Note

  This topic provides an example of using the Python SDK for Simple Message Queue (SMQ), formerly Message Service (MNS), to receive task notifications. For other ways to get task information, see Process asynchronous tasks.

Step 1: Upload a file

Use the Object Storage Service (OSS) console to upload the photos that you want to compare to the bound bucket.

On the upload page, click Scan Files and select the photos to upload.

Step 2: Add photos to dataset

• Use the Intelligent Media Management (IMM) console to add photos from your OSS bucket to a dataset to build a face library. The procedure is as follows:

On the dataset details page, navigate to the Data Ingestion > Batch Add tab and click Add Files to Dataset. In the dialog box that appears, configure the Notification settings as needed. To add files, click Select Files, or enter a full path in the input box and click Add to List. Review the Object Path, Custom Tags, and Actions for each file, and then click OK.

The selected files are displayed in the file list with their oss:// paths.

• You can also call the BatchIndexFileMeta operation to index information from face photos into the dataset in batches. This process runs as an asynchronous task. You can obtain task information by configuring the Notification parameter.

  Sample code:

  # -*- coding: utf-8 -*-
  # This file is auto-generated, don't edit it. Thanks.
  import os
  import sys
  from typing import List
  from alibabacloud_imm20200930.client import Client as imm20200930Client
  from alibabacloud_tea_openapi import models as open_api_models
  from alibabacloud_imm20200930 import models as imm_20200930_models
  from alibabacloud_tea_util import models as util_models
  from alibabacloud_tea_util.client import Client as UtilClient
  class Sample:
      def __init__(self):
          pass
      @staticmethod
      def create_client() -> imm20200930Client:
          """
          Use your AccessKey ID and AccessKey secret to initialize the client.
          @return: Client
          @throws Exception
          """
          # Leaking your project code may leak your AccessKey pair and compromise the security of all resources in your account. The following code is for reference only.
          # We recommend that you use a more secure method, such as by using Security Token Service (STS) temporary credentials, for authentication. For more information, see https://www.alibabacloud.com/help/document_detail/378659.html.
          config = open_api_models.Config(
              # Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is configured.
              access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
              # Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is configured.
              access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
          )
          # For more information about endpoints, see https://api.aliyun.com/product/imm.
          config.endpoint = f'imm.cn-hangzhou.aliyuncs.com'
          return imm20200930Client(config)
      @staticmethod
      def main(
          args: List[str],
      ) -> None:
          client = Sample.create_client()
          notification_mns = imm_20200930_models.MNS(
              topic_name='test-mns-topic'
          )
          notification = imm_20200930_models.Notification(
              mns=notification_mns
          )
          input_file_0 = imm_20200930_models.InputFile(
              uri='''[
      {
          "URI": "oss://test-bucket/test-object-1.jpg"
      },
      {
          "URI": "oss://test-bucket/test-object-2.jpg"
      },
      {
          "URI": "oss://test-bucket/test-object-3.jpg"
      }
  ]'''
          )
          batch_index_file_meta_request = imm_20200930_models.BatchIndexFileMetaRequest(
              project_name='test-project',
              dataset_name='test-dataset',
              files=[
                  input_file_0
              ],
              notification=notification
          )
          runtime = util_models.RuntimeOptions()
          try:
              # Print the API response on your own after you copy the code.
              client.batch_index_file_meta_with_options(batch_index_file_meta_request, runtime)
          except Exception as error:
              # In a production project, handle exceptions with care and do not ignore them. This is for demonstration only.
              # Error message
              print(error.message)
              # Troubleshooting URL
              print(error.data.get("Recommend"))
              UtilClient.assert_as_string(error.message)
      @staticmethod
      async def main_async(
          args: List[str],
      ) -> None:
          client = Sample.create_client()
          notification_mns = imm_20200930_models.MNS(
              topic_name='test-mns-topic'
          )
          notification = imm_20200930_models.Notification(
              mns=notification_mns
          )
          input_file_0 = imm_20200930_models.InputFile(
              uri='''[
      {
          "URI": "oss://test-bucket/1.jpg"
      },
      {
          "URI": "oss://test-bucket/2.jpg"
      },
      {
          "URI": "oss://test-bucket/3.jpg"
      },
      {
          "URI": "oss://test-bucket/4.jpg"
      },
      {
          "URI": "oss://test-bucket/5.jpg"
      },
      {
          "URI": "oss://test-bucket/6.jpg"
      }
  ]'''
          )
          batch_index_file_meta_request = imm_20200930_models.BatchIndexFileMetaRequest(
              project_name='test-project',
              dataset_name='test-dataset',
              files=[
                  input_file_0
              ],
              notification=notification
          )
          runtime = util_models.RuntimeOptions()
          try:
              # Print the API response on your own after you copy the code.
              await client.batch_index_file_meta_with_options_async(batch_index_file_meta_request, runtime)
          except Exception as error:
              # In a production project, handle exceptions with care and do not ignore them. This is for demonstration only.
              # Error message
              print(error.message)
              # Troubleshooting URL
              print(error.data.get("Recommend"))
              UtilClient.assert_as_string(error.message)
  if __name__ == '__main__':
      Sample.main(sys.argv[1:])

  Sample response:

  {
    'EventId':'049-1udsgM0nr0leAdDBAOxe4kDLYM5',
    'RequestId': 'D4C150A6-D8EF-502B-9F30-645346388E13'
   }

  Sample SMQ message:

  {
      "TopicOwner": "14133977656xxxxx",
      "Message": "{\"id\":\"077-1x2s0rqA6ZOENW6gjAiN5Dl796T\",\"source\":\"acs.imm\",\"type\":\"imm:FileMeta:Index\",\"subject\":\"acs:imm:cn-hangzhou:14133977656xxxxx:test-project/imm:FileMeta:Index\",\"time\":\"1729564297965\",\"content\":\"{\\\"ProjectName\\\":\\\"test-project\\\",\\\"DatasetName\\\":\\\"test-dataset\\\",\\\"RequestId\\\":\\\"7FE8A307-1649-6B0D-1AB8-0600C9D4877B\\\",\\\"StartTime\\\":\\\"2024-10-22T10:31:37.787209251+08:00\\\",\\\"EndTime\\\":\\\"2024-10-22T10:31:37.965992728+08:00\\\",\\\"Success\\\":true,\\\"Message\\\":\\\"\\\",\\\"Files\\\":[{\\\"URI\\\":\\\"[\\\\n    {\\\\n        \\\\\\\"URI\\\\\\\": \\\\\\\"oss://test-bucket/test-object-1.jpg\\\\\\\"\\\\n    },\\\\n    {\\\\n        \\\\\\\"URI\\\\\\\": \\\\\\\"oss://test-bucket/test-object-2.jpg\\\\\\\"\\\\n    },\\\\n    {\\\\n        \\\\\\\"URI\\\\\\\": \\\\\\\"oss://test-bucket/test-object-3.jpg\\\\\\\"\\\\n    }\\\\n],\\\"UserData\\\":\\\"\\\"}\"}",
      "Subscriber": "14133977656xxxxx",
      "PublishTime": "1729564298068",
      "SubscriptionName": "test-mns-subscription",
      "MessageMD5": "9921327B25E01FB38151781B81042BA7",
      "TopicName": "tf-test-mns-queue",
      "MessageId": "129D772E14277FA6182D6E67D354D069"
  }

Step 3: Create face search task

You can call the CreateFacesSearchingTask operation to find the top N photos that are most similar to the largest face in a specified image. The following example shows how to search the test-dataset dataset for photos similar to the image at oss://test-bucket/test-object.jpg.

Sample request

{
  "ProjectName": "test-project",
  "DatasetName": "test-dataset",
  "Sources": [{"URI": "oss://test-bucket/test-object.jpg"}],
  "Notification": {"MNS": {"TopicName": "tf-test-mns-topic"}},
  "MaxResult": 100
}

Sample response

{
    "TaskId": "CreateFacesSearchingTask-dedf1bd9-7edc-4d16-97f2-bbb2a4fc****",
    "RequestId": "BB9C38A3-BB7A-53B7-A168-6DBC1CF6****",
    "EventId": "0DA-1TAZO4ClNnKbn4Ungls8SOk****"
}

# -*- coding: utf-8 -*-
# This file is auto-generated, don't edit it. Thanks.
import os
import sys
from typing import List
from alibabacloud_imm20200930.client import Client as imm20200930Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_imm20200930 import models as imm_20200930_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient
class Sample:
    def __init__(self):
        pass
    @staticmethod
    def create_client(
        access_key_id: str,
        access_key_secret: str,
    ) -> imm20200930Client:
        """
        Use an AccessKey ID and AccessKey Secret to initialize the client.
        @param access_key_id:
        @param access_key_secret:
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config(
            access_key_id=access_key_id,
            access_key_secret=access_key_secret
        )
        # Specify the endpoint.
        config.endpoint = f'imm.cn-hangzhou.aliyuncs.com'
        return imm20200930Client(config)
    @staticmethod
    def main(
        args: List[str],
    ) -> None:
        # An AccessKey pair of an Alibaba Cloud account grants full permissions for all API operations. We recommend that you use a RAM user for API calls and routine O&M.
        # We strongly recommend that you do not save your AccessKey ID and AccessKey Secret in your project code. Otherwise, your AccessKey pair may be leaked, which compromises the security of all resources in your account.
        # This example reads the AccessKey pair from environment variables for authentication. For information about how to configure environment variables, see https://www.alibabacloud.com/help/document_detail/2361894.html.
        imm_access_key_id = os.getenv("AccessKeyId")
        imm_access_key_secret = os.getenv("AccessKeySecret")
        # Initialize the client.
        client = Sample.create_client(imm_access_key_id, imm_access_key_secret)
        notification_mns = imm_20200930_models.MNS(
            topic_name='tf-test-mns-topic'
        )
        notification = imm_20200930_models.Notification(
            mns=notification_mns
        )
        sources_0 = imm_20200930_models.CreateFacesSearchingTaskRequestSources(
            uri='''oss://test-bucket/test-object.jpg
'''
        )
        create_faces_searching_task_request = imm_20200930_models.CreateFacesSearchingTaskRequest(
            project_name='test-project',
            dataset_name='test-dataset',
            sources=[
                sources_0
            ],
            notification=notification,
            max_result=100
        )
        runtime = util_models.RuntimeOptions()
        try:
            # Print the API response on your own after you copy the code.
            client.create_faces_searching_task_with_options(create_faces_searching_task_request, runtime)
        except Exception as error:
            # If needed, print the error message.
            UtilClient.assert_as_string(error.message)
    @staticmethod
    async def main_async(
        args: List[str],
    ) -> None:
        # An AccessKey pair of an Alibaba Cloud account grants full permissions for all API operations. We recommend that you use a RAM user for API calls and routine O&M.
        # We strongly recommend that you do not save your AccessKey ID and AccessKey Secret in your project code. Otherwise, your AccessKey pair may be leaked, which compromises the security of all resources in your account.
        # This example reads the AccessKey pair from environment variables for authentication. For information about how to configure environment variables, see https://www.alibabacloud.com/help/document_detail/2361894.html.
        imm_access_key_id = os.getenv("AccessKeyId")
        imm_access_key_secret = os.getenv("AccessKeySecret")
        # Initialize the client.
        client = Sample.create_client(imm_access_key_id, imm_access_key_secret)
        notification_mns = imm_20200930_models.MNS(
            topic_name='tf-test-mns-topic'
        )
        notification = imm_20200930_models.Notification(
            mns=notification_mns
        )
        sources_0 = imm_20200930_models.CreateFacesSearchingTaskRequestSources(
            uri='''oss://test-bucket/test-object.jpg
'''
        )
        create_faces_searching_task_request = imm_20200930_models.CreateFacesSearchingTaskRequest(
            project_name='test-project',
            dataset_name='test-dataset',
            sources=[
                sources_0
            ],
            notification=notification,
            max_result=100
        )
        runtime = util_models.RuntimeOptions()
        try:
            # Print the API response on your own after you copy the code.
            await client.create_faces_searching_task_with_options_async(create_faces_searching_task_request, runtime)
        except Exception as error:
            # If needed, print the error message.
            UtilClient.assert_as_string(error.message)
if __name__ == '__main__':
    Sample.main(sys.argv[1:])

Step 4: View face search results

After the face search task is successfully created, you can retrieve the task information from the SMQ service. The following example shows how to get task information by using the Python SDK. For more information, see Step 4: Receive and delete messages.

1. In the sample directory, run the following command.

   python recvdelmessage.py tf-test-mns-queue

2. The console returns the result in JSON format. The following code shows the formatted content of the Message field.

   {
       "ProjectName": "test-project",
       "DatasetName": "test-dataset",
       "RequestId": "BB9C38A3-BB7A-53B7-A168-6DBC1CF6****",
       "StartTime": "2023-01-04T05:08:28.582Z",
       "EndTime": "2023-01-04T05:08:28.785Z",
       "UserData": "",
       "TaskType": "FacesSearching",
       "TaskId": "CreateFacesSearchingTask-dedf1bd9-7edc-4d16-97f2-bbb2a4fc****",
       "Status": "Succeeded",
       "Code": "",  // An empty Code field indicates that the operation was successful.
       "Message": "Success",
       "SimilarFaces": [
           {
               "URI": "oss://test-bucket/test-object.jpg",
               "Boundary": {
                   "Width": 109,
                   "Height": 150,
                   "Left": 69,
                   "Top": 49
               },
               // A list of similar faces.
               "SimilarFaces": [
                   {
                       "URI": "oss://test-bucket/test-object-1.jpg",
                       "FigureId": "4cacbb71-52fd-4d3f-9d14-0840fecee0bf",
                       "Similarity": 0.73321015
                   },
                   {
                       "URI": "oss://test-bucket/test-object-2.jpg",
                       "FigureId": "7a4cd08d-bcd0-4bc4-93f4-1291075819cf",
                       "Similarity": 0.77035695
                   },
                   {
                       "URI": "oss://test-bucket/test-object-3.jpg",
                       "FigureId": "da920124-410a-4493-9fd3-1a3b366dca86",
                       "Similarity": 0.9836307
                   }
               ]
           }
       ]
   }
   

   Note

   The message shows that the following three images in the test-dataset dataset are similar to the face in the query image:

   • Image 1: oss://test-bucket/test-object-1.jpg, with a similarity score of 0.73321015.

   • Image 2: oss://test-bucket/test-object-2.jpg, with a similarity score of 0.77035695.

   • Image 3: oss://test-bucket/test-object-3.jpg, with a similarity score of 0.9836307.