- Create a Face Group
- Edit a Face Group
- Set the Transfer Condition (From Stranger to Regular)
- Delete a Face Group
- Get the List of Face Groups
- Add a Face Attribute
- Delete a Face Attribute
- Get the List of Newly Added Face Attributes of a Specified Face Group
- Add a Face
- Delete Faces
- Update a Face
- Get the Info of a Face
- Get the List of Faces
- Get the Last N Face Records (Ranking per When They Pay the Last Visits)
- Get Face Picture through picture
- Clear Specified Face Group
Currently, this interface is only available to SUNMI FS. When the device is bound to the digital store and the device API is activated, the “editing” interface in this section is not available. That is, only the face grouping management interface of the cloud API can be used to manage the face database at this condition.
1. Create a Face Group
Description
This interface can be used to create a face group and configure its attributes. At present, up to 10 groups can exist – 2 default groups (stranger and regular) and 8 groups that can be created by users.
Interface
public void createGroup(String deviceId, String groupName, int capacity, String description, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
name | The group name (within 96 characters). There are two default groups (stranger and regular) in the system. | stranger |
capacity | The capacity of each group. The total capacity of all groups should be within 30K. | 10000 |
description | The group description, which shall not exceed 150 characters. | Black Card Customers |
callback | The calling result |
Please note:
1. The first character of a name should not be empty.
2. By default, the new customer group is named stranger, and the regular customer group is named regular.
Response Parameter
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 200, 201, 202, 211, 212, 220. Please refer to RPCErrorCode Class for details. |
2. Edit a Face Group
Description
This interface is used to edit the attributes of a specified face group.
Interface
public void updateGroup(String deviceId, String oldGroupName, String groupName, int capacity, String description, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
oldGroupName | The original name of the group. | Black Card Customers |
groupName | The modified name of the group (it can be the same as the original name). | Golden Card Customers |
capacity | The modified group capacity (it can be the same as the original capacity). | 10000 |
description | The group description, which shall not exceed 150 characters. | Card Application and Upgrade |
callback | The calling result. |
Please note:
1. The name of default face groups (stranger and regular) cannot be modified.
2. The first character of a name should not be empty.
Response Parameter
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 200, 201, 202, 204, 211, 212, 220. Please refer to RPCErrorCode Class for details. |
3. Set the Transfer Condition (From Stranger to Regular)
Description
When the system is activated, two face groups (stranger and regular) will be created. A stranger will be transferred to the regular group if a certain condition is met (by default, visiting a store 5 times within 7 days).
This interface is used to change the condition for the transfer.
Interface
public void updateMigration(String deviceId, int arrive_times, int period, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
arrive_times | An attribute unique to the stranger group. It ranges 1~10. | 5 |
period | An attribute unique to the stranger group. It ranges 1~100 (unit: day). | 20 |
callback | The calling result. |
Please note:
The arrive_times and period are attributes unique to the stranger group, which can be altered to change the transfer condition. A stranger will be transferred to the regular group if he/she visits certain times (arrive_times) within certain days (period).
Response Parameter
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220. Please refer to RPCErrorCode Class for details. |
4. Delete a Face Group
Description
This interface is used to delete a specified face group.
Interface
public void deleteGroup(String deviceId, String groupName, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
groupName | The default groups (stranger and regular) cannot be deleted. And please clear a group first before deleting it. | Black Card Customers |
callback | The calling result. |
Response Parameter
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 201, 204, 205, 211, 220. Please refer to RPCErrorCode Class for details. |
5. Get the List of Face Groups
Description
This interface is used to get the information of IPC face groups.
Interface
public void getGroupList(String deviceId, RpcCallback‹RpcResponse‹GroupCollection›› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
callback | The calling result. |
Response Parameters
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 211, 220. Please refer to RPCErrorCode Class for details. |
data | GroupCollection | This field shows only when the return code indicates a successful operation. Please refer to RPCResponse. GroupCollection for details. |
6. Add a Face Attribute
Description
Some face attributes are preset in the library. You can use this interface to add up to 5 attributes to the faces in a specified face group.
This interface is recommended to be used as needed after a group has been created but before any face has been added instead of adding face attributes after some faces have been added to a group.
Interface
public void addFaceInfoItem(String deviceId, String groupName, List‹String› attrs, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
groupName | The face group name. | vip |
attrs | It is an attribute list showing in an array. The attribute type is string and with a maximum length of 50 bytes. | [“hobby”] |
callback | The calling result. |
Please note:
1. No face attributes can be added to the default face groups.
2. The following fields are reserved and cannot be used as newly added attribute names: group_name, pic, age, gender, faceid, age_range, arrive_times, pic_url, total_num, return_num.
Response Parameter
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242. Please refer to RPCErrorCode Class for details. |
7. Delete a Face Attribute
Description
This interface is used to delete some user-defined attributes in a specified group when they go needless. However, please delete with caution.
Interface
public void removeFaceInfoItem(String deviceId, String groupName, List‹String› attrs, RpcCallback‹RpcResponse› callback);
Parameters.
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
groupName | The face group name | vip |
attrs | It is an attribute list showing in an array. The attribute type is string and with a maximum length of 50 bytes | [“hobby”] |
callback | The calling result. |
Please note:
No face attributes can be deleted from the default face groups.
Response Parameter
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 243. Please refer to RPCErrorCode Class for details. |
8. Get the List of Newly Added Face Attributes of a Specified Face Group
Description
This interface is used to get the list of face attributes added through the method stated in 2.4.6.。
Interface
public void getFaceInfoItem(String deviceId, String groupName, RpcCallback‹RpcResponse‹FaceAttributeCollection›› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
groupName | The face group name. | stranger |
callback | The calling result |
Response Parameters
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220. Please refer to RPCErrorCode Class for details. |
data | FaceAttributeCollection | This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceAttributeCollection for details. |
9. Add a Face
Description
This interface is used to add a face (and configure its attributes) to a specified group. One face can be added at a time.
Interface
public void addFaceRecord(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN. | C201D98T00094 |
options | The attributes related to a face record. See Options Description below for details. | |
callback | The calling result. |
Options Description
Parameter | Type | Description | Required | Example |
faceid | string | Face ID, which should be within 16 English characters. | N | 11024 |
pic | file | The face picture in jpg/png format. Its maximum resolution is 1920*1080, and the size should be within 1MB. | Y | 11024.jpg |
group_name | string | The face group name | Y | stranger |
age | int | Preset attribute – age. | N | 14 |
gender | int | Preset attribute – gender. 0: Unknow. 1: Male. 2: Female. | N | 1 |
item1 | string | User-defined attribute 1. | N | value1 |
item2 | string | User-defined attribute 2. | N | value2 |
item3 | string | User-defined attribute 3. | N | value3 |
item4 | string | User-defined attribute 4. | N | value4 |
item5 | string | User-defined attribute 5. | N | value5 |
Please note:
1. Attributes (item1/item2/item3/item4/item5) other than the preset face attributes stated above (which are built in the IPC database) are user-defined attributes, which should be added through calling the interface in 2.4.6. If a face attribute has not been added beforehand but a corresponding key-value has been added to the interface, the IPC won’t process the attribute.
2. If the age attribute has not been set, the IPC will automatically set the age range of a customer.
3. If the gender attribute has not been set, the IPC will automatically set the gender of a customer.
Response Parameter
Field | Type | Description | Example |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 206, 208, 210, 211, 220. Please refer to RPCErrorCode Class for details. |
10. Delete Faces
Description
This interface is used to delete some faces in a specified face group.
Interface
public void deleteFaceRecord(String deviceId, String groupName, List‹String› faceidList, RpcCallback‹RpcResponse‹DeleteFaceDetails›› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
groupName | The face group name. | vip |
faceidList | The list of Face IDs. | [“1988″,”2020”] |
callback | The calling result |
Response Parameters
Field | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220. Please refer to RPCErrorCode Class for details. |
data | DeleteFaceDetails | This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.DeleteFaceDetails for details. |
11. Update a Face
Description
This interface is used to update the information of a specified face.
Interface
public void updateFaceRecord(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
options | The attributes related to a face record. See Options Description below for details. | |
callback | The calling result |
Options Description
Parameter | Type | Description | Required | Example |
group_name | string | The face group name. | Y | stranger |
faceid | string | Face ID. | Y | 21 |
new_group_name | string | New group name. | N | VIP |
pic | file | The face picture in jpg/png format. Its maximum resolution is 1920*1080, and its size should be within 1MB. | N | example.jpg |
age | int | Preset attribute – age. | N | 10 |
gender | int | Gender, which can be updated to use 1 to represent male and 2 to represent female. | N | 1 |
item1 | string | User-defined attribute 1 | N | value1 |
item2 | string | User-defined attribute 2 | N | value2 |
item3 | string | User-defined attribute 3 | N | value3 |
item4 | string | User-defined attribute 4 | N | value4 |
item5 | string | User-defined attribute 5 | N | value5 |
Response Parameter
Parameter | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 207, 208, 210, 211, 220. Please refer to RPCErrorCode Class for details. |
Please note:
The hobby, vip_level, weight, phone_num (item1/item2/item3/item4) above are user-defined attributes, which can be added using the interface in 2.4.6. They are ready to be used after having been added.
12. Get the Info of a Face
Description
This interface is used to get the information of a face through a specified Face ID.
Interface
public void getFaceRecord(String deviceId, String faceId, RpcCallback‹RpcResponse‹FaceRecord›› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
faceId | Face Id | 105 |
callback | The calling result |
Response Parameters
Parameter | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 211. Please refer to RPCErrorCode Class for details. |
data | FaceRecord | This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceRecord for details. |
{
"code": 0,
"data": {
"arrive_time": 1566215943,
"arrive_count": 2,
"faceid": "4",
"group_name": "VIP",
"point": "113", //User-defined attribute
"gender": 1,
"age": 10,
"age_range": 2,
"vip_level": "1", //User-defined attribute
"hobby": "tennis", //User-defined attribute
"weight": "60", //User-defined attribute
"height": "180" //User-defined attribute
}
}
Please note:
The hobby, vip_level, weight, phone_num (item1/item2/item3/item4) above are user-defined attributes, which can be added using the interface in 2.4.6. These attributes can only be returned after they have been added.
13. Get the List of Faces
Description
This interface is used to get all face information of a specified face group.
Interface
public void getFaceRecordList(String deviceId, String groupName, int pageNum, int pageSize, RpcCallback‹RpcResponse‹FaceRecordCollection›› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
page_num | The current page number, whose default and minimum value is 1. | |
page_size | The number of items on the current page, which is 10 by default and ranges [1, 100]. | |
callback | The calling result |
Sample Result Returned
{ “code”: 0, “data”: { “total_num”: 2, “num”: 2, “faceid_list”: [ { “arrive_time”: 1566215929, “arrive_count”: 2, “faceid”: “3”, “point”: “113”, //User-defined attribute “gender”: 2, “vip_level”: “3”, //User-defined attribute “hobby”: “tennis”, //User-defined attribute “weight”: “60”, //User-defined attribute “height”: “180”, //User-defined attribute “age”: 10, “age_range”: 2 }, { “arrive_time”: 1566215998 “arrive_count”: 1 “faceid”: “4”, “point”: “113”, //User-defined attribute “gender”: 1, “vip_level”: “1”, //User-defined attribute “hobby”: “tennis”, //User-defined attribute “weight”: “60”, //User-defined attribute “height”: “180”, //User-defined attribute “age”: 10, “age_range”: 2 } ] } } |
14. Get the Last N Face Records (Ranking per When They Pay the Last Visits)
Description
This interface is used to get the information of the N faces who have not visited the store for a long time in a specified group.
Interface
public void getFaceByArrival(String deviceId, String groupName, int num, RpcCallback‹RpcResponse‹FaceRecordCollection›› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
groupName | The face group name. | VIP |
num | The number of faces to be obtained. Its default value is 1 and it ranges 1~10. | 2 |
callback | The calling result. |
Response Parameters
Parameter | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 207, 211. Please refer to RPCErrorCode Class for details. |
data | FaceRecordCollection | This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceRecordCollection for details. |
Sample Result Returned
{ “code”: 0, “data”: { “return_num”: 2, “faceid_list”: [ { “faceid”: “8”, “arrive_time”: 1566215929, “arrive_count”: 7, “age_range”: 5, “gender”: 1, “age”: 0, “item1”:value1, // User-defined attribute “item2”:value2, // User-defined attribute “item3”:value3, // User-defined attribute “item4”:value4, // User-defined attribute “item5”:value5 // User-defined attribute }, { “faceid”: “10”, “arrive_time”: 1566110525, “arrive_count”: 6, “age_range”: 4, “gender”: 2, “age”: 0, “item1”: value1, // User-defined attribute “item2”:value2, // User-defined attribute “item3”:value3, // User-defined attribute “item4”:value4, // User-defined attribute “item5”:value5 // User-defined attribute } ] } } |
15. Get Face Picture through picture
Description
This interface uses face picture to search for similar faces in IPC devices, and returns face records that are identified as the same person by eigenvalue matching.
Interface
public void getFaceRecordByPicture(String deviceId, String picPath, RpcCallback‹RpcResponse‹FaceRecord›› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
picPath | The picture path | /mnt/sdcard/1424.jpg |
callback | The calling result |
Response Parameters
Parameter | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 1, 2, 3, 5, 7, 210, 211, 283. Please refer to RPCErrorCode Class for details. |
data | FaceRecord | This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceRecord for details. |
16. Clear Specified Face Group
Description
Clear all face data from specified face group.
Interface
public void cleanGroup(String deviceId, String groupName, RpcCallback‹RpcResponse› callback);
Parameters
Parameter | Description | Example |
deviceId | IPC SN | C201D98T00094 |
groupName | The picture path | “vip” |
callback | The calling result |
Response Parameters
Parameter | Type | Description |
code | int | The return code indicating the operation result; The return codes of this interface contain 0, 2, 3, 12, 13, 204, 220. Please refer to RPCErrorCode Class for details. |