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

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

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

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

PreviousLIPSFace™ SDK NextUpdates

Last updated 1 year ago

1. Overview

2. Platforms Supported

3. Software Architecture

4. Build

5.LIPSFace™SDK API

5. Sample Code

5.1 Device

1. Get serial number

2. Get firmware version

3. Get driver version

4. Get supported video modes

5. Get laser status

6. Set laser status

5.2 FaceRecognition

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

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

6. Appendix

6.1 SDK Error Code (Facial Recognition/Face Registration)

6.2 SDK Warning Code (Facial Recognition/Face Registration)

6.3 Function Map to Realsense F455

`5.`LIPSFace™SDK API

`5.2` FaceRecognition

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

`6.1` SDK Error Code (Facial Recognition/Face Registration)

`6.2` SDK Warning Code (Facial Recognition/Face Registration)

`6.3` Function Map to Realsense F455