LUNA PLATFORM v.5.34.0#

Changes

The SDK has been updated to version 5.12.0. Key SDK changes affecting LUNA PLATFORM 5:
- the following estimators have been updated: LivenessOneShotRGB, FishEye, Orientation, HeadWear;
- the 54th, 56th, and 57th face descriptor extraction neural network models and the 104th and 107th body descriptor extraction neural network models have been removed. Support for these models remains available. If necessary, you can request them from VisionLabs specialists.
Now the default body descriptor extraction neural network model is 107 (setting "DEFAULT_HUMAN_DESCRIPTOR_VERSION" of the Handlers service).

Important information for upgrading from previous versions

You should do one of the following before starting the Handlers container:
- manually change the setting value "DEFAULT_HUMAN_DESCRIPTOR_VERSION" from "104" or "106" to "107". After changing the version of the neural network for extracting body descriptors, you should perform the "Additional extraction" task after starting the Admin service (see "Launch re-extraction task" section in the administrator manual). Otherwise, search and matching by old descriptors will be unavailable.
- disable the use of a neural network to extract the body descriptors by passing the "--enable-body-descriptor-estimator=0" argument when starting the Handlers container;
- request the 104th neural network model from VisionLabs and transfer it to the Handlers container according to the instructions described in the [Use non-delivery neural network model](https://docs.visionlabs.ai/luna/v.5.34.0/standard-distribution/admin-manual/additional-information/#use-non-delivery-neural-network-model] section in the administrator manual.
If one of the above actions is not performed, then starting the Handlers service will fail.

All of the above information has been added to the update manual in the "Changing the model of the neural network of bodies" section.

When launching LUNA PLATFORM from scratch, no additional actions are required.
New "meta" field has been added to the event structure, designed to store arbitrary user data in JSON format (no more than 2 MB).

It is assumed that with the help of this functionality, the user will create his own data model (event structure) and use it to store this data. Note that if you plan to store multiple structures, you must explicitly separate them to avoid overlapping fields. For example, as follows:
```
{
    "struct1": {
        ...
    },
    "struct2": {
        ...
    }
}
```
Data in the "meta" field can be set in the following ways:
- in the "generate events" request body with the content type "application/json" or "multipart/form-data";
- in the "save events" request body;
- using a custom plugin or client application.
In the "generate events" request body, it is possible to set the "meta" field both for specific images and for all images at once (mutual meta-information). For requests with aggregation enabled, only mutual meta-information will be used for the aggregated event, and meta-information for specific images will be ignored. See the detailed information in the "generate events" request body in the OpenAPI specification.

The "meta" field can be used as a filter in a "get events" request or as a value for the "target" parameter in a "get event" request.

The "meta" column has been added to the Reporter and Exporter tasks.

Support for event meta-information has also been added to the "ws handshake" resource.

If necessary, you can build an index to improve the search.

See the detailed description and operation features in the "Events meta-information" section of the administrator manual.
Support for the Liveness V1 service has been discontinued.

The Liveness V1 service has been removed from the documentation and service settings. Liveness V2 has been renamed to Liveness.
New argument "enable-all-estimators-by-default" has been added to the launch arguments of the Handlers container, enabling/disabling the initialization of all default estimators and detectors.

Previously, in order to use certain estimators or detectors, it was necessary to specify the status of each existing estimator. Now it's enough to disable the initialization of all estimators "enable-all-estimators-by-default=0" by default, and then specify only those estimators or detectors that you need to enable. An example of a command to start the Handlers service using only a face detector and estimators of face sample and emotions.
```
docker run 
...
--env=EXTEND_CMD="--enable-all-estimators-by-default=0 --enable-face-detector=1 --enable-face-warp-estimator=1 --enable-emotions-estimator=1" 
...
```
See the "Enable/disable several estimators and detectors" section of the administrator manual for details.
Now the filter by "account_id" is optional for the Clustering (request body filter), Cross-matching (request body filter for candidates or references) and Estimator (matching filters in handler policies) tasks. This enables you to match across objects from different accounts.
For the resources listed below, a new "external_url" parameter has been added to the response body, indicating the absolute address to the object:
- "create account",
- "create token",
- "replace token",
- "create images",
- "create objects",
- "extract attributes",
- "create face",
- "create list",
- "save event",
- "create verifier",
- "create handler".
The absolute address is the address of the API service specified in the "EXTERNAL_LUNA_API_ADDRESS" setting of the API service. The default setting value is http://127.0.0.1:5000/6/. This change enables you to use links from API service responses for your own purposes, without knowing the exact address of the service. The change also enables you to send links in a convenient format, by which you can get their contents.

Relative link example ("url" parameter): "/6/objects/4a870804-0cd6-4c13-9c78-98ad167dc4ec"

Absolute link example ("external_url" parameter): "http://127.0.0.1:5000/6/objects/4a870804-0cd6-4c13-9c78-98ad167dc4ec"
Support for the "Accept" header has been added to the "get face descriptor batches" resource of the Faces service, which takes two values — "application/x-flutbuf" (default) and "application/x-msgpack".
The unused "max_face_size" parameter of the "LUNA_HANDLERS_FACE_DETECTOR_SETTINGS" section has been removed from the Handlers service settings.

The "max_face_size" parameter is calculated as "min_face_size * 32".

LUNA Index Module changes

The LUNA Index Module installation manual has been updated.

Now by default there are commands to install the module in "/var/lib/luna/" directory instead of in "/var/lib/luna/current/" directory.

The index storage is now created in the "/var/lib/luna/" directory to simplify the upgrade process.
The LUNA Index Module upgrade manual has been added.
LUNA Index Module now takes into account changes in the version of face descriptors. It means that:
- the Indexer service builds an index from descriptors of the version specified in the "DEFAULT_FACE_DESCRIPTOR_VERSION" setting of the Index Manager service;
- the Index Manager service automatically rebuilds the index if it does not contain information about versions of descriptor;
- the Indexed Matcher service loads only those indexes that contain descriptors of the version specified in the "DEFAULT_FACE_DESCRIPTOR_VERSION" setting of the Index Manager service.
In this regard, the mandatory field "descriptor_version" has been added to the index metastructure ("meta.json"). The "get indexes" and "get most relevant indexes" requests also return the "descriptor_version" parameter.

Important information for upgrading from previous version

After starting the Index Manager service, it will automatically start rebuilding all indexes that do not contain information about descriptors, i.e. all indexes created in a previous version of LIM. Rebuilding the index can take a long time, depending on the number of faces on the lists. In order to avoid the lengthy process of rebuilding the index, you can add the "descriptor_version" field with the corresponding version of the descriptors to the "meta.json" files of all previously created indexes before starting the Index Manager service.

Reminder added to "Important information" section of the new LIM upgrade manual.
Now, by default, the Indexed Matcher service monitors changes in lists with faces. If new changes are made to the list, the Indexed Matcher service updates the corresponding indexes in its memory by gradually adding a small number of descriptors.

The use of this functionality is controlled by the "enabled" setting of the "LIM_MATCHER_REFRESH" section of the Configurator service.

When a cached index is updated, the Indexed Matcher service stops matching on that index, but continues to accept new match requests for that index. By adding a small number of descriptors to the cached index, the matching process is performed with minimal interruption. However, it should be taken into account that if elements are inserted into the list too often (dozens and hundreds of additions), then this can cause a significant degradation in the speed of work, up to an almost complete stop of the matching process.

If this functionality is used, then it is not necessary and not recommended to perform frequent index rebuilds. Accordingly, it is recommended to increase the planning routine period ("planning_period" setting of the "LIM_MANAGER_INDEXING" section of the Configurator service. However, adding new faces to the cached index is slower than rebuilding the index, so it makes no sense to use this function if a very large number of faces have been added to the list. In this case, it is easier to rebuild the index again.

See "Cached index refreshing" section in the LIM administrator manual.
Downloading descriptors from the Faces service has been optimized. The "Accept" header has been changed from application/x-flutbuf to application/x-msgpack.
"Warming up" (test matching) the first created index before starting to use it has been added. Subsequent indexes are not "warmed up".

"Warm-up" is performed after the index is loaded into the memory of the Indexed Matcher service and the service is waiting for a matching request.
The Python version has been updated to 3.10. Support for other versions has been discontinued.

Fixed errors

The API service OpenAPI specification has been corrected and extended the response code examples 403, 408, 413, 500, 503, and 504. See the response examples in the OpenAPI specification.
The "perform verification" request now has a previously missing parameter for specifying the type of image to be processed "image_type". Two values are available for this parameter — 0 (source image) and 1 (face sample).
Incorrect thresholds for the "mouth_occluded", "mouth_smiling" and "mouth_open" parameters of the "face_quality" parameter group in the "create handler", "get handlers", "get handler" and "replace handler" requests have been fixed in the OpenAPI specifications of API services and Handlers.

The specification previously stated that the allowed thresholds for the above parameters are [-1..1], although in fact the allowed thresholds are [0..1].