Match Images Against Stored Identities

Use the following parameters in your POST request to perform recognition of an image against the identities inserted in a directory, and request a specific number of matches along with match probability.

Method, Headers, and URL

POST -H "Content-Type:application/octet-stream" -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION: userId:pwd" "http://localhost:8080/people

Element Description Notes
X-RPC-AUTHORIZATION Header information for authentication purposes. (Required) Substitute the userid (user identifier) and pwd (password) with the credentials issued for your account.

Example: "X-RPC-AUTHORIZATION: exampleInc:123456"
X-RPC-DIRECTORY: main The header identifies the directory used. If necessary, substitute main with the appropriate directory name.
localhost Location of the API endpoint. Substitute with a proper IP address or domain name based on the service location.
–data-binary @{image file name} Identifies the graphic file used to perform recognition against the identities in a directory. (Required) Where {image file name} is the graphic file name to be used.
insert=false&update=false Ensures nothing in the directory is inserted or updated. (Required)
similar_limit={integer} Requests the top number of matches with probabilities of match. (Optional) Valid values are integers.

Use similar_limitquery parameter in POST /people request.

cURL Examples

Note: The previous request returns the top five (5) matches for each face found in the image. The order in which found faces/identities are returned is arbitrary; they're not sorted by similarityScore. For each found face, the top five (5) matching identities are provided in order of most similar first (highest similarityScore first).

The probability of a match is returned in the similarityScore attribute of records returned in the similar array. The score of 1.0 (100%) is tied to the set X-RPC-FACES-GROUPING-THRESHOLD; faces matching exactly at the threshold have similarityScore of 1.0. Those matching to a greater extent score > 1.0, while those matching to a lesser extent score < 1.0 .

The lower bound is 0, and the upper bound is 2 / (2 - sqrt(X-RPC-FACES-GROUPINGTHRESHOLD)). By default the X-RPC-FACES-GROUPING-THRESHOLD setting is 0.54; the upper bound is 1.581. The identity returned outside of the similar array is the best match with similarityScore >= 1.0, if any.

{
    "accountUpdated": false,
    "detectionTime": 616,
    "identifiedFaces": [
    {
        "attributes": {
            "centerPoseQuality": 0.58317417,
            "confidence": 0.99978894,
            "contrastQuality": 0.61625,
            "detectionVersion": 2,
            "dimension": {
                "height": 200,
                "width": 164
            },
            "landmarks": {
                "left-eye-center": {
                    "x": 0.31614387,
                    "y": 0.38013837
                },
                "left-mouth-corner": {
                    "x": 0.34892383,
                    "y": 0.7837046
                },
                "nose-tip": {
                    "x": 0.55630475,
                    "y": 0.6482113
                },
                "right-eye-center": {
                    "x": 0.7781885,
                    "y": 0.37358207
                },
                "right-mouth-corner": {
                    "x": 0.74510413,
                    "y": 0.7801639
                }
            },
            "provider": "RCV",
            "sharpnessQuality": 0.6402198
        },
    "lastOccurrenceDate": 1521757646850,
    "mediaId": "a058d139-4429- 4e3f-8603- 38290ac d3326",
    "occurrence": 2,
    "offsetX": 0.23326,
    "offsetY": 0.36203,
    "personId": "60046fb9-5b5d-4d2b-a3aa-6345e43da53d",
    "relativeHeight": 0.10982,
    "relativeWidth": 0.06004,
    "rootPersonAddDate": 1521747721069,
    "similar": [
        {
            "ignore": false,
            "lastOccurrenceDate": 1521747721069,
            "occurrence": 1,
            "personId": "60046fb9-5b5d-4d2b-a3aa-6345e43da53d",
            "similarityScore": 1.3789116
        },
        {
            "ignore": false,
            "lastOccurrenceDate": 1521747721069,
            "occurrence": 1,
            "personId": "328a6c14-c4b6-483b-8163- ac7390078a3f",
            "similarityScore": 0.6425859
        },
        {
            "ignore": false,
            "lastOccurrenceDate": 1521747721069,
            "occurrence": 1,
            "personId": "48328c18-044d-41d8-93c6- 73b7e6b68297",
            "similarityScore": 0.5377595
        },
        {
            "ignore": false,
            "lastOccurrenceDate": 1521747721069,
            "occurrence": 2,
            "personId": "83b86722-99d2-4327-8ded- a21be3d2382c",
            "similarityScore": 0.42808503
        },
        {
            "ignore": false,
            "lastOccurrenceDate": 1521723923106,
            "occurrence": 1,
            "personId": "ae4c5292-1e3a-4495-ba9a-6bd3d6c371e2",
            "similarityScore": 0.4004748
            }
    ],
    "tags": []
        }
    ]
}

API Response

The response is described in the following table:

Element Description Notes
identifiedFaces The esponse returns one entry in identifiedFaces array for each detected face. The order in which found faces (identities) are returned is arbitrary (i.e. they're not sorted by similarityScore)

Example: "identifiedFaces": [ { ... }, { ... }, { ... }, ... ]
Only positively identified faces (i.e. recognized with a similarityScore >= 1.0) are given a personId: "identifiedFaces": [ { "personId": "866e75a6-e22a-4077-97bb-e5dbfe1c513e", "personExternalId": " 0000001", "name": "0000001", ... }, { ... }, { ... }, ... ]
X-RPC-FACES-GROUPING-THRESHOLD Positive identification is governed by X-RPC-FACES-GROUPING-THRESHOLD. To override the default setting, the X-RPC-FACES-GROUPING-THRESHOLD header can be passed in each request.

Threshold Setting Guidelines

Similar Identities

For the similar_limit=5 parameter, each detected face contains the five most similar identities. Each similar identity has a personId and, if set, an externalId, as well as a similarityScore. The identities in the similar array are sorted by similarityScore in descending order with the highest similarityScore first:

"identifiedFaces": [
              {
                ...
                "similar" : [
                                     {
                       "personId": "866e75a6-e22a-4077-97bb-e5dbfe1c513e",
                       "name": " 0000001 ",
                       "externalId": " 0000001 ",
                       "similarityScore": 1.0804045,
                       ...
                                      },
                                      {
                       "personId": "92ca0413-4e67-4981-a649-cffa29c6d56c",
                       "name": " 0000023 ",
                       "externalId": " 0000023 ",
                       "similarityScore": 0.62635994,
                       ...
                                       },
                                       ...
              ]
            },
            {
              ...
              "similar" : [
                            ...
              ]
             },
             ...
]

Face Attributes

Each detected face has attributes detailing positioning, face landmarks, face image quality, CV algorithm provider (RCV), and face detection confidence. None of this is relevant for identification.

"identifiedFaces": [
    {
        ...
        "attributes": {
        provider": "RCV",
        ...
        }
    },
    {
        ...
        "attributes": {
        "provider": "RCV",
        ...
        }
    },
    {
        ...
        "attributes": {
        "provider": "RCV",
        ...
        }
    }
]

See Also