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

is_FaceDetection

uEye Camera Manual Version 3.80

is_FaceDetection

Windows_Logo

Linux_Logo

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 (e.g. enable/disable face detection, return number of detected faces). 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

nCommand

 

FDT_CMD_GET_CAPABILITIES

Returns the face detection functions supported by the camera.

More details

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.

More details

pParam: NULL

nSizeOfParam: 0

FDT_CMD_SET_DISABLE

Disables face detection.

More details

pParam: NULL

nSizeOfParam: 0

FDT_CMD_GET_ENABLE

Returns the face detection status (enabled/disabled).

More details

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.

More details

pParam: NULL

nSizeOfParam: 0

FDT_CMD_SET_RESUME

Resumes face detection.

More details

pParam: NULL

nSizeOfParam: 0

FDT_CMD_GET_SUSPEND

Returns the face detection status (suspended/running).

More details

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.

More details

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.

More details

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.

More details

pParam: NULL

nSizeOfParam: 0

FDT_CMD_SET_SEARCH_ANGLE_DISABLE

Disables the search angle for face detection.

More details

pParam: NULL

nSizeOfParam: 0

FDT_CMD_GET_SEARCH_ANGLE_ENABLE

Returns the status of the search angle for face detection.

More details

pParam: NULL

nSizeOfParam: 0

Output and marking of detected faces

FDT_CMD_GET_FACE_LIST

Returns a list of information on the detected faces.

More details

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.

More details

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.

More details

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.

More details

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.

More details

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.

More details

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.

More details

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.

More details

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.

More details

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

nSizeOfParam: 4

pParam

Pointer to a function parameter; which function parameter is referred to here 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

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_SUCCESS

Function executed successfully

IS_NO_SUCCESS

General error message

IS_NOT_SUPPORTED

This function is not supported by the current camera

IS_INVALID_CAPTURE_MODE

This function is not supported in the current operating mode

IS_INVALID_PARAMETER

One of the parameters passed is invalid


Suggestion for improvement? Send us your short Feedback on this chapter. Thank you very much!


© 2010 IDS Imaging Development Systems GmbH
http://www.ids-imaging.com