Skip to content

# Glossary

Term | Definition
--- | ---
Bestshot | The frame of the video stream in which the face is captured in the best angle for further use in a face recognition system
Liveness | Software method that enables you to confirm whether a person in one or more images is "real" or a fraudster using a fake ID (printed face photo, video, paper or 3D mask)
Detection | Actions to find areas of the image containing faces
Spoofing attack | Substitution of a real person for a fake image (for example, a photograph) to deceive the system

# Introduction

This document describes:

- the process of installing as well as uninstalling the VisionLabs LUNA KIOSK application,
- hardware and software requirements of the equipment.

VisionLabs LUNA KIOSK (hereinafter referred to as System) is a set of libraries that provide the possibility of realizing real-time operation to perform face detection in a frame, check the vitality of a person and transfer data to an external system.

The System is designed for:

- receiving and processing a color video stream from a video recording device,
- checking the image quality,
- selecting the bestshot,
- face detection by machine calculation method on two images,
- checking the presented image by Liveness-algorithms,
- protection against image spoofing by depth map analysis,
- subsequent transfer of the bestshot to device integration systems.

# System requirements

The minimum system requirements below (Table 1 and Table 2) must be met in order to install the full System package.

Table 1. Minimum system requirements for x64 architecture

Required Resource | Recommended
--- | ---
Processor | Intel(R) Core(TM) i3-10110U
RAM | 4GB or more
Hard disk drive | HDD or SSD at least 1,4 GB
Operating system | Windows 10 (64 bit); Ubuntu 24.04 x64; Debian 10 x64
Instruction Support | Advanced Vector Extensions 2 (AVX2)

> To run the application on Windows, install the Visual C++ Redistributable package.

Table 2. Minimum system requirements for ARM architecture

Required Resource | Recommended
--- | ---
Processor | Rockchip RK3588S
RAM | 4GB or more
Hard disk drive | HDD or SSD at least 128GB
Operating system | Armbian 23 (aarch64)

Correct operation of the System is ensured by Intel® RealSense™ Camera D400-Series 3D cameras with firmware version 5.15.0.2, VLS LUNA CAMERA 3D cameras and VLS LUNA CAMERA 2D IR cameras:

- Intel® RealSense™ Depth Cameras D415;
- Intel® RealSense™ Depth Cameras D435;
- Intel® RealSense™ Depth Cameras D435i;
- VLS LUNA CAMERA 3D / VLS LUNA CAMERA 3D Embedded;
- VLS LUNA CAMERA 2D.

> For information about VLS LUNA CAMERA 3D / VLS LUNA CAMERA 3D Embedded, please contact your VisionLabs representative.

Use USB 3.0 to work with Intel® RealSense™ Camera D400-Series 3D cameras, VLS LUNA CAMERA 3D and VLS LUNA CAMERA 2D.

# Licensing

To obtain a license, please contact your VisionLabs representative. The response will include the necessary license activation parameters.

> Note: You can use the same license activation data across all supported platforms, including Windows, Ubuntu, Debian, and Armbian. For the license activation process, see the Installation section.

## Switching the license type

You can configure the system to use either FIT or Zeus license by modifying the `licenseModel` parameter.

To do this, locate the `licenseModel` parameter in the data/license.conf file and assign one of the following values:

- `1` to use the FIT license.
- `2` to use the Zeus license.

Once configured, save the file and restart the service to initialize the new license type.

# Installation

LUNA KIOSK is distributed in two configurations, differing in how configuration settings are stored:

- On Ubuntu 24.04 x64, Debian 10 x64, and Armbian 23: Configuration files server.conf and rsengine.conf located in the /client directory are used.
- server.conf - Contains server operation and logging settings.
- rsengine.conf - Defines thresholds for Liveness estimations.
- On Windows: Settings are stored in the Windows Registry by default after installation.

> Note: The Windows distribution does not include configuration files in the /client folder, as registry-based configuration is recommended. If you require configuration files, please request them from VisionLabs.

## Installation on Windows

RSE Server is installed as a Windows service.

### Step 1: License activation

Before installation, configure the license by editing the data/license.conf file with values provided in your license letter from VisionLabs.

The table below outlines the parameters required for license activation:

Parameter | Description | Example
--- | --- | ---
`Server` | The URL of the activation server used to validate and activate the license. | https://
`EID` | A unique access authorization identifier. | 00000000-0000-0000-0000-0000-0000-000000000000
`ProductID` | The specific product identifier. | 00000000-0000-0000-0000-0000-0000-000000000000
`LICENSE_FILENAME` | A license file name. Non-public parameter, do not change. | license.dat
`LICENSE_CONTAINERMODE` | License execution mode: `0` - run in container `1` - local (recommended) | `1`
`licenseModel` | Defines the license to be used: `1` - The system uses the FIT license. `2` - The system uses the Zeus license. | `2`

### Step 2: Preparing for LUNA KIOSK installation

1. Run `InstallService.bat` as Administrator from the root of the distribution package.

2. During installation:

3. The service is registered in the Windows Registry.

4. A log directory is created at C:\RSE\logs by default.
   You can adjust logging levels later in the Windows Registry.

### Step 3: System configuration

All system parameters are written to the Windows Registry. The parameters are set to default values and can be customized by an administrator. For a full list of parameters, see Appendix 1.

### Step 4: System management

After the installation is complete, you can manage RSE Sever using the services.msc service manager.

> Important: Do not change the location of RSE Server and *.conf files after installation. Otherwise, the system functionality will be impaired.

### Delayed service start

When installing LUNA KIOSK, you can control whether the service will start immediately after installation.

To do this, use the `StartService` parameter of the installService.bat installation script. The parameter has the following values:

Value | Description
--- | ---
`true` | Default. The service will be automatically started after installation.
`false` | The service will be installed, but its startup will be skipped.

### Troubleshoot metadata sampling issues for RealSense camera sensors

Windows requires a special registry entry for each unique video device to provide metadata. Metadata, or metadata attributes, refer to additional information provided by the `librealsense` library and are necessary for proper interaction with RealSense camera sensors.

To activate the functionality related to metadata attributes, the realsense_metadata_win10.ps1 file is included with LUNA KIOSK. A script in the file creates and modifies entries in the Windows registry to ensure that the RealSense camera sensors work correctly. For more information on activating metadata, see `librealsense` library documentation.

## Installation on Ubuntu 24.04 x64, Debian 10 x64, and Armbian 23 operating systems

### Prerequisites

Use Ansible to automate installation on Linux-based systems:

1․ Install Ansible:

    apt-get install ansible

2․ Verify the installation:

    ansible --version

If the installation is successful, the console will display the Ansible version and other information:

      ansible [core 2.12.4]
        config file = /etc/ansible/ansible.cfg
        configured module search path = ['/home/vivek/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
        ansible python module location = /usr/lib/python3/dist-packages/ansible
        ansible collection location = /home/vivek/.ansible/collections:/usr/share/ansible/collections
        executable location = /usr/bin/ansible
        python version = 3.8.10 (default, Mar 15 2022, 12:22:08) [GCC 9.4.0]
        jinja version = 2.10.1
        libyaml = True

### Step 1: Pre-action and license activation

Before running the installation:

1․ Add addresses (`ip` or `hostname`) of target devices to the ansible/hosts file to install the distribution. Each line contains one address. For example:

    [rse]
    12.16.58.33

2․ Adjust the shared variables and license data in the group_vars/all.yml file:

> Note: `LICENSE_SERVER`, `LICENSE_EID`, `LICENSE_PRODUCTID` are responsible for licensing and provided by VisionLabs.

Variable | Description | Possible values
--- | --- | ---
`RSE_HOME` | Installation directory. Non-public value, do not change. | /var/lib/kiosk
`RSE_VERSION` | System version. The value must match the archive name. | ub1804_x64_v1.0.4_rc2
`RSE_ZIP_LOCATION` | Absolute or relative path to the RSE Server distribution within the distribution package. | ../distr/rse-server_v.2.5.0.zip
`LICENSE_SERVER` | License server address. Request data from VisionLabs. | https://.com
`LICENSE_EID` | Access license identifier. Request data from VisionLabs. | 00000000-0000-0000-0000-0000-000000000000
`LICENSE_PRODUCTID` | Product identifier. Request data from VisionLabs. | 00000000-0000-0000-0000-0000-0000-000000000000
`LICENSE_FILENAME` | License file name. Non-public parameter, do not change. | license.dat
`LICENSE_CONTAINERMODE` | License execution mode. | `0` - run in container `1` - local (recommended)
`licenseModel` | License type. Request data from VisionLabs. | `1` - The system uses the FIT license. `2` - The system uses the Zeus license.

### Step 2: LUNA KIOSK installation

The installation location of the system is specified in the `RSE_HOME` variable.

Navigate to the ansible folder and run:

- For remote hosts:

If the installation is performed on several devices at once (more than one IP address is specified in the host), run the command:

    ansible-playbook -I hosts install_rse.yml

During installation, Ansible attempts to connect as the system user (root by default) via the appropriate SSH key pair. If a password is used instead of keys, add the `--ask-pass` flag to the install command.

- For local installation:

If the installation is performed locally on one device, run the command:

    ansible-playbook -i hosts--connection=local--inventory 127.0.0.1, install_rse.yml

### Step 3: LUNA KIOSK setup

When starting the RSE Server, the system uses the settings from the `server.conf` and `rsengine.conf` configuration files. For setting descriptions, see Appendix 1.

If you need to change the client configuration settings, make changes in the `server.conf` and `rsengine.conf` files and restart the RSE Server.

If the installation is successful, the logs will be written to log files in the default ./logs directory after LUNA KIOSK is launched. To change the location, update the `log-path` parameter in the server.conf file.

### Step 4: LUNA KIOSK management in Linux

After the installation is complete, manage RSE Sever using the `systemctl` command line utility.

To start RSE Sever, run the following command:

    systemctl start kiosk

To stop the RSE Sever, run the following command:

    systemctl stop kiosk

## Offline license activation

Use offline activation when the target device has no internet access. In this scenario:

- The device fingerprint is generated on the offline device.
- The license is activated on an internet-connected device using that fingerprint.

### Prerequisites

Before you start, obtain the license server address and EID from VisionLabs.

### Step 1: Generate device fingerprint

On the offline device where the license will be installed:

1․ Open the license.conf file located in the data directory. 2․ Specify `EID` and save the file. 3․ Run the `FingerprintViewer` utility to generate the fingerprint:
- On Linux/Armbian:
1․ Navigate to the extras folder.

    2․ Grant access rights to the FingerprintViewer utility:

      ```bash
        chmod +x FingerprintViewer
      ```

    3․ Run the utility by specifying the path to the *license.conf* file:

      ```bash
      ./FingerprintViewer ../data/license.conf
      ```

- On Windows:

  Run FingerprintViewer.exe from the root folder of the distribution package.

4․ Copy the displayed fingerprint from the console for use in the next step.

### Step 2: Activate license

On an internet-connected device:

1. Go to the license activation portal (URL obtained from VisionLabs).
2. Log in using your EID.
3. Paste the copied device fingerprint to activate the license.
4. Download the generated license certificate (licenseFile.v2c).
5. Move licenseFile.v2c to the data directory.
6. Rename the file using one of the following methods:
7. Change the `Filename` parameter in the license.conf file according to the example:

       <param name="Filename" type="Value::String" text="licenseFile.v2c"/>

8. Rename licenseFile.v2c to license.dat and ensure the `Filename` parameter in the license.conf file matches the actual name:

       <param name="Filename" type="Value::String" text="license.dat"/>

### Step 3: Deploy license

Copy the obtained license.dat license key to the data directory.

# Deletion

## Uninstall on Windows

To uninstall RSE Server and logs on Windows OS, run the `uninstallService.bat` batch file, which is located in the root folder of the distribution.

The `uninstallService.bat` batch file:

- removes all settings from the registry;
- stops and removes the RSE Server service.

The logs folder is not automatically deleted, it must be deleted manually.

## Uninstall on Ubuntu 24.04 x64, Debian 10 x64 and Armbian 23

Uninstalling RSE Server and logs on Ubuntu 24.04 x64, Debian 10 x64 and Armbian 23 is done manually by the administrator, there is no executable batch file supplied. This requires:

1. Delete data from the `RSE_HOME` directory;

2. Delete the `systemd service` file from the `/etc/systemd/system/system/kiosk.service` directory.