is_FaceDetection


USB uEye XS	USB uEye XS

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.

With some uEye models, you can use the face detection function to control the automatic brightness.

Hinweis

This function is currently only supported by the USB uEye XS camera model.

Hinweis

Note on 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.

Hinweis

Note on resolution for face detection

The position and size coordinates of the detected faces are independent of the image size setting. You can query the horizontal and vertical resolution of the face detection function (see below). For the USB uEye XS the coordinates are 0...320 in X direction and 0...240 in Y direction. These coordinates may need to be converted to fit the image size. The coordinate (0,0) is at the top left corner of the image.

Achtung

When you are using a USB uEye XS, you can only call is_FaceDetection() in live mode. Calling this function in software trigger mode will cause an error message. If you enable the software trigger mode after starting face detection, face detection will continue running as normal.

Achtung

To ensure that the number of detected faces and their positions do not change during readout of the list, you should suspend the function with FDT_CMD_SET_SUSPEND before starting the readout. After the face detection results have been read out, you can resume the function again with FDT_CMD_SET_RESUME.

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_CAP_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

FDT_CMD_SET_SUSPEND

Temporarily suspends the face detection function.

•pParam: NULL

•nSizeOfParam: 0

FDT_CMD_SET_RESUME

Resumes face detection.

•pParam: NULL

•nSizeOfParam: 0

FDT_CMD_GET_SUSPEND

Returns the face detection status (suspended/running).

•pParam: Pointer to variable of type UINT
The bit mask returns either:
1 = face detection suspended (SUSPEND)
0 = face detection running (RESUME)

•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.

With the uEye XS, the detected faces are output sorted by size.

You can query the number of entries in the list with FDT_CMD_GET_MAX_NUM_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_GET_HORIZONTAL_RESOLUTION

Returns the horizontal resolution of the face detection function.

•pParam: Pointer to variable of type UINT returning the horizontal resolution (see note above).

•nSizeOfParam: 4

FDT_CMD_GET_VERTICAL_RESOLUTION

Returns the vertical resolution of the face detection function.

•pParam: Pointer to variable of type UINT returning the vertical resolution (see note above).

•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 (center) The face position always refers to the horizontal and vertical resolution of the face detection function (see note above).
INT	nFacePosY	Y position of the face (center)
INT	nFaceWidth	Width of the face The face size always refers to the horizontal and vertical resolution of the face detection function (see note above).
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

3	4	5

6	7	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 you local distributor or use the support form on our website.

Home > C: Programming > Function descriptions >	History back Previous chapter Next chapter Print
is_FaceDetection