Interface Documentation
Image Acquisition Interface for Andor Scientific Cameras
| Interface: | Andor |
| Revision: | 13.0.1 |
| Date: | 2016-10-28 |
| HALCON Version: | 13.0 |
- General
- System Requirements
- Features
- Limitations
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- HDevelop Examples
- Release Notes
General
This page provides the documentation of the HALCON Andor image acquisition interface for accessing the scientific cameras from
Andor Technology.
Registered customers can download the
latest revision of this interface from the
MVTec WWW server.
System Requirements
- Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK.
- Andor device drivers included in Andor SDK 2.
- Andor DLL atmcd32d.dll version 2.100 or higher. Please download and install the needed SDK from Andor Technology. This DLL must be within your search path %PATH% (typically, it resides in the directory of the Andor installation path.
- HALCON image acquisition interface hAcqAndor.dll
or hAcqAndorxl.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 a variety of camera parameters.
- Cropping of image parts.
- Support of dual exposure mode to grab images with different internal exposure times, without the need of further settings.
- Tested on the following cameras: Luca-S, Luca-R, iKon-M and iXon. However, the interface will work with any Andor camera.
Limitations
- Using multiple cameras at the same time not supported yet.
Parameters for info_framegrabber
| Parameter | Value List | Type | Kind | Description |
|---|---|---|---|---|
| 'bits_per_channel' | [] | Unused. | ||
| 'camera_type' | [] | Unused. | ||
| 'color_space' | [] | Unused. | ||
| 'defaults' | [1, 1, 0, 0, 0, 0, 'progressive', -1, 'gray', -1.0, 'false', 'default', '0', 1, 0] | mixed | pre-defined | Default values for open_framegrabber. |
| 'device' | ['0', '1', '2', '3'] | string | pre-defined | Pre-defined list of possible device IDs. |
| 'external_trigger' | ['false', 'true'] | string | pre-defined | Values for the external trigger. |
| 'field' | [] | Unused. | ||
| 'general' | [] | string | pre-defined | Information about the HALCON Andor interface. |
| 'generic' | [] | Unused. | ||
| 'horizontal_resolution' | [1, 2, 4] | integer | pre-defined | Value list for horizontal resolution. |
| 'image_height' | [] | Unsupported query. | ||
| 'image_width' | [] | Unsupported query. | ||
| 'info_boards' | ['device:<device_id>'] | string | dynamic | A list of the available devices. |
| 'parameters' | ['<parameters>'] | string | pre-defined | Pre-defined parameters of the HALCON interface. |
| 'parameters_readonly' | ['<parameters>'] | string | pre-defined | Pre-defined read-only parameters of the HALCON interface. |
| 'parameters_writeonly' | ['<parameters>'] | string | pre-defined | Pre-defined write-only parameters of the HALCON interface. |
| 'port' | [] | Unused. | ||
| 'revision' | '<revision>' | string | pre-defined | Revision number of the Andor interface. |
| 'start_column' | [] | Unsupported query. | ||
| 'start_row' | [] | Unsupported query. | ||
| 'vertical_resolution' | [1, 2, 4] | integer | pre-defined | Value list for vertical resolution. |
Parameters for open_framegrabber
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| Name | 'Andor' | string | Name of the HALCON interface. | |
| HorizontalResolution | 1, 2, 3, 4 | 1 | integer | Desired horizontal resolution of the camera image:
|
| VerticalResolution | 1, 2, 3, 4 | 1 | integer | Desired vertical resolution of the camera image:
|
| ImageWidth | 0, <width> | 0 | integer | Width of the desired image part ('0' stands for the complete image). |
| ImageHeight | 0, <height> | 0 | integer | Height of the desired image part ('0' stands for the complete image). |
| StartRow | 0, <row> | 0 | integer | Row coordinate of the upper left pixel within the desired image part. |
| StartColumn | 0, <column> | 0 | integer | Column coordinate of the upper left pixel within the desired image part. |
| Field | --- | Ignored. | ||
| BitsPerChannel | --- | -1 | Ignored. | |
| ColorSpace | 'gray' | 'gray' | string | Only the gray formats are supported by the camera models. |
| Generic | --- | Ignored. | ||
| ExternalTrigger | 'false', 'true' | 'false' | string | Status of the external trigger. |
| CameraType | --- | Ignored. | ||
| Device | --- | Ignored. | ||
| Port | --- | 1 | Ignored. | |
| LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| 'ad_channel' | <channel> | integer | A/D channel to one of the possible A/D's in the system. | |
| 'baseline_clamp' | 'disable', 'enable' | 'disable' | string | Baseline level of each scan in a series. |
| 'continuous_grabbing' | 'disable', 'enable' | 'disable' | string | Single scan or continuous capture mode (video mode) of the camera. The continuous mode is related to the 'RunTillAbort' parameter described in the Andor documentation. |
| 'cooler' | 'off', 'on' | 'on' | string | Running state of the device cooler (please keep in mind, that this feature is not supported by every camera model). |
| 'do_abort_grab' | --- | Cancel current grab. | ||
| 'do_force_trigger' | --- | Forces an event trigger when using software trigger. This might be useful for testing purposes. | ||
| 'do_prepare_acquisition' | --- | Update any data that has changed without starting the image acquisition. | ||
| 'do_start_video' | --- | Starts the camera running in video mode. In this mode the camera will continuously grab images, which the user can get using grab_image or grab_image_async, until the action parameter 'do_abort_grab' is called. | ||
| 'dual_exposure_mode' | 'disable', 'enable' | string | Dual exposure mode. Dual exposure mode will acquire 2 images at two different exposure times for every trigger that is sent to the camera. It will only operate on certain cameras. The parameter 'continuous_grabbing' must be set to 'continuous' (video mode), and the parameter 'trigger_source' must be set to 'hardware'. | |
| 'dual_exposure_time_1' | <seconds> | 0 | float | First dual exposure time in seconds of the camera. |
| 'dual_exposure_time_2' | <seconds> | 0 | float | Second dual exposure time in seconds of the camera. |
| 'em_advanced' | 'off', 'on' | string | The parameter turns 'on' and 'off' access to higher EM gain levels. | |
| 'em_gain' | <gain> | integer | CCD gain value. The valid range depends on what gain mode the camera is operating in. | |
| 'em_gain_mode' | 'dac_255', 'dac_4095', 'linear', 'real' | string | EM gain mode. | |
| 'exposure' | <seconds> | 0.1 | float | Desired exposure time in seconds of the camera |
| 'fan_mode' | 'full', 'low', 'off' | 'full' | string | Mode of the camera fan. If the system is cooled, the fan should only be turned off for short periods of time. During the time, the body of the camera will warm up which could compromise cooling capabilities. If the camera temperature gets to high, some models will signal an alarm via a buzzer. If this happens, turn off the external power supply and allow the system to stabilize before continuing. |
| 'frame_transfer' | 'off', 'on' | string | Enables/disables frame transfer mode. | |
| 'grab_timeout' | <milliseconds> | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
| 'horizontal_binning' | 1, 2, 3, 4 | 1 | integer | Horizontal binning factor. |
| 'hs_speed' | <speed> | integer | Shift speed of the pixels when they are shifted into the output node during the acquisition readout phase. Typically the camera will be capable of operating several shift speeds. Please keep in mind, that several cameras also support the 'output_amplifier' parameter which could also affect the 'hs_speed' parameter. | |
| 'image_height' | <height> | integer | Height of the desired image part ('0' stands for the complete image). | |
| 'image_width' | <width> | integer | Width of the desired image part ('0' stands for the complete image). | |
| 'output_amplifier' | <index> | 0 | integer | Index of the used output amplifier. If multiple amplifiers are supported by the device, please check the camera documentation for detailed amplifier description. The 'output_amplifier' parameter is also internally used by the 'hs_speed' and 'num_hs_speeds' parameters. |
| 'preamp_gain' | <gain> | -1 | float | Pre-amp gain to be used for subsequent acquisition. |
| 'shutter_closetime' | <milliseconds> | 1 | integer | Time in milliseconds specifies how long the shutter needs to close. |
| 'shutter_mode' | 'auto', 'close', 'open' | string | The parameter configures whether the shutter open and closes automatically with the value 'auto'. Setting the value to 'open' forces a permanently opened shutter. With 'close' the shutter is closed permanently. | |
| 'shutter_opentime' | <milliseconds> | 1 | integer | Time in milliseconds specifies how long the shutter needs to open. |
| 'shutter_ttl' | 'low', 'high' | 'low' | string | Behavior of the shutter. With 'low' the output TTL low signal will open the shutter. With 'high' the output TTL high signal will close the shutter. |
| 'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted. |
| 'start_column' | <column> | integer | Column coordinate of the upper left pixel within the desired image part. | |
| 'start_row' | <row> | integer | Row coordinate of the upper left pixel within the desired image part. | |
| 'target_temperature' | <degree> | integer | Target temperature in Celsius the camera should achieve. The current status could be queried with the 'temperature_status' parameter. | |
| 'trigger_source' | 'internal', 'hardware', 'software' | 'internal' | string | One of the trigger sources. Be aware of the settings your camera supplies. |
| 'vertical_binning' | 1, 2, 3, 4 | 1 | integer | Vertical binning factor. |
| 'vs_speed' | <speed> | integer | Shift speed of the pixels when they are shifted into the output node during the acquisition readout phase. Typically the camera will be capable of operating several shift speeds. |
Parameters for get_framegrabber_param
There may exist additional read-only parameters with the following postfixes:
- '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
- '_range': These parameters provide the minimum, maximum, step width, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, default].
- '_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'].
All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.
| Parameter | Values | Default | Type | Kind | Description |
|---|---|---|---|---|---|
| 'ad_channel' | <channel> | integer | dynamic | A/D channel to one of the possible A/D's in the system. | |
| 'baseline_clamp' | 'disable', 'enable' | 'disable' | string | dynamic | Baseline level of each scan in a series. |
| 'bits_per_channel' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'camera_type' | '<default>' | 'default' | string | pre-defined | The value is not used, so a default value is returned. |
| 'color_space' | 'gray' | 'gray' | string | pre-defined | Desired color space and thus the number of image channels of the resulting HALCON image. |
| 'continuous_grabbing' | 'disable', 'enable' | 'disable' | string | pre-defined | Single scan or continuous capture mode (video mode) of the camera. The continuous mode is related to the 'RunTillAbort' parameter described in the Andor documentation. |
| 'cooler' | 'off', 'on' | 'on' | string | dynamic | Running state of the device cooler (please keep in mind, that this feature is not supported by every camera model). |
| 'device' | '<device_id>' | string | dynamic | Current device ID. | |
| 'dual_exposure_mode' | 'disable', 'enable' | string | dynamic | Dual exposure mode. Dual exposure mode will acquire 2 images at two different exposure times for every trigger that is sent to the camera. It will only operate on certain cameras. The parameter 'continuous_grabbing' must be set to 'continuous' (video mode), and the parameter 'trigger_source' must be set to 'hardware'. | |
| 'dual_exposure_time_1' | <seconds> | 0 | float | dynamic | First dual exposure time in seconds of the camera. |
| 'dual_exposure_time_2' | <seconds> | 0 | float | dynamic | Second dual exposure time in seconds of the camera. |
| 'em_advanced' | 'off', 'on' | string | dynamic | The parameter turns 'on' and 'off' access to higher EM gain levels. | |
| 'em_gain' | <gain> | integer | dynamic | CCD gain value. The valid range depends on what gain mode the camera is operating in. | |
| 'em_gain_mode' | 'dac_255', 'dac_4095', 'linear', 'real' | string | dynamic | EM gain mode. | |
| 'exposure' | <seconds> | 0.1 | float | dynamic | Desired exposure time in seconds of the camera |
| 'external_trigger' | 'false', 'true' | 'false' | string | pre-defined | Status of the external trigger. |
| 'fan_mode' | 'full', 'low', 'off' | 'full' | string | dynamic | Mode of the camera fan. If the system is cooled, the fan should only be turned off for short periods of time. During the time, the body of the camera will warm up which could compromise cooling capabilities. If the camera temperature gets to high, some models will signal an alarm via a buzzer. If this happens, turn off the external power supply and allow the system to stabilize before continuing. |
| 'field' | '<default>' | 'progressive' | string | pre-defined | The value is not used, so a default value is returned. |
| 'frame_transfer' | 'off', 'on' | string | dynamic | Enables/disables frame transfer mode. | |
| 'generic' | <default> | -1 | mixed | pre-defined | The value is not used, so a default value is returned. |
| 'grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
| 'horizontal_binning' | 1, 2, 3, 4 | 1 | integer | pre-defined | Horizontal binning factor. |
| 'horizontal_resolution' | 1, 2, 4 | 1 | integer | pre-defined | Horizontal binning factor. |
| 'hs_speed' | <speed> | integer | dynamic | Shift speed of the pixels when they are shifted into the output node during the acquisition readout phase. Typically the camera will be capable of operating several shift speeds. Please keep in mind, that several cameras also support the 'output_amplifier' parameter which could also affect the 'hs_speed' parameter. | |
| 'image_height' | <height> | 0 | integer | pre-defined | Height of the desired image part ('0' stands for the complete image). |
| 'image_width' | <width> | 0 | integer | pre-defined | Width of the desired image part ('0' stands for the complete image). |
| 'line_in' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'name' | 'Andor' | string | pre-defined | Name of the HALCON interface. | |
| 'num_ad_channels' | <number_channels> | integer | dynamic | Number of supported ad channels. | |
| 'num_amplifier' | <number_amplifiers> | integer | dynamic | Number of supported amplifiers. | |
| 'num_hs_speeds' | <microseconds> | integer | dynamic | Number of the horizontal shift speeds in microseconds which are supported by the device. The camera will be capable of operating several shift speeds. Please keep in mind, that several cameras also support the 'output_amplifier' parameter. The number of shift speeds is also based on the currently set amplifier type. | |
| 'num_vs_speeds' | <microseconds> | integer | dynamic | Number of the vertical shift speeds in microseconds which are supported by the device. | |
| 'output_amplifier' | <index> | 0 | integer | dynamic | Index of the used output amplifier. If multiple amplifiers are supported by the device, please check the camera documentation for detailed amplifier description. The 'output_amplifier' parameter is also internally used by the 'hs_speed' and 'num_hs_speeds' parameters. |
| 'port' | <port> | 1 | integer | pre-defined | Current port number. |
| 'preamp_gain' | <gain> | -1 | float | dynamic | Pre-amp gain to be used for subsequent acquisition. |
| 'preamp_gain_text' | <gain> | integer | dynamic | Gets the supported preamp gain values. | |
| 'revision' | '<revision>' | string | pre-defined | Revision number of the Andor interface. | |
| 'shutter_closetime' | <milliseconds> | 1 | integer | dynamic | Time in milliseconds specifies how long the shutter needs to close. |
| 'shutter_mode' | 'auto', 'close', 'open' | string | dynamic | The parameter configures whether the shutter open and closes automatically with the value 'auto'. Setting the value to 'open' forces a permanently opened shutter. With 'close' the shutter is closed permanently. | |
| 'shutter_opentime' | <milliseconds> | 1 | integer | dynamic | Time in milliseconds specifies how long the shutter needs to open. |
| 'shutter_ttl' | 'low', 'high' | 'low' | string | dynamic | Behavior of the shutter. With 'low' the output TTL low signal will open the shutter. With 'high' the output TTL high signal will close the shutter. |
| 'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | pre-defined | Status of 'start_async_after_grab_async'. |
| 'start_column' | <column> | 0 | integer | pre-defined | Returns the current start column of the HALCON image. |
| 'start_row' | <row> | 0 | integer | pre-defined | Returns the current start row of the HALCON image. |
| 'target_temperature' | <degree> | integer | dynamic | Target temperature in Celsius the camera should achieve. The current status could be queried with the 'temperature_status' parameter. | |
| 'temperature' | <degree> | integer | dynamic | Current temperature in Celsius. | |
| 'temperature_float' | <degree> | float | dynamic | Current temperature in Celsius as float type. | |
| 'temperature_status' | <status> | integer | dynamic | Status of the cooling state of the camera. | |
| 'trigger_source' | 'internal', 'hardware', 'software' | 'internal' | string | dynamic | One of the trigger sources. Be aware of the settings your camera supplies. |
| 'vertical_binning' | 1, 2, 3, 4 | 1 | integer | pre-defined | Vertical binning factor. |
| 'vertical_resolution' | 1, 2, 4 | 1 | integer | pre-defined | Vertical binning factor. |
| 'video_running' | 'false', 'true' | 'false' | string | dynamic | Information whether the video mode is active or not. |
| 'vs_speed' | <speed> | integer | dynamic | Shift speed of the pixels when they are shifted into the output node during the acquisition readout phase. Typically the camera will be capable of operating several shift speeds. |
Operator set_framegrabber_lut
Not supported by this interface.
Operator get_framegrabber_lut
Not supported by this interface.
Operator set_framegrabber_callback
Not supported by this interface.
Operator get_framegrabber_callback
Not supported by this interface.
Operator grab_image_start
Starts a new asynchronous grab. See also grab_image_start.
Operator grab_image
grab_image starts a new synchronous grab. See also grab_image. Note that
the interface converts the image from the device to the desired image format
specified by the parameters 'image_width', 'image_height', 'start_row',
'start_column', 'bits_per_channel', and 'color_space'.
Operator grab_image_async
grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async.
Note that
the interface converts the image from the device to the desired image format
specified by the parameters 'image_width', 'image_height', 'start_row',
'start_column', 'bits_per_channel', and 'color_space'.
Operator grab_data
Not supported by this interface.
Operator grab_data_async
Not supported by this interface.
Operator close_framegrabber
This operator closes the device. See also close_framegrabber.
HDevelop Examples
For this interface there are the following examples available:
- andor.hdev - Benchmark
- andor_parameters.hdev - Lists all parameters of a device.
- andor_simple.hdev - A simple example to show the usage of the interface.
Release Notes
- Revision 13.0.1 (Oct 28, 2016):
- HALCON 13 version of the interface.
- Revision 6.0 Addendum (Feb 15, 2016):
- Adapted documentation. Now, the system requirements section refers to the new Andor SDK 2 version which is full compatible with this interface.
- Revision 6.0 (Oct 31, 2014):
- HALCON 12 version of the interface.
- Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- Adapted to new SDK version 2.93.
- Added support for Windows x64.
- Added new parameters 'preamp_gain_text', 'shutter_min_closetime' and 'shutter_min_opentime'.
- Fixed thread safety problem in grab_image and grab_image_async that could occur if a pending grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param.
- Revision 4.3 (Apr 18, 2011):
- Added new parameters 'fan_mode', 'temperature_float', 'image_width', 'image_height', 'start_row', and 'start_column'.
- Fixed bug in parameter 'do_abort_grab' to ensure the proper abort of all current image acquisition activities.
- Revision 4.2 (Dec 10, 2010):
- Added new parameters 'output_amplifier' and 'num_amplifiers'.
- Changed default shutter values: Set 'shutter_mode' to 'open', 'shutter_ttl' to 'high', and the 'shutter_opentime' and 'shutter_closetime' to 0.
- Revision 4.1 (Aug 10, 2010):
- Adapted to SDK version 2.88.
- Added new parameters 'continuous_grabbing', 'do_start_video', 'dual_exposure_mode', 'dual_exposure_time_1', 'dual_exposure_time_2', and 'video_running'.
- HALCON 10 version of the interface (included in HALCON 10 DVD).
- Revision 4.0 (Jan 12, 2010):
- First official release.