Luxand FaceSDK – Working with Cameras

The library offers a set of functions to work with DirectShow/v4l2-compatible web cameras and IP cameras with an MJPEG interface. The functions allow single frames to be retrieved from a camera one-by-one; they are stored in HImage descriptors. The application usually grabs frames in a loop, displaying each frame in its window and performing manipulations with images (such as face detection).

Web camera functions are available only for Windows and Linux platforms. IP camera functions are available for all platforms.

Android and iOS samples include platform-specific code working with cameras on phones and tablets.

    Data Types

There are data types to store the information about video formats. Note that the names of video cameras are stored in wide char format (each char occupies two bytes).

C++ Declaration:

typedef struct {
    int Width;
    int Height;
    int BPP;
} FSDK_VideoFormatInfo;

typedef enum {
    FSDK_MJPEG
} FSDK_VIDEOCOMPRESSIONTYPE;

Delphi Declaration:

FSDK_VideoFormatInfo = record
   Width: integer;
   Height: integer;
   BPP: integer;
end;

PFSDK_VideoFormatInfo = ^FSDK_VideoFormatInfo;
FSDK_VideoFormatInfoArray = array[0..255] of FSDK_VideoFormatInfo;
PFSDK_VideoFormatInfoArray = ^FSDK_VideoFormatInfoArray;
FSDK_CameraList = array[0..255] of PWideChar;
PFSDK_CameraList = ^FSDK_CameraList;
FSDK_VIDEOCOMPRESSIONTYPE = ( FSDK_MJPEG );

VB Declaration:

Type FSDK_VideoFormatInfo
   Width As Long
   Height As Long
   BPP As Long
End Type

Enum FSDK_VIDEOCOMPRESSIONTYPE
   FSDK_MJPEG
End Enum

Java Declaration:

The class FSDK_VideoFormatInfo has the following properties:

   public int Width, Height, BPP;

class FSDK_VideoFormats {
   public FSDK_VideoFormatInfo.ByValue formats[];
}

class TCameras {
   public String cameras[];
}

Java and Android Declaration:

class HCamera {
   protected int hcamera;
}

class FSDK_VIDEOCOMPRESSIONTYPE {
   public static final int FSDK_MJPEG = 0;
}

Python Declaration:

class Camera(ctypes.Structure):
    fields_ = ("handle", c_int), # FSDK camera handle
    def __init__(self, cameraName=None): # cameraName is for windows only
    def Open(self, cameraName);
    def Close(self)
    def GrabFrame(self)

# for windows and linux only
class VideoFormatInfo(ctypes.Structure):
    fields = ("Width", c_int), ("Height", c_int), ("FormatIndex", c_int)

  FSDK_InitializeCapturing Function

This function initializes the capturing process (but does not open a camera). This function should be called in a certain thread that works with cameras. Note that on Windows platforms this function initializes COM in the thread; if you already initialized COM, you must not call this function, and you must not call FSDK_FinalizeCapturing.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

None

  FSDK_FinalizeCapturing Function

This function finalizes the capturing process, initialized by the FSDK_InitializeCapturing function (and finalizes COM on Windows platforms). If you already finalized COM, you must not call this function.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

None.

  FSDK_SetCameraNaming Function

Sets the retrieval format for the FSDK_GetCameraList function. Depending on the value of the argument, either web camera names (by default) or their unique IDs (Device Path) are returned. Device Path may be necessary if the system has several web cameras from the same manufacturer that have the same name. This function does not support IP cameras.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

UseDevicePathAsName – sets a retrieval format for the FSDK_GetCameraList function.

FALSE: FSDK_GetCameraList returns the list of names for cameras installed in the system;

TRUE: FSDK_GetCameraList returns the list of unique device paths of these cameras.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

None.

  FSDK_GetCameraList Function

This function retrieves the list of web cameras available in the system. The name of each camera is stored in wide char format (each character occupies two bytes). The function does not support IP cameras. The camera list must be destroyed by calling the FSDK_FreeCameraList function after the list is no longer needed.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

CameraList – pointer to wchar_t** variable to store the camera list.

CameraCount – pointer to integer variable to store the count of cameras in the system.

Return Value:

Returns FSDKE_OK if successful.

Example

Python Syntax:

Return Value:

The list of CameraName objects.

Note:

The CameraName class is a string with an extra field devicePath.

  FSDK_GetCameraListEx Function

This function retrieves the list of names and the device paths of the web cameras available in the system. The name and the device path of each camera are stored in wide char format (each character occupies two bytes) at the same indices at the corresponding arrays. The function does not support IP cameras. Both lists must be destroyed by calling the FSDK_FreeCameraList function after they are no longer needed.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

CameraNameList – pointer to wchar_t** variable to store the camera name list.

CameraDevicePathList – pointer to wchar_t** variable to store the camera device path list.

CameraCount – pointer to integer variable to store the count of cameras in the system.

Return Value:

Returns FSDKE_OK if successful.

  FSDK_FreeCameraList Function

This function frees the list of web cameras obtained from the FSDK_GetCameraList or FSDK_GetCameraListEx function. The call of the function is not required in .NET, VB and Java.

C++ Syntax:

Delphi Syntax:

Parameters:

CameraList – pointer to wchar_t** variable where the camera list is stored.

CameraCount – the count of cameras in the system, obtained from the FSDK_GetCameraList or FSDK_GetCameraListEx function.

Note:

You must call FSDK_FreeCameraList for CameraNameList and CameraDevicePathList, if you were using FSDK_GetCameraListEx.

Return Value:

Returns FSDKE_OK if successful.

  FSDK_GetVideoFormatList Function

This function returns the list of video formats supported by a given camera. This function does not support IP cameras.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

CameraName – pointer to name of desired video camera.

VideoFormatList – pointer to FSDK_VideoFormatInfo* variable to store the list of video formats.

VideoFormatCount – pointer to integer variable to store the count of video formats.

Return Value:

Returns FSDKE_OK if successful.

  FSDK_FreeVideoFormatList Function

This function frees the list of video formats obtained from FSDK_GetVideoFormatList. Calling this function is not required in .NET, VB and Java.

C++ Syntax:

Delphi Syntax:

Parameters:

VideoFormatList – pointer to FSDK_VideoFormatInfo* variable where the list of video formats is stored.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

The list of VideoFormatInfo objects.

  FSDK_SetVideoFormat Function

The function sets the format of camera output. The function does not support IP cameras.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

CameraName – pointer to name of desired video camera.

VideoFormat – desired video format.

Return Value:

Returns FSDKE_OK if successful.

Example

Python Syntax:

Return Value:

None.

  FSDK_OpenVideoCamera Function

The function opens the web camera of a given name and returns its handle.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

CameraName – pointer to name of video camera to open.

CameraHandle – pointer to integer variable to store the opened camera handle.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

New Camera object.

  FSDK_OpenIPVideoCamera Function

This function opens the IP camera at a given URL and returns its handle. You may call the FSDK_SetHTTPProxy function to set an HTTP proxy for accessing the camera.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

Parameters:

CompressionType – the type of video stream (MJPEG by default).

URL – URL of the IP camera to be opened.

Username – IP camera access username.

Password – IP camera access password.

TimeoutSeconds – connection timeout in seconds.

CameraHandle – pointer to integer variable to store the opened camera handle.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

New Camera object.

  FSDK_SetHTTPProxy Function

This function sets an HTTP proxy to be used with an IP camera. If a proxy is required, the function should be called before the FSDK_OpenIPVideoCamera function.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

Parameters:

ServerNameOrIPAddress – proxy address.

Port – proxy port.

UserName – proxy username.

Password – proxy password.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

None.

  FSDK_GrabFrame Function

Retrieves the current frame from a web camera or an IP camera and stores the frame in the created HImage handle. If a camera returns an image, mirrored horizontally (it depends on the camera settings), then you can mirror it by using FSDK_MirrorImage.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

Parameters:

CameraHandle – handle of the opened camera to grab frame.

Image – pointer to HImage variable to store the frame. Note that the created HImage handle should be deleted once it is no longer needed using the FSDK_FreeImage function.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

A new image with grabbed frame.

  FSDK_CloseVideoCamera Function

The function closes the camera, opened by the FSDK_OpenVideoCamera or FSDK_OpenIPVideoCamera function.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

CameraHandle – handle of opened video camera to close.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

None.

Note:

The camera is closed automatically by calling the destructor of Camera object.

 

Next chapter: Tracker API: Face Recognition and Tracking in Video Streams

Contents