is_ImageFormat


USB uEye XS	USB uEye XS

Syntax

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

Description

Using is_ImageFormat(), you can query a list of possible image sizes and set a new image format if supported by your uEye model. This is useful for sensors that do not support a free selection of the area of interest or image format. Using the AOI, binning/subsampling or scaling functions, the driver sets the selected image format to achieve the best possible image quality. For a complete list of available image formats see table "Image formats" below.

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.

Achtung

This function is currently only supported by camera models with CMOS sensors.

Achtung

Note on USB uEye XS image formats

•Image sizes exceeding 1280 x 720 pixels are only available in software trigger mode.

•To disable the software trigger mode, you need to set an image size that is available both in software trigger mode and in live mode. Which image sizes are available in a mode can be queried using the is_ImageFormat() function. For a list of supported image formats see also the UI-1008XS sensor data chapter

Input parameters

hCam

Camera handle

IMGFRMT_CMD_GET_LIST

Returns a list of all image formats supported by the sensor.

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

•pParam: Pointer to list of type IMAGE_FORMAT_LIST. The list must be preallocated as specified below.

•nSizeOfParam: Size of the list
Size of (IMAGE_FORMAT_LIST + (number of list entries - 1) *
Size of (IMAGE_FORMAT_INFO))

IMGFRMT_CMD_GET_NUM_ENTRIES

Returns the number of entries in the list.

•pParam: Pointer to variable of type UINT returning the number of list entries.

•nSizeOfParam: 4

IMGFRMT_CMD_SET_FORMAT

Sets the desired image format.

•pParam: Pointer to variable of type UINT passing the format ID of the desired image format.

•nSizeOfParam: 4

IMGFRMT_CMD_GET_ARBITRARY_AOI_SUPPORTED

Returns if the sensor supports a free selection of the area of interest (AOI).

•pParam: Pointer to variable of type UINT indicating if free AOI selection is supported:
0 = No free AOI supported
1 = Free AOI supported

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

Contents of the IMAGE_FORMAT_LIST list of image formats

UINT	nSizeOfListEntry	Must be preset with the size of a list entry in bytes
UINT	nNumListElements	Must be preset with the number of list entries (from IMGFRMT_CMD_GET_NUM_ENTRIES)
UINT	nReserved[4]	Reserved
IMAGE_FORMAT_INFO	FormatInfo[0]	First entry in the list. After having been filled by IMGFRMT_CMD_GET_LIST, the list contains additional entries FormatInfo[1]…FormatInfo[nNumListElements-1].

Contents of the list entry IMAGE_FORMAT_INFO

INT	nFormatID	Format ID of the specified image format (see table "Image formats" below)
UINT	nWidth	Width of the area of interest
UINT	nHeight	Height of the area of interest
UINT	nX0	Start point of the area of interest (X)
UINT	nY0	Start point of the area of interest (Y)
UINT	nSupportedCaptureModes	Image capture modes supported for this format (see table below)
UINT	nBinningMode	Binning mode used
UINT	nSubsamplingMode	Subsampling mode used
IS_CHAR	strFormatName[64]	Description of the format
double	dSensorScalerFactor	Scaling factor used (only sensors that support scaling).
UINT	nReserved[24]	Reserved

Possible values for CAPTUREMODE

CAPTMODE_SINGLE	Freerun mode, single frame (freerun snap)
CAPTMODE_FREERUN	Freerun mode, continuous (freerun live)
CAPTMODE_TRIGGER_SOFT_SINGLE	Software triggered mode, single frame
CAPTMODE_TRIGGER_SOFT_CONTINUOUS	Software triggered mode, continuous
CAPTMODE_TRIGGER_HW_SINGLE	Hardware triggered mode, single frame
CAPTMODE_TRIGGER_HW_CONTINUOUS	Hardware triggered mode, continuous

For further information on the image capture modes, see also in the Basics: Operating modes chapter.

Image formats of CMOS sensors

Format ID

Resolution

Name

Camera model

UI-149x

UI-148x

UI-158x

UI-146x

UI-155x

UI-164x

UI-154x

UI-124x

UI-122x

XS Live

XS Snap

UI-112x

3264x2448

(8M)

3264x2176

(8M 3:2)

3264x1836

(8M 16:9)

2592x1944

(5M)

2048x1536

(3M)

1920x1080

(Full HD 16:9)

1632x1224

(2M)

1280x960

(1.2M 4:3)

1280x720

(HD 16:9)

960x480

(WVGA 2:1)

800x480

(WVGA)

640x480

(VGA)

640x360

(VGA 16:9)

400x240

(WQVGA)

352x288

(CIF)

288x352

(CIF Portrait)

320x240

(QVGA)

240x320

(QVGA Portrait)

1600x1200

(UXGA)

3840x2748

(10M)

1920x1080

(Full HD 16:9, HQ)

2560x1920

(5M)

768x576

(CCIR)

1280x1024

(1.3M SXGA)

2448x2048

(5M)

1024x768

(XGA)

1024x1024

(1M)

800x600

(SVGA)

1360x1024

(1.4M 4:3)

Image formats of CCD sensors

Format ID	Resolution	Name	Camera model
Format ID	Resolution	Name	UI-214x	UI-228x
1	3264x2448	(8M)
2	3264x2176	(8M 3:2)
3	3264x1836	(8M 16:9)
4	2592x1944	(5M)
5	2048x1536	(3M)		X
6	1920x1080	(Full HD 16:9)		X
7	1632x1224	(2M)		X
8	1280x960	(1.2M 4:3)	X	X
9	1280x720	(HD 16:9)	X	X
11	960x480	(WVGA 2:1)	X	X
12	800x480	(WVGA)	X	X
13	640x480	(VGA)	X	X
14	640x360	(VGA 16:9)	X
15	400x240	(WQVGA)	X
16	352x288	(CIF)	X
17	288x352	(CIF Portrait)	X
18	320x240	(QVGA)	X
19	240x320	(QVGA Portrait)	X
20	1600x1200	(UXGA)		X
21	3840x2748	(10M)
22	1920x1080	(Full HD 16:9, HQ)
23	2560x1920	(5M)
24	768x576	(CCIR)	X	X
25	1280x1024	(1.3M SXGA)		X
26	2448x2048	(5M)		X
27	1024x768	(XGA)	X	X
28	1024x1024	(1M)	X	X
29	800x600	(SVGA)	X	X
30	1360x1024	(1.4M 4:3)		X

Return values

IS_CANT_ADD_TO_SEQUENCE	The image memory is already included in the sequence and cannot be added again.
IS_BAD_STRUCTURE_SIZE	An internal structure has an incorrect size.
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_CAPTURE_RUNNING	A capturing operation is in progress and must be terminated before you can start another one.
IS_DR_CANNOT_CREATE_SURFACE	The image surface or overlay surface could not be created.
IS_DR_CANNOT_CREATE_TEXTURE	The texture could not be created.
IS_DR_CANNOT_CREATE_VERTEX_BUFFER	The vertex buffer could not be created.
IS_DR_DEVICE_OUT_OF_MEMORY	Not enough graphics memory available.
IS_DR_LIBRARY_NOT_FOUND	The DirectRenderer library could not be found.
IS_INVALID_BUFFER_SIZE	The image memory has an inappropriate size to store the image in the desired format.
IS_INVALID_CAMERA_TYPE	The camera type defined in the .ini file does not match the current camera model.
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_MEMORY_POINTER	Invalid pointer or invalid memory ID
IS_INVALID_MODE	Camera is in standby mode, function not allowed
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_INVALID_PIXEL_CLOCK	This setting is not available for the currently set pixel clock frequency.
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_ACTIVE_IMG_MEM	No active image memory available. You must set the memory to active using the is_SetImageMem() function or create a sequence using the is_AddToSequence() function.
IS_NO_SUCCESS	General error message
IS_NOT_CALIBRATED	The camera does not contain any calibration data.
IS_NOT_SUPPORTED	The camera model used here does not support this function or setting.
IS_NULL_POINTER	Invalid array
IS_OUT_OF_MEMORY	No memory could be allocated.
IS_SEQUENCE_BUF_ALREADY_LOCKED	The memory could not be locked. The pointer to the buffer is invalid.
IS_SUCCESS	Function executed successfully
IS_TIMED_OUT	A timeout occurred. An image capturing process could not be terminated within the allowable period.
IS_TRIGGER_ACTIVATED	The function cannot be used because the camera is waiting for a trigger signal.

Related functions

•is_AOI()

•is_SetBinning()

•is_SetSubSampling()

Example

HIDS hCam;

char strCamFileName[256];

int nRet;

// Get number of available formats and size of list

UINT count;

UINT bytesNeeded = sizeof(IMAGE_FORMAT_LIST);

nRet = is_ImageFormat(hCam, IMGFRMT_CMD_GET_NUM_ENTRIES, &count, 4);

bytesNeeded += (count - 1) * sizeof(IMAGE_FORMAT_INFO);

void* ptr = malloc(bytesNeeded);

// Create and fill list

IMAGE_FORMAT_LIST* pformatList = (IMAGE_FORMAT_LIST*) ptr;

pformatList->nSizeOfListEntry = sizeof(IMAGE_FORMAT_INFO);

pformatList->nNumListElements = count;

nRet = is_ImageFormat(hCam, IMGFRMT_CMD_GET_LIST, pformatList, bytesNeeded);

// Activate trigger mode for capturing high resolution images (USB uEye XS)

nRet = is_StopLiveVideo(hCam, IS_WAIT);

nRet = is_SetExternalTrigger(hCam, IS_SET_TRIGGER_SOFTWARE);

// Prepare for creating image buffers

char* pMem = NULL;

int memID = 0;

// Set each format and then capture an image

IMAGE_FORMAT_INFO formatInfo;

for (int i = 0; i < count; i++)

{

formatInfo = pformatList->FormatInfo[i];

int width = formatInfo.nWidth;

int height = formatInfo.nHeight;

// Allocate image mem for current format, set format

nRet = is_AllocImageMem(hCam, width, height, 24, &pMem, &memID);

nRet = is_SetImageMem(hCam, pMem, memID);

nRet = is_ImageFormat(hCam, IMGFRMT_CMD_SET_FORMAT, &formatInfo.nFormatID, 4);

// Capture image

nRet = is_FreezeVideo(hCam, IS_WAIT);

}

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_ImageFormat