Previous chapter Return to chapter overview Next chapter Print chapter

C: Programming > Function descriptions > is_FaceDetection

is_FaceDetection

uEye Camera Manual Version 4.92

is_FaceDetection

Windows_Logo
Linux_Logo

USB 3 uEye XC

USB 3 uEye XC

Syntax

INT is_FaceDetection (HIDS hCam, UINT nCommand, void *pParam, UINT nSizeOfParam)

Description

Using is_FaceDetection(), you can control the built-in face detection function if supported by your uEye model.

The nCommand input parameter is used to select the function mode. The pParam input parameter depends on the selected function mode. If you select functions for setting or returning a value, pParam contains a pointer to a variable of the UINT type. The size of the memory area to which pParam refers is specified in the nSizeOfParam input parameter.

hint_info

This function is currently only supported by the UI-3013XC camera model.

Camera orientation

To increase the detection reliability when the camera is turned upright, you can preset a facial orientation angle (search angle).

Upside-down faces are not detected. You have to turn the camera or enable the mirror function with is_SetRopEffect() in order to detect upside-down faces.

Resolution for face detection

The position and size coordinates of the detected faces depend on the image resolution. The coordinate (0,0) is at the top left corner of the image.

Data update

The polling of the face detection is limited to an interval of 500 ms to keep the load in data transmission low.

hint_info

For UI-3013XC, the face detection is only active in live mode but not in snapshot mode.

Input parameters

hCam

Camera handle

FDT_CMD_GET_CAPABILITIES

Returns the face detection functions supported by the camera.

•pParam: Pointer to bit mask of type UINT
In the bit mask, the status flags from FDT_CAPABILITY_FLAGS are returned.

•nSizeOfParam: 4

Start/stop face detection

FDT_CMD_SET_ENABLE

Enables face detection.

•pParam: NULL

•nSizeOfParam: 0

FDT_CMD_SET_DISABLE

Disables face detection.

•pParam: NULL

•nSizeOfParam: 0

FDT_CMD_GET_ENABLE

Returns the face detection status (enabled/disabled).

•pParam: Pointer to variable of type UINT
The bit mask returns either:
0 = face detection disabled
1 = face detection enabled

•nSizeOfParam: 4

Search angle (facial orientation angle) for face detection

FDT_CMD_SET_SEARCH_ANGLE

Sets a search angle for face detection.

You can set an angle of 0°, 90° or 270° (clockwise). The face detection feature will take only those faces into account that match the set facial orientation angle. You can use this function, for example, to increase the detection reliability when you have turned the camera upright.

To detect upside-down faces, you have to turn the camera or enable the mirror function with is_SetRopEffect().

•pParam: Pointer to variable of type UINT that passes the angle of 0, 90 or 270 degrees.

•nSizeOfParam: 4

FDT_CMD_GET_SEARCH_ANGLE

Returns the search angle that is currently set for face detection.

See also the information on FDT_CMD_SET_SEARCH_ANGLE

•pParam: Pointer to variable of type UINT returning the angle of 0, 90 or 270 degrees.

•nSizeOfParam: 4

FDT_CMD_SET_SEARCH_ANGLE_ENABLE

Enables the search angle for face detection.

•pParam: NULL

•nSizeOfParam: 0

FDT_CMD_SET_SEARCH_ANGLE_DISABLE

Disables the search angle for face detection.

•pParam: NULL

•nSizeOfParam: 0

FDT_CMD_GET_SEARCH_ANGLE_ENABLE

Returns the status of the search angle for face detection.

•pParam: NULL

•nSizeOfParam: 0

Output and marking of detected faces

FDT_CMD_GET_FACE_LIST

Returns a list of information on the detected faces.

The detected faces are output sorted by size.

You can query the number of entries in the list with FDT_CMD_GET_NUMBER_FACES.

•pParam: Pointer to list of type FDT_INFO_LIST

•nSizeOfParam: Size of the list
Size of FDT_INFO_LIST + (number of faces - 1) * Size of (FDT_INFO_EL)

FDT_CMD_GET_NUMBER_FACES

Returns the current number of detected faces.

•pParam: Pointer to variable of type UINT returning the number of detected faces.

•nSizeOfParam: 4

FDT_CMD_GET_MAX_NUM_FACES

Returns the maximum number of faces that can be detected by the camera.

•pParam: Pointer to variable of type UINT returning the maximum number of faces.

•nSizeOfParam: 4

FDT_CMD_SET_INFO_MAX_NUM_OVL

Sets the maximum number of faces that will be marked with an overlay box in the live image.

The detected faces are marked with an overlay box in the image. The box marking the largest face detected has a green border, the boxes for the other faces have white borders. Using the FDT_CMD_SET_INFO_OVL_LINE_WIDTH function, you can set the line width for the border.

•pParam: Pointer to variable of type UINT that passes the maximum number of faces to be marked with an overlay box.

•nSizeOfParam: 4

FDT_CMD_GET_INFO_MAX_NUM_OVL

Returns the maximum number of faces that will be marked with an overlay box in the live image.

•pParam: Pointer to variable of type UINT returning the maximum number of faces to be marked with an overlay box.

•nSizeOfParam: 4

FDT_CMD_SET_INFO_OVL_LINE_WIDTH

Sets the line width you want to use for the overlay boxes around the detected faces in the live image.

•pParam: Pointer to variable of type UINT that passes the line width set for the overlay boxes around detected faces.

•nSizeOfParam: 4

FDT_CMD_GET_INFO_OVL_LINE_WIDTH

Returns the line width set for the overlay boxes that indicate the detected faces in the live image.

•pParam: Pointer to variable of type UINT returning the line width set for the overlay boxes.

•nSizeOfParam: 4

pParam

Pointer to a function parameter, whose function depends on nCommand.

nSizeOfParam

Size (in bytes) of the memory area to which pParam refers.

Status flags from FDT_CAPABILITY_CAP_FLAGS

FDT_CAP_SUPPORTED

The camera supports face detection

FDT_CAP_SEARCH_ANGLE

Face detection supports presetting a search angle

FDT_CAP_SEARCH_AOI

Face detection supports presetting a search area

FDT_CAP_INFO_POSX

Face detection supports output of the X position of a face

FDT_CAP_INFO_POSY

Face detection supports output of the Y position of a face

FDT_CAP_INFO_WIDTH

Face detection supports output of the width of a face

FDT_CAP_INFO_HEIGHT

Face detection supports output of the height of a face

FDT_CAP_INFO_ANGLE

Face detection supports output of the orientation angle of a face

FDT_CAP_INFO_POSTURE

Face detection supports output of the posture of a face

FDT_CAP_INFO_FACENUMBER

Face detection supports output of the number of faces detected

FDT_CAP_INFO_OVL

Face detection supports marking detected faces with an overlay box

FDT_CAP_INFO_NUM_OVL

Face detection supports setting the maximum number of faces for marking

FDT_CAP_INFO_OVL_LINEWIDTH

Face detection supports setting the line width for the overlay boxes

Contents of the list of detected faces FDT_INFO_LIST

UINT

nSizeOfListEntry

Must be preset with the size of a list entry in bytes

UINT

nNumDetectedFaces

Returns the number of detected faces

UINT

nNumListElements

Must be preset with the number of list entries

UINT

nReserved[4]

Reserved

FDT_INFO_EL

FaceEntry

First entry in the list. The memory area for additional list entries has to come directly after this entry.

Contents of the list entry FDT_INFO_EL

INT

nFacePosX

X position of the face (upper left corner)

INT

nFacePosY

Y position of the face (upper left corner)

INT

nFaceWidth

Width of the face

INT

nFaceHeight

Height of the face

INT

nAngle

Orientation angle of the face:

0/90/270: Angle in degrees (0° corresponds to 12 o'clock position)

-1: undefined

UINT

nPosture

Posture of the face; see table below

0...8

UEYETIME

TimestampSystem

Structure with timestamp information in PC system time format, see is_GetImageInfo(). The time resolution is approx. 15 ms.

UINT64

nReserved

Reserved

UINT

nReserved2[4]

Reserved

Possible values for posture (viewing direction)

0

1

2
FaceDetect_Posture_0
FaceDetect_Posture_1
FaceDetect_Posture_2

3

4

5
FaceDetect_Posture_3
FaceDetect_Posture_4
FaceDetect_Posture_5

6

7

8
FaceDetect_Posture_6
FaceDetect_Posture_7
FaceDetect_Posture_8

Return values

IS_CANT_COMMUNICATE_WITH_DRIVER

Communication with the driver failed because no driver has been loaded.

IS_CANT_OPEN_DEVICE

An attempt to initialize or select the camera failed (no camera connected or initialization error).

IS_INVALID_CAPTURE_MODE

The function can not be executed in the current camera operating mode (free run, trigger or standby).

IS_INVALID_CAMERA_HANDLE

Invalid camera handle

IS_INVALID_PARAMETER

One of the submitted parameters is outside the valid range or is not supported for this sensor or is not available in this mode.

IS_IO_REQUEST_FAILED

An IO request from the uEye driver failed. Possibly the versions of the ueye_api.dll (API) and the driver file (ueye_usb.sys or ueye_eth.sys) do not match.

IS_NO_SUCCESS

General error message

IS_NOT_SUPPORTED

The camera model used here does not support this function or setting.

IS_OUT_OF_MEMORY

No memory could be allocated.

IS_SUCCESS

Function executed successfully

Suggestion for improvement? Send us your short Feedback on this chapter. Thank you very much!
For technical questions please contact your local distributor or use the support form on our website.

© 2019 IDS Imaging Development Systems GmbH
https://en.ids-imaging.com