Image Acquisition for VC-Z embedded device

Interface: VC-Z
Revision: 6.0.70
Date: 2018-02-14
HALCON Version: 13.0

General

This page provides the documentation of the HALCON image acquistion for VC-Z embedded device from Vision Components.
Vision Components customers can ask the latest revision of this interface.
The evaluation version of this interface has no restriction but it shows a logo inside the grabbed images.

System Requirements

The system requirements for the interface are lited below:

Features

Limitations

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [-1, 8] integer pre-defined Values for bits per channel.
'color_space' ['default', 'gray', 'rgb', 'yuv', 'bayer'] string pre-defined Values for color space.
'defaults' [0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1, 'false', 'default', 'default', -1, -1] mixed pre-defined Default values for open_framegrabber.
'device' string dynamic Name of the device detected. There is only one by embedded device, you must use 'default' value.
'field' [] Unused.
'general' [1, 0, 0] string pre-defined HALCON image acquisition interface for VC-Z embedded devices. Version of libvclinux compiled with this interface.
'generic' ['', 'num_buffers=<num>'] string pre-defined Value list for the Generic parameter.
'horizontal_resolution' [1, 2, 4, 8] integer Specifies the horizontal sub-sampling ratio for the image resolution (cpt.sen[0].subsmplX):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
The subsampling and ROI on sensor could be defined by these parameters:
  • horizontal_resolution -> cpt.sen[0].subsmplX
  • vertical_resolution -> cpt.sen[0].subsmplY
  • start_row -> cpt.sen[0].y0
  • start_column -> cpt.sen[0].x0
  • image_width -> cpt.sen[0].img.dx
  • image_height -> cpt.sen[0].img.dy
This image shows you the effect on pixel position after a subsampling and a ROI on the sensor:
Pixel Positions Under Subsampling
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' string Lists the device available but there is always one: 'device:default'.
'parameters' ['<parameters>'] string pre-defined Pre-defined parameters of the VC-Z HALCON interface.
'parameters_readonly' ['<parameters>'] string pre-defined Pre-defined read-only parameters of the VC-Z HALCON interface.
'parameters_writeonly' ['<parameters>'] string pre-defined Pre-defined write-only parameters of the VC-Z HALCON interface.
'port' [] pre-defined Unused.
'revision' '<revision>' string pre-defined Revision number of the VC-Z interface.
'start_column' [] integer Specifies the index of the starting column to define a ROI (cpt.sen[0].x0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'start_row' [] integer Specifies the index of the starting row to define a ROI (cpt.sen[0].y0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'vertical_resolution' [1, 2, 4, 8] integer Specifies the vertical sub-sampling ratio for the image resolution (cpt.sen[0].subsmplY):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
To understand how to set a subsampling on the sensor, have a look at the parameter 'horizontal_resolution'.

Parameters for open_framegrabber

Parameter Values Default Type Description
BitsPerChannel -1, 8 -1 integer Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. Currently the device does not support a value greater than 8.
Device string Name of the device detected. There is only one by embedded device, you must use 'default' value.
HorizontalResolution 1, 2, 4, 8, resolution 0 integer Specifies the horizontal sub-sampling ratio for the image resolution (cpt.sen[0].subsmplX):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
The subsampling and ROI on sensor could be defined by these parameters:
  • horizontal_resolution -> cpt.sen[0].subsmplX
  • vertical_resolution -> cpt.sen[0].subsmplY
  • start_row -> cpt.sen[0].y0
  • start_column -> cpt.sen[0].x0
  • image_width -> cpt.sen[0].img.dx
  • image_height -> cpt.sen[0].img.dy
This image shows you the effect on pixel position after a subsampling and a ROI on the sensor:
Pixel Positions Under Subsampling
VerticalResolution 1, 2, 4, 8, resolution 0 integer Specifies the vertical sub-sampling ratio for the image resolution (cpt.sen[0].subsmplY):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
To understand how to set a subsampling on the sensor, have a look at the parameter 'horizontal_resolution'.
ImageWidth 0, <width> 0 integer Width of the desired image part ('0' stands for the complete image). Specifies the width of the image to define a ROI (cpt.sen[0].img.dx). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
ImageHeight 0, <height> 0 integer Height of the desired image part ('0' stands for the complete image). Specifies the height of the image to define a ROI (cpt.sen[0].img.dy). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
StartRow 0, <row> 0 integer Specifies the index of the starting row to define a ROI (cpt.sen[0].y0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
StartColumn 0, <column> 0 integer Specifies the index of the starting column to define a ROI (cpt.sen[0].x0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
Field --- Ignored.
ColorSpace 'default', 'gray', 'rgb', 'yuv', 'bayer' 'default' string Desired color space and thus the number of image channels of the resulting HALCON image. Currently there are these colospace for monochrome or color camera:
  • On monochrome camera, 'default' = 'gray'.
  • On color camera, 'default' = 'rgb'.
  • On color camera, you can force this parameter during the connection (open_framegrabber) to:
    • 'gray' in order to get monochrome images.
    • 'rgb' in order to get RGB images.
    • 'yuv' in order to get YUV or YCbCr images.
    • 'bayer' in order to get bayer pattern images.
Generic '', 'num_buffers=<num>', -1 -1 mixed With the Generic parameter some important values can be set before the camera is initialized. Note that the parameter names including the values must be strings, e.g., 'num_buffers=5' sets the number of buffers to 5.
The following parameters are available:
  • num_buffers: To set the maximum number of buffers in the HALCON acquisition interface, a value greater than 1 has to be used. Note that depending on the image size of the used camera a high number of buffers can exceed the available memory size of your computer. We recommend to use at least 2 buffers. Default: 4.
ExternalTrigger 'false', 'true' 'false' string External Trigger: if 'false' -> freerun or 'true' -> external trigger mode with the TrigIn line.
Port <port> -1 integer Unused.

Parameters for set_framegrabber_param

Parameter Values Default Type Description
'debug' mixed Print values (Tuple) in the console (printf). Useful for debugging on the embedded device, not for acquisition topic.
'debug_capt' mixed Prints the values of the VCCaptCfg struct to the console (printf). Useful for debugging on the embedded device, not for acquisition topic.
'do_abort_grab' --- Cancel current grab.
'exposure' 10000 integer Exposure Time in Microseconds.
'external_trigger' 'false', 'true' string External Trigger: if 'false' -> freerun or 'true' -> external trigger mode with the TrigIn line.
'flip' 'none', 'hor', 'vert' 'none' string This parameter identifies the Sensor Flipping mode.
'gain' 96.0 double Gain Value.
'grab_timeout' integer Specifies the desired timeout for aborting a pending grab in milliseconds.
'horizontal_resolution' 1, 2, 4, 8, resolution integer Specifies the horizontal sub-sampling ratio for the image resolution (cpt.sen[0].subsmplX):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
The subsampling and ROI on sensor could be defined by these parameters:
  • horizontal_resolution -> cpt.sen[0].subsmplX
  • vertical_resolution -> cpt.sen[0].subsmplY
  • start_row -> cpt.sen[0].y0
  • start_column -> cpt.sen[0].x0
  • image_width -> cpt.sen[0].img.dx
  • image_height -> cpt.sen[0].img.dy
This image shows you the effect on pixel position after a subsampling and a ROI on the sensor:
Pixel Positions Under Subsampling
'image_height' <height> integer Height of the desired image part ('0' stands for the complete image). Specifies the height of the image to define a ROI (cpt.sen[0].img.dy). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'image_width' <width> integer Width of the desired image part ('0' stands for the complete image). Specifies the width of the image to define a ROI (cpt.sen[0].img.dx). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'start_column' <column> integer Specifies the index of the starting column to define a ROI (cpt.sen[0].x0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'start_row' <row> integer Specifies the index of the starting row to define a ROI (cpt.sen[0].y0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'strobe' 'none', 'ringled', 'flash0', 'flash1', '0', '1', '31' 'none' string Activate an output during the exposure time of the sensor. By default, no output are strobed, the value is 'none'. If the value is 'ringled', the ring LEDs of the VC Pro Z will be strobed. Otherwise you can set a custom GPIO Nr, for example '0', '1', ...
For every VC Z camera, the values should a conbination of these values:
  • 'none', no output is strobed during exposure time.
  • '0', the GPIONr 0 (OUT0) will be strobed during exposure time.
  • '1', the GPIONr 1 (OUT1) will be strobed during exposure time.
  • '2', the GPIONr 2 (OUT2) will be strobed during exposure time.
  • '3', the GPIONr 3 (OUT3) will be strobed during exposure time.
  • '31', the GPIONr 31 (TrigOut) will be strobed during exposure time.
For VC ProZ camera, there are more possibilities for 4 LED controllers:
  • 'ringled', the GPIONr 19 and 20 for the integrated ring LEDs will be strobed during exposure time.
  • 'flash0', the GPIONr 31 (TrigOut), the LED controller Flash0 will be strobed during exposure time.
  • 'flash1', the GPIONr 18 (Flash1), the LED controller Flash1 will be strobed during exposure time.
For VC ProZ camera, the 4 LED controllers are set to provide maximum current, 1.5A by default, during the exposure time with a limit of 100us.
'vertical_resolution' 1, 2, 4, 8, resolution integer Specifies the vertical sub-sampling ratio for the image resolution (cpt.sen[0].subsmplY):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
To understand how to set a subsampling on the sensor, have a look at the parameter 'horizontal_resolution'.

Parameters for get_framegrabber_param

Parameter Values Default Type Kind Description
'bits_per_channel' -1, 8 -1 integer pre-defined Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. Currently the device does not support a value greater than 8.
'camera_type' string Type of the VC device.
'color_space' 'default', 'gray', 'rgb', 'yuv', 'bayer' string pre-defined Desired color space and thus the number of image channels of the resulting HALCON image. Currently there are these colospace for monochrome or color camera:
  • On monochrome camera, 'default' = 'gray'.
  • On color camera, 'default' = 'rgb'.
  • On color camera, you can force this parameter during the connection (open_framegrabber) to:
    • 'gray' in order to get monochrome images.
    • 'rgb' in order to get RGB images.
    • 'yuv' in order to get YUV or YCbCr images.
    • 'bayer' in order to get bayer pattern images.
'device' string dynamic Name of the device detected. There is only one by embedded device, you must use 'default' value.
'exposure' 10000 integer Exposure Time in Microseconds.
'external_trigger' 'false', 'true' 'false' string External Trigger: if 'false' -> freerun or 'true' -> external trigger mode with the TrigIn line.
'field' '<default>' 'default' string pre-defined The value is not used, so a default value is returned.
'flip' 'none', 'hor', 'vert' 'none' string This parameter identifies the Sensor Flipping mode.
'gain' 96.0 double Gain Value.
'generic' '', 'num_buffers=<num>', -1 -1 mixed pre-defined Values of the Generic parameter.
'grab_timeout' integer Specifies the desired timeout for aborting a pending grab in milliseconds.
'horizontal_resolution' 1, 2, 4, 8, resolution 0 integer Specifies the horizontal sub-sampling ratio for the image resolution (cpt.sen[0].subsmplX):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
The subsampling and ROI on sensor could be defined by these parameters:
  • horizontal_resolution -> cpt.sen[0].subsmplX
  • vertical_resolution -> cpt.sen[0].subsmplY
  • start_row -> cpt.sen[0].y0
  • start_column -> cpt.sen[0].x0
  • image_width -> cpt.sen[0].img.dx
  • image_height -> cpt.sen[0].img.dy
This image shows you the effect on pixel position after a subsampling and a ROI on the sensor:
Pixel Positions Under Subsampling
'image_height' <height> 0 integer pre-defined Height of the desired image part ('0' stands for the complete image). Specifies the height of the image to define a ROI (cpt.sen[0].img.dy). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'image_width' <width> 0 integer pre-defined Width of the desired image part ('0' stands for the complete image). Specifies the width of the image to define a ROI (cpt.sen[0].img.dx). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'mac_address' '00:00:00:00:00:00' string MAC address of the device (eth0).
'num_buffers' <number> 4 integer pre-defined Number of buffers used for the internal VC image acquisition. Could be adjusted with the parameter generic in open_framegrabber().
'port' <port> -1 integer pre-defined Current port number.
'revision' '<revision>' string pre-defined Revision number of the VC-Z interface.
'sn' '0000000' string Serial number of the device (s/n).
'start_column' <column> 0 integer Specifies the index of the starting column to define a ROI (cpt.sen[0].x0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'start_row' <row> 0 integer Specifies the index of the starting row to define a ROI (cpt.sen[0].y0). To understand how to set a ROI on the sensor, have a look at the parameter 'horizontal_resolution'.
'strobe' 'none', 'ringled', 'flash0', 'flash1', '0', '1', '31' 'none' string Activate an output during the exposure time of the sensor. By default, no output are strobed, the value is 'none'. If the value is 'ringled', the ring LEDs of the VC Pro Z will be strobed. Otherwise you can set a custom GPIO Nr, for example '0', '1', ...
For every VC Z camera, the values should a conbination of these values:
  • 'none', no output is strobed during exposure time.
  • '0', the GPIONr 0 (OUT0) will be strobed during exposure time.
  • '1', the GPIONr 1 (OUT1) will be strobed during exposure time.
  • '2', the GPIONr 2 (OUT2) will be strobed during exposure time.
  • '3', the GPIONr 3 (OUT3) will be strobed during exposure time.
  • '31', the GPIONr 31 (TrigOut) will be strobed during exposure time.
For VC ProZ camera, there are more possibilities for 4 LED controllers:
  • 'ringled', the GPIONr 19 and 20 for the integrated ring LEDs will be strobed during exposure time.
  • 'flash0', the GPIONr 31 (TrigOut), the LED controller Flash0 will be strobed during exposure time.
  • 'flash1', the GPIONr 18 (Flash1), the LED controller Flash1 will be strobed during exposure time.
For VC ProZ camera, the 4 LED controllers are set to provide maximum current, 1.5A by default, during the exposure time with a limit of 100us.
'vertical_resolution' 1, 2, 4, 8, resolution 0 integer Specifies the vertical sub-sampling ratio for the image resolution (cpt.sen[0].subsmplY):
  • 0: Use full resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
  • resolution: User defined horizontal resolution is set.
To understand how to set a subsampling on the sensor, have a look at the parameter 'horizontal_resolution'.
'volatile' 'disable', 'enable' 'enable' string pre-defined You can not set this parameter. It is enable by default to optimize the performance of the embedded device. In the volatile mode the VC acquisition buffers (cpt.sen[0].img.st) 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! The volatile mode switches automatically to disable when the the line pitch of the VC buffer does not equal PixelSize * ImageWidth, it is due to the HALCON image internal structure.

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

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'

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:

Release Notes


Legal disclaimer regarding hyperlinks: This page may provide users with access by hypertext links to external, non-MVTec websites. Any such access is provided with the understanding that the contents of non-MVTec sites are beyond the control of MVTec Software GmbH, that MVTec Software GmbH makes no representations whatsoever about such sites, and that users shall proceed at their own risk. MVTec Software GmbH is not responsible for the privacy practices or the content of external, non-MVTec websites.
Copyright notes: © Copyright MVTec Software GmbH. All rights reserved. Unless otherwise stated, the copyright and similar rights in the contents of this page, including but not limited to all text, designs and images appearing herein, are copyrighted works owned by MVTec Software GmbH. "MVTec Software GmbH" and "HALCON" are registered trademarks of MVTec Software GmbH. All other brand names, designs, service marks and trademarks (whether or not registered) referenced or used herein are the property of their respective owners.