Please enable JavaScript to view this site.

IDS Software Suite 4.96.1

Windows_Logo
Linux_Logo

USB 2.0

USB 3.x

GigE

USB 2.0

USB 3.x

GigE

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 (profiles) and set a new profile. 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 size to achieve the best possible image quality. The aim here is to achieve the lowest possible data rate with a maximum field of view. For a complete list of available image profiles see Camera and sensor data.

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.

Input parameters

hCam

Camera handle

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

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 profile

UINT

nWidth

Width of the area of interest

UINT

nHeight

Height of the area of interest

INT

nX0

Start point of the area of interest (X)

INT

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.

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

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, sizeof(count));
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);
 
// 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, sizeof(formatInfo.nFormatID));
 
    // Capture image
    nRet = is_FreezeVideo(hCam, IS_WAIT);
}

© 2022 IDS Imaging Development Systems GmbH