Edge Devices ============== What are edge devices ----------------------- Edge devices are physical devices (e.g., :term:`Identity authentication terminals`), which can connect and send images to FindFace Lite to recognise objects. In order to these devices get the results of recognition :term:`webhooks` should be set. The process of recognition from edge devices is the same as from CCTV cameras, the only difference is that Events are created directly from an edge device via POST request, but not from FindFace Lite system. Preparation to recognition process ---------------------------------- Before edge device integration, authenticate a device and create :term:`Objects` and :term:`Cards`, which will be compared with the created :term:`Events`. Authenticate a device ++++++++++++++++++++++++ In order to execute all operations (except those which are connected with Events) authenticate a device in the system, using **/v1/auth/login** POST request. For Events there is a token from the :ref:`config file` is used. For **username** and **password** parameters use data you got on :ref:`the STEP 5 `. **Request example:** .. code-block:: json { "username": "login", "password": "password" } **Successful response example:** .. code-block:: json { "access_token": "token" } Create a Card +++++++++++++++ :term:`Card` is used for keeping several Objects of a person or a car under the one profile. In the process of recognition the Card is treated as a *result*. To create a Card, use the **/v1/cards/** POST request. All parameters are described below. +----------------+-----------------+-----------------------------------------------+ | **Parameters** | **Value types** | **Description** | +================+=================+===============================================+ | **name** | string | The name of a Card. | +----------------+-----------------+-----------------------------------------------+ | **active** | true | The Card is enabled. | | +-----------------+-----------------------------------------------+ | | false | The Card is disabled. | +----------------+-----------------+-----------------------------------------------+ | **type** | face | The Card is created for the face recognition. | | +-----------------+-----------------------------------------------+ | | car | The Card is created for the car recognition. | +----------------+-----------------+-----------------------------------------------+ | **wiegand** | string | Wiegand code. | +----------------+-----------------+-----------------------------------------------+ **Request example:** .. code-block:: json { "name": "test card", "active": true, "type": "face", "wiegand": "test wiegand code" } **Successful response example:** .. code-block:: json { "name": "test card2", "active": true, "type": "face", "wiegand": "test wiegand cod2e", "id": 2, "objects": [] } Create an Object +++++++++++++++++ :term:`Objects` are used for representation of a face or a car. To create it add the image and link to the Card, using **/v1/objects/** POST request. All operations are described below. +----------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | **Parameters** | **Value types** | **Description** | +======================+=========================+===================================================================================================================================================+ | **card_id** | a number | The Card ID, which you want to connect with the Object. With one Card can be connected several Objects. | +----------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | **type** | enum | The type of the Object you want to create. **Сar** is for car image, **face** is for face image and **license_plate** is for license plate image. | +----------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | **input_file** | string | Put the filename which contains a face or car you would like to add to the database of Objects. | +----------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ **Request example:** .. code-block:: json { "card_id": "2", "type": "face", "input_file": "somehash.jpg" } **Successful response example:** .. code-block:: json { "id": 1, "emben": "vV1yPfc2izy...de8vY/bvNXLfDw=", "type": "face", "card": 4, "filename": "somehash.jpg" } Edge Devices integration ------------------------- To integrate an edge device with FindFace Lite, use API. All operations are described below. Create a Camera ++++++++++++++++ Create :term:`Camera` object using :code:`/v1/cameras/` POST request. .. note:: Camera object is only needed for further Event objects creations. It is not used in the flow of recognition via edge devices. Here is the description of needed parameters. Parameters, which are not included, describe settings for strreams. As you do not have any streams, you may not pay attention to them. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+ | **Parameters** | **Description** | +======================+==================================================================================================================================+ | **name** | The name for the Camera object. You can choose any. | +----------------------+----------------------------------------------------------------------------------------------------------------------------------+ | **url** | URL of an added stream. As you don't have the stream, set any value, beginning with :code:`rtmp://`. | +----------------------+----------------------------------------------------------------------------------------------------------------------------------+ | **active** | Camera object status. Set it to disabled – :code:`false`. | +----------------------+----------------------------------------------------------------------------------------------------------------------------------+ | **stream_settings** | Settings for streams from the CCTV camera. You have to fill only the mandatory parameter – **detectors**. | +----------------------+----------------------------------------------------------------------------------------------------------------------------------+ | **detectors** | Detectors settings. You have to include this parameter into the request, but you can leave it empty. | +----------------------+----------------------------------------------------------------------------------------------------------------------------------+ **Request example:** .. code-block:: json { "name": "Edge device", "url": "rtmp://none", "active": false, "stream_settings": { "detectors": { } } } **Successful response example:** .. code-block:: json { "name": "Edge device", "url": "rtmp://none", "active": false, "single_pass": false, "stream_settings": { "rot": "", "play_speed": -1, "disable_drops": false, "ffmpeg_format": "", "ffmpeg_params": [], "video_transform": "", "use_stream_timestamp": false, "start_stream_timestamp": 0, "detectors": {} }, "id": 2, "status": "UNKNOWN" } Configure the Edge Device ++++++++++++++++++++++++++ .. _conf_the_edge: .. warning:: After this step the edge device will be able to send data to FindFace Lite for recognition. To get the results back you should set the :term:`Webhook`. Configure the edge device to send Events :code:`/v1/events/{object_type}/add` POST requests. Event in case of edge device is a representation of an object (face or car) occurrence in the edge device zone, which is sent as a static file to the FinFace lite via API. Here is the description of parameters the edge device should send to FindFace Lite API. +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Parameters** | **Value types** | **Description** | +=================+=================+==========================================================================================================================================================================+ | **object_type** | car | The path parameter :code:`/v1/events/{object_type}/add`, which specify the object of recognition. | | +-----------------+ | | | face | | | +-----------------+ | | | license_plate | | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **token** | string | Authorization via **event_creation_token** set in :ref:`configuration file `. | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **camera** | a number | Camera ID with which the Event will be connected. | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **fullframe** | binary | Image in any suitable for static content format (jpeg, png, etc.). | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **rotate** | true | The technology of image rotation is enabled. System checks the objects position and tries to rotate if objects are upside down. | | +-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | false | The technology of image rotation is disabled. | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **timestamp** | date-time | The data-time in ISO format **yyyy-MM-dd'T'HH:mm:ss. SSSXXX**, for example: **2000-10-31T01:30:00.000-05:00** | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **mf_selector** |all | Multiface selector is enabled. All objects of Event are detected. | | +-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |biggest | Multiface selector is disabled. There is only biggest object on the image is detected. | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **roi** | numbers | Region of interest, which means image detection area. Specify the value in the [left, top, right, bottom] format, where values in the brackets are the numbers in grades | +-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ **Request example:** .. code-block:: json { "object_type": "face", "token": "change_me", "camera": 2, "fullframe": "somehash.jpg", "rotate": true, "timestamp": "2000-10-31T01:30:00.000-05:00", "mf_selector": "biggest", "roi": 15,20,12,14 } **Successful response example:** The response view will be different, depending on the value of the setting :code:`event_creation_response_type` in the :ref:`config file`. * If :code:`ID` is set, you will see only main information and the ID of a created Event .. code-block:: json { "events": [ "cc04cc9c-f355-4121-80c4-94a02eec652a", "c7d51db3-5b52-4318-9565-e2651308c1a6" ] } * If :code:`serialized` is set, you will see full information about a created Event, including matched Card, path to the fullframe image, etc. .. code-block:: json { "events": [ { "bbox_bottom": 97, "bbox_left": 170, "bbox_right": 214, "bbox_top": 39, "bs_type": "realtime", "camera": 1, "card": null, "confidence": null, "created_date": "2022-12-29 13:02:07.910724+00:00", "emben": "bmY3Pff9Grt1Ah09lp8kvn+a6Tw8SZs8K5xtvLOjtrxFtJ+9d5WIPH3PHL39acg9oNWhu4Mv2j2VjPo8QqDjubiFkz05Bou9SywUvMZ39bxYIhs9ucWxPTbApD3n8468/aQBvfdqFD2/woc9j03iO5U3vT1P6ya9BfNyPUCBkz1Smmm8CIPvPRPxWTzWXxo8DwRGvMxfp7zRhGw8KyZzPtwoCT0Bx7C9AcKWvflgUb2NLWQ9KmmjPUJ83D3XFVY9wdO7vX7/BD7OU8M9grEbPVTZCb3mgXg+LxfEvdm6uL2wLh08BU6yPQhREz0kj1M98tY+PNbA9D1MDC07Tp4dPjh7n7zZAQS9/JFzPWEJCb1CTwU+3deFvQb/hz2YaAa+Qbjpvd0UFb7HVtG9NEhLPMfS1rouTk49f6DTOy9r/j373aG7hBa3PW/eJT5Zuz08cO+2PZXVDL3hemE8sYa0PY7Xtj06NAG+Stw4vrhQhb2KtJe9J8hCvTM/Gr4vr0m9S3jJvfnBHz2QVgk97HuzvH2V/71lQsk9l4UTvqE3XD1ssos9ErvcvY5CCr6ftJ+9EOarPOKvKr0JFa69sdyCvQPcuj2nLtO89I+iuzS+aj1bTgY+qT4dPtREVz2iwLu9pM45PTjxe7yOyOm88t74PXgj3b0FDKA9uiaRvcs1Ez5dchS+5lTpO7D3Tb3CVLw8zrQwvczzq7wPVEo9OeEgvORUOz1x2Qk9pWKDPTdDjT24pXQ9MCWJPRe8iD1Vxse7iNmivY+coT2VRrG93XugPeZlrr3LSoU9iwpcPTF2uT2Bwei8ffa+u6JwLTwAk8M8NfAaveDZqT3AchA9Y/rVPA==", "features": { "headpose": { "pitch": 11.207756, "roll": 3.1429868, "yaw": 4.652887 }, "liveness": 0.6584981 }, "fullframe": "2022/12/29/13/c436c2d92c4c627d5c6d13f9f1d9555a.jpg", "type": "face", "uuid": "2f25dd19-d0cd-4b44-9147-69a7dc57450e" }, { "bbox_bottom": 75, "bbox_left": 57, "bbox_right": 100, "bbox_top": 15, "bs_type": "realtime", "camera": 1, "card": 1, "confidence": 0.8306973576545715, "created_date": "2022-12-29 13:02:07.917896+00:00", "emben": "yRukvSOo1r2Bcm699SGTO/SPBz64MvK9xINqPYDge708nSW9ba4BvAVgLz77ctw7A2OhvZ5LRD2rA1488DLnvSKQXT0ER367zf20vdypqb2Lhog8nIxjPa7E9rwqCuI9+lHAPDjvWLzxJko+aXkRPBgWfr1u9pi982G8PW4FEr3vlqM91VW5vXRxoz3B4OE9kLLPPfznu71po4w9sPVFPR4tH73Qe4+9/wKlvVlwr724Ll09LdqYPeOq170bDua8Zn2lPNy8dr0TF9G7VhMXPT6yQz0aCI49h8OJPQVTKb25oB+9x9++PEKCFj4uq0i8bBhoPbJPVjxkCgO+drV/PR3mrbxs+rW7TQqNO4QcFz2oI407H4nfvY/nQD57Y2m9ItFMPZQKibzobRi6cf9wPT1itz0lkw89qUv0vS9RVDxjGoC9E3SiOxqSsbzjnyc+P4ZnPpFjEz5XMZE8IuILvYvgQjwYu/A9waicOx9On7z0kW+9k7EmvIxuuLwdPPo9t5H3vQETLz6FcGQ+1fOqvfkwKz0rfSO9ckoivV65k70xw5296raIvYnnE70gaYa8IE1pvQZ+tr0VpJM8oAAWO8lU8zxlaai9WbnJvYPgHL29ouy8GyALvsoj1D1BiHg4+F2xPZlVhTyiiIS8eZFCPvUfTD4UcNQ9j2bqvUjSlbySk1+9q4ljvdcqyTzCnLa7hDgLvcb1oL2ScLo8GSYqvZW82b1Ppma9Ni2ePcrWQj34xxs8WU+2vbGUuD1+r0S9wieuPUfEkLthyCE9iZ3oOy9TED2RAVW93nXMvcVoAz1plvK9n8UOPUV3grvH+yO9DEohPAMYDD0hd+698x6TvQ==", "features": { "headpose": { "pitch": -2.1808214, "roll": -0.5856089, "yaw": -4.5041146 }, "liveness": 0.5574532 }, "fullframe": "2022/12/29/13/4ef96c620d738d87c00aaaaa12fccca2.jpg", "type": "face", "uuid": "9b718d45-919a-490f-9fe6-b2af58cbf83a" } ] } * If :code:`serialized_verbose` is set, you will see full information about a created Event (including a matched Card, path to the fullframe image, etc) and full information about the Card. .. code-block:: json { "events": [ { "bbox_bottom": 97, "bbox_left": 170, "bbox_right": 214, "bbox_top": 39, "bs_type": "realtime", "camera": { "active": false, "id": 1, "name": "test camera", "single_pass": false, "status": "DISABLED", "url": "rtmp://test" }, "card": null, "confidence": null, "created_date": "2022-12-29 13:48:34.624541+00:00", "emben": "bmY3Pff9Grt1Ah09lp8kvn+a6Tw8SZs8K5xtvLOjtrxFtJ+9d5WIPH3PHL39acg9oNWhu4Mv2j2VjPo8QqDjubiFkz05Bou9SywUvMZ39bxYIhs9ucWxPTbApD3n8468/aQBvfdqFD2/woc9j03iO5U3vT1P6ya9BfNyPUCBkz1Smmm8CIPvPRPxWTzWXxo8DwRGvMxfp7zRhGw8KyZzPtwoCT0Bx7C9AcKWvflgUb2NLWQ9KmmjPUJ83D3XFVY9wdO7vX7/BD7OU8M9grEbPVTZCb3mgXg+LxfEvdm6uL2wLh08BU6yPQhREz0kj1M98tY+PNbA9D1MDC07Tp4dPjh7n7zZAQS9/JFzPWEJCb1CTwU+3deFvQb/hz2YaAa+Qbjpvd0UFb7HVtG9NEhLPMfS1rouTk49f6DTOy9r/j373aG7hBa3PW/eJT5Zuz08cO+2PZXVDL3hemE8sYa0PY7Xtj06NAG+Stw4vrhQhb2KtJe9J8hCvTM/Gr4vr0m9S3jJvfnBHz2QVgk97HuzvH2V/71lQsk9l4UTvqE3XD1ssos9ErvcvY5CCr6ftJ+9EOarPOKvKr0JFa69sdyCvQPcuj2nLtO89I+iuzS+aj1bTgY+qT4dPtREVz2iwLu9pM45PTjxe7yOyOm88t74PXgj3b0FDKA9uiaRvcs1Ez5dchS+5lTpO7D3Tb3CVLw8zrQwvczzq7wPVEo9OeEgvORUOz1x2Qk9pWKDPTdDjT24pXQ9MCWJPRe8iD1Vxse7iNmivY+coT2VRrG93XugPeZlrr3LSoU9iwpcPTF2uT2Bwei8ffa+u6JwLTwAk8M8NfAaveDZqT3AchA9Y/rVPA==", "features": { "headpose": { "pitch": 11.207756, "roll": 3.1429868, "yaw": 4.652887 }, "liveness": 0.6584981 }, "fullframe": "2022/12/29/13/5e870f4f9dbd1e27652f6384663b8cab.jpg", "type": "face", "uuid": "df0821b4-6e52-4b66-abd2-0f642e2a090a" }, { "bbox_bottom": 75, "bbox_left": 57, "bbox_right": 100, "bbox_top": 15, "bs_type": "realtime", "camera": { "active": false, "id": 1, "name": "test camera", "single_pass": false, "status": "DISABLED", "url": "rtmp://test" }, "card": { "active": true, "id": 1, "name": "test card", "objects": [], "type": "face", "wiegand": "test wiegand code" }, "confidence": 0.8306973576545715, "created_date": "2022-12-29 13:48:34.633562+00:00", "emben": "yRukvSOo1r2Bcm699SGTO/SPBz64MvK9xINqPYDge708nSW9ba4BvAVgLz77ctw7A2OhvZ5LRD2rA1488DLnvSKQXT0ER367zf20vdypqb2Lhog8nIxjPa7E9rwqCuI9+lHAPDjvWLzxJko+aXkRPBgWfr1u9pi982G8PW4FEr3vlqM91VW5vXRxoz3B4OE9kLLPPfznu71po4w9sPVFPR4tH73Qe4+9/wKlvVlwr724Ll09LdqYPeOq170bDua8Zn2lPNy8dr0TF9G7VhMXPT6yQz0aCI49h8OJPQVTKb25oB+9x9++PEKCFj4uq0i8bBhoPbJPVjxkCgO+drV/PR3mrbxs+rW7TQqNO4QcFz2oI407H4nfvY/nQD57Y2m9ItFMPZQKibzobRi6cf9wPT1itz0lkw89qUv0vS9RVDxjGoC9E3SiOxqSsbzjnyc+P4ZnPpFjEz5XMZE8IuILvYvgQjwYu/A9waicOx9On7z0kW+9k7EmvIxuuLwdPPo9t5H3vQETLz6FcGQ+1fOqvfkwKz0rfSO9ckoivV65k70xw5296raIvYnnE70gaYa8IE1pvQZ+tr0VpJM8oAAWO8lU8zxlaai9WbnJvYPgHL29ouy8GyALvsoj1D1BiHg4+F2xPZlVhTyiiIS8eZFCPvUfTD4UcNQ9j2bqvUjSlbySk1+9q4ljvdcqyTzCnLa7hDgLvcb1oL2ScLo8GSYqvZW82b1Ppma9Ni2ePcrWQj34xxs8WU+2vbGUuD1+r0S9wieuPUfEkLthyCE9iZ3oOy9TED2RAVW93nXMvcVoAz1plvK9n8UOPUV3grvH+yO9DEohPAMYDD0hd+698x6TvQ==", "features": { "headpose": { "pitch": -2.1808214, "roll": -0.5856089, "yaw": -4.5041146 }, "liveness": 0.5574532 }, "fullframe": "2022/12/29/13/6041c2a71f4e2020d4cbaa52ce9b41f8.jpg", "type": "face", "uuid": "4dad4c16-f1cd-4ff1-a18a-268b71c1dbec" } ] }