MVTec HALCON 10: Image Acquisition Interface for Sony XCI-V100/C and XCI-SX100/C
This page provides the documentation of the HALCON image acquisition interface for the XCI-V100/C and XCI-SX100/C smart cameras from Sony. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 4.5
System Requirements
- Sony XCI-V100/C or XCI-SX100/C with Windows XP Embedded operating and camera driver 1.0.0.0.
- SonyICam DLL version 1.0.0.0 for XCI-V100/C or XCI-SX100/C. This DLL must be within your search path %PATH% (typically, it resides in the directory %WINDIR%\system32). If you do not have these DLLs, please contact Sony or the vendor from which you bought the camera.
- HALCON image acquisition interface hAcqSonyXCI-2.dll or hAcqSonyXCI-2xl.dll, respectively. If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
Features
- Synchronous and asynchronous grabbing.
- Software control of various parameters like shutter, trigger, and digital I/O.
- Software control of binning and partial scan.
- Support of lookup tables and thresholding via gamma settings.
Limitations
- grab_data, grab_data_async, get_framegrabber_lut, and set_framegrabber_lut not supported.
Description
Parameters for open_framegrabber():
| Name | 'SonyXCI-2' | The name of the HALCON image acquisition interface. | |||
| HorizontalResolution | --- | Ignored. | |||
| VerticalResolution | --- | Ignored. | |||
| ImageWidth | --- | Ignored. | |||
| ImageHeight | --- | Ignored. | |||
| StartRow | --- | Ignored. | |||
| StartColumn | --- | Ignored. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | --- | Ignored. | |||
| ColorSpace | 'default', 'gray', 'rgb', 'yuv', 'raw' | Specifies the desired color space and thus the number of image channels of the resulting HALCON image. 'default' means to adopt the camera setting. Default: 'default'. | |||
| Generic | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Enables or disables the external trigger mode. | |||
| CameraType | 'default', 'XCI-V100', 'XCI-V100C', 'XCI-SX100', 'XCI-SX100C' | Sets the type of the connected camera. 'default' means to adopt the camera setting. Default: 'default'. | |||
| Device | '0' | Specifies the current camera device. Default: '0'. | |||
| Port | --- | Ignored. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
| 'auto_gain' | 'enable', 'disable' | Specifies the auto gain mode. If set to 'enable', the auto gain mode is enabled and the auto gain correction is controlled by the parameter 'auto_gain_correction'. Default: 'disable'. | |||
| 'auto_gain_correction' | -8 ... 8 | Specifies the auto gain correction in auto gain mode. Default: 0. | |||
| 'camera_gain' | camera_gain (long) | Specifies the gain of the camera. | |||
| 'cds_gain' | cds_gain (long) | Specifies the CDS gain of the camera. | |||
| 'com_trigger_mode' | mode (long) | Sets the common trigger counter operation mode (see Sony documentation for more details). | |||
| 'continuous_grabbing' | 'enable', 'disable' | Sets the grabbing mode from single frame capture to continuous mode. If the continuous mode is enabled, the camera will grab all the time. Note that the continuous mode is automatically disabled in case of external triggering! Default: 'disable'. | |||
| 'do_com_trigger_counter_reset' | -- | Resets the common trigger counter value. | |||
| 'do_white_balance' | -- | Generates a white balance one-push trigger. | |||
| 'do_soft_trigger' | -- | Generates a software trigger. | |||
| 'do_trigger_counter_reset' | -- | Resets the trigger counter. | |||
| 'external_trigger' | 'true', 'false' | Sets the external trigger from the camera. If set, the continuous grabbing mode will be set to 'disable'. | |||
| 'gamma' | 0 ... 4 (long) | Sets a LUT table (0=off, 1=0.45, 2=2.2, 3=reverse, 4=bin). | |||
| 'gamma_threshold' | 1 ... 1023 (long) | Sets the threshold value, if the gamma mode is set to 4 (bin). | |||
| 'gpio_delay_step' | 0 ... 65535 (long) | Sets the GPIO input delay time in microseconds. | |||
| 'gpio_delay_select' | 0 ... 31 (long) | Sets the GPIO input delay output. | |||
| 'gpio_delay_source_select' | 'input0', 'input1', 'input2', 'input3', 'trigger' | Sets the GPIO input delay source. | |||
| 'gpio_output_select:X' | 'input0', 'input1', 'input2', 'input3', 'trigger', 'delay', 'WDT', 'CPU_GPO' | Select the GPIO output source (with X = 0,1,...,7 as unique index of the desired GPIO line). | |||
| 'gpio_output:X' | 0, 1 | Sets the GPIO output signal (with X = 0,1,...,7 as unique index of the desired GPIO line). | |||
| 'gpio_status_led' | 'enable', 'disable' | Sets the state of the status LED. | |||
| 'grab_timeout' | 100 ... 327680 (long) | Specifies the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000. | |||
| 'horizontal_binning' | 'enable', 'disable' | Grayscale only. Specifies the horizontal binning mode. | |||
| 'image_full' | 'enable', 'disable' | Enables the grabbing of images with the size of the full sensor. The original chosen values for partial grabbing ('image_part') are stored internal and used if partial grabbing is chosen again. If 'image_full' is enabled, with the next 'image_part', 'image_full' is automatically disabled. Default: 'enable'. | |||
| 'image_height' | height (long) | Specifies the height of the grabbed image. Please note the step width of the height parameter. If a non-valid value is set, it is adjusted to the next valid value. | |||
| 'image_part' | [row1 (long), col1 (long), row2 (long), col2 (long)] | Specifies the upper left (row1, col1) and lower right (row2, col2) corner of the desired rectangular image part which will be actually acquired by the camera. Please note the valid step widths of these parameters. If a non-valid value is set, it is adjusted to the next valid value. This means that the grabbed image part is equal to the specified image part or actually includes the image part specified by row1, col1, row2, and col2. | |||
| 'image_width' | width (long) | Specifies the width of the grabbed image. Please note the step width of the width parameter. If a non-valid value is set, it is adjusted to the next valid value. | |||
| 'offset' | offset (long) | Specifies the offset (clamp level) of the camera. | |||
| 'start_column' | start_column (long) | Specifies the start column of the grabbed image. Please note the step width of the width parameter. If a non-valid value is set, it is adjusted to the next valid value. | |||
| 'start_row' | start_row (long) | Specifies the start row of the grabbed image. Please note the step height of the height parameter. If a non-valid value is set, it is adjusted to the next valid value. | |||
| 'shutter_delay' | delay (long) | Specify the delay of the shutter in milliseconds. The camera waits the specified time after the trigger pulse before starting the exposure. | |||
| 'shutter_speed' | shutter_speed (long) | Specifies the shutter speed. In continuous mode 0 means shutter speed is off (see Sony documentation for more details). | |||
| 'strobe_delay' | 0 ... 4095 (long) | Sets the strobe delay value between 0 and 4095 microseconds. | |||
| 'test_image' | 0, 1, 2, 3, 7 (long) | Sets a gray scale test image (see Sony documentation for more details). Default: 0 (no test image). | |||
| 'trigger_signal' | 'falling', 'rising' | Specifies the trigger signal. | |||
| 'trigger_mode' | 'enable', 'disable' | Sets the trigger counter operation mode. | |||
| 'vertical_binning' | 'enable', 'disable' | Grayscale only. Specifies the vertical binning mode. | |||
| 'volatile' | 'enable', 'disable' | In the volatile mode the image acquisition interface buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'disable'. | |||
| 'white_balance' | 'off', '3200k', '5600k', 'user-preset', 'one-push', 'auto' | Sets the white balance mode. | |||
| 'white_balance_target_blue' | -128 ... 127 | Sets the blue convergent value (correction value) during the auto white balance mode. | |||
| 'white_balance_target_red' | -128 ... 127 | Sets the red convergent value (correction value) during the auto white balance mode. | |||
| 'wide_dynamic_range' | 'enable', 'disable' | Sets the wide dynamic range feature (see Sony documentation for more details). | |||
| 'wide_dynamic_range_speed1' | speed1 (long) | Sets the shutter speed1 of wide dynamic range feature (see Sony documentation for more details). | |||
| 'wide_dynamic_range_speed2' | speed2 (long) | Sets the shutter speed2 of wide dynamic range feature (see Sony documentation for more details). | |||
Parameters for get_framegrabber_param():
Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:
- '_description': These parameters provide the tooltip of the corresponding parameter as a string.
- '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'shutter_speed_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
- '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].
| 'com_trigger_counter' | com_trigger_counter (long) | Gets the common trigger total count value. | |||
| 'driver_version' | version (long) | Returns the major version number of the camera driver. | |||
| 'frame_rate' | frame_rate (long) | Returns the ideal frames per second value. | |||
| 'gpio_dipsw_input:X' | 0, 1 (long) | Status of the dip switch (with X = 1,2,3,4 as unique index of the desired GPIO line). | |||
| 'gpio_iso_input:X' | 0, 1 (long) | Status of the isolated input channel (with X = 1,2,3,4 as unique index of the desired GPIO line). | |||
| 'image_available' | 0, 1 (long) | Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. In particular, this functionality might be useful in combination with external triggering. | |||
| 'product_information' | product_information (string) | Gets the model identification information of the camera. | |||
| 'revision' | revision (string) | The revision number of the HALCON SonyXCI-2 interface. | |||
| 'serial_number' | serial_number (long) | Returns the serial number of the camera. | |||
| 'trigger_counter' | trigger_counter (long) | Gets the trigger total count value. | |||
Release Notes
-
Revision 4.5 (Jun 10, 2011):
- Fixed bug in grab_image and grab_image_async that caused grabbing black images in external trigger mode.
-
Revision 4.4 (Apr 8, 2011):
- Added GPIO parameters 'gpio_output:X' and 'gpio_status_led'.
- Renamed GPIO parameters 'digital_delay_step' to 'gpio_delay_step', 'digital_delay_select' to 'gpio_delay_select', 'digital_delay_source_select' to 'gpio_delay_source_select', 'digital_output_select' to 'gpio_output_select:X', 'gpio_iso_input' to 'gpio_iso_input:X', and 'gpio_ttl_input' to 'gpio_dipsw_input:X'.
- Fixed bug to ensure correct behavior of parameter 'image_available'.
- Changed the default setting of parameter 'continuous_grabbing' from 'enable' to 'disable'.
- Removed the automatic activation of the auto white balance mode when setting a value for the parameters 'white_balance_target_blue' and 'white_balance_target_red'.
- Reviewed this HTML documentation.
-
Revision 4.3 (Jan 22, 2010):
- Added error handling for parameter 'image_part'.
- Code review for adapting the actual image size via the parameters 'image_width', 'image_height', 'start_column', and 'start_row'.
- Added missing parameter 'shutter_speed_range'.
- HALCON 10 version of the interface (included in HALCON 10 DVD).
-
Revision 4.2 (Jul 31, 2009):
- Fixed bug in the correct handling of the valid (camera model dependent) values for the parameters 'image_width', 'image_height', 'start_row', 'start_column', and 'image_part'.
- Fixed bug in 'horizontal_binning'.
-
Revision 4.1 (Mar 24, 2009):
- New parameters 'white_balance', 'do_white_balance', 'white_balance_target_red', and 'white_balance_target_blue'.
- Support of grabbing YUV images.
- Support of volatile grabbing also for RGB and YUV images.
- Fixed bug in color conversion.
- Fixed bug in grabbing images with Sony XCI-V100/C cameras.
-
Revision 4.0 (Dec 1, 2008):
- First official release.
