FindDescriptor

We can perform queries to find descriptors that have some specific properties. We can also perform queries to find descriptors that are similar to some “query” descriptor. Descriptor blob(s) are returned unless “blob” is explicitly set to false in the “results” block (please see “results” block).

Parameters

  • set: name of the set.
  • [optional] _ref: for reference.
  • [optional] k_neighbors: number of neighbors to be returned.
  • [optional] knnfirst: [True or False]. If a user wants to get k-neighbors as well as apply constraints when finding a descriptor, both can be specified but the order in which they are applied is determined by this variable.

Blocks

  • [optional] properties
  • [optional] constraints
  • [optional] results

“knnfirst” is set to True by default which means k-neighbors is done first and then constraints are applied. If it is set to false, it applies constraints first and then finds KNN descriptors. The latter is a more expensive operation since a descriptor index is constructed on the fly with descriptors that match a certain constraint. These descriptors do need to be from the same descriptor set.

Examples

For instance, suppose that we want to get all the descriptors from people that have certain age, as we are interested in studying some particular characteristics of those descriptors.

We can run that query by doing:

"FindDescriptor": {
    "set": "party_faces",            # Specify the descriptor set
    "constraints": {
        "age": [">=", "30"]          # We want only those which correspond to people
    },                               # 30 years or more older.
    "results": {
        "list": ["age", "gender"]    # We want some properties to be returned
    }
}

In this case, ApertureData Platform will return:

"FindDescriptor": {
    "status": "success",
    "entities": [
        {                       # Let's say this represents Ricky Fort
            "age": 45,
            "gender": "M"
        },
        {                       # Let's say this represents Regina George
            "age": 32,
            "gender": "F"
        }
    ]
}
# + blob                        # The blob is returned using the client library.
                                # In this case, it will be an array with the values :
                                # [2.12, 3.4, 56.3, ...](Ricky) and
                                # [16.5, 4.7, 28.1, ...](Regina)

Suppose that we want to get all the descriptors that are most similar to:

[16.6, 4.9, 27.8, ...] (query descriptor)

We can run the following query:

"FindDescriptor": {
    "set": "party_faces",  # Specify the descriptor set

    # We specify that we want only the two nearest neighbor
    "k_neighbors": 2,

    "results": {
        "list": [
            "_label",      # We want the label assigned to that descriptor
            "gender",      # its gender
            "_distance"    # and its distance to the query descriptor
        ],

        # We specify that in this case,
        # we don't want the actual descriptor to be returned.
        "blob": False

    }
}

+ blob          # The blob is passed using the client library.
                # In this case, it will be an array with the values :
                # [16.6, 4.9, 27.8, ...] (the query descriptor)

Naturally, the closest neighbor to that query descriptor will be the one that corresponds to Regina George’s face.

In this case, ApertureData Platform will return:

"FindDescriptor": {
    "status": "success",
    "entities": [
        {
            "_label": "Regina George",
            "gender": "F",
            "_distance": 34.342
        },
        {
            "_label": "Karen Smith",
            "gender": "F",
            "_distance": 287.345
        }
    ]
}