Skip to main content

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": [
                    [0, 2.0],
                    [1, 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
        }
    }]