.. _AddDescriptorSet:
AddDescriptorSet
================
Add a descriptor set and properties associated with it.
Parameters
----------
* :ref:`name `: Name of the DescriptorSet.
* :ref:`dimensions `: Number of dimensions of the descriptor.
* [optional] :ref:`engine `:
Specifies the implementation for indexing and computing distances.
* [optional] :ref:`metric `:
Specifies the metric used to calculate distances.
* [optional] :ref:`_ref [`: reference to be used within the transaction.
* [optional] :ref:`properties `
* [optional] :ref:`connect `
Details
-------
A DescriptorSet is a group of descriptors with a fixed number of
dimensions that are the result of the same algorithm for feature extraction.
For instance, we can create a DescriptorSet and insert multiple descriptors
obtained by using OpenFace (128 dimensions),
and then index and perform matching operations over those descriptors.
.. include:: add_details.rst
.. _set_name:
**name** specifies the set name that will be used for later access to the
set, or for running knn within the set.
A DescriptorSet is conditionally added if and only if a
DescriptorSet with the same **name** does not exist.
.. _dimensions:
**dimensions** specifies the number of dimensions of the descriptor.
For instance, a DescriptorSet used to store descriptors of faces using
OpenFace will have 128 dimensions.
.. _engine:
The **engine** parameter specifies the method used to index descriptors,
and consequently, the structure of the index.
The **engine** defines trade-offs of accuracy vs latency:
some indexes will compute "exact" search, taking longer to compute,
and some other indexes will compute an "approximate" search much faster.
The supported engines are:
* FaissFlat [Exact search] [Default]
* FaissIVFFlat [Approximate search]
* TileDBDense [Exact search]
* TileDBSparse [Exact search]
.. _metric:
The **metric** parameter specifies the metric used to compute distances
between descriptors, when performing similarity search.
The supported metrics are:
* L2 (euclidean distance) [Default]
* IP (inner product)
Examples
--------
Insert a DescriptorSet for face recognition, using 128-dimensional descriptors
and engine for exact search (FaissFlat).
.. code-block:: python
[ {
"AddDescriptorSet": {
"name": "pretty_faces",
"dimensions": 128,
"engine": "FaissFlat",
"metric": "L2",
"properties": {
"year_created": 2018,
"description": "face recognition descriptors"
}
}
} ]
]