FindDescriptorBatch

Find descriptors that satisfy the specified constraints.

If a descriptor is provided in the array of blobs, a k-nearest neighbor search is computed.

Parameters

  • [optional] set: Name of the set.

  • [optional] n_descriptors: the number of descriptors represented in the blob (Default: 1)

  • [optional] k_neighbors: Specifies the number of nearest neighbors to be returned.

  • [optional] knn_first: Specifies whether the k-nearest neighbor computation will be run before or after the constraints are applied.

  • [optional] engine: Specifies the engine used for indexing and computing distances. If not specified, the default engine will be used.

  • [optional] metric: Specifies the metric used to compute distances. If not specified, the default metric will be used.

  • [optional] labels: indicates whether the labels of the descriptor will be returned as part of the response (Default: false).

  • [optional] distances: indicates whether the distances to the k-nn search will be returned as part of the response (Default: false).

  • [optional] blobs: indicates whether the blobs will be returned

  • [optional] with_label

  • [optional] indexed_results_only: only consider for nearest neighbor descriptors that have been indexed for search (Default: false). This makes the query more efficient at the risk of missing descriptors that have been added recently (typically, within the last hour or so).

Details

The set parameter specifies the “name” of the DescriptorSet in which the k-nearest neighbor computation will be performed. If DescriptorSet with that “name” does not exist, an error is returned.

The k_neighbors parameter specifies the number of k-nearest neighbors that will be computed. This parameter requires that BOTH a descriptor will be provided in the array of blobs AND a set name is provided, as the set defined the search space.

The knn_first is a Boolean parameter that specifies whether the k-nearest neighbors computation must be run before or after filtering descriptors with the constraints. specified in constraints. If set to “true”, k-nearest neighbors are computed first and then constraints are applied. If it is set to false, it applies constraints first and then k-nearest neighbors are computed. The latter is a more expensive operation since a descriptor index is constructed on-the-fly with descriptors that satisfy the specified constraints. By default, it is set to “true”.

If only one ref parameter is used in the is_connected_to array, the resulting objects obtained after traversing the given connection can be associated with their source objects by specifying the parameter group_by_source as true. The parameter is ignored if is_connected_to is absent. It is set to false by default.

Examples

Find the 10 nearest-neighbors of a given batch of descriptors, retrieve the “year_created” and “description” properties of those descriptors, and also retrieve the “label” associated with the descriptor and the “distances” of the k-nn computation.

[{
    "FindDescriptorBatch": {
        "set": "party_faces",
        "k_neighbors": 4,
        "n_descriptors": 2,
        "labels": true,
        "distances": true
    }
}]

Note: A blob must be passed together with the JSON Query. The blob is an array of 32bit floating point values represeting the input query descriptors.

Example response:

[{
    "FindDescriptorBatch": {
        "entities": [{
            "_distances": [
                [0, 2.0],
                [1, 4.0]
            ],
            "_label": "Pilypas Bruno"
        }, {
            "_distances": [
                [0, 2.0],
                [1, 4.0]
            ],
            "_label": "Era Aivar"
        }, {
            "_distances": [
                [1, 2.0],
                [0, 2.0]
            ],
            "_label": "Radha Akash"
        }, {
            "_distances": [
                [0, 1.0],
                [1, 3.0]
            ],
            "_label": "Kwasi Publius"
        }, {
            "_distances": [
                [1, 2.0],
                [0, 4.0]
            ],
            "_label": "Broccomaglos Tyree"
        }, {
            "_distances": [
                [1, 2.0],
                [0, 4.0]
            ],
            "_label": "Gregoria Hine"
        }, {
            "_distances": [
                [1, 1.0],
                [0, 3.0]
            ],
            "_label": "Marjeta Pe\u0111a"
        }, {
            "_distances": [
                [0, 1.0],
                [1, 5.0]
            ],
            "_label": "Harisha Balaram"
        }],
        "returned": 8,
        "status": 0
    }
}]