xiAPI Manual¶

Table of Contents¶

• xiAPI Manual
• Table of Contents
• Writing Applications with xiAPI
  • Default parameters
• xiAPI Functions.
  • xiOpenDevice
  • xiOpenDeviceBy
  • xiCloseDevice
  • xiGetNumberDevices
  • xiStartAcquisition
  • xiStopAcquisition
  • xiGetImage
    • GPI_level-Sampling-in-Header
  • xiSetParam
  • xiGetDeviceInfoString
  • xiGetParam
• xiAPI Parameters.
• Device info parameters.
  • XI_PRM_DEVICE_NAME or “device_name”
  • XI_PRM_DEVICE_INSTANCE_PATH or "device_inst_path"
  • XI_PRM_DEVICE_LOCATION_PATH or "device_loc_path"
  • XI_PRM_DEVICE_TYPE or “device_type”
  • XI_PRM_DEVICE_MODEL_ID or “device_model_id”
  • XI_PRM_SENSOR_MODEL_ID or “sensor_model_id”
  • XI_PRM_DEVICE_SN or “device_sn”
  • XI_PRM_DEVICE_SENS_SN or device_sens_sn
  • XI_PRM_DEVICE_USER_ID or "device_user_id"
  • XI_PRM_DEVICE_MANIFEST or "device_manifest"
  • XI_PRM_DEBUG_LEVEL or 'debug_level'
  • XI_PRM_AUTO_BANDWIDTH_CALCULATION or 'auto_bandwidth_calculation'
  • XI_PRM_PROC_NUM_THREADS or 'proc_num_threads'
  • XI_PRM_NEW_PROCESS_CHAIN_ENABLE or 'new_process_chain_enable'
• Device acquisition parameters.
  • XI_PRM_EXPOSURE or “exposure”
  • XI_PRM_EXPOSURE_BURST_COUNT or "exposure_burst_count"
  • XI_PRM_GAIN_SELECTOR or “gain_selector”
  • XI_PRM_GAIN or “gain”
  • XI_PRM_DOWNSAMPLING or “downsampling”
  • XI_PRM_DOWNSAMPLING_TYPE or “downsampling_type”
• Binning and Decimation
  • XI_PRM_BINNING_SELECTOR or “binning_selector”
  • XI_PRM_BINNING_VERTICAL_MODE or “binning_vertical_mode”
  • XI_PRM_BINNING_VERTICAL or “binning_vertical”
  • XI_PRM_BINNING_HORIZONTAL_MODE or “binning_horizontal_mode”
  • XI_PRM_BINNING_HORIZONTAL or “binning_horizontal”
  • XI_PRM_BINNING_HORIZONTAL_PATTERN or “binning_horizontal_pattern”
  • XI_PRM_BINNING_VERTICAL_PATTERN or “binning_vertical_pattern”
  • XI_PRM_DECIMATION_SELECTOR or “decimation_selector”
  • XI_PRM_DECIMATION_VERTICAL or “decimation_vertical”
  • XI_PRM_DECIMATION_HORIZONTAL or “decimation_horizontal”
  • XI_PRM_DECIMATION_HORIZONTAL_PATTERN or “decimation_horizontal_pattern”
  • XI_PRM_DECIMATION_VERTICAL_PATTERN or “decimation_vertical_pattern”
  • XI_PRM_TEST_PATTERN_GENERATOR_SELECTOR or “test_pattern_generator_selector”
  • XI_PRM_TEST_PATTERN or “test_pattern”
  • XI_PRM_SHUTTER_TYPE or "shutter_type"
  • XI_PRM_IMAGE_DATA_FORMAT or “imgdataformat”
  • Image Data Formats
  • XI_PRM_IMAGE_DATA_FORMAT_RGB32_ALPHA or “imgdataformatrgb32alpha”
  • Data Format Dependency Table
  • XI_PRM_IMAGE_PAYLOAD_SIZE or "imgpayloadsize"
  • XI_PRM_TRANSPORT_PIXEL_FORMAT or "transport_pixel_format"
  • XI_PRM_FRAMERATE or “framerate”
  • XI_PRM_BUFFER_POLICY or “buffer_policy”
  • XI_PRM_COUNTER_SELECTOR or “counter_selector”
  • XI_PRM_COUNTER_VALUE or “counter_value”
  • XI_PRM_OFFSET_X or “offsetX”
  • XI_PRM_OFFSET_Y or “offsetY”
  • XI_PRM_WIDTH or “width”
  • XI_PRM_HEIGHT or “height”
  • XI_PRM_REGION_SELECTOR or "region_selector"
  • XI_PRM_REGION_MODE or "region_mode"
  • XI_PRM_HORIZONTAL_FLIP or "horizontal_flip"
  • XI_PRM_VERTICAL_FLIP or "vertical_flip"
  • XI_PRM_LUT_EN or “LUTEnable”
  • XI_PRM_LUT_INDEX or “LUTIndex”
  • XI_PRM_LUT_VALUE or “LUTValue”
  • XI_PRM_TRG_SOURCE or “trigger_source”
  • XI_PRM_TRG_SOFTWARE or “trigger_software”
  • XI_PRM_TRG_DELAY or "trigger_delay"
  • XI_PRM_AVAILABLE_BANDWIDTH "available_bandwidth"
  • XI_PRM_LIMIT_BANDWIDTH "limit_bandwidth"
  • XI_PRM_LIMIT_BANDWIDTH_MODE "limit_bandwidth_mode"
  • XI_PRM_SENSOR_TAPS "sensor_taps"
  • XI_PRM_SENSOR_CLOCK_FREQ_HZ "sensor_clock_freq_hz"
  • XI_PRM_SENSOR_CLOCK_FREQ_INDEX "sensor_clock_freq_index"
  • XI_PRM_SENSOR_OUTPUT_CHANNEL_COUNT "sensor_output_channel_count"
  • XI_PRM_SENSOR_DATA_BIT_DEPTH "sensor_bit_depth"
  • XI_PRM_OUTPUT_DATA_BIT_DEPTH "output_bit_depth"
  • XI_PRM_IMAGE_DATA_BIT_DEPTH "image_data_bit_depth"
  • XI_PRM_OUTPUT_DATA_PACKING "output_bit_packing"
  • XI_PRM_OUTPUT_DATA_PACKING_TYPE "output_bit_packing_type"
  • XI_PRM_ACQ_TIMING_MODE "acq_timing_mode"
  • XI_PRM_TRG_SELECTOR "trigger_selector"
  • XI_PRM_TRG_OVERLAP "trigger_overlap"
  • XI_PRM_ACQ_FRAME_BURST_COUNT "acq_frame_burst_count"
  • XI_PRM_TIMESTAMP "timestamp"
  • XI_PRM_IMAGE_USER_DATA "image_user_data"
• Color management settings
  • XI_PRM_WB_KR or “wb_kr”
  • XI_PRM_WB_KG or “wb_kg”
  • XI_PRM_WB_KB or “wb_kb”
  • XI_PRM_MANUAL_WB or “manual_wb”
  • XI_PRM_AUTO_WB or “auto_wb”
  • XI_PRM_WB_ROI_OFFSET_X or “wb_roi_offset_x”
  • XI_PRM_WB_ROI_OFFSET_Y or “wb_roi_offset_y”
  • XI_PRM_WB_ROI_WIDTH or “wb_roi_width”
  • XI_PRM_WB_ROI_HEIGHT or “wb_roi_height”
  • XI_PRM_GAMMAY or “gammaY”
  • XI_PRM_GAMMAC or “gammaC”
  • XI_PRM_SHARPNESS or “sharpness”
  • XI_PRM_CC_MATRIX_00 or “ccMTX00”
  • XI_PRM_CC_MATRIX_01 or “ccMTX01”
  • XI_PRM_CC_MATRIX_02 or “ccMTX02”
  • XI_PRM_CC_MATRIX_03 or “ccMTX03”
  • XI_PRM_CC_MATRIX_10 or “ccMTX10”
  • XI_PRM_CC_MATRIX_11 or “ccMTX11”
  • XI_PRM_CC_MATRIX_12 or “ccMTX12”
  • XI_PRM_CC_MATRIX_13 or “ccMTX13”
  • XI_PRM_CC_MATRIX_20 or “ccMTX20”
  • XI_PRM_CC_MATRIX_21 or “ccMTX21”
  • XI_PRM_CC_MATRIX_22 or “ccMTX22”
  • XI_PRM_CC_MATRIX_23 or “ccMTX23”
  • XI_PRM_CC_MATRIX_30 or “ccMTX30”
  • XI_PRM_CC_MATRIX_31 or “ccMTX31”
  • XI_PRM_CC_MATRIX_32 or “ccMTX32”
  • XI_PRM_CC_MATRIX_33 or “ccMTX33”
  • XI_PRM_DEFAULT_CC_MATRIX or “defccMTX”
  • XI_PRM_IMAGE_IS_COLOR or “iscolor”
  • XI_PRM_COLOR_FILTER_ARRAY or "cfa"
  • XI_PRM_CMS or "cms"
  • XI_PRM_CMS_INTENT or "cms_intent"
  • XI_PRM_APPLY_CMS or "apply_cms"
  • XI_PRM_INPUT_CMS_PROFILE or "input_cms_profile"
  • XI_PRM_OUTPUT_CMS_PROFILE or "output_cms_profile"
• Device IO parameters.
  • XI_PRM_GPI_SELECTOR or “gpi_selector”
  • XI_PRM_GPI_MODE or “gpi_mode”
  • XI_PRM_GPI_LEVEL or “gpi_level”
  • XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_START or gpi_level_at_image_exp_start
  • XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_END or gpi_level_at_image_exp_end
  • XI_PRM_GPO_SELECTOR or “gpo_selector”
  • XI_PRM_GPO_MODE or “gpo_mode”
  • XI_PRM_LED_SELECTOR or “led_selector”
  • XI_PRM_LED_MODE or “led_mode”
  • XI_PRM_TS_RST_SOURCE “ts_rst_source”
  • XI_PRM_TS_RST_MODE “ts_rst_mode”
• Extended Device Parameters.
  • XI_PRM_ACQ_BUFFER_SIZE or “acq_buffer_size”
  • XI_PRM_ACQ_BUFFER_SIZE_UNIT or "acq_buffer_size_unit"
  • XI_PRM_ACQ_TRANSPORT_BUFFER_SIZE or "acq_transport_buffer_size"
  • XI_PRM_ACQ_TRANSPORT_PACKET_SIZE or "acq_transport_packet_size"
  • XI_PRM_BUFFERS_QUEUE_SIZE or “buffers_queue_size”
  • XI_PRM_ACQ_TRANSPORT_BUFFER_COMMIT or “acq_transport_buffer_commit”
  • XI_PRM_RECENT_FRAME or “recent_frame”
  • XI_PRM_TRANSPORT_DATA_TARGET or “transport_data_target”
  • XI_PRM_DEVICE_RESET or “device_reset”
  • XI_PRM_AEAG or “aeag”
  • XI_PRM_AE_MAX_LIMIT or “ae_max_limit”
  • XI_PRM_AG_MAX_LIMIT or “ag_max_limit”
  • XI_PRM_EXP_PRIORITY or “exp_priority”
  • XI_PRM_AEAG_LEVEL or “aeag_level”
  • XI_PRM_AEAG_ROI_OFFSET_X or “aeag_roi_offset_x”
  • XI_PRM_AEAG_ROI_OFFSET_Y or “aeag_roi_offset_y”
  • XI_PRM_AEAG_ROI_WIDTH or “aeag_roi_width”
  • XI_PRM_AEAG_ROI_HEIGHT or “aeag_roi_height”
  • XI_PRM_DEBOUNCE_EN or “dbnc_en”
  • XI_PRM_DEBOUNCE_T0 or “dbnc_t0”
  • XI_PRM_DEBOUNCE_T1 or “dbnc_t1”
  • XI_PRM_DEBOUNCE_POL or “dbnc_pol”
• Temperature
  • XI_PRM_IS_COOLED or "iscooled"
  • XI_PRM_COOLING or "cooling"
  • XI_PRM_TARGET_TEMP or "target_temp"
  • XI_PRM_TEMP_SELECTOR or "temp_selector"
  • XI_PRM_TEMP or "temp"
  • XI_PRM_CHIP_TEMP or "chip_temp"
  • XI_PRM_HOUS_TEMP or "hous_temp"
  • XI_PRM_HOUS_BACK_SIDE_TEMP or "hous_back_side_temp"
  • XI_PRM_SENSOR_BOARD_TEMP or "sensor_board_temp"
  • XI_PRM_TEMP_CONTROL_MODE or "device_temperature_ctrl_mode"
  • XI_PRM_TEMP_ELEMENT_SEL or "device_temperature_element_sel"
  • XI_PRM_TEMP_ELEMENT_VALUE or "device_temperature_element_val"
• Device Connection
  • XI_PRM_IS_DEVICE_EXIST or "isexist"
• Sensor Defects Correction parameters
  • XI_PRM_SENS_DEFECTS_CORR_LIST_SELECTOR “bpc_list_selector”
  • XI_PRM_SENS_DEFECTS_CORR_LIST_CONTENT “sens_defects_corr_list_content”
  • XI_PRM_SENS_DEFECTS_CORR or “bpc”
  • XI_PRM_FFC or “ffc”
  • XI_PRM_FFC_FLAT_FIELD_FILE_NAME or "ffc_flat_field_file_name"
  • XI_PRM_FFC_DARK_FIELD_FILE_NAME or "ffc_dark_field_file_name"
  • XI_PRM_COLUMN_FPN_CORRECTION or “column_fpn_correction”
  • XI_PRM_ROW_FPN_CORRECTION or “row_fpn_correction”
• Sensor Specific Parameters
  • XI_PRM_HDR or "hdr"
  • XI_PRM_HDR_KNEEPOINT_COUNT or "hdr_kneepoint_count"
  • XI_PRM_HDR_T1 or "hdr_t1"
  • XI_PRM_HDR_T2 or "hdr_t2"
  • XI_PRM_KNEEPOINT1 or "hdr_kneepoint1"
  • XI_PRM_KNEEPOINT2 or "hdr_kneepoint2"
  • XI_PRM_SENSOR_MODE or "sensor_mode"
  • XI_PRM_IMAGE_BLACK_LEVEL or "image_black_level"
  • XI_PRM_API_CONTEXT_LIST or "xiapi_context_list"
• Api version and device driver/firmware info
  • XI_PRM_API_VERSION or "api_version"
  • XI_PRM_DRV_VERSION or "drv_version"
  • XI_PRM_MCU1_VERSION or "version_mcu1"
  • XI_PRM_MCU2_VERSION or "version_mcu2"
  • XI_PRM_MCU3_VERSION or "version_mcu3"
  • XI_PRM_FPGA1_VERSION or "version_fpga1"
  • XI_PRM_XMLMAN_VERSION or "version_xmlman"
  • XI_PRM_HW_REVISION or "hw_revision"
• Flash file system control
  • XI_PRM_FFS_FILE_NAME or "ffs_file_name"
  • XI_PRM_READ_FILE_FFS or "read_file_ffs"
    • HSI Calibration Files Access
  • XI_PRM_WRITE_FILE_FFS or "write_file_ffs"
  • XI_PRM_FFS_FILE_ID or "ffs_file_id"
  • XI_PRM_FFS_FILE_SIZE or "ffs_file_size"
  • XI_PRM_FREE_FFS_SIZE or "free_ffs_size"
  • XI_PRM_USED_FFS_SIZE or "used_ffs_size"
  • XI_PRM_FFS_ACCESS_KEY or "ffs_access_key"
• Camera Lens Control
  • XI_PRM_LENS_MODE or lens_mode
  • XI_PRM_LENS_APERTURE_VALUE or lens_aperture_value
  • XI_PRM_LENS_APERTURE_INDEX or lens_aperture_index
  • XI_PRM_LENS_FOCUS_MOVEMENT_VALUE or lens_focus_movement_value
  • XI_PRM_LENS_FOCUS_MOVE or lens_focus_move
  • XI_PRM_LENS_FOCUS_DISTANCE or lens_focus_distance
  • XI_PRM_LENS_FOCAL_LENGTH or lens_focal_length
  • XI_PRM_LENS_FEATURE_SELECTOR or lens_feature_selector
  • XI_PRM_LENS_FEATURE or lens_feature
• Sensor Feature Control
  • XI_PRM_SENSOR_FEATURE_SELECTOR or sensor_feature_selector
    • Selector description
  • XI_PRM_SENSOR_FEATURE_VALUE or sensor_feature_value
  • XI_PRM_ACQUISITION_STATUS_SELECTOR or “acquisition_status_selector”
  • XI_PRM_ACQUISITION_STATUS or “acquisition_status”
  • XI_PRM_GENTL_DATASTREAM_ENABLED or “gentl_stream_en”
  • XI_PRM_GENTL_DATASTREAM_CONTEXT or “gentl_stream_context”
  • XI_PRM_DP_UNIT_SELECTOR or “dp_unit_selector”
  • XI_PRM_DP_PROC_SELECTOR or “dp_proc_selector”
  • XI_PRM_DP_PARAM_SELECTOR or “dp_param_selector”
  • XI_PRM_DP_PARAM_VALUE or “dp_param_value”
• API parameter modifiers
  • XI_PRM_INFO_MIN
  • XI_PRM_INFO_MAX
  • XI_PRM_INFO_INCREMENT
  • XI_PRMM_DIRECT_UPDATE
• Image Buffers Queue
  • Functionality
  • Capturing
  • Flushing the queue

Writing Applications with xiAPI¶

Default parameters¶

After camera is opened by xiOpenDevice the default camera parameters are set by API. The default parameters might be different in different API versions. In order to ensure that your application will have camera in expected state with any API version - please set all parameters expected by your application to required value.

xiAPI Functions.¶

xiOpenDevice¶

Description:
This function initializes the device and returns a device handle.

Parameters:

• DevId - index of the device
• hDevice - handle to device

C Prototype:

XI_RETURN xiOpenDevice(IN DWORD DevId, OUT PHANDLE * hDevice);

xiOpenDeviceBy¶

Description:
This function initializes the device and returns a device handle. Device is selected according to used enumerator.

Parameters:

• sel - select method to be used for camera selection
• prm - string to identify device
• hDevice - handle to device

C Prototype:

XI_RETURN __cdecl xiOpenDeviceBy(IN XI_OPEN_BY sel, IN const char* prm, OUT PHANDLE hDevice);

Corresponding Enumerator XI_OPEN_BY

type	representing value	result
XI_OPEN_BY_INST_PATH	0	Open camera by its hardware path
XI_OPEN_BY_SN	1	Open camera by its serial number
XI_OPEN_BY_USER_ID	2	Open camera by its custom user ID
XI_OPEN_BY_LOC_PATH	3	Open camera by its hardware location path

Note: When the value of the parameter XI_PRM_DEVICE_USER_ID is changed and we want to open the camera with function xiOpenDeviceBy with the value XI_OPEN_BY_USER_ID, it is necessary to do a power cycle on this camera beforehand. This affects only cameras with USB data interface.

xiCloseDevice¶

Description:
This function will un-initialize the specified device, closes its handle and releases allocated resources.

Parameters:

• hDevice - handle to device

C Prototype:

XI_RETURN xiCloseDevice(IN HANDLE hDevice);

xiGetNumberDevices¶

Description: This function enumerates all devices connected and returns the number of discovered devices. It is needed to be called before any other function of API is called by application.

Parameters:

• pNumberDevices - number of discovered devices

C Protopype:

XI_RETURN xiGetNumberDevices(OUT DWORD *pNumberDevices);

xiStartAcquisition¶

Description:
This function starts the data acquisition on the devices specified by the handle.

Parameters:

• hDevice - handle to device

C Prototype:

XI_RETURN xiStartAcquisition(IN HANDLE hDevice);

xiStopAcquisition¶

Description:
Ends the work cycle of the camera, stops data acquisition and deallocates internal image buffers.

Parameters:

• hDevice - handle to device

C Prototype:

XI_RETURN xiStopAcquisition(IN HANDLE hDevice);

xiGetImage¶

Description:
This function waits for next image is available at transport buffer. If available - it does all required image processing (unpack, sensor-defect-correction, demosaic) and fills image information to structure at img parameter. Note: Image processing is not done if XI_FRM_TRANSPORT_DATA is selected. In this case the function just set pointer to transport-buffer without any processing.

Parameters:

• hDevice - handle to device
• TimeOut - time interval required to wait for the image (in milliseconds).
• img - Pointer to image info structure

Note: Allocation of buffers is influenced by buffering policy. See details of behavior at parameter XI_PRM_BUFFER_POLICY.

C Prototype:

XI_RETURN xiGetImage(IN HANDLE hDevice, IN DWORD TimeOut, 
                     INOUT XI_IMG * img);

The image structure XI_IMG description:

bytes	field name	description
4	size	Size of current structure on application side.
ptr	bp	pointer to first pixel of image data
4	bp_size	Filled buffer size. When buffer policy is set to XI_BP_SAFE, xiGetImage will fill this field with current size of image data received.
4	frm	format of image data (same as in parameter XI_PRM_IMAGE_DATA_FORMAT)
4	width	width of image in pixels
4	height	height of image in pixels
4	nframe	frame number (reset by exposure, gain, downsampling change, auto exposure (AEAG))
4	tsSec	TimeStamp in seconds (See note 1*)
4	tsUSec	TimeStamp in microseconds (See note 1*)
4	GPI_level	Level of Digital inputs/outputs sampled at the start/finish of exposure. See parameters XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_START and XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_END
4	black_level	Black level of image (ONLY for MONO and RAW formats. See note 2*)
4	padding_x	Number of extra bytes provided at the end of each line to facilitate image alignment in buffers
4	AbsoluteOffsetX	Horizontal offset of origin of sensor and buffer image first pixel
4	AbsoluteOffsetY	Vertical offset of origin of sensor and buffer image first pixel
4	transport_frm	Current format of pixels on transport layer. XI_GenTL_Image_Format_e.
x	img_desc	Image data description, necessary for offline processing
4	DownsamplingX	Total horizontal subsampling
4	DownsamplingY	Total vertical subsampling
4	exposure_time_us	Exposure time of this image in microseconds (See note 3*)
4	gain_db (float)	Gain used for this image in dB (only valid for MQ,MD,MR camera families)
4	acq_nframe	Frame number. Reset only by acquisition start. NOT reset by change of exposure, gain, downsampling, auto exposure (AEAG).
4	image_user_data	data controlled by user application using XI_PRM_IMAGE_USER_DATA parameter
20	exposure_sub_times_us	Sub exposure times in microseconds for Multiple_exposures_in_one_frame or HDR
8	data_saturation	Maximum possible value of one pixel
4	wb_red	Red coefficient of white balance
4	wb_green	Green coefficient of white balance
4	wb_blue	Blue coefficient of white balance

1 *Note: Depending on camera family the TimeStamp is represented as counter:

• xiQ, xiD: 40 bit microsecond number - (overlaps after 305 hours)
• xiC,xiB,xiT,xiX: 64 bit 4-nanoseconds number (overlaps after 2339 years)
  This counter is converted to image header the fields tsSec and tsUSec.
  TimeStamp on xiQ, xiD is recorded at the start of Data Readout.
  TimeStamp on xiC, xiB, xiX, xiT is recorded at the start of Exposure.
  TimeStamp is NOT implemented on some cameras. xiMU (MU9). Image header contains only constant number instead of valid TimeStamp.
  2 *Note: xiQ cameras reports calculated black_level. We do not guaranty the precision of black_level calculation above 50ms of exposure and/or gain above 3dB.
  3 *Note: Some camera models (MQ,MU) might report this exposure time earlier before exposure is applied to image. Cameras with IMX sensors (MC,MX,MT) report value measured by FPGA - this value is systemically lower then value returned by xiGetParam with XI_PRM_EXPOSURE parameter; difference is typically below 20 us.

GPI_level-Sampling-in-Header¶

Digital Inputs are sampled on some cameras.

• MQ: at exposure end
• CB,MX,MC: at exposure start and exposure end
  The samples are available after calling of xiGetImage using the parameters XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_START, XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_END. See example at the parameters description.

xiSetParam¶

Description:
This function configures device (see xiAPI Parameters below).

Parameters:

• hDevice - handle to device
• prm - parameter name string.
• value - value that should be set to parameter
• size - size of value
• type - data type of value

C Prototype:

XI_RETURN xiSetParam(IN HANDLE hDevice, IN CHAR * prm, IN VOID * value,
                     IN DWORD size, IN XI_PRM_TYPE type);

xiGetDeviceInfoString¶

Description:
This function returns selected parameter of camera without opening it. It allows to quickly get information from each camera in multiple camera setups.

Parameters:

• Devid - index of the camera (same as on xiOpenDevice)
• prm - parameter name string
• value - pointer to result string
• value_size - size of string

C Prototype:

XIAPI XI_RETURN __cdecl xiGetDeviceInfoString(IN DWORD DevId, const char* prm, char* value, DWORD value_size);

Note: This function is capable to return only limited set of parameters:

• XI_PRM_DEVICE_SN
• XI_PRM_DEVICE_NAME
• XI_PRM_DEVICE_INSTANCE_PATH
• XI_PRM_DEVICE_LOCATION_PATH
• XI_PRM_DEVICE_TYPE

xiGetParam¶

Description:
This function returns parameters information (current value, minimum, maximum)(see xiAPI Parameters below).

Parameters:

• hDevice - handle to device
• prm - parameter name string
• value - value buffer where result will be stored
• size - size of value buffer
• type - expected value type

C Prototype:

XI_RETURN xiGetParam(IN HANDLE hDevice, IN CHAR * prm, IN VOID * value,
                     INOUT DWORD * size, OUT XI_PRM_TYPE * type);

xiAPI Parameters.¶

Each parameter contains of:

• Description: Describing the parameter behavior
• Type: Data type used internally for modeling parameter
• Default: Describing typical default value, however it can be different for different cameras
• Invalidators: List of parameters. Changing of any of those might lead to change of value or range (min, max, increment) of parameter described.
• Usage: Example of usage of this parameter in application (C code)

Device info parameters.¶

XI_PRM_DEVICE_NAME or “device_name”¶

Description: Returns device name.

Type: String.
Default: -

Usage:

xiGetParamString(handle, XI_PRM_DEVICE_NAME, char *, size);

XI_PRM_DEVICE_INSTANCE_PATH or "device_inst_path"¶

Description: Returns device instance path in operating system.

Type: String.
Default: -

Usage:

xiGetParamString(handle, XI_PRM_DEVICE_INSTANCE_PATH, path, sizeof(path));

XI_PRM_DEVICE_LOCATION_PATH or "device_loc_path"¶

Description: Returns device location path in operating system. It should reflect the connection position.

Type: String.
Default: -

Usage:

xiGetParamString(handle, XI_PRM_DEVICE_LOCATION_PATH, path, sizeof(path));

XI_PRM_DEVICE_TYPE or “device_type”¶

Description: Returns device type (1394, USB2.0, CURRERA…..).

Type: String.
Default: -

Usage:

xiGetParamString(handle, XI_PRM_DEVICE_TYPE, char*, size);

XI_PRM_DEVICE_MODEL_ID or “device_model_id”¶

Description: Returns the device model id.

Type: Integer.
Default: -

Usage:

xiGetParamInt(handle, XI_PRM_DEVICE_MODEL_ID, &model_id);

XI_PRM_SENSOR_MODEL_ID or “sensor_model_id”¶

Description: Returns the device sensor model id.

Type: Integer.
Default: -

Usage:

xiGetParamInt(handle, XI_PRM_SENSOR_MODEL_ID, &sensor_id);

XI_PRM_DEVICE_SN or “device_sn”¶

Description: Returns device serial number. Only string form is possible. It might contain also alphabet characters.

Type: String
Default: -

Usage:

  
char sn[20]="";
xiGetParamString(handle, XI_PRM_DEVICE_SN, sn, sizeof(sn));

Example:

// show serial number of this camera
char sn[20]="";
xiGetParamString(handle, XI_PRM_DEVICE_SN, sn, sizeof(sn));
printf("Serial number of the camera is: %s\n",sn);

XI_PRM_DEVICE_SENS_SN or device_sens_sn¶

Description: Returns sensor serial number.

Type: String.
Default: -

Usage:

char sens_sn[100]="";
xiGetParamString(handle, XI_PRM_DEVICE_SENS_SN, sens_sn, 100);

XI_PRM_DEVICE_USER_ID or "device_user_id"¶

Description: Get/Set custom user ID stored in camera non volatile memory. This can be later used as a handle for opening or identification.

Type: String (ASCII).
Note: Available currently on certain models

Model	Maximum length	Note
xiQ, xiC	10
xiB, xiT, xiX	4	Power off/on required after User ID changed

Default: -

Usage:

xiGetParamString(handle,XI_PRM_DEVICE_USER_ID,name,sizeof(name));

Example of setting and retrieving the DEVICE_USER_ID

Note: Only after a successful reboot of the camera, it can be opened with the newly assigned XI_PRM_DEVICE_USER_ID.

XI_PRM_DEVICE_MANIFEST or "device_manifest"¶

Description: Get XML of current device parameters and capabilities.

Type: String.
Note: Available currently on xiQ USB3.0, xiB, xiT cameras.
Default: -

Usage:

char* manifest_data=NULL;
#define MANIF_MAX_SIZE 2*1024*1024
manifest_data = malloc(MANIF_MAX_SIZE);
xiGetParamString(handle,XI_PRM_DEVICE_MANIFEST,manifest_data,MANIF_MAX_SIZE);

XI_PRM_DEBUG_LEVEL or 'debug_level'¶

Description: Setting the API debug level allows to select amount of messages stored to debug output.

• In Windows use DebugView to view the current messages.
• In Linux the messages are printed to stderr

Type: Integer.

type	representing value	result
XI_DL_DETAIL	0	Prints same as XI_DL_TRACE plus locking of resources
XI_DL_TRACE	1	Prints errors, warnings and important informations
XI_DL_WARNING	2	Prints all errors and warnings
XI_DL_ERROR	3	Prints all errors
XI_DL_FATAL	4	Prints only important errors
XI_DL_DISABLED	100	Prints no messages

Default: XI_DL_WARNING

Usage:

xiSetParamInt(0, XI_PRM_DEBUG_LEVEL, XI_DL_TRACE);

XI_PRM_AUTO_BANDWIDTH_CALCULATION or 'auto_bandwidth_calculation'¶

Description: Setting this parameter the application can control API behavior. Setting to XI_OFF - API will skip auto bandwidth measuring and calculation before opening the camera (xiOpenDevice). Setting to XI_ON the measurement is enabled (default).

Note: It is important to set this parameter to XI_OFF in case when multiple cameras are connected to one hub with enabled acquisition and new camera should be opened - to not affect overall streaming by auto bandwidth measurement.

Type: Integer.
Default: XI_ON

Usage:

xiSetParamInt(0, XI_PRM_AUTO_BANDWIDTH_CALCULATION, XI_OFF);

XI_PRM_PROC_NUM_THREADS or 'proc_num_threads'¶

Description: Number of threads per image processor. Application can change this number in order to optimize performance or decrease number of threads to save resources.

Type: Integer.
Default: Number of CPU cores.

Usage:

xiSetParamInt(0, PROC_NUM_THREADS, 4);

XI_PRM_NEW_PROCESS_CHAIN_ENABLE or 'new_process_chain_enable'¶

Description: Setting this parameter the application can control API behavior. When set to XI_OFF - API will use original processing in image pipe for cameras families MU, MQ, MD. Setting to XI_ON - API will use newer processing type.

Note: There are some differences between processing so the switching may be done with caution. For older implementation we advise to stick to original processing. Only if some features require the newer processing it might be enabled. Switching may be done before xiOpenDevice.

Type: Integer.
Default: XI_ON

Usage:

xiSetParamInt(0, XI_PRM_NEW_PROCESS_CHAIN_ENABLE, XI_ON);

Device acquisition parameters.¶

XI_PRM_EXPOSURE or “exposure”¶

Description: Current exposure time in microseconds. When parameter is set by xiSetParam the API checks the range. If it is within the range, it tries to find the closest settable value and set it. The actual value can be read by xiGetParam. E.g. Application set exposure time to 1000us, however closest possible value is 1029us (it is typically based on sensor line read-out period). This value is accessable over xiGetParam.

Type: Integer.
Default: 0

Usage:

xiSetParamInt(handle, XI_PRM_EXPOSURE, time_in_us);

XI_PRM_EXPOSURE_BURST_COUNT or "exposure_burst_count"¶

Description: Sets the number of times of exposure in one frame.
To finish exposure burst change this parameter to 1 and exposure will be finished by next trigger.
See more details in article Multiple_exposures_in_one_frame
Note: This setting is valid only if the trigger selector is set to ExposureActive or ExposureStart.
Type: Integer.
Default: 1
Supported cameras: MC031xG-SY, MC050xG-SY, MC089xG-SY, MC124xG-SY, MX031xG-SY, MX050xG-SY, MX089xG-SY, MX124xG-SY, MT031xG-SY, MT050xG-SY
Usage:

xiSetParamInt(handle, XI_PRM_TRG_SELECTOR, XI_TRG_SEL_EXPOSURE_ACTIVE);
xiSetParamInt(handle, XI_PRM_EXPOSURE_BURST_COUNT, 5);

XI_PRM_GAIN_SELECTOR or “gain_selector”¶

Description: Selects type of gain for XI_PRM_GAIN. On some cameras there is possibility to select analog or digital gain separately.

Selector XI_GAIN_SELECTOR_ALL is mapped on most cameras to analog gain.

Type: Integer.
Default: All

Usage:

xiSetParamInt(handle, XI_PRM_GAIN_SELECTOR, XI_GAIN_SELECTOR_ANALOG_ALL );  

XI_PRM_GAIN or “gain”¶

Description: Current gain in dB. When parameter is set by xiSetParam the API checks the range. If it is within the range, it tries to find the closest settable value and set it. The actual value can be read by xiGetParam. E.g. Application set gain to 1.3dB, however closest possible value is 1.35dB (analog gain is typically based on sensor PGA registers capabilities). This value is accessable over xiGetParam.

Type: Float
Default: 0

Usage:

xiSetParamFloat(handle, XI_PRM_GAIN, gain_in_db );  

XI_PRM_DOWNSAMPLING or “downsampling”¶

Description: Changes image resolution by binning or skipping.
Parameter downsampling_rate controls the mapping of sensor pixels to output data.
Type: Integer.

downsampling_rate	result image
1	1 sensor pixel = 1 image pixel
2	2x2 sensor pixels = 1 image pixel
4	4x4 sensor pixels = 1 image pixel

Default: 1
Note: Downsampling can be changed only before an acquisition is started.

Usage:

xiSetParamInt(handle, XI_PRM_DOWNSAMPLING, 2);

Note: Changing this parameter will flush all images from the buffer queue.

XI_PRM_DOWNSAMPLING_TYPE or “downsampling_type”¶

Description: Changes image downsampling type (binning or skipping).
Type: Integer.

type	value	result image
XI_BINNING	0	pixels are interpolated - better image
XI_SKIPPING	1	pixels are skipped - higher frame rate

Default: 0 (XI_BINNING)
Usage:

xiSetParamInt(handle, XI_PRM_DOWNSAMPLING_TYPE, XI_SKIPPING);

Note: Changing this parameter will remove all images from the buffer queue.
Note 2: Please use this parameter only for cameras that support symmetrical binning/skipping with dimensions at least 2x2.

Binning and Decimation¶

xiAPI allows to set different combinations of binning and decimation parameters.
On xiC, xiB, xiX, xiT cameras the parameters of units (Sensor, FPGA, CPU) are accessible with selectors (e.g. XI_PRM_BINNING_SELECTOR). After setting of selector, multiple parameters could be get of set for the selected unit. They can be divided into:

• Patterns (e.g. XI_PRM_BINNING_HORIZONTAL_PATTERN). If new pattern is set - the API might change the Values automatically in order to achieve setting of the new pattern.
• Values (e.g. XI_PRM_BINNING_HORIZONTAL). If new value is set - the API might change other values automatically in order to achieve setting of the new. Firstly it tries to find exact mode keeping the unchanged values, secondary it tries to find similar mode (trying to keep the other part - e.g. changing binning is trying to keep decimation parameters). If first and second attempts fails, the API tries to find any mode where new-value is found without keeping any other parameters, keeping Patterns.
• Modes for binning (e.g. XI_PRM_BINNING_VERTICAL_MODE)

XI_PRM_BINNING_SELECTOR or “binning_selector”¶

Description: Selects Binning engine to configure.
Type: Integer.

type	value	binning engine
XI_BIN_SELECT_SENSOR	0	parameters for image sensor binning are selected
XI_BIN_SELECT_DEVICE_FPGA	1	parameters for device (camera) FPGA decimation are selected
XI_BIN_SELECT_HOST_CPU	2	parameters for Host CPU binning are selected

Default: 0 (XI_BIN_SELECT_SENSOR)
Usage:

xiSetParamInt(handle, XI_PRM_BINNING_SELECTOR, XI_BIN_SELECT_SENSOR);

XI_PRM_BINNING_VERTICAL_MODE or “binning_vertical_mode”¶

Description: Sets the mode to use to combine vertical pixel together.
Type: Integer.

XI_BIN_MODE	value	binning engine
XI_BIN_MODE_SUM	0	The response from the combined pixels will be added, resulting in increased sensitivity.
XI_BIN_MODE_AVERAGE	1	The response from the combined pixels will be averaged, resulting in increased signal/noise ratio.

Default: 0 (XI_BIN_MODE_SUM)
Invalidators: XI_PRM_BINNING_SELECTOR

Usage:

xiSetParamInt(handle, XI_PRM_BINNING_VERTICAL_MODE, XI_BIN_MODE_AVERAGE);

XI_PRM_BINNING_VERTICAL or “binning_vertical”¶

Description: Defines number of vertical photo-sensitive cells to combine.
Type: Integer.
Default: 1
Invalidators: XI_PRM_BINNING_SELECTOR, XI_PRM_BINNING_HORIZONTAL, XI_PRM_DECIMATION_HORIZONTAL, XI_PRM_DECIMATION_VERTICAL, XI_PRM_BINNING_HORIZONTAL_PATTERN, XI_PRM_BINNING_VERTICAL_PATTERN, XI_PRM_DECIMATION_HORIZONTAL_PATTERN, XI_PRM_DECIMATION_VERTICAL_PATTERN

Usage:

xiSetParamInt(handle, XI_PRM_BINNING_VERTICAL, 2);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to achieve a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_BINNING_HORIZONTAL_MODE or “binning_horizontal_mode”¶

Description: Sets the mode to use to combine horizontal pixel together.
Type: Integer.

XI_BIN_MODE	value	binning engine
XI_BIN_MODE_SUM	0	The response from the combined pixels will be added, resulting in increased sensitivity.
XI_BIN_MODE_AVERAGE	1	The response from the combined pixels will be averaged, resulting in increased signal/noise ratio.

Default: 0 (XI_BIN_MODE_SUM)
Invalidators: XI_PRM_BINNING_SELECTOR
Usage:

xiSetParamInt(handle, XI_PRM_BINNING_HORIZONTAL_MODE, XI_BIN_MODE_AVERAGE);

XI_PRM_BINNING_HORIZONTAL or “binning_horizontal”¶

Description: Defines number of horizontal photo-sensitive cells to combine.
Type: Integer.
Default: 1
Invalidators: XI_PRM_BINNING_SELECTOR, XI_PRM_BINNING_VERTICAL, XI_PRM_DECIMATION_HORIZONTAL, XI_PRM_DECIMATION_VERTICAL, XI_PRM_BINNING_HORIZONTAL_PATTERN, XI_PRM_BINNING_VERTICAL_PATTERN, XI_PRM_DECIMATION_HORIZONTAL_PATTERN, XI_PRM_DECIMATION_VERTICAL_PATTERN

Usage:

xiSetParamInt(handle, XI_PRM_BINNING_HORIZONTAL, 2);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to achieve a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_BINNING_HORIZONTAL_PATTERN or “binning_horizontal_pattern”¶

Description: Defines binning horizontal pattern.
Type: Integer.

type	value	result image
XI_BIN_MONO	1	adjacent pixels are combined
XI_BIN_BAYER	2	Bayer pattern is preserved during pixel combining

Default: XI_BIN_MONO (for Monochorme cameras) / XI_BIN_BAYER (for Color cameras)
Invalidators: XI_PRM_BINNING_SELECTOR
Usage:

xiSetParamInt(handle, XI_PRM_BINNING_HORIZONTAL_PATTERN, XI_BIN_BAYER);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to achieve a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_BINNING_VERTICAL_PATTERN or “binning_vertical_pattern”¶

Description: Defines binning vertical pattern.
Type: Integer.

type	value	result image
XI_BIN_MONO	1	adjacent pixels are combined
XI_BIN_BAYER	2	Bayer pattern is preserved during pixel combining

Default: XI_BIN_MONO (for Monochorme cameras) / XI_BIN_BAYER (for Color cameras)
Invalidators: XI_PRM_BINNING_SELECTOR
Usage:

xiSetParamInt(handle, XI_PRM_BINNING_VERTICAL_PATTERN, XI_BIN_BAYER);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to achieve a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_DECIMATION_SELECTOR or “decimation_selector”¶

Description: Selects Decimation engine to configure.
Type: Integer.

type	value	decimation engine
XI_DEC_SELECT_SENSOR	0	parameters for image sensor decimation are selected
XI_DEC_SELECT_DEVICE_FPGA	1	parameters for device (camera) FPGA decimation are selected
XI_DEC_SELECT_HOST_CPU	2	parameters for Host CPU decimation are selected

Default: 0 (XI_DEC_SELECT_SENSOR)
Usage:

xiSetParamInt(handle, XI_PRM_DECIMATION_SELECTOR, XI_DEC_SELECT_SENSOR);

XI_PRM_DECIMATION_VERTICAL or “decimation_vertical”¶

Description: Reduces the vertical resolution of the image by the specified decimation factor.
Type: Integer.
Default: 1
Invalidators: XI_PRM_DECIMATION_SELECTOR, XI_PRM_BINNING_HORIZONTAL, XI_PRM_BINNING_VERTICAL, XI_PRM_DECIMATION_HORIZONTAL, XI_PRM_BINNING_HORIZONTAL_PATTERN, XI_PRM_BINNING_VERTICAL_PATTERN, XI_PRM_DECIMATION_HORIZONTAL_PATTERN, XI_PRM_DECIMATION_VERTICAL_PATTERN

Usage:

xiSetParamInt(handle, XI_PRM_DECIMATION_VERTICAL, 2);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to achieve a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_DECIMATION_HORIZONTAL or “decimation_horizontal”¶

Description: Reduces the horizontal resolution of the image by the specified decimation factor.
Type: Integer.
Default: 1
Invalidators: XI_PRM_DECIMATION_SELECTOR, XI_PRM_BINNING_HORIZONTAL, XI_PRM_BINNING_VERTICAL, XI_PRM_DECIMATION_VERTICAL, XI_PRM_BINNING_HORIZONTAL_PATTERN, XI_PRM_BINNING_VERTICAL_PATTERN, XI_PRM_DECIMATION_HORIZONTAL_PATTERN, XI_PRM_DECIMATION_VERTICAL_PATTERN

Usage:

xiSetParamInt(handle, XI_PRM_DECIMATION_HORIZONTAL, 2);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to achieve a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_DECIMATION_HORIZONTAL_PATTERN or “decimation_horizontal_pattern”¶

Description: Defines decimation horizontal pattern.
Type: Integer.
Invalidators: XI_PRM_DECIMATION_SELECTOR

type	value	result image
XI_DEC_MONO	1	adjacent pixels are decimated
XI_DEC_BAYER	2	Bayer pattern is preserved during pixel decimation

Default: XI_DEC_MONO (for Monochorme cameras) / XI_DEC_BAYER (for Color cameras)
Usage:

xiSetParamInt(handle, XI_PRM_DECIMATION_HORIZONTAL_PATTERN, XI_DEC_BAYER);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to set a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_DECIMATION_VERTICAL_PATTERN or “decimation_vertical_pattern”¶

Description: Defines decimation vertical pattern.
Type: Integer.
Invalidators: XI_PRM_DECIMATION_SELECTOR

type	value	result image
XI_DEC_MONO	1	adjacent pixels are decimated
XI_DEC_BAYER	2	Bayer pattern is preserved during pixel decimation

Default: XI_DEC_MONO (for Monochorme cameras) / XI_DEC_BAYER (for Color cameras)
Usage:

xiSetParamInt(handle, XI_PRM_DECIMATION_VERTICAL_PATTERN, XI_DEC_BAYER);

Note: Setting this feature may automatically change other Binning/Decimation parameters in order to set a valid combination.
Note: This feature influences image size + sets ROI to default full image values.

XI_PRM_TEST_PATTERN_GENERATOR_SELECTOR or “test_pattern_generator_selector”¶

Description: Selects Test Pattern Generator Engine.
Type: Integer.

type	value	result image
XI_TESTPAT_GEN_SENSOR	0	Sensor Testpattern Generator
XI_TESTPAT_GEN_FPGA	1	FPGA Testpattern Generator

Default: 0 (XI_TESTPAT_GEN_SENSOR)
Usage:

xiSetParamInt(handle, XI_PRM_TEST_PATTERN_GENERATOR_SELECTOR , XI_TESTPAT_GEN_SENSOR);

XI_PRM_TEST_PATTERN or “test_pattern”¶

Description: Selects Test Pattern Type to be generated by the selected Generator Engine.
Type: Integer.

type	value	result image
XI_TESTPAT_OFF	0	Testpattern turned off.
XI_TESTPAT_BLACK	1	Image is filled with darkest possible image.
XI_TESTPAT_WHITE	2	Image is filled with brightest possible image.
XI_TESTPAT_GREY_HORIZ_RAMP	3	Image is filled horizontally with an image that goes from the darkest possible value to the brightest.
XI_TESTPAT_GREY_VERT_RAMP	4	Image is filled vertically with an image that goes from the darkest possible value to the brightest.
XI_TESTPAT_GREY_HORIZ_RAMP_MOVING	5	Image is filled horizontally with an image that goes from the darkest possible value to the brightest and moves from left to right.
XI_TESTPAT_GREY_VERT_RAMP_MOVING	6	Image is filled vertically with an image that goes from the darkest possible value to the brightest and moves from left to right.
XI_TESTPAT_HORIZ_LINE_MOVING	7	A moving horizontal line is superimposed on the live image.
XI_TESTPAT_VERT_LINE_MOVING	8	A moving vertical line is superimposed on the live image.
XI_TESTPAT_COLOR_BAR	9	Image is filled with stripes of color including White, Black, Red, Green, Blue, Cyan, Magenta and Yellow.
XI_TESTPAT_FRAME_COUNTER	10	A frame counter is superimposed on the live image.
XI_TESTPAT_DEVICE_SPEC_COUNTER	11	128bit counter.

Default: 0 (XI_TESTPAT_OFF)
Usage:

xiSetParamInt(handle, XI_PRM_TEST_PATTERN , XI_TESTPAT_OFF);

XI_PRM_SHUTTER_TYPE or "shutter_type"¶

Description: Type of sensor shutter.

Type: Integer.

type	value	result image
XI_SHUTTER_GLOBAL	0	Sensor Global Shutter(CMOS sensor)
XI_SHUTTER_ROLLING	1	Sensor Electronic Rolling Shutter(CMOS sensor)
XI_SHUTTER_GLOBAL_RESET_RELEASE	2	Sensor Global Reset Release Shutter(CMOS sensor)

Default: Depends on camera model
Invalidators: XI_PRM_TRG_SOURCE
Usage:

xiSetParamInt(handle, XI_PRM_SHUTTER_TYPE , shutter_type);

Note: This feature is available only on xiMU camera models.

XI_PRM_IMAGE_DATA_FORMAT or “imgdataformat”¶

Description: Format of image data returned by function xiGetImage. In order to simplify the control of the camera from application - the xiAPI automatically changes selected camera parameters and Image Processing after setting of XI_PRM_IMAGE_DATA_FORMAT. See Format Dependency Table.

Type: Integer.
Default: MONO8
Possible values:

Image Data Formats¶

value	one pixel data in memory [one_byte]
XI_MONO8	[Intensity] (Note1,Note2)
XI_MONO16	[Intensity LSB] [Intensity MSB] (Note1,Note2)
XI_RGB24	[Blue][Green][Red] (Note1)
XI_RGB32	[Blue][Green][Red][0]* (Note1)
XI_RGB48	[Blue low byte][Blue high byte][Green low][Green high][Red low][Red high] (Note1)
XI_RGB64	[Blue low byte][Blue high byte][Green low][Green high][Red low][Red high][0][0] (Note1)
XI_RGB_PLANAR	[Red][Red]...[Green][Green]...[Blue][Blue]... (Note1)
XI_RAW8	[pixel byte] raw data from transport (camera output)
XI_RAW8X2	[ch1 pixel byte] [ch2 pixel byte] 8 bits raw data from 2 channels (e.g. high gain and low gain channels of sCMOS cameras)
XI_RAW8X4	[ch1 pixel byte [ch2 pixel byte] [ch3 pixel byte] [ch4 pixel byte] 8 bits raw data from 4 channels (e.g. sCMOS cameras)
XI_RAW16	[pixel byte low] [pixel byte high] 16 bits (depacked) raw data
XI_RAW16X2	[ch1 pixel byte low] [ch1 pixel byte high] [ch2 pixel byte low] [ch2 pixel byte high] 16 bits (depacked) raw data from 2 channels (e.g. high gain and low gain channels of sCMOS cameras)
XI_RAW16X4	[ch1 pixel byte low] [ch1 pixel byte high] [ch2 pixel byte low] [ch2 pixel byte high] [ch3 pixel byte low] [ch3 pixel byte high] [ch4 pixel byte low] [ch4 pixel byte high] 16 bits (depacked) raw data from 4 channels (e.g. sCMOS cameras)
XI_FRM_TRANSPORT_DATA	depends on data on the transport layer (Note3)
XI_RAW32	4 bytes (LSB first) pixel (depacked) raw data
XI_RAW32FLOAT	4 bytes per pixel (depacked) raw data

Note1: Higher CPU processing is required when this mode is selected because color filter array processing is implemented on PC. This processing is serialized when multiple cameras is used at once. The most effective way to get data from camera is to use XI_RAW8, where no additional processing is done in API.
Note2: On monochromatic cameras the black level is not subtracted in XI_MONO8 and XI_MONO16 formats by Image Processing in xiAPI, so black level remains the same as in RAW format.
Note3: When using Transport Data Format, the Image Processing block from Image Data Flow is skipped and therefore the Transport format is the most effective data format in terms of CPU and RAM usage.

XI_PRM_IMAGE_DATA_FORMAT_RGB32_ALPHA or “imgdataformatrgb32alpha”¶

Description: The alpha channel of RGB32 output image format(see XI_PRM_IMAGE_DATA_FORMAT).
Type: Integer.
Default: 0
Possible values:

Data Format Dependency Table¶

Following parameters and Image Processing are controlled automatically by setting of XI_PRM_IMAGE_DATA_FORMAT:

Format	Parameters controlled automatically	Image Processing
XI_MONO8	XI_PRM_SENSOR_DATA_BIT_DEPTH = 8* XI_PRM_OUTPUT_DATA_BIT_DEPTH = 8* XI_PRM_OUTPUT_DATA_PACKING = OFF	enabled
XI_RAW8	XI_PRM_SENSOR_DATA_BIT_DEPTH = 8* XI_PRM_OUTPUT_DATA_BIT_DEPTH = 8* XI_PRM_OUTPUT_DATA_PACKING = OFF	disabled
XI_MONO16**	XI_PRM_SENSOR_DATA_BIT_DEPTH = maximum XI_PRM_OUTPUT_DATA_BIT_DEPTH = SENSOR_DATA_BIT_DEPTH XI_PRM_OUTPUT_DATA_PACKING = ON*	enabled
XI_RAW16**	XI_PRM_SENSOR_DATA_BIT_DEPTH = maximum XI_PRM_OUTPUT_DATA_BIT_DEPTH = SENSOR_DATA_BIT_DEPTH XI_PRM_OUTPUT_DATA_PACKING = ON*	disabled
XI_RGB32 XI_RGB24 XI_RGB_PLANAR	XI_PRM_SENSOR_DATA_BIT_DEPTH = maximum XI_PRM_OUTPUT_DATA_BIT_DEPTH = SENSOR_DATA_BIT_DEPTH XI_PRM_OUTPUT_DATA_PACKING = ON*	enabled

Note (*): Only if camera implementation allows this mode.
Note (**): For XI_RAW16, XI_MONO16 the parameter XI_PRM_IMAGE_DATA_BIT_DEPTH will be equal to XI_PRM_OUTPUT_DATA_BIT_DEPTH. For other formats the XI_PRM_IMAGE_DATA_BIT_DEPTH will be 8.

After changing of XI_PRM_IMAGE_DATA_FORMAT the image resolution (XI_PRM_WIDTH,XI_PRM_HEIGHT) might change. Please check or set image resolution after changing of Image Data Format.

Bits alignment: Values are aligned to LSB.

sensor bits per pixel	values in modes XI_RAW16
10	0-1023
12	0-4095
14	0-16383

Example: Camera produces 10 bits data and data format XI_RAW16 bit is selected - each 16bit word (pixel) can contain values in range 0-1023.

Usage:

xiSetParamInt(handle, XI_PRM_IMAGE_DATA_FORMAT, XI_MONO8);

Note: For color modes XI_RGB32 and XI_RGB24 the image from sensor should be pre-processed. CPU load is higher in these modes. Setting this parameter will reset current region of interest. XI_RGB24 is being processed from the XI_RGB32 by removing the unused Alpha channel creating a slightly higher CPU load then the XI_RGB32 format.

XI_PRM_IMAGE_PAYLOAD_SIZE or "imgpayloadsize"¶

Description: Buffer size in bytes sufficient for output image returned by xiGetImage.

Type: Integer - Read only

XI_PRM_TRANSPORT_PIXEL_FORMAT or "transport_pixel_format"¶

Description: Transport pixel format is format of data transported by link to transport layer. It might be modified after setting of XI_PRM_IMAGE_DATA_FORMAT, XI_PRM_OUTPUT_DATA_PACKING, XI_PRM_OUTPUT_DATA_BIT_DEPTH, ...

Type: Enumerator - Enumerated by XI_GenTL_Image_Format_e
Default: (depends on camera model)

XI_PRM_FRAMERATE or “framerate”¶

Description: Defines frames per second of sensor. On some sensors it is possible to set framerate - see Note.

See more details in article Frame Rate Control.

Type: Float.
Default: Maximum possible at current exposure.
Invalidators: XI_PRM_IMAGE_DATA_FORMAT, XI_PRM_EXPOSURE, XI_PRM_ACQ_TIMING_MODE, XI_PRM_LIMIT_BANDWIDTH, XI_PRM_SENSOR_TAPS, XI_PRM_DOWNSAMPLING, XI_PRM_DOWNSAMPLING_TYPE, XI_PRM_HEIGHT
Usage:

float fps=0;
xiGetParamFloat(handle, XI_PRM_FRAMERATE, &fps);

Note: On some camera models it is possible to change or limit acquisition frame rate. Frame rate value should be within possible range. Use following code to get range.

xiGetParamFloat(handle, XI_PRM_FRAMERATE XI_PRM_INFO_MIN, &min_fps);
xiGetParamFloat(handle, XI_PRM_FRAMERATE XI_PRM_INFO_MAX, &max_fps);

Use following code to set 10 FPS on MQ, MD cameras:

xiSetParamInt(h,XI_PRM_ACQ_TIMING_MODE, XI_ACQ_TIMING_MODE_FRAME_RATE);
xiSetParamFloat(h, XI_PRM_FRAMERATE, 10);

Use following code to limit frame rate 10 to FPS on CB,MT,MX,MC cameras:

xiSetParamInt(h,XI_PRM_ACQ_TIMING_MODE, XI_ACQ_TIMING_MODE_FRAME_RATE_LIMIT);
xiSetParamFloat(h, XI_PRM_FRAMERATE, 10);

XI_PRM_BUFFER_POLICY or “buffer_policy”¶

Description: Defines buffer handling. Can be safe, data will be copied to user/app buffer or unsafe, user will get internally allocated buffer without data copy. Size of the image buffer can be obtained by parameter XI_PRM_IMAGE_PAYLOAD_SIZE.

Type: Integer.
Default: BP_UNSAFE.

Usage:

xiSetParamInt(handle, XI_PRM_BUFFER_POLICY, XI_BP_SAFE);

Note: Click to below link to open simple description of buffer policy.
buffer_policy_in_xiApi.png

XI_PRM_COUNTER_SELECTOR or “counter_selector”¶

Description: Selects which frame counter must be returned

Type: Integer.

counter selector	value	meaning
XI_CNT_SEL_TRANSPORT_SKIPPED_FRAMES	0	Number of skipped frames on transport layer (e.g. when an image gets lost while transmission). Occur when the capacity of transport channel does not allow to transfer all data.
XI_CNT_SEL_API_SKIPPED_FRAMES	1	Number of skipped frames on API layer. Occur when application does not process the images as quickly as they are received from the camera
XI_CNT_SEL_TRANSPORT_TRANSFERRED_FRAMES	2	Number of successfully transferred frames on the transport layer.
XI_CNT_SEL_FRAME_MISSED_TRIGGER_DUETO_OVERLAP*	3	Number of missed triggers due to overlap.
XI_CNT_SEL_FRAME_MISSED_TRIGGER_DUETO_FRAME_BUFFER_OVR*	4	Number of missed triggers due to frame buffer full.
XI_CNT_SEL_FRAME_BUFFER_OVERFLOW*	5	Frame buffer full counter.

Note (*): available only on PCIe cameras (xiX, xiB, xiT cameras.)
Default: XI_CNT_SEL_TRANSPORT_SKIPPED_FRAMES.
Usage:

xiSetParamInt(handle, XI_PRM_COUNTER_SELECTOR, XI_CNT_SEL_TRANSPORT_SKIPPED_FRAMES);

Note: Could be returned number of skipped frames on the transport layer, number of skipped frames on API layer, number of successfully transferred frames.

XI_PRM_COUNTER_VALUE or “counter_value”¶

Description: Returns value of selected (by XI_PRM_COUNTER_SELECTOR) frame counter.
Type: Integer.
Default: 0.

Usage:

int number_of_skipped_frames = 0;
xiSetParamInt(handle, XI_PRM_COUNTER_SELECTOR, XI_CNT_SEL_API_SKIPPED_FRAMES);
xiGetParamInt(handle, XI_PRM_COUNTER_VALUE, &number_of_skipped_frames);

Note: All counters are reset with the camera open, and counters XI_CNT_SEL_TRANSPORT_SKIPPED_FRAMES, XI_CNT_SEL_API_SKIPPED_FRAMES and XI_CNT_SEL_TRANSPORT_TRANSFERRED_FRAMES are also reset with acquisition start.

XI_PRM_OFFSET_X or “offsetX”¶

Description: Horizontal offset from the origin to the area of interest (in pixels). The sum of XI_PRM_OFFSET_X and XI_PRM_WIDTH must be equal or lower than the image resolution(width). Number must be divisible by the minimum increment which can be read out using the api parameter modifier XI_PRM_INFO_INCREMENT
Type: Integer.
Default: 0
Invalidators: XI_DOWNSAMPLING_TYPE, XI_PRM_DOWNSAMPLING
Usage:

xiSetParamInt(handle, XI_PRM_OFFSET_X, offset_x);

Note: Changing of this parameter will remove all images from buffer queue.

XI_PRM_OFFSET_Y or “offsetY”¶

Description: Vertical offset from the origin to the area of interest (in pixels). The sum of XI_PRM_OFFSET_Y and XI_PRM_HEIGHT must be equal or lower than the image resolution(height). Number must be divisible by the minimum increment which can be read out using the api parameter modifier XI_PRM_INFO_INCREMENT

Type: Integer.
Default: 0
Invalidators: XI_DOWNSAMPLING_TYPE, XI_PRM_DOWNSAMPLING
Usage:

xiSetParamInt(handle, XI_PRM_OFFSET_Y, offset_y);

Note: Changing of this parameter will remove all images from buffer queue.

XI_PRM_WIDTH or “width”¶

Description:

• If camera runs in single region mode: this parameter is width of the image provided by the device (in pixels). The sum of XI_PRM_OFFSET_X and XI_PRM_WIDTH must be equal or lower than the image resolution(width). Number must be divisible by the minimum increment which can be read out using the api parameter modifier XI_PRM_INFO_INCREMENT
• If camera runs in multiple region mode (XI_PRM_REGION_SELECTOR): this parameter is width of region currently selected (in pixels).
  Type: Integer.
  Default: Full resolution width.
  Invalidators: XI_DOWNSAMPLING_TYPE, XI_PRM_DOWNSAMPLING, XI_PRM_IMAGE_DATA_FORMAT, XI_PRM_OUTPUT_DATA_PACKING, XI_PRM_OUTPUT_DATA_BIT_DEPTH, XI_PRM_HEIGHT

Usage:

xiSetParamInt(handle, XI_PRM_WIDTH, image_width);

Note: Changing of this parameter will remove all images from buffer queue.

XI_PRM_HEIGHT or “height”¶

Description:

• If camera runs in single region mode: this parameter is height of the image provided by the device (in pixels). The sum of XI_PRM_OFFSET_Y and XI_PRM_HEIGHT must be equal or lower than the image resolution(height). Number must be divisible by the minimum increment which can be read out using the api parameter modifier XI_PRM_INFO_INCREMENT
• If camera runs in multiple region mode (XI_PRM_REGION_SELECTOR): this parameter is height of region currently selected.
  Type: Integer.
  Default: Full resolution height.
  Invalidators: XI_DOWNSAMPLING_TYPE, XI_PRM_DOWNSAMPLING, XI_PRM_REGION_SELECTOR, XI_PRM_IMAGE_DATA_FORMAT, XI_PRM_OUTPUT_DATA_PACKING, XI_PRM_OUTPUT_DATA_BIT_DEPTH, XI_PRM_WIDTH

Usage:

xiSetParamInt(handle, XI_PRM_HEIGHT, image_height);

Note 1: Changing of this parameter will remove all images from buffer queue.
Note 2: In case of using small ROI in combination with Fresco FL1100 controller, please read this article.

XI_PRM_REGION_SELECTOR or "region_selector"¶

Description: Selects Region in Multiple ROI. Parameters: XI_PRM_WIDTH, XI_PRM_HEIGHT, XI_PRM_OFFSET_X, XI_PRM_OFFSET_Y, XI_PRM_REGION_MODE are related to the particular region
Type: Integer.
Default: 0.
Invalidators: XI_DOWNSAMPLING_TYPE, XI_PRM_DOWNSAMPLING
Usage:

xiSetParamInt(handle, XI_PRM_REGION_SELECTOR , selector);

Note: width and offset_x could be changed only for Region 0
Note2: Regions has to be in order from top to bottom. Region N has to start after Region N-1 ends.

XI_PRM_REGION_MODE or "region_mode"¶

Description: Activates/deactivates Region selected by Region Selector in Multiple ROI.
Type: Integer.
Default: 1 for Region selector 0 and 0 for all other regions
Invalidators: XI_DOWNSAMPLING_TYPE, XI_PRM_DOWNSAMPLING
Usage:

xiSetParamInt(handle, XI_PRM_REGION_MODE , mode);

Note: Region 0 is always activated, it is not possible to deactivate it.

XI_PRM_HORIZONTAL_FLIP or "horizontal_flip"¶

Description: Activates horizontal flip if available in camera.
Type: Integer.
Default: 0 for disabled flipping
Usage:

xiSetParamInt(handle, XI_PRM_HORIZONTAL_FLIP , 1);  //enable horizontal flipping

XI_PRM_VERTICAL_FLIP or "vertical_flip"¶

Description: Activates vertical flip if available in camera.
Type: Integer.
Default: 0 for disabled flipping
Usage:

xiSetParamInt(handle, XI_PRM_VERTICAL_FLIP, 1);  //enable horizontal flipping

XI_PRM_LUT_EN or “LUTEnable”¶

Description: Activates Look-Up-Table (LUT).
Type: Integer.
Default: 0ff(0).

lut_state	operation
0	sensor pixels are transferred directly
1	sensor pixels are mapped through LUT

Usage:

xiSetParamInt(handle, XI_PRM_LUT_EN, lut_state);

Note: LUT parameters are valid only for some cameras. E.g. CURRERA-R and xiQ supports LUT. xiMU (MU9PM-MH) does NOT support it.
Note2: For xiQ cameras setting XI_PRM_LUT_EN also uploads previously set values in to camera. Values are latched in API.

XI_PRM_LUT_INDEX or “LUTIndex”¶

Description: Controls the index (offset) of the coefficient to access in the LUT.
Type: Integer.
Default: 0

Usage:

xiSetParamInt(handle, XI_PRM_LUT_INDEX, lut_index);

Note: Range of applicable indexes depends on sensor digitization bit depth (sensor_bit_depth). It could be obtained:

xiGetParamInt(handle, XI_PRM_LUT_INDEX XI_PRM_INFO_MIN, &minimum_lut_index);
xiGetParamInt(handle, XI_PRM_LUT_INDEX XI_PRM_INFO_MAX, &maximum_lut_index);

All xiQ cameras have LUT N-bit to N-bit, based on the sensor_bit_depth of the specific camera. All xiC/xiX/xiT cameras have LUT 12-bit to 12-bit. Currera-R features LUT N-bit to 8-bit.

XI_PRM_LUT_VALUE or “LUTValue”¶

Description: Defines value at entry LUTIndex of the LUT.
Type: Integer.
Default: 0

Usage:

xiSetParamInt(handle, XI_PRM_LUT_VALUE, lut_value_for_index);

Note: Range of applicable values depends on sensor digitization bit depth (sensor_bit_depth). It could be obtained:

xiGetParamInt(handle, XI_PRM_LUT_VALUE XI_PRM_INFO_MIN, &minimum_lut_value);
xiGetParamInt(handle, XI_PRM_LUT_VALUE XI_PRM_INFO_MAX, &maximum_lut_value);

All xiQ cameras have LUT N-bit to N-bit, based on the sensor_bit_depth of the specific camera. All xiC/xiX/xiT cameras have LUT 12-bit to 12-bit. Currera-R features LUT N-bit to 8-bit.
Note: For xiQ cameras setting values has no direct effect on image, only after setting XI_PRM_LUT_EN to value 1, will apply all changes to camera.

XI_PRM_TRG_SOURCE or “trigger_source”¶

Description: Defines source of trigger.
Type: Integer.
Default: TRG_OFF
Invalidators: XI_PRM_AVAILABLE_BANDWIDTH
Possible values:

trigger_source	Camera operation
XI_TRG_OFF	Capture of next image is automatically started after previous.
XI_TRG_EDGE_RISING	Capture is started on rising edge of selected input.
XI_TRG_EDGE_FALLING	Capture is started on falling edge of selected input.
XI_TRG_SOFTWARE	Capture is started with software trigger. See here.
XI_TRG_LEVEL_HIGH	Specifies that the trigger is considered valid as long as the level of the source signal is high.
XI_TRG_LEVEL_LOW	Specifies that the trigger is considered valid as long as the level of the source signal is low.

Usage:

xiSetParamInt(handle, XI_PRM_TRG_SOURCE, trigger_source);

Note: To set input as external trigger, XI_PRM_GPI_MODE of selected input should be set to XI_GPI_TRIGGER. See example at XI_PRM_GPI_MODE.

Example:

// enable trigger by software
xiSetParamInt(handle, XI_PRM_TRG_SOURCE, XI_TRG_SOFTWARE);
// start acquisition
xiStartAcquisition(handle);
int frames=5;
while (frames--)
{
  // trigger next image
  int trigger_retry=1000;
  while(--trigger_retry)
  {
    if (XI_OK == xiSetParamInt(handle, XI_PRM_TRG_SOFTWARE, 1))
      break;
    // on some cameras (CURRERA-R) the TRG software
    // returns error in case if it is too early
    // to start next exposure
    Sleep(1);
  }
  // get the image
  xiGetImage(handle, 1000, &image);
}

For more examples see xiAPI Camera Trigger and Synchronization Signals.

XI_PRM_TRG_SOFTWARE or “trigger_software”¶

Description: Generates an internal trigger. XI_PRM_TRG_SOURCE have be set to TRG_SOFTWARE.
Type: Integer.
Default: -

Usage:

xiSetParamInt(handle, XI_PRM_TRG_SOFTWARE, 0);

Note: In several models xiMU (MU9), xiQ, Currera R this is active even if XI_PRM_TRG_SOURCE is set to external signal.

XI_PRM_TRG_DELAY or "trigger_delay"¶

Description: When set delay time is inserted between camera trigger input and activating sensor integration. Delay time is set in us.
Type: Integer.
Default: 0us
Invalidators: XI_PRM_TRG_SELECTOR

Usage:

xiSetParamInt(handle, XI_PRM_TRG_SELECTOR , XI_TRG_SEL_FRAME_START);
xiSetParamInt(handle, XI_PRM_TRG_DELAY , 5000);  //5ms delay

Note: Setting of this parameter is applicable for selected cameras:

• xiX, xiB, xiT, xiC
• xiMU (MU9). Granularity of real delay duration depends on sensor settings (line read out time). Typical granularity is up to 100 microseconds. Maximum time is approx. 100ms for xiMU camera.

XI_PRM_AVAILABLE_BANDWIDTH "available_bandwidth"¶

Description: Calculate and return available interface bandwidth. Unit is Megabits (1000000) per sec.
Type: Integer.
Default: Maximum of given interface

Usage:

xiGetParamInt(handle, XI_PRM_AVAILABLE_BANDWIDTH, &interface_data_rate);

XI_PRM_LIMIT_BANDWIDTH "limit_bandwidth"¶

Description: Camera acquisition data-rate Limit on transport layer in Megabits (1000000) per second. API controls the camera clock or increases the line period ¹ in order to achieve the closest data-rate as the Limit value set, ensuring the data-rate is below the Limit. This parameter can be used to decrease data-rate e.g. when more cameras are connected to same interface to share same channel. In order to activate the limit - application should set also XI_PRM_LIMIT_BANDWIDTH_MODE = XI_ON, see example below.
Type: Integer.
Default: Maximum of given camera

Note ¹: Controlling method (clock or line period) depends on the camera model.

Usage:

xiSetParamInt(handle, XI_PRM_LIMIT_BANDWIDTH , datarate_in_Mbits_sec);

Example:

// get interface data rate
int interface_data_rate_mbps=2500;
// calculate datarate for each camera
#define CONNECTED_CAMERAS_TO_SAME_HUB 3
int camera_data_rate = interface_data_rate_mbps / CONNECTED_CAMERAS_TO_SAME_HUB;
#define MARGIN_MBitsPER_SECOND 300
camera_data_rate -= MARGIN_MBitsPER_SECOND;
// set data rate
xiSetParamInt(handle, XI_PRM_LIMIT_BANDWIDTH , camera_data_rate);
// enable the limiting
xiSetParamInt(handle, XI_PRM_LIMIT_BANDWIDTH_MODE , XI_ON);

See more at our application note about Multiple Cameras Setup

XI_PRM_LIMIT_BANDWIDTH_MODE "limit_bandwidth_mode"¶

Description: Controls if the XI_PRM_LIMIT_BANDWIDTH is active. When disabled, lower level specific features are expected to control the throughput. When enabled, XI_PRM_LIMIT_BANDWIDTH controls the overall throughput.*Type:* Integer.
Default: ON (after auto bandwidth measurement)

Usage:

xiSetParamInt(handle, XI_PRM_LIMIT_BANDWIDTH_MODE , XI_OFF);

Note: This parameter is not supported on MQ, MU, MD, MR camera families.

XI_PRM_SENSOR_TAPS "sensor_taps"¶

Description: Set/get the number of taps used on sensor.
Type: Integer.
Default: 1
Usage:

xiSetParamInt(handle, XI_PRM_SENSOR_TAPS ,number_of_taps);

XI_PRM_SENSOR_CLOCK_FREQ_HZ "sensor_clock_freq_hz"¶

Description: Set or return the sensor clock frequency. This clock is specific to sensor used. See documentation/application for the camera to use this parameter.
Type: Float.
Default: (depends on sensor)
Invalidators: XI_PRM_LIMIT_BANDWIDTH
Usage:

xiSetParamInt(handle, XI_PRM_SENSOR_CLOCK_FREQ_HZ, clock_freq);

XI_PRM_SENSOR_CLOCK_FREQ_INDEX "sensor_clock_freq_index"¶

Description: Sensor clock frequency. Selects frequency on cameras which supports only some specific frequencies.
Type: Int.
Default: (depends on sensor)
Invalidators: XI_PRM_LIMIT_BANDWIDTH
Usage:

xiSetParamInt(handle, XI_PRM_SENSOR_CLOCK_FREQ_INDEX, clock_id);

XI_PRM_SENSOR_OUTPUT_CHANNEL_COUNT "sensor_output_channel_count"¶

Description: Number of output channels from sensor used for data transfer.
Type: Int.
Default: (depends on sensor)
Invalidators:
Usage:

int count=0;
xiGetParamInt(handle, XI_PRM_SENSOR_OUTPUT_CHANNEL_COUNT, &count);

XI_PRM_SENSOR_DATA_BIT_DEPTH "sensor_bit_depth"¶

Description: Returns the bit depth of the pixel data received from sensor.
Type: Int.
Default: (depends on sensor)
Invalidators: XI_PRM_IMAGE_DATA_FORMAT

Usage:

xiGetParamInt(handle,XI_PRM_SENSOR_DATA_BIT_DEPTH ,&sensor_bit_depth);

Read more at XiAPI Image Data Flow.

XI_PRM_OUTPUT_DATA_BIT_DEPTH "output_bit_depth"¶

Description: The bit depth of the output data from camera (=transport layer).
Type: Int.
Default: (depends on camera and sensor)
Invalidators: XI_PRM_IMAGE_DATA_FORMAT

Usage:

xiGetParamInt(handle,XI_PRM_OUTPUT_DATA_BIT_DEPTH ,&sensor_bit_depth);

Read more at XiAPI Image Data Flow.

XI_PRM_IMAGE_DATA_BIT_DEPTH "image_data_bit_depth"¶

Description: The bit depth of the pixel data returned by function xiGetImage. If MONO16 or RAW16 image formats are used this parameter defines the alignment of the data on the xiGetImage.
Type: Int.
Default: (depends on sensor)
Invalidators: XI_PRM_IMAGE_DATA_FORMAT, XI_PRM_OUTPUT_DATA_BIT_DEPTH

Usage:

xiGetParamInt(handle,XI_PRM_IMAGE_DATA_BIT_DEPTH ,&image_data_bit_depth);

XI_PRM_OUTPUT_DATA_PACKING "output_bit_packing"¶

Description: This feature enables bit packing on transport data layer, thus increasing the maximum frame rate when data with 10 or 12 bits per pixel is transported. For more info please see Transport Data Packing feature description.

Type: Int.
Default: XI_OFF
Invalidators: XI_PRM_IMAGE_DATA_FORMAT, XI_PRM_OUTPUT_DATA_BIT_DEPTH
Usage:

xiSetParamInt(handle,XI_PRM_OUTPUT_DATA_PACKING,XI_ON);

Read more at XiAPI Image Data Flow.

XI_PRM_OUTPUT_DATA_PACKING_TYPE "output_bit_packing_type"¶

Description: This feature chooses output data packing type(ximea grouping 10g160, 12g192, 14g224), PFNC packing 10p, 12p...). For more info please see Transport Data Packing feature description.

Type: Int.
Default: XI_DATA_PACK_XI_GROUPING
Invalidators: XI_PRM_IMAGE_DATA_FORMAT, XI_PRM_OUTPUT_DATA_BIT_DEPTH
Usage:

xiSetParamInt(handle,XI_PRM_OUTPUT_DATA_PACKING_TYPE,XI_DATA_PACK_XI_GROUPING);

XI_PRM_ACQ_TIMING_MODE "acq_timing_mode"¶

Description: This parameter defines the acquisition timing mode.
Type: Int.
Default: XI_ACQ_TIMING_MODE_FREE_RUN
Possible Values:

Values	Description
XI_ACQ_TIMING_MODE_FREE_RUN	camera acquires images at a maximum possible framerate
XI_ACQ_TIMING_MODE_FRAME_RATE	please refer to our Frame Rate Control support page
XI_ACQ_TIMING_MODE_FRAME_RATE_LIMIT	please refer to our Frame Rate Control support page

Usage:

xiSetParamInt(handle,XI_PRM_ACQ_TIMING_MODE,XI_ACQ_TIMING_MODE_FRAME_RATE);

XI_PRM_TRG_SELECTOR "trigger_selector"¶

Description: This parameter selects the type of trigger .
Type: Int.
Default: XI_TRG_SEL_FRAME_START
Possible Values:

Values	Description
XI_TRG_SEL_FRAME_START	the trigger defines the start of the frame exposure
XI_TRG_SEL_EXPOSURE_ACTIVE	the trigger controls the start and length of the exposure. Please refer to our Exposure Defined by Trigger Pulse Length support page
XI_TRG_SEL_FRAME_BURST_START	please refer to our Frame Burst Modes support page
XI_TRG_SEL_FRAME_BURST_ACTIVE	please refer to our Frame Burst Modes support page
XI_TRG_SEL_EXPOSURE_START	the trigger controls the start of the exposure. Please refer to our Multiple exposures in one frame support page
XI_TRG_SEL_MULTI_SLOPE_PHASE_CHANGE	the trigger controls the multi slope phase in one Frame (phase0 -> phase1) or (phase1 -> phase2)

Usage:

xiSetParamInt(handle,XI_PRM_TRG_SELECTOR,XI_TRG_SEL_EXPOSURE_ACTIVE);

XI_PRM_TRG_OVERLAP "trigger_overlap"¶

Description: This parameter selects the type of trigger overlap.
Type: Int.
Default: XI_TRG_OVERLAP_PREV_FRAME
Possible Values:

Value	Description
XI_TRG_OVERLAP_OFF	No trigger overlap is permitted. If camera is in read-out phase, all triggers are rejected.
XI_TRG_OVERLAP_READ_OUT	Trigger is accepted only when sensor is ready to start next exposure with defined exposure time. Trigger is rejected when sensor is not ready for new exposure with defined exposure time. Note: This mode is planned and not yet supported by cameras.
XI_TRG_OVERLAP_PREV_FRAME	Trigger is accepted by camera any time. If sensor is not ready for the next exposure – the trigger is latched and sensor starts exposure as soon as exposure can be started with defined exposure time.

Usage:

xiSetParamInt(handle,XI_PRM_TRG_OVERLAP,XI_TRG_OVERLAP_OFF);

XI_PRM_ACQ_FRAME_BURST_COUNT "acq_frame_burst_count"¶

Description: Sets the number of frames to be acquired after trigger pulse has been sent to the camera. This setting is valid only if the trigger selector is set to FrameBurstStart. For more info please refer to our Frame Burst Modes support page. If burst count is set to zero (0) then number of acquired frames will not be limited (=endless).
Type: Int.
Default: 1

Usage:

xiSetParamInt(handle,XI_PRM_ACQ_FRAME_BURST_COUNT,3);

XI_PRM_TIMESTAMP "timestamp"¶

Description: Reads the current timestamp value from camera in nanoseconds.

Type: Int64.
Default: -

Usage:

uint64_t time_stamp = 0;
DWORD size = sizeof(uint64_t);
XI_PRM_TYPE type = xiTypeInteger64;
xiGetParam(xiH, XI_PRM_TIMESTAMP, &time_stamp, &size, &type);

XI_PRM_IMAGE_USER_DATA "image_user_data"¶

Description: Sets the user data (32bit number) into camera. The following frame captured by camera will have this number stored at image header. The number is accessible later after xiGetImage in XI_IMG structure as image_user_data.
Type: Int.
Default: 0
Cameras supported: xiB, xiT

Usage:

uint32_t data=7;
xiSetParamInt(handle,XI_PRM_IMAGE_USER_DATA,data);
xiGetImage(handle,5000,&image);
printf("Image captured has user_data:%d\n",image.image_user_data);

Color management settings¶

Note: Works only for color cameras.

XI_PRM_WB_KR or “wb_kr”¶

Description: White balance red coefficient.
Type: Float.
Default: 1.0

Usage:

xiSetParamFloat(handle, XI_PRM_WB_KR, wb_coef);

XI_PRM_WB_KG or “wb_kg”¶

Description: White balance green coefficient.
Type: Float.
Default: 1.0

Usage:

xiSetParamFloat(handle, XI_PRM_WB_KG, wb_coef);

XI_PRM_WB_KB or “wb_kb”¶

Description: White balance blue coefficient.
Type: Float.
Default: 1.0

Usage:

xiSetParamFloat(handle, XI_PRM_WB_KB, wb_coef);

XI_PRM_MANUAL_WB or “manual_wb”¶

Description: Manual white balance. Takes white balance from square in image center of next image received by xiGetImage. Square have 1/8th of width and height of image. The function expects white sheet of paper exposed to 50% of values (RGB values should be around 128). As result of setting of manual_wb three parameters are changed: "wb_kb", "wb_kg" and "wb_kr". User application can store them and recall when needed to set the white balance back.

Type: Integer.
Default: -
Usage:

// now camera should see the white color in approximately 50% of level
xiSetParamInt(handle, XI_PRM_MANUAL_WB, 1);
xiGetImage(handle, 1000, &image); // now API automatically calculates the white balance
xiGetImage(handle, 1000, &image); // this and next images will have corrected white balance

XI_PRM_AUTO_WB or “auto_wb”¶

Description: Automatic white balance.
Type: Integer.
Default: 0 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_AUTO_WB, 1);

XI_PRM_WB_ROI_OFFSET_X or “wb_roi_offset_x”¶

Description: X offset of the area used for manual WB calculation. The sum of XI_PRM_WB_ROI_OFFSET_X and XI_PRM_WB_ROI_WIDTH must be equal or lower than the image resolution(width). Supported by MC,CB,MX cameras.
Type: Int.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_WB_ROI_OFFSET_X,40);

XI_PRM_WB_ROI_OFFSET_Y or “wb_roi_offset_y”¶

Description: Y offset of the area used for manual WB calculation. The sum of XI_PRM_WB_ROI_OFFSET_Y and XI_PRM_WB_ROI_HEIGHT must be equal or lower than the image resolution(height). Supported by MC,CB,MX cameras.
Type: Int.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_WB_ROI_OFFSET_Y,40);

XI_PRM_WB_ROI_WIDTH or “wb_roi_width”¶

Description: width of the area used for manual WB calculation. The sum of XI_PRM_WB_ROI_OFFSET_X and XI_PRM_WB_ROI_WIDTH must be equal or lower than the image resolution(width). Supported by MC,CB,MX cameras.
Type: Int.
Default: depends on the sensors resolution and downsampling
Usage:

xiSetParamInt(handle, XI_PRM_WB_ROI_WIDTH,400);

XI_PRM_WB_ROI_HEIGHT or “wb_roi_height”¶

Description: width of the area used for manual WB calculation. The sum of XI_PRM_WB_ROI_OFFSET_Y and XI_PRM_WB_ROI_HEIGHT must be equal or lower than the image resolution(height). Supported by MC,CB,MX cameras.
Type: Int.
Default: depends on the sensors resolution and downsampling
Usage:

xiSetParamInt(handle, XI_PRM_WB_ROI_HEIGHT,400);

XI_PRM_GAMMAY or “gammaY”¶

Description: Luminosity gamma.
Range: 0.3 (highest correction); 1 (no correction)
Type: Float.
Default: 0.47

Usage:

xiSetParamFloat(handle, XI_PRM_GAMMAY, gammaY);

Note: Works also for XI_MONO* formats, but only for color cameras.

XI_PRM_GAMMAC or “gammaC”¶

Description: Chromaticity gamma.
Type: Float.
Default: 0.8

Usage:

xiSetParamFloat(handle, XI_PRM_GAMMAC, gammaC);

XI_PRM_SHARPNESS or “sharpness”¶

Description: Sharpness Strength. The range is -4 (less sharp) to +4 (more sharp).
Type: Float.
Default: 0.0 (neutral)

Usage:

xiSetParamFloat(handle, XI_PRM_SHARPNESS, sharpness_level);

Note: Works also for XI_MONO* formats, but only for color cameras.

XI_PRM_CC_MATRIX_00 or “ccMTX00”¶

XI_PRM_CC_MATRIX_01 or “ccMTX01”¶

XI_PRM_CC_MATRIX_02 or “ccMTX02”¶

XI_PRM_CC_MATRIX_03 or “ccMTX03”¶

XI_PRM_CC_MATRIX_10 or “ccMTX10”¶

XI_PRM_CC_MATRIX_11 or “ccMTX11”¶

XI_PRM_CC_MATRIX_12 or “ccMTX12”¶

XI_PRM_CC_MATRIX_13 or “ccMTX13”¶

XI_PRM_CC_MATRIX_20 or “ccMTX20”¶

XI_PRM_CC_MATRIX_21 or “ccMTX21”¶

XI_PRM_CC_MATRIX_22 or “ccMTX22”¶

XI_PRM_CC_MATRIX_23 or “ccMTX23”¶

XI_PRM_CC_MATRIX_30 or “ccMTX30”¶

XI_PRM_CC_MATRIX_31 or “ccMTX31”¶

XI_PRM_CC_MATRIX_32 or “ccMTX32”¶

XI_PRM_CC_MATRIX_33 or “ccMTX33”¶

Description: Color Correction Matrix elements.
Type: Float.
Default:

coefficients					default values
M_00	M_01	M_02	M_03	=	1.0	0.0	0.0	0.0
M_10	M_11	M_12	M_13	=	0.0	1.0	0.0	0.0
M_20	M_21	M_22	M_23	=	0.0	0.0	1.0	0.0
M_30	M_31	M_32	M_33	=	0.0	0.0	1.0	0.0

Usage:

xiSetParamFloat(handle, XI_PRM_CC_MATRIX_00, float);

XI_PRM_DEFAULT_CC_MATRIX or “defccMTX”¶

Description: Set default Color Correction Matrix.
Type: -.
Default: -

Usage:

xiSetParamFloat(handle, XI_PRM_DEFAULT_CC_MATRIX, 0);

XI_PRM_IMAGE_IS_COLOR or “iscolor”¶

Description: Returns 1 for color cameras.

Type: Integer.
Default: By default -.

Usage:

xiGetParam(handle, XI_PRM_IMAGE_IS_COLOR or "iscolor", &iscolor, sizeof(int), xiTypeInteger);
int xiGetParamInt(handle, XI_PRM_IMAGE_IS_COLOR, &iscolor);

XI_PRM_COLOR_FILTER_ARRAY or "cfa"¶

Description: Returns color filter array type of RAW data.

Type: Integer - Read only.
Values:

value	note
XI_CFA_NONE	Result pixels have no filters applied in this format
XI_CFA_BAYER_RGGB
XI_CFA_CMYG
XI_CFA_RGR
XI_CFA_BAYER_BGGR
XI_CFA_BAYER_GRBG
XI_CFA_BAYER_GBRG

Usage:

xiGetParamInt(handle, XI_PRM_COLOR_FILTER_ARRAY, &cfa);

XI_PRM_CMS or "cms"¶

Description: Enable or disable color management.

Type: Integer.
Default:XI_CMS_DIS
Possible Values:

value	note
XI_CMS_DIS	disables color management
XI_CMS_EN	enables color management (high CPU usage)
XI_CMS_EN_FAST	enables fast color management (high RAM usage)

Usage:

xiSetParamInt(handle, XI_PRM_CMS, XI_CMS_EN);

Note: This feature is in Beta stage.

XI_PRM_CMS_INTENT or "cms_intent"¶

Description: Defines rendering intents.

Type: Integer.
Default:XI_CMS_INTENT
Possible Values:

value	note
XI_CMS_INTENT_PERCEPTUAL
XI_CMS_INTENT_RELATIVE_COLORIMETRIC
XI_CMS_INTENT_SATURATION
XI_CMS_INTENT_ABSOLUTE_COLORIMETRIC

Absolute colorimetric
Absolute colorimetry and relative colorimetry actually use the same table but differ in the adjustment for the white point media. If the output device has a much larger gamut than the source profile, i.e., all the colors in the source can be represented in the output, using the absolute colorimetry rendering intent would "ideally" (ignoring noise, precision, etc.) give an exact output of the specified CIELAB values. Perceptually, the colors may appear incorrect, but instrument measurements of the resulting output would match the source. Colors outside of the proof print system's possible color are mapped to the boundary of the color gamut. Absolute colorimetry is useful to get an exact specified color (e.g., IBM blue), or to quantify the accuracy of mapping methods.

Relative colorimetric
The goal in relative colorimetry is to be truthful to the specified color, with only a correction for the media. Relative colorimetry is useful in proofing applications, since you are using it to get an idea of how a print on one device will appear on a different device. Media differences are the only thing you really would like to adjust for. Obviously there has to be some gamut mapping going on also. Usually this is done in a way where hue and lightness are maintained at the cost of reduced saturation. Relative colorimetric is the default rendering intent on most systems.

Perceptual and Saturation
The perceptual and saturation intents are where the results really depend upon the profile maker. This is even how some of the competitors in this market differentiate themselves. These intents should be created by the profile maker so that pleasing images occur with the perceptual intent while eye-catching business graphics occur with the saturation intent. This is achieved through the use of different perceptual remaps of the data as well as different gamut mapping methods. Perceptual rendering is recommended for color separation.

In practice, photographers almost always use relative or perceptual intent, as for natural images, absolute causes color cast, while saturation produces unnatural colors.[6] Relative intent handles out-of-gamut by clipping (burning) these colors to the edge of the gamut, leaving in-gamut colors unchanged, while perceptual intent smoothly moves out-of-gamut colors into gamut, preserving gradations, but distorts in-gamut colors in the process. If an entire image is in-gamut, relative is perfect, but when there are out of gamut colors, which is more preferable depends on a case-by-case basis.

Saturation intent is most useful in charts and diagrams, where there is a discrete palette of colors that the designer wants saturated to make them intense, but where specific hue is less important.

Usage:

xiSetParamInt(handle, XI_PRM_CMS_INTENT, XI_CMS_INTENT_PERCEPTUAL);

Note: This feature is in Beta stage.

XI_PRM_APPLY_CMS or "apply_cms"¶

Description: If set to XI_ON applies CMS profile to xiGetImage.

Type: Integer.
Default:XI_OFF
Possible Values:

Usage:

xiSetParamInt(handle, XI_PRM_APPLY_CMS, XI_ON);

XI_PRM_INPUT_CMS_PROFILE or "input_cms_profile"¶

Description: Filename of the input cms profile (e.g. input.icc)

Type: String.
Default:Default device profile.

Usage:

xiSetParamString(h,XI_PRM_INPUT_CMS_PROFILE,"C:\\ICC\\custom_in.icc",(DWORD) strlen("C:\\ICC\\custom_in.icc"));

XI_PRM_OUTPUT_CMS_PROFILE or "output_cms_profile"¶

Description: Filename of the output cms profile (e.g. output.icc)

Type: String.
Default:(sRGB profile).

Usage:

xiSetParamString(h,XI_PRM_INPUT_CMS_PROFILE,"C:\\ICC\\custom_out.icc",(DWORD) strlen("C:\\ICC\\custom_out.icc"));

Device IO parameters.¶

XI_PRM_GPI_SELECTOR or “gpi_selector”¶

Description: Selects GPI.
Type: Integer.
Default: 1

Usage:

xiSetParamInt(handle, XI_PRM_GPI_SELECTOR, gpi_index);

Example: See XI_PRM_GPI_LEVEL

On each camera family or model the relation of gpi_index and physical pin differs. Following table list the camera families and gpi_index relations.

Families: xiQ/MQ

gpi_index	physical pin on the camera
1	1 (IN1 - optical)

Models: xiC/MC

gpi_index	physical pin on the camera
1	5 (IN1 - optical)
2	8 (INOUT1)
3	2 (INOUT2)

Models: MXxxxxx-xx-X2G2 (X2G2 version)

gpi_index	physical pin on the camera
1	22 (IN1 - optical)
2	20 (INOUT1)
3	21 (INOUT2)

Models: MXxxxxx-xx-X4G2 (X4G2 version)

gpi_index	physical pin on the camera
1	2 (IN1 - optical)
2	4 (IN2 - optical)
3	6 (INOUT1)
4	7 (INOUT2)
5	45 (INOUT3)
6	46 (INOUT4)

Models: CBxxxxx-xx (X4G2 version)

gpi_index	physical pin on the camera
1	3 (IN1 - optical)
2	4 (IN2 - optical)
3	6 (INOUT1)
4	7 (INOUT2)
5	11 (INOUT3)
6	12 (INOUT4)

Models: CBxxxxx-xx-X8G3 (X8G3 version)

gpi_index	physical pin on the camera
1	2 (IN1 - optical)
2	1 (IN2 - optical)
3	7 (INOUT1)
4	9 (INOUT2)
5	8 (INOUT3)
6	12 (INOUT4)

Models: MX377-MTP (X4G3 version)

gpi_index	physical pin on the camera
1	8 (IN1 - optical)
2	13 (IN2 - optical)
3	2 (INOUT1)
4	3 (INOUT2)
5	4 (INOUT3)
6	5 (INOUT4)
7	12 (INOUT5)
8	14 (INOUT6)
9	9 (INOUT7)
10	7 (INOUT8)

XI_PRM_GPI_MODE or “gpi_mode”¶

Description: Defines GPI functionality.
Type: Integer.
Default: XI_GPI_OFF
Possible values:

value	meaning
XI_GPI_OFF	Input is not used for triggering, but can be used to get XI_PRM_GPI_LEVEL. This can be used to switch I/O line on some cameras to input mode.
XI_GPI_TRIGGER	Input can be used for triggering
XI_GPI_EXT_EVENT	External signal input (not implemented)

Usage:

xiSetParamInt(handle, XI_PRM_GPI_MODE, XI_GPI_TRIGGER);

Note: To use GPI as trigger source, the XI_PRM_TRG_SOURCE should be also set to XI_TRG_EDGE_RISING or XI_TRG_EDGE_FALLING

Example:

// select digital input (for xiQ=1, for xiC=1 or 2)
int input_id = 1;
xiSetParamInt(handle, XI_PRM_GPI_SELECTOR,  input_id);
// set input as frame trigger
xiSetParamInt(handle, XI_PRM_GPI_MODE, XI_GPI_TRIGGER);
// enable triggering of image from digital input
xiSetParamInt(handle, XI_PRM_TRG_SOURCE, XI_TRG_EDGE_RISING);

Note: On CURRERA-R it is possible to test inputs using button connected to BOB144

XI_PRM_GPI_LEVEL or “gpi_level”¶

Description: Level of digital input selected by XI_PRM_GPI_SELECTOR.
Type: Integer.
Default: -
Note: When used on pin that could be input or output (E.g. pin 8 on MC023 camera), then associated GPO needs to be in mode XI_GPO_HIGH_IMPEDANCE. Otherwise pin can be pulled down (GPO_OFF) or up (GPO_ON). Such pins are HIGH_IMPEDANCE as default so application does not to setup it when used only as input.

Usage:

xiGetParamInt(handle, XI_PRM_GPI_LEVEL, &gpi_level);

Example:

// select digital input (different mapping to physical pin on each model, see table below)
int gpi_index = 1;
xiSetParamInt(handle, XI_PRM_GPI_SELECTOR,  gpi_index);
// get input level
int gpi_level = 0;
xiGetParamInt(handle, XI_PRM_GPI_LEVEL,  &gpi_level);
printf("Level on digital input %d is %d\n", gpi_index, gpi_level);

XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_START or gpi_level_at_image_exp_start¶

Description: Level of digital input selected by XI_PRM_GPI_SELECTOR sampled at exposure start of the last image received by xiGetImage.
Type: Integer.
Default: -

Usage:

xiGetParamInt(handle, XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_START, &gpi_level_at_image_exp_start);

Example:

if (XI_OK == xiGetImage(xiH, 5000, &image))
{
  int level_input_1_at_exp_start = 0;
  xiSetParamInt(xiH, XI_PRM_GPI_SELECTOR, 1);
  xiGetParamInt(xiH,XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_START, &level_input_1_at_exp_start);
}

XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_END or gpi_level_at_image_exp_end¶

Description: Level of digital input selected by XI_PRM_GPI_SELECTOR sampled at exposure end of the last image received by xiGetImage.
Type: Integer.
Default: -

Usage:

xiGetParamInt(handle, XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_END, &gpi_level_at_image_exp_end);

Example:

if (XI_OK == xiGetImage(xiH, 5000, &image))
{
  int level_input_2_at_exp_end = 0;
  xiSetParamInt(xiH, XI_PRM_GPI_SELECTOR, 2);
  xiGetParamInt(xiH, XI_PRM_GPI_LEVEL_AT_IMAGE_EXP_END, &level_input_2_at_exp_end);
}

XI_PRM_GPO_SELECTOR or “gpo_selector”¶

Description: Selects GPO.
Type: Integer.
Default: 1

Usage:

xiSetParamInt(handle, XI_PRM_GPO_SELECTOR, gpo_index);

Example: See XI_PRM_GPO_MODE

On each camera family or model the relation of gpo_index and physical pin differs. Following table list the camera families and gpi_index relations.

Families: xiQ/MQ

gpo_index	physical pin on the camera
1	2 (OUT1 - optical)

Models: MC023,MT023,MC031,MT031,MC050,MT050,MC089,MT089,MC124,MT124

gpo_index	physical pin on the camera
1	3 (OUT1 - optical)
2	8 (INOUT1)
3	2 (INOUT2)

Models: MX023,MX031,MX050,MX089,MX124

gpo_index	physical pin on the camera
1	24 (OUT1 - optical)
2	20 (INOUT1)
3	21 (INOUT2)

Models: MX120,MX200,MX500

gpo_index	physical pin on the camera
1	50 (OUT1 - optical)
2	48 (OUT2 - optical)
3	6 (INOUT1)
4	7 (INOUT2)
5	45 (INOUT3)
6	46 (INOUT4)

Models: CB120,CB200,CB500

gpo_index	physical pin on the camera
1	8 (OUT1 - optical)
2	9 (OUT2 - optical)
3	6 (INOUT1)
4	7 (INOUT2)
5	11 (INOUT3)
6	12 (INOUT4)

Models: CB120-X8G3

gpo_index	physical pin on the camera
1	4 (OUT1 - optical)
2	3 (OUT2 - optical)
3	7 (INOUT1)
4	9 (INOUT2)
5	8 (INOUT3)
6	12 (INOUT4)

Models: MX377-MTP (X4G3 version)

gpo_index	physical pin on the camera
1	19 (OUT1 - optical)
2	17 (OUT2 - optical)
3	2 (INOUT1)
4	3 (INOUT2)
5	4 (INOUT3)
6	5 (INOUT4)
7	12 (INOUT5)
8	14 (INOUT6)
9	9 (INOUT7)
10	7 (INOUT8)

XI_PRM_GPO_MODE or “gpo_mode”¶

Description: Defines GPO functionality.
Type: Integer.
Default: XI_GPO_OFF (or XI_GPO_HIGH_IMPEDANCE when INOUTx pin is selected)
Possible values:

value	meaning
XI_GPO_OFF**	Output is off (zero voltage or switched_off)
XI_GPO_ON**	Output is on (voltage or switched_on)
XI_GPO_FRAME_ACTIVE*	Output is on while frame exposure,read,transfer
XI_GPO_FRAME_ACTIVE_NEG*	Output is off while frame exposure,read,transfer
XI_GPO_EXPOSURE_ACTIVE*	Output is on while frame exposure
XI_GPO_EXPOSURE_ACTIVE_NEG*	Output is off while frame exposure
XI_GPO_FRAME_TRIGGER_WAIT*	Output is on while camera is ready for trigger
XI_GPO_FRAME_TRIGGER_WAIT_NEG*	Output is off while camera is ready for trigger
XI_GPO_EXPOSURE_PULSE***	Output is on short pulse at the beginning of frame exposure
XI_GPO_EXPOSURE_PULSE_NEG***	Output is off short pulse at the beginning of frame exposure
XI_GPO_BUSY	Output is on when camera has received trigger until end of transfer
XI_GPO_BUSY_NEG	Output is off when camera has received trigger until end of transfer
XI_GPO_HIGH_IMPEDANCE	Associated pin is in high impedance (tri-stated) and can be driven externally. E.g. for triggering or reading status by GPI_LEVEL.

*Note1: On some camera models (MR, MH): Modes FRAME_ACTIVE or EXPOSURE_ACTIVE are supported only if XI_PRM_TRG_SOURCE is set to XI_TRG_SOFTWARE or XI_TRG_EDGE_RISING or XI_TRG_EDGE_FALLING. See section TriggerSource
On models xiMU (MU9), xiQ, CURRERA-R the XI_GPO_EXPOSURE_ACTIVE can be used when XI_PRM_TRG_SOURCE is OFF (Live mode).

**Note2: Some camera families (e.g. MR) does not support the software control of outputs. Only one of mode: FRAME_ACTIVE and EXPOSURE_ACTIVE can be set.

***Note3: Duration of pulse depends on camera model and polarity of signal.

****Note4: Each bidirectional line has only one control for inverter (as in GenICam-SFNC). If output mode with _NEG extension is set then also input signal becomes inverted.

Usage:

xiSetParamInt(handle, XI_PRM_GPO_MODE, XI_GPO_ON);

Example:

// select digital output (on CURRERA-R 1-4)
xiSetParamInt(handle, XI_PRM_GPO_SELECTOR, 1);
// make output on (one)
xiSetParamInt(handle, XI_PRM_GPO_MODE,  XI_GPO_ON);
Sleep(1000); // wait to see the output is on (e.g. LED)
// make output off
xiSetParamInt(handle, XI_PRM_GPO_MODE,  XI_GPO_OFF);

Note: On CURRERA-R it is possible to test output state using LED connected to BOB144

XI_PRM_LED_SELECTOR or “led_selector”¶

Description: Selects LED.
Type: Integer.
Default: 1

Usage:

xiSetParamInt(handle, XI_PRM_LED_SELECTOR, 1);

XI_PRM_LED_MODE or “led_mode”¶

Description: Defines LED functionality.
Type: Integer.
Default: -
Possible values:

value	meaning
XI_LED_HEARTBEAT	Set led to blink (1 Hz) if link is OK.
XI_LED_TRIGGER_ACTIVE	Set led to blink if trigger detected.
XI_LED_EXT_EVENT_ACTIVE	Set led to blink if external signal detected.
XI_LED_ACQUISITION	Set led to blink if data streaming.
XI_LED_EXPOSURE_ACTIVE	Set led to blink if sensor integration time.
XI_LED_FRAME_ACTIVE	Set led to blink if device busy/not busy.
XI_LED_LINK	Set led to blink if link is ok.
XI_LED_OFF	Set led to off.
XI_LED_ON	Set led to on.

Usage:

xiSetParamInt(handle, XI_PRM_LED_MODE, XI_LED_TRIGGER_ACTIVE);

XI_PRM_TS_RST_SOURCE “ts_rst_source”¶

Description: Defines source for time stamp reset engine as well as the polarity active signal. Engine is edge sensitive.
Type: Integer.
Default: XI_TS_RST_OFF
Possible values:

value	meaning
XI_TS_RST_OFF	No source selected time stamp reset is not armed
XI_TS_RST_SRC_GPI_1	GPI1 rising edge is active (signal after de-bounce module)
XI_TS_RST_SRC_GPI_2	GPI2 rising edge is active
XI_TS_RST_SRC_GPI_3	GPI3 rising edge is active
XI_TS_RST_SRC_GPI_4	GPI4 rising edge is active
XI_TS_RST_SRC_GPI_5	GPI5 rising edge is active
XI_TS_RST_SRC_GPI_6	GPI6 rising edge is active
XI_TS_RST_SRC_GPI_1_INV	GPI1 falling edge is active
XI_TS_RST_SRC_GPI_2_INV	GPI2 falling edge is active
XI_TS_RST_SRC_GPI_3_INV	GPI3 falling edge is active
XI_TS_RST_SRC_GPI_4_INV	GPI4 falling edge is active
XI_TS_RST_SRC_GPI_5_INV	GPI5 falling edge is active
XI_TS_RST_SRC_GPI_6_INV	GPI6 falling edge is active
XI_TS_RST_SRC_TRIGGER	TRIGGER to sensor rising edge is active
XI_TS_RST_SRC_TRIGGER_INV	TRIGGER to sensor falling edge is active
XI_TS_RST_SRC_SW	time stamp is reset by software take effect imminently
XI_TS_RST_SRC_EXPACTIVE	Exposure Active signal rising edge
XI_TS_RST_SRC_EXPACTIVE_INV	Exposure Active signal falling edge
XI_TS_RST_SRC_FVAL	Frame valid signal rising edge (internal signal in camera)
XI_TS_RST_SRC_FVAL_INV	Frame valid signal falling edge (internal signal in camera)

Note: Number of active GPI or GPO depends on camera model

Usage:

xiSetParamInt(handle, XI_PRM_TS_RST_MODE , XI_TS_RST_ARM_ONCE);
xiSetParamInt(handle, XI_PRM_TS_RST_SOURCE , XI_TS_RST_SRC_TRIGGER);

XI_PRM_TS_RST_MODE “ts_rst_mode”¶

Description: Defines way time stamp reset engine is armed.
Type: Integer.
Default: XI_TS_RST_ARM_ONCE
Possible values:

value	meaning
XI_TS_RST_ARM_ONCE	Engine is disabled after time stamp has been reset after selected event.
XI_TS_RST_ARM_PERSIST	Engine is armed permanently so each selected event will trigger time stamp reset.

Usage:

xiSetParamInt(handle, XI_PRM_TS_RST_MODE , XI_TS_RST_ARM_ONCE);
xiSetParamInt(handle, XI_PRM_TS_RST_SOURCE , XI_TS_RST_SRC_TRIGGER);

Extended Device Parameters.¶

XI_PRM_ACQ_BUFFER_SIZE or “acq_buffer_size”¶

Description: Defines the size of the acquisition buffer in bytes(see Image below). This is a circle buffer which contains image data from sensor. This parameter can be set only when acquisition is stopped.
Type: Integer.
Defaults: Depends on camera family:

Camera Family	Default
MQ,MD,MU9,MJ	128MiB
CB,MX,MT,MC,MU1	512MiB

Usage:

xiSetParamInt(handle, XI_PRM_ACQ_BUFFER_SIZE, buf_size_bytes);

Example:

• Application sets buffer size to 70MB (on CURRERA-R)
  

  xiSetParamInt(handle, XI_PRM_ACQ_BUFFER_SIZE, 70*1000*1000)
  

• Sensor gives 1MB of data per image @ 10 frames/second
• Application retrieves image data by xiGetImage
• Application has access to the frame at most 7 seconds (70MB/(1MB*10fps))

Note: If the processing of this image takes more time than these 7seconds, the image data will be automatically overwritten with new image data due to the circular character of the buffer.
Note2: The maximal value for this parameter is 2147483647 because it uses the signed integer.

XI_PRM_ACQ_BUFFER_SIZE_UNIT or "acq_buffer_size_unit"¶

Description: Acquisition buffer size unit. Default 1. E.g. Value 1024 means that buffer_size is in KiBytes.

Type: Integer.
Default: 1
Usage:

// set unit to 1 MiB
xiSetParamInt(handle, XI_PRM_ACQ_BUFFER_SIZE_UNIT, 1024*1024);
// set buffer size to 200 MiB
xiSetParamInt(handle, XI_PRM_ACQ_BUFFER_SIZE, 200);

XI_PRM_ACQ_TRANSPORT_BUFFER_SIZE or "acq_transport_buffer_size"¶

Description: Size of one transport buffer in bytes. Frame/Field can contain multiple transport buffers. To decrease CPU load and increase system performance on committing transport buffers to kernel driver, transport buffer size has to be as high as possible. However in case of small Frame/Field size and high framerates it is necessary to decrease transport buffer size and increase queue of Frame/Field buffers(XI_PRM_BUFFERS_QUEUE_SIZE). Check out How to optimize software performance on high frame rates for more info.
Type: Integer.
Default: Value compatible for all tested controllers.
Note: Whole range minimum to maximum is not guaranteed on all tested configurations. Please be aware of possible issues on some controllers.

Usage:

xiSetParamInt(handle, XI_PRM_ACQ_TRANSPORT_BUFFER_SIZE, size_in_bytes);

Example:

• Application set transport buffer size to 128KiB for small (80KB images)
  

  xiSetParamInt(handle, XI_PRM_ACQ_TRANSPORT_BUFFER_SIZE, 128*1024);
  

XI_PRM_ACQ_TRANSPORT_PACKET_SIZE or "acq_transport_packet_size"¶

Description: Acquisition transport packet size in bytes.
Type: Integer.
Default: by interface
Usage:

// Get packet size
xiGetParamInt(handle, XI_PRM_ACQ_TRANSPORT_PACKET_SIZE, &packet_size);

XI_PRM_BUFFERS_QUEUE_SIZE or “buffers_queue_size”¶

Description: XI_PRM_BUFFERS_QUEUE_SIZE - 1 is the maximum number of images which can be stored in the buffers queue.
Type: Integer.
Default: 4 (Which means 3 images can be stored in the queue)
Invalidators: XI_PRM_ACQ_BUFFER_SIZE, XI_PRM_ACQ_BUFFER_SIZE_UNIT

Usage:

xiSetParamInt(handle, XI_PRM_BUFFERS_QUEUE_SIZE, images_count);

Example:

• Application sets queue size to 7
  

  xiSetParamInt(handle, XI_PRM_BUFFERS_QUEUE_SIZE, 7);
  xiSetParamInt(handle, XI_PRM_ACQ_BUFFER_SIZE, 40*1024*1024);
  

• Sensor acquires images at 10 frames/second. It means new image is acquired every 100ms, therefore queue can contain up to 6 images acquired during 600ms (=6*100ms) time span.
• Application needs typically 40ms for processing of an image.
• If it takes 400ms for the application to process one of the images (e.g. saving it to a server) the subsequent 4 frames are still available since they are stored in the queue (images 17-19 on the below figure).
  
  
  Illustration of normal status when application is processing one frame longer
  
• If it takes 1000ms for the application to process one of the images, the buffer queue will fill up and some images will be skipped (images 16-20 on the below figure). The user can check for such situation by checking the image sequence number (nframe of XI_IMG structure) of each image.
  
  
  Illustration of state when application gets late. Longer than queue.
  
• The application can work with the image data at most acq_buffer_size/(frame_rate_FPS*bytes_per_frame) seconds before the data is overwritten due to the circular character of the buffer. If the application needs more time to process the image, XI_PRM_BUFFER_POLICY must be set to XI_BP_SAFE. In this case API copies the image to a user/API allocated memory where it can be accessed without the risk of being overwritten. This copying however takes extra CPU time.

XI_PRM_ACQ_TRANSPORT_BUFFER_COMMIT or “acq_transport_buffer_commit”¶

Description: Defines number of buffers to commit to low level.
Type: Integer.
Defaults:
Usage:

xiSetParamInt(handle, XI_PRM_ACQ_TRANSPORT_BUFFER_COMMIT, number_of_buffers);

XI_PRM_RECENT_FRAME or “recent_frame”¶

Description: This parameter changes the behavior of xiGetImage.

value	xiGetImage behavior
0 (default)	Retrieves next available image from buffer
1	Retrieves the most recent image from buffer

Type: Integer.
Default: 0 (=off)

Usage:

xiSetParamInt(handle, XI_PRM_RECENT_FRAME, 1);

XI_PRM_TRANSPORT_DATA_TARGET or “transport_data_target”¶

Description: Sets image data delivery target to CPU RAM (default) or GPU RAM.
Type: Integer.
Default: 0 (XI_TRANSPORT_DATA_TARGET_CPU_RAM).

target	value	comment
XI_TRANSPORT_DATA_TARGET_CPU_RAM	0	normal CPU memory buffer is used for image data
XI_TRANSPORT_DATA_TARGET_GPU_RAM	1	data is delivered straight to GPU memory using GPUDirect technology: see detailed description
XI_TRANSPORT_DATA_TARGET_UNIFIED	2	CUDA managed memory is used for image data: see detailed description
XI_TRANSPORT_DATA_TARGET_ZEROCOPY	3	CUDA zerocopy memory is used for image data: see detailed description

Usage:

xiSetParamInt(handle, XI_PRM_TRANSPORT_DATA_TARGET, XI_TRANSPORT_DATA_TARGET_GPU_RAM);

XI_PRM_DEVICE_RESET or “device_reset”¶

Description: Resets the camera firmware. From the functional view, it is the same as disconnection and connection of the camera.
It is typically followed by an enumeration of the operating system which might take some time (e.g. 10 seconds).
Application shall wait some time after the reset and then use xiGetNumberDevices in order to enumerate the camera again. It should be used on the device with the stopped acquisition. After re-enumeration closing of the old device to release its handler is recommended. A new handler should be used for further image acquisition.
Type: Integer.
Default: 0 (disabled)
Note: currently supported only for xiQ camera family
Usage:

xiSetParamInt(old_handle, XI_PRM_DEVICE_RESET, 1);
Sleep(10000); // wait 10 seconds for enumeration by OS
DWORD devices_count=0;
xiGetNumberDevices(&devices_count);
xiCloseDevice(old_handle);
HANDLE new_handle= NULL;
xiOpenDevice(0, &new_handle);

XI_PRM_AEAG or “aeag”¶

Description: Automatic exposure/gain.
Type: Integer.
Default: 0 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_AEAG, 1);

XI_PRM_AE_MAX_LIMIT or “ae_max_limit”¶

Description: Maximum limit of exposure (in uSec) in AEAG procedure.
Type: Integer.
Default: 100000 uSec
Usage:

xiSetParamFloat(handle, XI_PRM_AE_MAX_LIMIT, 123);

XI_PRM_AG_MAX_LIMIT or “ag_max_limit”¶

Description: Maximum limit of gain in AEAG procedure.
Type: Float.
Default: depends on camera type (dB)
Usage:

xiSetParamFloat(handle, XI_PRM_AG_MAX_LIMIT, 12);

XI_PRM_EXP_PRIORITY or “exp_priority”¶

Description: Exposure priority for Auto Exposure / Auto Gain function.

Value	Meaning
1	Exposure priority. Only exposure will be changed.
0.5	Exposure and gain will be used (50%:50%)
0	Gain priority. Only gain will be changed.

Type: Float.
Default: 0.8
Usage:

xiSetParamFloat(handle, XI_PRM_EXP_PRIORITY, 0.9);

XI_PRM_AEAG_LEVEL or “aeag_level”¶

Description: Average intensity of output signal AEAG should achieve(in %).
Type: Float.
Default: 40 (%)
Usage:

xiSetParamFloat(handle, XI_PRM_AEAG_LEVEL, 50);

XI_PRM_AEAG_ROI_OFFSET_X or “aeag_roi_offset_x”¶

Description: X offset of the area used for AEAG calculation. The sum of XI_PRM_AEAG_ROI_OFFSET_X and XI_PRM_AEAG_ROI_WIDTH must be equal or lower than the image resolution(width).
Type: Int.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_AEAG_ROI_OFFSET_X,40);

XI_PRM_AEAG_ROI_OFFSET_Y or “aeag_roi_offset_y”¶

Description: Y offset of the area used for AEAG calculation. The sum of XI_PRM_AEAG_ROI_OFFSET_Y and XI_PRM_AEAG_ROI_HEIGHT must be equal or lower than the image resolution(height).
Type: Int.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_AEAG_ROI_OFFSET_Y,40);

XI_PRM_AEAG_ROI_WIDTH or “aeag_roi_width”¶

Description: width of the area used for AEAG calculation. The sum of XI_PRM_AEAG_ROI_OFFSET_X and XI_PRM_AEAG_ROI_WIDTH must be equal or lower than the image resolution(width).
Type: Int.
Default: depends on the sensors resolution and downsampling
Usage:

xiSetParamInt(handle, XI_PRM_AEAG_ROI_WIDTH,400);

XI_PRM_AEAG_ROI_HEIGHT or “aeag_roi_height”¶

Description: height of the area used for AEAG calculation. The sum of XI_PRM_AEAG_ROI_OFFSET_Y and XI_PRM_AEAG_ROI_HEIGHT must be equal or lower than the image resolution(height).
Type: Int.
Default: depends on the sensors resolution and downsampling
Usage:

xiSetParamInt(handle, XI_PRM_AEAG_ROI_HEIGHT,400);

XI_PRM_DEBOUNCE_EN or “dbnc_en”¶

Description: Enable/Disable debounce to selected GPI (see XI_PRM_GPI_SELECTOR parameter).
Type: Integer.
Default: 0 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_DEBOUNCE_EN, 1);

XI_PRM_DEBOUNCE_T0 or “dbnc_t0”¶

Description: Debounce time (x * 10us) for transition to inactive level of GPI selected by XI_PRM_DEBOUNCE_POL(see XI_PRM_DEBOUNCE_POL).
Type: Integer.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_DEBOUNCE_T0 , 10);

XI_PRM_DEBOUNCE_T1 or “dbnc_t1”¶

Description: Debounce time (x * 10us)for transition to active level of GPI selected by XI_PRM_DEBOUNCE_POL(see XI_PRM_DEBOUNCE_POL).
Type: Integer.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_DEBOUNCE_T1 , 10);

XI_PRM_DEBOUNCE_POL or “dbnc_pol”¶

Description: Debounce polarity selects active level of GPI (see XI_PRM_GPI_SELECTOR parameter). Does not inverts the signal if set.
Type: Integer.
Default: 1 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_DEBOUNCE_POL, 1);

Temperature¶

XI_PRM_IS_COOLED or "iscooled"¶

Description: Returns 1 for cameras that support cooling.
Type: Integer. Read only.
Default: By default -.
Usage:

xiGetParamInt(handle, XI_PRM_IS_COOLED, &is_cooled);

XI_PRM_COOLING or "cooling"¶

Description: Set camera cooling control. Replaced by XI_PRM_TEMP_CONTROL_MODE
Type: Enumerator.
Default: By default 0 (Off).

Value	Mode
XI_TEMP_CTRL_MODE_OFF	Controlling of elements (TEC/Peltier, Fans) is turned off
XI_TEMP_CTRL_MODE_AUTO	Controlling of elements is performed automatically by API or camera in order to reach XI_PRM_TARGET_TEMP
XI_TEMP_CTRL_MODE_MANUAL	Controlling of elements is done manually by application

Usage:

xiSetParamInt(handle, XI_PRM_TEMP_SELECTOR, XI_TEMP_SENSOR_BOARD);
xiSetParamFloat(handle, XI_PRM_TARGET_TEMP, 18.5); 
xiSetParamInt(handle, XI_PRM_COOLING, XI_TEMP_CTRL_MODE_AUTO); 

XI_PRM_TARGET_TEMP or "target_temp"¶

Description: Set target temperature for temperature control. XI_PRM_TEMP_SELECTOR might be used for selection of thermometer.
Type: Float.
Default: By default 20 °C.
Usage:

xiSetParamFloat(handle, XI_PRM_TARGET_TEMP, 18.5); 
xiGetParamFloat(handle, XI_PRM_TARGET_TEMP, &target_temp); 

XI_PRM_TEMP_SELECTOR or "temp_selector"¶

Description: Temperature sensor selector.
Type: Integer.
Default: 0 (XI_TEMP_IMAGE_SENSOR_RAW)

The parameter selects one of the temperature sensors.

Value	Thermometer location
XI_TEMP_IMAGE_SENSOR_DIE_RAW	Image sensor die (non-calibrated)
XI_TEMP_IMAGE_SENSOR_DIE	Image sensor die (calibrated)
XI_TEMP_SENSOR_BOARD	PCB as image sensor
XI_TEMP_INTERFACE_BOARD	Interface board
XI_TEMP_FRONT_HOUSING	Front part of camera housing
XI_TEMP_REAR_HOUSING	Rear part of camera housing
XI_TEMP_TEC1_COLD	TEC1 cold side temperature
XI_TEMP_TEC1_HOT	TEC1 hot side temperature

Usage:

float temperature=0;
xiSetParamInt(handle, XI_PRM_TEMP_SELECTOR, XI_TEMP_IMAGE_SENSOR_RAW); 
xiGetParamFloat(handle, XI_PRM_TEMP, &temperature); 

XI_PRM_TEMP or "temp"¶

Description: Selected thermometer reading in degree Celsius. Thermometer can be selected by XI_PRM_TEMP_SELECTOR.
Type: Float.
Default: By default -.
Usage:

float temperature_c=0;
xiGetParamFloat(handle, XI_PRM_TEMP, &temperature_c);

XI_PRM_CHIP_TEMP or "chip_temp"¶

Description: Temperature reading of thermometer chip. Sensor is located on the PCB close to imaging sensor. Units: degrees of Celsius.

Type: Float.
Default: By default -.
Usage:

xiGetParamFloat(handle, XI_PRM_CHIP_TEMP, &temperature_chip_temp); 

XI_PRM_HOUS_TEMP or "hous_temp"¶

Description: Camera housing temperature.
Type: Float.
Default: By default -.
Usage:

xiGetParamFloat(handle, XI_PRM_HOUS_TEMP, &house_temp);

XI_PRM_HOUS_BACK_SIDE_TEMP or "hous_back_side_temp"¶

Description: Camera housing back side temperature.
Type: Float.
Default: By default -.
Usage:

xiGetParamFloat(handle, XI_PRM_HOUS_BACK_SIDE_TEMP, &house_temp);

XI_PRM_SENSOR_BOARD_TEMP or "sensor_board_temp"¶

Description: Camera sensor board temperature.
Type: Float.
Default: By default -.
Usage:

xiGetParamFloat(handle, XI_PRM_SENSOR_BOARD_TEMP, &sensor_board_temp); 

XI_PRM_TEMP_CONTROL_MODE or "device_temperature_ctrl_mode"¶

Description: Temperature control mode
Type: Enumerator.
Default: 0 (XI_TEMP_CTRL_MODE_OFF)

The parameter selects one of temperature sensors.

Value	Mode
XI_TEMP_CTRL_MODE_OFF	Controlling of elements (TEC/Peltier, Fans) is turned off
XI_TEMP_CTRL_MODE_AUTO	Controlling of elements is performed automatically by API or camera in order to reach XI_PRM_TARGET_TEMP
XI_TEMP_CTRL_MODE_MANUAL	Controlling of elements is done manually by application

Usage:

xiSetParamInt(handle, XI_PRM_TEMP_SELECTOR, XI_TEMP_SENSOR_BOARD);
xiSetParamFloat(handle, XI_PRM_TARGET_TEMP, 18.5); 
xiSetParamInt(handle, XI_PRM_COOLING, XI_TEMP_CTRL_MODE_AUTO); 

XI_PRM_TEMP_ELEMENT_SEL or "device_temperature_element_sel"¶

Description: Temperature element selector (TEC, Fan)
Type: Enumerator.
Default: 0 (XI_TEMP_ELEM_TEC1)

Value	Element
XI_TEMP_ELEM_TEC1	TEC1 = TEC/Peltier that is closest to the image sensor
XI_TEMP_ELEM_TEC2	TEC2 = TEC/Peltier location depends on camera model
XI_TEMP_ELEM_FAN1	FAN1 = Fan

Usage: See XI_PRM_TEMP_ELEMENT_VALUE

XI_PRM_TEMP_ELEMENT_VALUE or "device_temperature_element_val"¶

Description: Temperature element value in percents of full control range
Type: Float.
Default: By default -.
Usage:

xiSetParamInt(handle, XI_PRM_COOLING, XI_TEMP_CTRL_MODE_MANUAL); 
xiSetParamInt(handle, XI_PRM_TEMP_ELEMENT_SEL, XI_TEMP_ELEM_TEC1);
xiSetParamFloat(handle, XI_PRM_TEMP_ELEMENT_VALUE, 50.1); 

Device Connection¶

XI_PRM_IS_DEVICE_EXIST or "isexist"¶

Description: Returns 1 if camera connected and works properly.
Type: Integer.

Usage:

xiGetParamInt(handle, XI_PRM_IS_DEVICE_EXIST, &is_ok); 

Sensor Defects Correction parameters¶

XI_PRM_SENS_DEFECTS_CORR_LIST_SELECTOR “bpc_list_selector”¶

Description: Selector for current sensor defects list used by Sensor Defect Correction. For more information see Sensor Defect Correction support page.
Type: Enumerator.
Default: By default 0 (Off).

Value	Mode
XI_SENS_DEFFECTS_CORR_LIST_SEL_FACTORY	List calibrated in camera production factory
XI_SENS_DEFFECTS_CORR_LIST_SEL_USER0	User list, created by user

Usage:

xiSetParamInt(handle, XI_PRM_SENS_DEFECTS_CORR_LIST_SELECTOR , XI_SENS_DEFFECTS_CORR_LIST_SEL_USER0 );
xiSetParamInt(handle, XI_PRM_SENS_DEFECTS_CORR, XI_ON); 

XI_PRM_SENS_DEFECTS_CORR_LIST_CONTENT “sens_defects_corr_list_content”¶

Description: Set/Get current sensor defects list used by Sensor Defect Correction(in specific text format).
Type: String.
Default: By default -

Usage:

xiSetParamString(handle, XI_PRM_SENS_DEFECTS_CORR_LIST_CONTENT , string, strlen(string) );
xiGetParamString(handle, XI_PRM_SENS_DEFECTS_CORR_LIST_CONTENT, string, string_size); 

XI_PRM_SENS_DEFECTS_CORR or “bpc”¶

Description: Correction of sensor defects. For more information see Sensor Defect Correction support page.
Type: Integer.
Default: 0 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_SENS_DEFECTS_CORR, 1);

XI_PRM_FFC or “ffc”¶

Description: Image flat field correction.(XI_PRM_NEW_PROCESS_CHAIN_ENABLE must be XI_ON).
For more information see Flat Field Correction support page.
Type: Integer.
Default: 0 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_FFC, 1);

XI_PRM_FFC_FLAT_FIELD_FILE_NAME or "ffc_flat_field_file_name"¶

Description: Set name of file of image flat field to be applied for FFC processor(in tiff format). (XI_PRM_NEW_PROCESS_CHAIN_ENABLE must be XI_ON).
For more information see Flat Field Correction support page.
Type: String.
Default: By default -.
Usage:

xiSetParamString(handle, XI_PRM_FFC_FLAT_FIELD_FILE_NAME, filename, size);

XI_PRM_FFC_DARK_FIELD_FILE_NAME or "ffc_dark_field_file_name"¶

Description: Set name of file of image dark field to be applied for FFC processor(in tiff format). (XI_PRM_NEW_PROCESS_CHAIN_ENABLE must be XI_ON).
For more information see Flat Field Correction support page.
Type: String.
Default: By default -.
Usage:

xiSetParamString(handle, XI_PRM_FFC_DARK_FIELD_FILE_NAME, filename, size);

XI_PRM_COLUMN_FPN_CORRECTION or “column_fpn_correction”¶

Description: Correction of column fpn.
Type: Integer.
Default: 0 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_COLUMN_FPN_CORRECTION, 1);

XI_PRM_ROW_FPN_CORRECTION or “row_fpn_correction”¶

Description: Correction of row fpn.
Type: Integer.
Default: 0 (disabled)
Usage:

xiSetParamInt(handle, XI_PRM_ROW_FPN_CORRECTION, 1);

Sensor Specific Parameters¶

XI_PRM_HDR or "hdr"¶

Note: ebables HDR mode for certain type of sensors. For more information see HDR mode support page.

Description: Enable High Dynamic Range sensor feature.
Type: Integer.
Default: By default 0.
Usage:

xiSetParamInt(handle, XI_PRM_HDR, 1);
xiGetParamInt(handle, XI_PRM_HDR, &hdr_enabled);

XI_PRM_HDR_KNEEPOINT_COUNT or "hdr_kneepoint_count"¶

Note: Defines the number of kneepoints in the Piecewise Linear Response (PWLR) curve.

Description: number of kneepoints.
Type: Integer.
Default: depends on sensor.
Usage:

xiSetParamInt(handle, XI_PRM_HDR_KNEEPOINT_COUNT, 1);
xiGetParamInt(handle, XI_PRM_HDR_KNEEPOINT_COUNT, &hdr_kp_count);

Note: In case of one kneepoint, the kneepoint is defined by parameters (T2,SL2). In case of two kneepoints define both (T1,SL1), (T2,SL2).

XI_PRM_HDR_T1 or "hdr_t1"¶

Description: Exposure time (T1) of 1st kneepoint in % of XI_PRM_EXPOSURE.
Type: Integer.
Default: By default 60
Usage:

xiSetParamInt(handle, XI_PRM_HDR_T1, 70);

XI_PRM_HDR_T2 or "hdr_t2"¶

Description: Exposure time (T2) of 2nd kneepoint in % of XI_PRM_EXPOSURE.
Type: Integer.
Default: By default 80
Usage:

 xiSetParamInt(handle, XI_PRM_HDR_T2, 20);

XI_PRM_KNEEPOINT1 or "hdr_kneepoint1"¶

Description: Saturation level (SL1) of 1st kneepoint in % of sensor saturation.
Type: Integer.
Default: By default 40
Usage:

xiSetParamInt(handle, XI_PRM_KNEEPOINT1, 30);

XI_PRM_KNEEPOINT2 or "hdr_kneepoint2"¶

Description: Saturation level (SL2) of 2nd kneepoint in % of sensor saturation.
Type: Integer.
Default: By default 60
Usage:

xiSetParamInt(handle, XI_PRM_KNEEPOINT2, 70); 

XI_PRM_SENSOR_MODE or "sensor_mode"¶

Description: For some cameras this sensor specific parameter allows to select from predefined sensor modes. Setting of this parameter affects the image dimensions and downsampling.
Type: Integer.
Default: 0

Usage:

xiSetParamInt(handle, XI_PRM_SENSOR_MODE, 1); 

XI_PRM_IMAGE_BLACK_LEVEL or "image_black_level"¶

Description: Black level is calculated level (in pixel counts) that should reflect the value of pixels without light. It should be the same as XI_IMG.black_level from last image get using xiGetImage.
Type: Integer. Read Only.
Default: 0

XI_PRM_API_CONTEXT_LIST or "xiapi_context_list"¶

Description: API Context contains text representation of current settings for offline image processing. It can be get while acquisition to store the context. Respectively it can be set while offline processing - to restore context.
Type: Text.

Api version and device driver/firmware info¶

XI_PRM_API_VERSION or "api_version"¶

Description: Returns the version of API.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_API_VERSION, char *, size);

XI_PRM_DRV_VERSION or "drv_version"¶

Description: Returns the version of the current device driver.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_DRV_VERSION, char *, size);

XI_PRM_MCU1_VERSION or "version_mcu1"¶

Description: Returns the version of the current MCU1 firmware.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_MCU1_VERSION, char *, size);

XI_PRM_MCU2_VERSION or "version_mcu2"¶

Description: Returns the version of the current MCU2 firmware.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_MCU2_VERSION, char *, size);

XI_PRM_MCU3_VERSION or "version_mcu3"¶

Description: Returns the version of the current MCU3 firmware.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_MCU3_VERSION, char *, size);

XI_PRM_FPGA1_VERSION or "version_fpga1"¶

Description: Returns the version of the current FPGA1 firmware.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_FPGA1_VERSION, char *, size);

XI_PRM_XMLMAN_VERSION or "version_xmlman"¶

Description: Returns version of XML manifest.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_XMLMAN_VERSION, char *, size);

XI_PRM_HW_REVISION or "hw_revision"¶

Description: Returns the hardware revision number of the camera.
Type: String.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_HW_REVISION, char *, size);

Flash file system control¶

Some of XIMEA cameras contain Flash File System. It allows to store/read small customer file in each camera.

Example program for working with FFS

XI_PRM_FFS_FILE_NAME or "ffs_file_name"¶

Description: Name of file to be written/read from camera FFS.
Type: String.
Note: On MX,MC,CB,MT cameras family, there is limited set of filenames. User's application can use filenames: User1, User2, User3 to store some application specific data.
Default: By default -.
Usage:

char filename[100]="User1";
xiSetParamString(handle, XI_PRM_FFS_FILE_NAME, filename, size);

XI_PRM_READ_FILE_FFS or "read_file_ffs"¶

Description: File data to be read from camera flash file system.
Type: String. Read only.
Default: By default -.
Usage:

xiGetParamString(handle, XI_PRM_READ_FILE_FFS, data_buff, max_size);

Example: Example below reads the sensor defects file. This file exist on xiQ cameras.

// set filename
char filename[100]="bad_pixel_list.txt";
stat = xiSetParamString(xiH, XI_PRM_FFS_FILE_NAME, filename, sizeof(filename));
HandleResult(stat,"xiSetParamString (XI_PRM_FFS_FILE_NAME)");
// allocate buffer
#define MAX_FILE_SIZE 1000*1000 // 1MB
char* file_content=NULL;
file_content = (char*) calloc(1,MAX_FILE_SIZE);
if (!file_content)
{
  printf("Error on memory allocation for file content.\n");
  return;
}
// read file
stat = xiGetParamString(xiH, XI_PRM_READ_FILE_FFS, file_content, MAX_FILE_SIZE);
HandleResult(stat,"xiGetParamString (XI_PRM_READ_FILE_FFS)");
// print file content
printf("Text read from FFS file:%s\n%s\n\n", filename, file_content);
free(file_content);

HSI Calibration Files Access¶

For reading out Hyper-Spectral sensor calibration data from the camera - use the same code as above, but replace the filename with 'sens_calib.dat'

Code to be used for HSI Calibration:

// set filename for HSI Sensor Calibration
char filename[100]="sens_calib.dat";
stat = xiSetParamString(xiH, XI_PRM_FFS_FILE_NAME, filename, sizeof(filename));
// continue like in example for reading FFS file

XI_PRM_WRITE_FILE_FFS or "write_file_ffs"¶

Description: File data to be written to camera flash file system.
Type: String. Write only.
Default: By default -.
Usage:

xiSetParamString(handle, XI_PRM_WRITE_FILE_FFS, data_buff, size);

Delete file:

xiSetParamString(xiH, XI_PRM_FFS_FILE_NAME, "filename.txt", strlen("filename.txt"));
xiSetParamString(xiH, XI_PRM_WRITE_FILE_FFS, NULL, 0);

XI_PRM_FFS_FILE_ID or "ffs_file_id"¶

Description: File number(id) in camera FFS.
Type: Integer.
Default: By default 0.
Usage:

xiSetParamInt(handle, XI_PRM_FFS_FILE_ID, file_id);
xiGetParamInt(handle, XI_PRM_FFS_FILE_ID, &file_id);

Get list of files:

        int max_file_id = 0;
        xiGetParamInt(xiH, XI_PRM_FFS_FILE_ID XI_PRM_INFO_MAX, &max_file_id);
    char file_name[MAX_PATH];

    for(int i = 0; i <= max_file_id; i++)
    {
        memset(file_name, 0, MAX_PATH);
        stat = xiSetParamInt(xiH, XI_PRM_FFS_FILE_ID, i);
        stat = xiGetParamString(xiH, XI_PRM_FFS_FILE_NAME, file_name, MAX_PATH);
    }

XI_PRM_FFS_FILE_SIZE or "ffs_file_size"¶

Description: Size of a file specified with parameter XI_PRM_FFS_FILE_ID in bytes.
Type: Integer. Read only.
Default: By default -.
Usage:

xiSetParamInt(handle, XI_PRM_FFS_FILE_ID, 1);
xiGetParamInt(handle, XI_PRM_FFS_FILE_SIZE, &file_size);

XI_PRM_FREE_FFS_SIZE or "free_ffs_size"¶

Description: Size of free camera flash file system space in bytes.
Type: Integer. Read only.
Default: By default -.
Usage:

xiGetParamInt(handle, XI_PRM_FREE_FFS_SIZE, &free_size);

XI_PRM_USED_FFS_SIZE or "used_ffs_size"¶

Description: Size of used camera flash file system space in bytes.
Type: Integer. Read only.
Default: By default -.
Usage:

xiGetParamInt(handle, XI_PRM_USED_FFS_SIZE, &used_size);

XI_PRM_FFS_ACCESS_KEY or "ffs_access_key"¶

Description: Setting of the key enables file operations on some cameras. It is required to set before usage of XI_PRM_WRITE_FILE_FFS.
Type: Integer.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_FFS_ACCESS_KEY, 0x12345678);

Camera Lens Control¶

Some of XIMEA cameras can be equipped with controlled lens. API for lens control contains couple of parameters.

Lens tested OK with CB cameras (2017-04):

• CANON EF 50mm f/1.4 USM
• CANON EF 50mm f/1.8 II
• CANON EF 24-105 f4 L IS USM
• CANON EF 17-40mm f/4L USM
• CANON EF 100mm f/2.8 Macro USM
• CANON EF-S 17-55mm f/2.8 IS USM
• CANON EF 70-200mm f/4L IS USM
• CANON EF 50mm f/1.8 STM
• CANON EF 24mm f/2.8 STM
• CANON EF 10-18mm f/4.5-5.6 STM
• CANON EF 18-135mm f/3.5-5.6 STM
• Sigma 150mm f/2.8 EX DG OS HSM APO Macro
• Sigma 15mm f/2.8 EX DG

XI_PRM_LENS_MODE or lens_mode¶

Description: Status of lens control interface. This shall be set to XI_ON before any Lens operations.
Type: Integer.
Default: By default XI_OFF.
Usage:

xiSetParamInt(handle, XI_PRM_LENS_MODE, XI_ON);

XI_PRM_LENS_APERTURE_VALUE or lens_aperture_value¶

Description: Current lens aperture value in aperture stops. Examples: 2.8, 4, 5.6, 8, 11
Type: Float.
Default: -
Usage:

xiSetParamFloat(handle, XI_PRM_LENS_APERTURE_VALUE, 5.6);

XI_PRM_LENS_APERTURE_INDEX or lens_aperture_index¶

Description: Current lens aperture step value.
Type: Integer.
Default: -
Usage:

xiSetParamFloat(handle, XI_PRM_LENS_APERTURE_INDEX, 24);

XI_PRM_LENS_FOCUS_MOVEMENT_VALUE or lens_focus_movement_value¶

Description: Lens current focus movement value to be used by XI_PRM_LENS_FOCUS_MOVE in motor steps. Positive numbers will direct the movement to infinity. Negative numbers will direct the movement to macro.
Type: Integer.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_LENS_FOCUS_MOVEMENT_VALUE, 10);

XI_PRM_LENS_FOCUS_MOVE or lens_focus_move¶

Description: Moves lens focus motor by steps set in XI_PRM_LENS_FOCUS_MOVEMENT_VALUE.
Type: Command
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_LENS_MODE, XI_ON);
xiSetParamFloat(handle, XI_PRM_LENS_FOCUS_MOVEMENT_VALUE, 10);
xiSetParamInt(handle, XI_PRM_LENS_FOCUS_MOVE, 0); // move 10 steps to infinity

XI_PRM_LENS_FOCUS_DISTANCE or lens_focus_distance¶

Description: Lens focus distance in cm.
Type: Float
Default: 1000
Usage:

float distance_cm=0;
xiGetParamFloat(handle, XI_PRM_LENS_FOCUS_DISTANCE, &distance_cm);

XI_PRM_LENS_FOCAL_LENGTH or lens_focal_length¶

Description: Lens focal distance in mm. This parameter is constant for prime lens and can change in real time for zoom lens.
Type: Float. Read only.
Default: 0
Usage:

float zoom_min_mm=0;
float zoom_max_mm=0;
xiGetParamFloat(handle, XI_PRM_LENS_FOCAL_LENGTH XI_PRM_INFO_MIN, &zoom_min_mm);
xiGetParamFloat(handle, XI_PRM_LENS_FOCAL_LENGTH XI_PRM_INFO_MAX, &zoom_max_mm);

XI_PRM_LENS_FEATURE_SELECTOR or lens_feature_selector¶

Description: Selects the current feature which is accessible by XI_PRM_LENS_FEATURE.
Type: Integer
Default: 0
Usage: See parameter XI_PRM_LENS_FEATURE
Possible values:

XI_PRM_LENS_FEATURE_SELECTOR	Value on XI_PRM_LENS_FEATURE
XI_LENS_FEATURE_MOTORIZED_FOCUS_SWITCH	Status of lens motorized focus switch
XI_LENS_FEATURE_MOTORIZED_FOCUS_BOUNDED	On read = 1 if motorized focus is on one of limits.
XI_LENS_FEATURE_MOTORIZED_FOCUS_CALIBRATION	On read = 1 if motorized focus is calibrated. Write 1 to start calibration.
XI_LENS_FEATURE_IMAGE_STABILIZATION_ENABLED	On read = 1 if image stabilization is enabled. Write 1 to enable image stabilization.
XI_LENS_FEATURE_IMAGE_STABILIZATION_SWITCH_STATUS	On read = 1 if image stabilization switch is in position On.
XI_LENS_FEATURE_IMAGE_ZOOM_SUPPORTED	On read = 1 if lens supports zoom = are not prime

XI_PRM_LENS_FEATURE or lens_feature¶

Description: Allows access to lens feature value currently selected by XI_PRM_LENS_FEATURE_SELECTOR.
Type: Integer
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_LENS_FEATURE_SELECTOR, XI_LENS_FEATURE_MOTORIZED_FOCUS_SWITCH);
int switch_status=0;
xiGetParamInt(handle, XI_PRM_LENS_FEATURE, &switch_status);
if (switch_status > 0)
   printf("The motorized focus switch on the lens is switched on.\n");

Sensor Feature Control¶

Some of XIMEA cameras has sensors with specific features

XI_PRM_SENSOR_FEATURE_SELECTOR or sensor_feature_selector¶

Description: Selects the current feature which is accessible by XI_PRM_SENSOR_FEATURE_VALUE.
Type: Integer.
Default: XI_SENSOR_FEATURE_ZEROROT_ENABLE
Usage:

xiSetParamInt(handle, XI_PRM_SENSOR_FEATURE_SELECTOR, XI_SENSOR_FEATURE_ZEROROT_ENABLE);

Selector	Camera model	Default value
XI_SENSOR_FEATURE_ZEROROT_ENABLE	MQ013xG-ON (PYTHON)	XI_OFF
XI_SENSOR_FEATURE_BLACK_LEVEL_CLAMP	MD	XI_OFF
XI_SENSOR_FEATURE_MD_FPGA_DIGITAL_GAIN_DISABLE	MD	XI_OFF
XI_SENSOR_FEATURE_ACQUISITION_RUNNING	CB,MC,MX,MT	XI_OFF

Selector description¶

• XI_SENSOR_FEATURE_ZEROROT_ENABLE
  When this feature is enabled the readout fof pixel line is overlapped with vertical shift of pixels from pixel are to readout shift registers. This effectively can eliminate time needed between consequent live readouts. The price for it is that the dynamic range is lower by 6dB compared to normal ROT.

• XI_SENSOR_FEATURE_ACQUISITION_RUNNING
  When this feature value is 1 - acquisition is running. Application can stop just acquisition of the sensor without freeing of image buffers by setting this value to 0. Then acquisition could be resumed by setting 1. It is also much faster compared to xiStopAcquisition/xiStartAcquisition.

This feature can be also added to CamTool.
Copy the file xiapi_camera_description_FULL.xml to \XIMEA\XIMEACamTool64\camdesc and replace the original file. When CamTool is opened, there are two xiAPI parameters of this feature (Sensor feature selector, Sensor feature value) in Performance tab on the right side (Visibility level: Guru). Select Enable Zero ROT and check Sensor feature value.

XI_PRM_SENSOR_FEATURE_VALUE or sensor_feature_value¶

Description: Allows access to sensor feature value currently selected by XI_PRM_SENSOR_FEATURE_SELECTOR.
Type: Integer.
Default: 0
Usage:

xiSetParamInt(handle, XI_PRM_SENSOR_FEATURE_SELECTOR, XI_SENSOR_FEATURE_ZEROROT_ENABLE);
xiSetParamInt(handle, XI_PRM_SENSOR_FEATURE_VALUE, XI_ON);

XI_PRM_ACQUISITION_STATUS_SELECTOR or “acquisition_status_selector”¶

Description: Selects the internal acquisition signal to read using XI_PRM_ACQUISITION_STATUS.
Type: Integer.
Default: All

Usage:

xiSetParamInt(handle, XI_PRM_ACQUISITION_STATUS_SELECTOR, XI_ACQUISITION_STATUS_ACQ_ACTIVE );  

XI_PRM_ACQUISITION_STATUS or “acquisition_status”¶

Description: Returns status of acquisition.

Type: Integer.
Default: By default -.

Usage:

xiGetParam(handle, XI_PRM_ACQUISITION_STATUS, &value, sizeof(int), xiTypeInteger);
int xiGetParamInt(handle, XI_PRM_ACQUISITION_STATUS, &value);

XI_PRM_GENTL_DATASTREAM_ENABLED or “gentl_stream_en”¶

Description: Control of GenTL data stream. Enabling by XI_ON the acquisition buffering must be controlled by GenTL interface (e.g. DSAllocAndAnnounceBuffer, DSQueueBuffer)

Type: Integer.
Default: By default XI_OFF.

Usage:

xiSetParamInt(handle, XI_PRM_GENTL_DATASTREAM_ENABLED, XI_ON);

XI_PRM_GENTL_DATASTREAM_CONTEXT or “gentl_stream_context”¶

Description: Pointer to GenTL stream context. It can be used later with GenTL buffers handling.
Type: String.
Usage: See more details in the example xiAPI-capture-50-images-gentl

xiSetParamInt(handle, XI_PRM_GENTL_DATASTREAM_ENABLED, XI_ON);
void* stream_h=NULL;
xiGetParamString(handle, XI_PRM_GENTL_DATASTREAM_CONTEXT, &stream_h, sizeof(void*)));
void* buffer_handle=NULL;
AllocAndAnnounceBuffer(stream_h, payload_size, NULL, &buffer_handle);

XI_PRM_DP_UNIT_SELECTOR or “dp_unit_selector”¶

Description: Data Pipe Unit Selector.

Type: Integer.
Default: All

Usage:

xiSetParamInt(handle, XI_PRM_DP_UNIT_SELECTOR, 0);  

XI_PRM_DP_PROC_SELECTOR or “dp_proc_selector”¶

Description: Data Pipe Processor Selector.

Type: Integer.
Default: All

Usage:

xiSetParamInt(handle, XI_PRM_DP_PROC_SELECTOR, 0);  

XI_PRM_DP_PARAM_SELECTOR or “dp_param_selector”¶

Description: Data Pipe Processor parameter Selector.

Type: Integer.
Default: All

Usage:

xiSetParamInt(handle, XI_PRM_DP_PARAM_SELECTOR, 0);  

XI_PRM_DP_PARAM_VALUE or “dp_param_value”¶

Description: Data Pipe processor parameter value.

Type: Float
Default: 0

Usage:

xiSetParamFloat(handle, XI_PRM_DP_PARAM_VALUE, 0);  

API parameter modifiers¶

Description: The parameter modifiers allow you to acquire more information about the camera parameters (e.g. min. or max. value).
Also with certain parameters they allow direct update of these parameters without interrupting the image acquisition
loop (e.g. setting of exposure and gain).

XI_PRM_INFO_MIN¶

Description: Acquire parameter minimum value.
Usage:

xiGetParamInt(handle, XI_PRM_EXPOSURE XI_PRM_INFO_MIN, &exp_min);

XI_PRM_INFO_MAX¶

Description: Acquire parameter maximum value.
Usage:

xiGetParamInt(handle, XI_PRM_EXPOSURE XI_PRM_INFO_MAX, &exp_max);

XI_PRM_INFO_INCREMENT¶

Description: Get parameter possible increment step. The setting of value is limited to values MinumumValue+(N*IncrementValue)
Usage:

xiGetParamInt(handle, XI_PRM_HEIGHT XI_PRM_INFO_INCREMENT, &width_inc);

XI_PRMM_DIRECT_UPDATE¶

Description: Parameter modifier for direct update without stopping the streaming. Currently XI_PRM_EXPOSURE and XI_PRM_GAIN can be used with this modifier.
Usage:

xiSetParamInt(handle, XI_PRM_EXPOSURE XI_PRMM_DIRECT_UPDATE, exp_val);
xiSetParamInt(handle, XI_PRM_GAIN XI_PRMM_DIRECT_UPDATE, gain_val);

Image Buffers Queue¶

Functionality¶

The Image Buffers is first-in first-out (FIFO) type of queue.

Capturing¶

Each captured image is stored in the buffers queue. When application calls xiGetImage - the oldest image is removed from queue. Maximum number of images in queue can be set by parameter XI_PRM_BUFFERS_QUEUE_SIZE.

Flushing the queue¶

The images remain in the queue until they are overwritten or flushed. The queue is flushed on one of following conditions:

• acquisition is stopped (xiStopAcquisition)
• application set some of parameters using xiSetParam:
  • Exposure (XI_PRM_EXPOSURE) *Note
  • Gain (XI_PRM_GAIN) *Note
  • Downsampling (XI_PRM_DOWNSAMPLING)
  • Data Format (XI_PRM_IMAGE_DATA_FORMAT)
  • Width (XI_PRM_WIDTH)
  • Height (XI_PRM_HEIGHT)
  • Offset X (XI_PRM_OFFSET_X)
  • Offset Y (XI_PRM_OFFSET_Y)

*Note: Some of parameters can be changed without flushing the queue. It is possible to change parameter using modifier: XI_PRMM_DIRECT_UPDATE