xiAPI¶

xiAPI

xiAPI stands for XIMEA Application Programming Interface.
It is a new common interface for all XIMEA cameras, and represents a simplified version of generic M3API.

Documentation¶

xiAPI Manual
Camera Trigger and Synchronization Signals
Image Data Flow
Sample code

Architecture¶

API is a software interface between the camera system driver and application.

On Windows: xiAPI is compiled into xiapi32.dll or xiapi64.dll
On Linux: xiAPI is compiled into /usr/lib/libm3api.so

Multi-process¶

It is possible to enumerate all cameras from multiple processes. It is possible to use xiGetParamInfoString to obtain SN, User_ID or Model name from any process or thread. However the camera can be opened only once by xiOpenDevice. If camera is opened by one process or thread - other processes can't open this camera until previous process closes the handle by xiCloseDevice or is finished by operating system.

Multi-thread¶

It is possible to use the same handle returned by xiOpenDevice of one camera from multiple threads within one process.
It is suggested:

to have one Acquisition thread (calling xiGetImage)
to have other Main Control Thread (calling xiGetParam, xiSetParam)
to close acquisition thread before the acquisition is stopped by Main Control Thread.

Installation¶

On Windows: To add xiAPI support please install XIMEA Windows Software Package to PC or CURRERA.
On Linux: To add xiAPI support please install XIMEA Linux Software Package to PC or CURRERA.

Sample¶

Here follows a sample code which captures one raw image data from the sensor without any post-processing.
Exposure time is set 10 ms.

#include "..\include\xiApi.h" 
#include <memory.h>
#define HandleResult(res,place) if (res!=XI_OK) {printf("Error after %s (%d)",place,res);goto finish;}

HANDLE xiH = NULL;
XI_RETURN stat = XI_OK;

// image buffer
XI_IMG image;
memset(&image,0,sizeof(image));
image.size = sizeof(XI_IMG);

// Retrieving a handle to the camera device 
stat = xiOpenDevice(0, &xiH);
HandleResult(stat,"xiOpenDevice");

// Setting Exposure Time parameter (10ms)
stat = xiSetParamInt(xiH, XI_PRM_EXPOSURE, 10000); // microseconds
HandleResult(stat,"xiSetParam (exposure time set)");

// Note:
// The default parameters of each camera might be different
// in different API versions, please set all parameters
// expected by your application to required value.

// Start acquisition
stat = xiStartAcquisition(xiH);
HandleResult(stat,"xiStartAcquisition");

// getting image from camera
stat = xiGetImage(xiH, 1000, &image);
HandleResult(stat,"xiGetImage");

printf("OK - Got one image (%dx%d) from camera\n", image.width, image.height);

finish:
// Close device
if (xiH) xiCloseDevice(xiH);

XIMEA API Sample With Start Stop Acquisition

Interface¶

The core of xiAPI are the following 6 functions, which allow to control most of the camera functionality.

// open interface
XI_RETURN xiOpenDevice(IN DWORD DevId, OUT PHANDLE hDevice);

// set parameter
XI_RETURN xiSetParam(IN HANDLE hDevice, const char* prm, void* val, DWORD size, PRM_TYPE type);

// get parameter
XI_RETURN xiGetParam(IN HANDLE hDevice, const char* prm, void* val, DWORD * size, PRM_TYPE * type);

// start acquisition
XI_RETURN xiStartAcquisition(IN HANDLE hDevice);

// get next image from queue
XI_RETURN xiGetImage(IN HANDLE hDevice, IN DWORD timeout_ms, OUT LPXI_IMG img);

// close interface
XI_RETURN xiCloseDevice(IN HANDLE hDevice);

Offline Processing¶

xiAPI allows to process already captured and stored images using Offline Processing. Please read more at xiAPI Offline Processing.

Acquisition over GenTL¶

Handling of image buffers in xiAPI is simplified.
It does not allow allocating of buffers by application or controlling each image buffer independently.
However, if your application requires full control over buffering, the standard GenTL acquisition interface combined with xiAPI parameters interface can be used.

Benefits¶

xiAPI with acquisition over GenTL offers:

Allocation of buffers by application over GenTL
Control which buffer is ready to be filled by the camera over GenTL
Control which buffer should be kept by application for processing over GenTL
Control of camera parameters over xiAPI (e.g. xiSetParam)

Multiple GenTL functions are implemented under xiAPI library, such as DSAnnounceBuffer, DSQueueBuffer.

Examples¶

You can find the source file for sample application - xiAPI-capture-50-images-gentl-main.cpp.
Full example is included in Windows SP or in Linux SP - within the folder Examples/xiAPI/capture-50-images-gentl

Supported for Cameras¶

xiAPI acquisition over GenTL is supported for all PCIe interface models (xiX, xiB, xiT) and the most recent USB3 interface (xiC) camera models.