Merged PR 3143: Million Scale Python SDK update.

Author: Xuan (Sean) Hu

cognitive_face/__init__.py

@@ -7,6 +7,11 @@
 
 from . import face
 from . import face_list
+from . import large_face_list
+from . import large_face_list_face
+from . import large_person_group
+from . import large_person_group_person
+from . import large_person_group_person_face
 from . import person
 from . import person_group
 from . import util

cognitive_face/face.py

@@ -43,14 +43,15 @@ def detect(image, face_id=True, landmarks=False, attributes=''):
 
 def find_similars(face_id,
                   face_list_id=None,
+                  large_face_list_id=None,
                   face_ids=None,
                   max_candidates_return=20,
                   mode='matchPerson'):
     """Given query face's `face_id`, to search the similar-looking faces from a
-    `face_id` array or a `face_list_id`.
+    `face_id` array, a `face_list_id` or a `large_face_list_id`.
 
-    Parameter `face_list_id` and `face_ids` should not be provided at the same
-    time.
+    Parameter `large_face_list_id`, `face_list_id` and `face_ids` should not be 
+    provided at the same time.
 
     Args:
         face_id: `face_id` of the query face. User needs to call `face.detect`
@@ -59,6 +60,10 @@ def find_similars(face_id,
         face_list_id: An existing user-specified unique candidate face list,
             created in `face_list.create`. Face list contains a set of
             `persisted_face_ids` which are persisted and will never expire.
+        large_face_list_id: An existing user-specified unique candidate face
+            list, created in `large_face_list.create`. Large Face list contains
+            a set of `persisted_face_ids` which are persisted and will never
+            expire.
         face_ids: An array of candidate `face_id`s. All of them are created by
             `face.detect` and the `face_id`s will expire in 24 hours after the
             detection call. The number of `face_id`s is limited to 1000.
@@ -70,12 +75,13 @@ def find_similars(face_id,
     Returns:
         An array of the most similar faces represented in `face_id` if the
         input parameter is `face_ids` or `persisted_face_id` if the input
-        parameter is `face_list_id`.
+        parameter is `face_list_id` or `large_face_list_id`.
     """
     url = 'findsimilars'
     json = {
         'faceId': face_id,
         'faceListId': face_list_id,
+        'largeFaceListId': large_face_list_id,
         'faceIds': face_ids,
         'maxNumOfCandidatesReturned': max_candidates_return,
         'mode': mode,
@@ -104,17 +110,20 @@ def group(face_ids):
 
 
 def identify(face_ids,
-             person_group_id,
+             person_group_id=None,
+             large_person_group_id=None,
              max_candidates_return=1,
              threshold=None):
-    """Identify unknown faces from a person group.
+    """Identify unknown faces from a person group or a large person group.
 
     Args:
         face_ids: An array of query `face_id`s, created by the `face.detect`.
             Each of the faces are identified independently. The valid number of
             `face_ids` is between [1, 10].
         person_group_id: `person_group_id` of the target person group, created
             by `person_group.create`.
+        large_person_group_id: `large_person_group_id` of the target large
+            person group, createdJ by `large_person_group.create`.
         max_candidates_return: Optional parameter. The range of
             `max_candidates_return` is between 1 and 5 (default is 1).
         threshold: Optional parameter. Confidence threshold of identification,
@@ -127,6 +136,7 @@ def identify(face_ids,
     url = 'identify'
     json = {
         'personGroupId': person_group_id,
+        'largePersonGroupId': large_person_group_id,
         'faceIds': face_ids,
         'maxNumOfCandidatesReturned': max_candidates_return,
         'confidenceThreshold': threshold,
@@ -135,21 +145,27 @@ def identify(face_ids,
     return util.request('POST', url, json=json)
 
 
-def verify(face_id, another_face_id=None, person_group_id=None,
+def verify(face_id,
+           another_face_id=None,
+           person_group_id=None,
+           large_person_group_id=None,
            person_id=None):
     """Verify whether two faces belong to a same person or whether one face
     belongs to a person.
 
     For face to face verification, only `face_id` and `another_face_id` is
     necessary. For face to person verification, only `face_id`,
-    `person_group_id` and `person_id` is needed.
+    `person_group_id` (or `large_person_group_id`) and `person_id` is needed.
 
     Args:
         face_id: `face_id` of one face, comes from `face.detect`.
         another_face_id: `face_id` of another face, comes from `face.detect`.
         person_group_id: Using existing `person_group_id` and `person_id` for
             fast loading a specified person. `person_group_id` is created in
             `person_group.create`.
+        large_person_group_id: Using existing `large_person_group_id` and
+            `person_id` for fast loading a specified person.
+            `large_person_group_id` is created in `large_person_group.create`.
         person_id: Specify a certain person in a person group. `person_id` is
             created in `person.create`.
 
@@ -167,6 +183,7 @@ def verify(face_id, another_face_id=None, person_group_id=None,
         json.update({
             'faceId': face_id,
             'personGroupId': person_group_id,
+            'largePersonGroupId': large_person_group_id,
             'personId': person_id,
         })
 

cognitive_face/large_face_list.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+File: large_face_list.py
+Description: Large Face List section of the Cognitive Face API.
+"""
+from . import util
+
+
+def create(large_face_list_id, name=None, user_data=None):
+    """Create an empty large face list with user-specified
+    `large_face_list_id`, `name` and an optional `user_data`.
+
+    Args:
+        large_face_list_id: Valid character is letter in lower case or digit or
+            '-' or '_', maximum length is 64.
+        name: Name of the created large face list, maximum length is 128.
+        user_data: Optional parameter. User-defined data for the large face
+            list.  Length should not exceed 16KB.
+
+    Returns:
+        An empty response body.
+    """
+    name = name or large_face_list_id
+    url = 'largefacelists/{}'.format(large_face_list_id)
+    json = {
+        'name': name,
+        'userData': user_data,
+    }
+
+    return util.request('PUT', url, json=json)
+
+
+def delete(large_face_list_id):
+    """Delete an existing large face list according to `large_face_list_id`.
+    Persisted face images in the large face list will also be deleted.
+
+    Args:
+        large_face_list_id: Valid character is letter in lower case or digit or
+            '-' or '_', maximum length is 64.
+
+    Returns:
+        An empty response body.
+    """
+    url = 'largefacelists/{}'.format(large_face_list_id)
+
+    return util.request('DELETE', url)
+
+
+def get(large_face_list_id):
+    """Retrieve a large face list's information, including
+    `large_face_list_id`, `name`, `user_data`. Large face list simply
+    represents a list of faces, and could be treated as a searchable data
+    source in `face.find_similars`.
+
+    Args:
+        large_face_list_id: Valid character is letter in lower case or digit or
+            '-' or '_', maximum length is 64.
+
+    Returns:
+        The large face list's information.
+    """
+    url = 'largefacelists/{}'.format(large_face_list_id)
+
+    return util.request('GET', url)
+
+
+def get_status(large_face_list_id):
+    """Retrieve the training status of a large face list (completed or
+    ongoing). Training can be triggered by `large_face_list.train`. The
+    training will process for a while on the server side.
+
+    Args:
+        large_face_list_id: `large_face_list_id` of the target large face list.
+
+    Returns:
+        The large face list's training status.
+    """
+    url = 'largefacelists/{}/training'.format(large_face_list_id)
+
+    return util.request('GET', url)
+
+
+def list(start=None, top=None):
+    """Retrieve information about all existing large face lists. Only
+    `large_face_list_id`, `name` and `user_data` will be returned.
+
+    Args:
+        start: Optional parameter. List large face lists from the least
+            `large_face_list_id` greater than the "start". It contains no more
+            than 64 characters. Default is empty.
+        top: The number of large face lists to list, ranging in [1, 1000].
+            Default is 1000.
+
+    Returns:
+        An array of large face lists.
+    """
+    url = 'largefacelists'
+    params = {
+        'start': start,
+        'top': top,
+    }
+
+    return util.request('GET', url, params=params)
+
+
+def train(large_face_list_id):
+    """Queue a large face list training task, the training task may not be
+    started immediately.
+
+    Args:
+        large_face_list_id: Target large face list to be trained.
+
+    Returns:
+        An empty JSON body.
+    """
+    url = 'largefacelists/{}/train'.format(large_face_list_id)
+
+    return util.request('POST', url)
+
+
+def update(large_face_list_id, name=None, user_data=None):
+    """Update information of a large face list, including `name` and `user_data`.
+
+    Args:
+        large_face_list_id: Valid character is letter in lower case or digit or
+            '-' or '_', maximum length is 64.
+        name: Name of the created large face list, maximum length is 128.
+        user_data: Optional parameter. User-defined data for the large face
+            list. Length should not exceed 16KB.
+
+    Returns:
+        An empty response body.
+    """
+    url = 'largefacelists/{}'.format(large_face_list_id)
+    json = {
+        'name': name,
+        'userData': user_data,
+    }
+
+    return util.request('PATCH', url, json=json)

cognitive_face/large_face_list_face.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+File: large_face_list_face.py
+Description: Large Face List Face section of the Cognitive Face API.
+"""
+from . import util
+
+
+def add(image, large_face_list_id, user_data=None, target_face=None):
+    """Add a face to a large face list.
+
+    The input face is specified as an image with a `target_face` rectangle. It
+    returns a `persisted_face_id` representing the added face, and
+    `persisted_face_id` will not expire.
+
+    Args:
+        image: A URL or a file path or a file-like object represents an image.
+        large_face_list_id: Valid character is letter in lower case or digit or
+            '-' or '_', maximum length is 64.
+        user_data: Optional parameter. User-specified data about the large face
+            list for any purpose. The maximum length is 1KB.
+        target_face: Optional parameter. A face rectangle to specify the target
+            face to be added into the large face list, in the format of
+            "left,top,width,height". E.g. "10,10,100,100". If there are more
+            than one faces in the image, `target_face` is required to specify
+            which face to add. No `target_face` means there is only one face
+            detected in the entire image.
+
+    Returns:
+        A new `persisted_face_id`.
+    """
+    url = 'largefacelists/{}/persistedFaces'.format(large_face_list_id)
+    headers, data, json = util.parse_image(image)
+    params = {
+        'userData': user_data,
+        'targetFace': target_face,
+    }
+
+    return util.request(
+        'POST', url, headers=headers, params=params, json=json, data=data)
+
+
+def delete(large_face_list_id, persisted_face_id):
+    """Delete an existing face from a large face list (given by a
+    `persisted_face_id` and a `large_face_list_id`). Persisted image related to
+    the face will also be deleted.
+
+    Args:
+        large_face_list_id: Valid character is letter in lower case or digit or
+            '-' or '_', maximum length is 64.
+        persisted_face_id: `persisted_face_id` of an existing face. Valid
+            character is letter in lower case or digit or '-' or '_', maximum
+            length is 64.
+
+    Returns:
+        An empty response body.
+    """
+    url = 'largefacelists/{}/persistedFaces/{}'.format(large_face_list_id,
+                                                       persisted_face_id)
+
+    return util.request('DELETE', url)
+
+
+def get(large_face_list_id, persisted_face_id):
+    """Retrieve information about a persisted face (specified by
+    `persisted_face_id` and a `large_face_list_id`).
+
+    Args:
+        large_face_list_id: Valid character is letter in lower case or digit or
+            '-' or '_', maximum length is 64.
+        persisted_face_id: `persisted_face_id` of an existing face. Valid
+            character is letter in lower case or digit or '-' or '_', maximum
+            length is 64.
+
+    Returns:
+        The target persisted face's information (`persisted_face_id` and
+        `user_data`).
+    """
+    url = 'largefacelists/{}/persistedFaces/{}'.format(large_face_list_id,
+                                                       persisted_face_id)
+
+    return util.request('GET', url)
+
+
+def list(large_face_list_id, start=None, top=None):
+    """Retrieve information (`persisted_face_id` and `user_data`) about
+    existing persisted faces in a large face list.
+
+    Args:
+        start: Optional parameter. List large face lists from the least
+            `large_face_list_id` greater than the "start". It contains no more
+            than 64 characters. Default is empty.
+        top: The number of large face lists to list, ranging in [1, 1000].
+            Default is 1000.
+
+    Returns:
+        An array of persisted faces and their information (`persisted_face_id`
+        and `user_data`).
+    """
+    url = 'largefacelists/{}/persistedFaces'.format(large_face_list_id)
+    params = {
+        'start': start,
+        'top': top,
+    }
+
+    return util.request('GET', url, params=params)
+
+
+def update(large_face_list_id, persisted_face_id, user_data=None):
+    """Update a persisted face's `user_data` field in a large face list.
+
+    Args:
+        large_face_list_id: largeFaceListId of an existing large face list.
+            person.
+        person_id: `person_id` of the target person.
+        persisted_face_id: `persisted_face_id` of the target face, which is
+            persisted and will not expire.
+        user_data: Optional parameter. Attach `user_data` to person's
+            persisted face. The size limit is 1KB.
+
+    Returns:
+        An empty response body.
+    """
+    url = 'largefacelists/{}/persistedFaces/{}'.format(large_face_list_id,
+                                                       persisted_face_id)
+    json = {
+        'userData': user_data,
+    }
+
+    return util.request('PATCH', url, json=json)