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:

A VC-Z device series.
On embedded device:
Installed driver vclinux_3.0.0 (or higher), currently vclib is not used by the interface but used by HALCON itself (libhalcon.so).
VC Lib Q library installed, have a look at this procedure.
HALCON image acquisition interface hAcqVC-Z.so . If you have properly installed the interface, all these SOs should reside in /usr/lib. The variable %HALCONARCH% is armv7a-linux and the HALCON base directory %HALCONROOT% is /opt/halcon/ set during the installation of HALCON embedded VC Lib Q library.

Features

Synchronous and asynchronous grabbing images.
Support the Exposure time parameter.
Support the Gain parameter.
Support subsampling the sensor resolution.
Support partial scan of the Sensor.
Support freerun or external trigger mode.
If there are more than one sensor, the number of channel in the grabbed images is equal to the number of sensor. (not tested...)
The color camera provides 3 channels for RGB or YUV image or 1 channel for gray or bayer image. The color processing is done by the FPGA.
A vertical or horizontal flip can be applied on the image. This processing is done by the FPGA.
Some outputs could be affected as a strobe signal automatically activated during the exposure time of the sensor.

Limitations

If there are more than one sensor, every parameters are duplicated on every sensors. You can not set different exposure time for 2 sensors.
Tested only on a VC nano Z 0011 and VC Pro Z 0015 color

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

VC-Z_simple.hdev - A simple example to show the usage of the interface. There are some processings to detect circular shapes. The images could be seen on a X-Server.
VC-Z_external_trigger.hdev - A example of acquisition with an external hardware trigger.
VC-Z_parameters.hdev - Lists all parameters of a device and log them in the console and in a txt file.
VC-Z_subsampling_partialscan.hdev - A example of acquisition with a subsampling and an ROI on the sensor.
VC-Z_CaptFPS.hdev - A example to measure the max FPS for a serie of image height resolutions.
VC-Z_simple_color.hdev - Like the simple example but only for color cameras. We try every color_spaces available : RGB, YUV, BAYER and GRAY images and the YUV images are converted in RGB to display color.
VC-Z_simple_strobe.hdev - Like the simple example but we use the parameter 'strobe' to activate output during the exposure time. It works also with the VC Pro Z camera and his integrated ring led.

Release Notes

Revision 6.0.70 (2018-02-14):
- First official release.

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.