LIPSFace™ SDK Overview

1. Overview

LIPSFace™ HW Series On-Device 3D Facial Recognition Camera Kit is designed for facial recognition applications. The camera kit supports both facial recogntion and liveness detection to deliver accurate and anti-spoofing 3D facial recognition. With depth accuracy of 0.3% @100cm, the camera kit effectively blocks spoofing attacks and makes user authentication more secure. Equipped with 940nm VCSEL, LIPSFace™ HW Series **** is suitable for the deployment in both indoor and outdoor environments with harsh light conditions.

LIPSFace™ HW Series enables you to build a facial authentication solution that prevents unauthorized access with a less than 0.001% Spoof Acceptance Rate, 99.00% True Acceptance Rate and a one in one million False Acceptance Rate.

With a fast and easy enrollment, only registered users are authenticated — and Face Recognition speed takes less than a second. On-device 3D facial recognition & anti-spoofing authentication could store up to 1000 IDs.

Notice: The sample codes as below are based on HW120/125 SDK v1.0.3.0 “LIPS_Samples/Ni2FaceRecognition-gl/Source/main.cpp”

2. Platforms Supported

• Windows 10 (tested on windows 10, msvc 2017)

• Linux Ubuntu 18.04/20.04 LTS (tested on ubuntu 18, gcc 7.5+)

3. Software Architecture

---

4. Build

Use CMake version 3.1 or above:

$ cd C:\Program Files\OpenNI2\LIPS_Samples\Ni2FaceRecognition-gl

$ mkdir Build

$ cd Build

$ cmake ..

5.LIPSFace™SDK API

Name	Language	Description	OS	Extra Cmake flag needed
Get serial number	C++	Get camera serial number.	Windows, Linux	None
Get firmware version	C++	Get camera firmware version	Windows, Linux	None
Get driver version	C++	Get camera driver version	Windows, Linux	None
Get supported video modes	C++	Provides a list of video modes that this camera can support	Windows, Linux	None
Get laser status	C++	Get the status of the laser	Windows, Linux	None
Set laser status	C++	Set the status of the laser	Windows, Linux	None
Face recognition	C++	Connect to device and perform face recognition	Windows, Linux	None
Face registration	C++	Enroll one face id for a new user.	Windows, Linux	None
Delete faces in face database	C++	Delete a registered user's face id from the database on device	Windows, Linux	None
Camera start/stop	C++	Start/stop data generation from this video stream	Windows, Linux	None
Get video mode	C++	Get the video mode the camera was configured to when the frame was produced and can be used to determine the pixel format and resolution of the data. It will also provide the frame rate that the camera was running at when it recorded this frame.	Windows, Linux	None
Set video mode	C++	Setter function for the resolution of this VideoMode	Windows, Linux	None
Query frame	C++	Read the next frame from this video stream	Windows, Linux	None
Mirror	C++	Enable or disable mirroring for this stream	Windows, Linux	None

5. Sample Code

5.1 Device

The sample code shows how to get important device information from the library.

1. Get serial number

openni::Device devDevice;

char serialNumberBuffer[1024] = { 0 };

devDevice.getProperty( ONI_DEVICE_PROPERTY_SERIAL_NUMBER, &serialNumberBuffer );

printf( "serial number = %s\n", serialNumberBuffer );

2. Get firmware version

openni::Device devDevice;

char firmwareVersionBuffer[1024] = { 0 };

devDevice.getProperty( ONI_DEVICE_PROPERTY_FIRMWARE_VERSION, &firmwareVersionBuffer );

printf( "firmware version= %s\n", firmwareVersionBuffer );

3. Get driver version

openni::Device devDevice;

OniVersion driverVersion;

devDevice.getProperty( ONI_DEVICE_PROPERTY_DRIVER_VERSION, &driverVersion );

printf( "driver version = %i.%i.%i.%i\n", driverVersion.major, driverVersion.minor, driverVersion.maintenance, driverVersion.build );

4. Get supported video modes

openni::Device devDevice;

const openni::SensorInfo* sinfo = devDevice.getSensorInfo( openni::SENSOR_COLOR );

const openni::Array< openni::VideoMode>& modes = sinfo->getSupportedVideoModes();

for ( int i = 0; i < modes.getSize(); i++ )
{
    int xRes = modes[i].getResolutionX();
    int yRes = modes[i].getResolutionY();
    int fps = modes[i].getFps();

    openni::PixelFormat pixelFormat = colorStream.getVideoMode().getPixelFormat();

    printf( "xRes = %i, yRes = %i, fps = %i\n", xRes, yRes, fps );
}

5. Get laser status

openni::Status rc;
int mode;
rc = devDevice.getProperty( LIPS_DEVICE_PROPERTY_LASER_ENABLE, &mode );

6. Set laser status

rc = devDevice.setProperty( LIPS_DEVICE_PROPERTY_LASER_ENABLE, &mode, sizeof( int ) );

5.2 FaceRecognition

The sample code shows basic usage of the library. It shows how to register a new user, how to recognize a user, and how to delete faces in database.

1. Face recognition - Connect to device and perform face recognition.

If you use LIPSFace SDK v1.0.3.0

unsigned short face_id = 0x0000;

devDevice.setProperty( LIPS_DEVICE_FACE_RECOGNITION, &face_id, sizeof( unsigned short ) );

unsigned short int result;

devDevice.getProperty( LIPS_DEVICE_FACE_RECOGNITION, &result );

If you use LIPSFace SDK v1.0.3.1 or later

devDevice.setProperty( LIPS_DEVICE_FACE_RECOGNITION, NULL, NULL );

unsigned short int result;

devDevice.getProperty( LIPS_DEVICE_FACE_RECOGNITION, &result );

2. Face registration - Enroll one face id for a new user

If you use LIPSFace SDK v1.0.3.0

unsigned short int face_id = 0x0000;

devDevice.setProperty( LIPS_DEVICE_FACE_REGISTRATION, &face_id, sizeof( unsigned short ) );

unsigned short int result;

devDevice.getProperty( LIPS_DEVICE_FACE_REGISTRATION, &result );

If you use v1.0.3.1 or later

devDevice.setProperty( LIPS_DEVICE_FACE_REGISTRATION, NULL, NULL );

unsigned short int result;

devDevice.getProperty( LIPS_DEVICE_FACE_REGISTRATION, &result );

``

3. Face Deletion - Delete a registered user's face id from the database on device

unsigned short face_id = 0xFFFF;

devDevice.setProperty( LIPS_DEVICE_FACE_DELETE_DATABASE, &face_id, sizeof( unsigned short ) );

unsigned short int result;

devDevice.getProperty( LIPS_DEVICE_FACE_DELETE_DATABASE, &result );

6. Appendix

6.1 SDK Error Code (Facial Recognition/Face Registration)

The list below is a partial list, please refer to most recent documents for updated material, including User Manual and Updates on each section on our documentation.

Code	Message
0xE001	Face Not Recognize
0xE002	No Face Detect
0xE003	Liveness Fail
0xE004	Mask Fail
0xE005	Liveness Fail
0xE006	Get Feature Fail
0xE00C	Has Shielding Fail
0xE00D	Eye Unclear
0xE00E	Low Confidence Landmark

6.2 SDK Warning Code (Facial Recognition/Face Registration)

The list below is a partial list, please refer to most recent documents for updated material, including User Manual and Updates on each section on our documentation.

Code	Message
0xF001	Face distance too close
0xF002	Face distance too far
0xF003	Face angle too large (yaw/pitch/roll > angle threshold)
0xF004	Mask judge fail
0xF005	Face beyond the top edge
0xF006	Face beyond the bottom edge
0xF007	Face beyond the left edge
0xF008	Face beyond the right edge
0xF009	Face at the top left corner
0xF00A	Face at the bottom left corner
0xF00B	Face at the top right corner
0xF00C	Face at the bottom right corner

6.3 Function Map to Realsense F455