Image Acquisition PhoXi

Interface:	PhoXi
Revision:	1.2.14
Date:	2020-02-06
HALCON Version:	12,19

General

This page provides the documentation of the HALCON image acquisition PhoXi.

Download HALCON
Download PhoXi Control - HALCON Interface

Examples are in directory:

Windows: C:\Users\Public\Documents\PhoHalcon\examples
Linux: /opt/PhotoneoHalconDriver/examples

System Requirements

System requirements:

Supported OS are Windows 10 x64, Ubuntu 16 x64 (gcc5.4.0).
Installed PhoXi Control version 1.2.14.
HALCON 12 & HALCON 19 (backward compatible with HALCON 13 and newer)
- Windows: HALCON image acquisition interface hAcqPhoXi.dll, hAcqPhoXixl.dll and PhoXi_API_Release_X.X.X.dll, respectively.
  - If you have properly installed the interface, all these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
- Linux: HALCON image acquisition interface libhAcqPhoXi.so, libhAcqPhoXixl.so and libPhoXi_API_Release_X.X.X.so, respectively.
  - If you have properly installed the interface, the shared objects should reside in lib\$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON. Symbolic links hAcqPhoXi.so, AcqPhoXixl.so should be created in /usr/lib.

Parameters for info_framegrabber

Parameter	Value List	Type	Kind	Description
bits_per_channel	[-1, 8, 10, 12, 16, 32]	integer	pre-defined	Number of bits per channel of the resulting HALCON image. PhoXi uses 32bit images.
camera_type	['default', 'auto', 'pal', 'ntsc']	string	pre-defined	`Unsupported query.` Value list for camera type parameter.
color_space	['default', 'gray', 'raw', 'rgb']	string	pre-defined	`Unsupported query.` Value list for color space parameter.
defaults	[]	mixed	pre-defined	Default values for `open_framegrabber`. e.g. ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
device	['<devices>']	string	dynamic	Value list for device parameter.
field	['default', 'interlaced', 'progressive']	string	pre-defined	`Unsupported query.` Value list for field parameter.
general	[]	string	pre-defined	Information about the HALCON PhoXi interface.
generic	['<parameters>']	mixed	pre-defined	`Unsupported query.` Value list for field parameter.
horizontal_resolution	[1, 2]	integer	pre-defined	Value list for horizontal resolution. 1: Use full resolution. 2: Use half resolution. Resolution: User defined horizontal resolution is set.
info_boards	['<devices>']	string	dynamic	A list of the available devices.
name	'PhoXi'	string	pre-defined	Name of the HALCON interface.
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	[<ports>]	integer	pre-defined	`Unsupported query.` Value list for port parameter.
revision	'<revision>'	string	pre-defined	Revision number of the PhoXi interface.
vertical_resolution	[1, 2]	integer	pre-defined	Value list for vertical resolution. 1: Use full resolution. 2: Use half resolution. Resolution: User defined vertical resolution is set.

Parameters for open_framegrabber

Opens and configures PhoXi image acquisition device. Every PhoXi Control installer has a FileCamera example included. It's connection can be established with these parameters:

('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'InstalledExamples-basic-example(File3DCamera)', -1, -1)

Parameter	Values	Default	Type	Description
Name	'<name>'	'PhoXi'	string	HALCON image acquisition interface name. ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
HorizontalResolution	[1, 2]	1	integer	1 for full resolution (2064x1544) 2 for half resolution (1032x772) ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
VerticalResolution	[1, 2]	1	integer	1 for full resolution (2064x1544) 2 for half resolution (1032x772) ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ImageWidth	0 .. width	0	integer	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ImageHeight	0 .. height	0	integer	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
StartRow	0 .. width	0	integer	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
StartColumn	0 .. height	0	integer	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
Field		'default'	string	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
BitsPerChannel	[-1, 8, 10, 12, 16, 32]	-1	integer	`Ignored.` PhoXi uses fixed 32bit images. ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ColorSpace	['default', 'gray', 'raw', 'rgb']	'default'	string	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
Generic		-1.0	double	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ExternalTrigger	['true', 'false']	'false'	string	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
CameraType	['default', 'auto', 'pal', 'ntsc']	'default'	string	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
Device	'<device>'	'InstalledExamples-basic-example(File3DCamera)'	string	Serial number of a scanner (YYMMxxx or YYYY-MM-xxx-LCx) or value from DeviceInfo array (see PhoXi's `info_framegrabber` with 'device' parameter) ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
Port	[<ports>]	-1	integer	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
LineIn		-1	integer	`Ignored.` ('PhoXi', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)

Parameters for set_framegrabber_param

Parameter	Values	Default	Type	Description
3droi_camera_space_max	-99999.0 .. 99999.0	0.0	double	Defines data cutting volumes in Camera space. Setting the minimal and maximal thresholds for components based on Camera Space cuts off data outside of this range. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Camera Space Min Z to 500 and Camera Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
3droi_camera_space_min	-99999.0 .. 99999.0	0.0	double	Defines data cutting volumes in Camera space. Setting the minimal and maximal thresholds for components based on Camera Space cuts off data outside of this range. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Camera Space Min Z to 500 and Camera Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
3droi_point_cloud_space_max	-99999.0 .. 99999.0	0.0	double	Defines data cutting volumes in Point Cloud space. Setting the minimal and maximal thresholds for components based on Point Cloud Space cuts off data outside of this range. Works differently than Camera Space ROI only when the Coordinate Space is other than Camera Space. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Point Cloud Space Min Z to 500 and Point Cloud Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
3droi_point_cloud_space_min	-99999.0 .. 99999.0	0.0	double	Defines data cutting volumes in Point Cloud space. Setting the minimal and maximal thresholds for components based on Point Cloud Space cuts off data outside of this range. Works differently than Camera Space ROI only when the Coordinate Space is other than Camera Space. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Point Cloud Space Min Z to 500 and Point Cloud Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
ambient_light_suppression	['enable', 'disable']	'disable'	string	Ambient light suppression samples the scene multiple times during one pattern exposure. These samples are thencombined and used to suppress the effect of ambient illumination by eliminating most of the shot noise caused by longer exposure of ambient light. Enabling the mode will set Shutter multiplier to fixed value of 2.
bits_per_channel	[-1, 8, 10, 12, 16, 32]	32	integer	`Unsupported command!` PhoXi uses fixed 32bit images.
calibration_volume_only	['enable', 'disable']	'disable'	string	By default the volume captured by the scanner is cut off by near and far planes of the recommended scanning range. Calibration Volume Only allows to switch off the cut. When off the application displays uncut data from the whole captured volume. When on the application displays data captured only in the recommended scanning volume of the scanner.
camera_only_mode	['enable', 'disable']	'disable'	string	Specifies a mode, where only the camera captures the frame. With Camera Only Mode, you can use the internal camera of the scanner to capture 2D images of the scene. These images can be read out as Texture. It is useful to either navigate the scanner around the scene, or to take a quick snapshot to look for changes in scene. It does not perform any computations necessary for 3D Scanning and has low latency.
coding_quality	['Ultra', 'High', 'Fast']	'High'	string	Approach to achieve subpixel accuracy: Fast - without subpixel accuracy High - sub-pixel accuracy Ultra - enhanced sub-pixel accuracy This parameter influences the processing time. Coding quality set to Ultra ensures in many cases best accuracy but fewer measured points.
coding_strategy	['Normal', 'Interreflections']	'Interreflections'	string	Coding strategy optimized for Interreflections uses advanced digital coding to make diffuse interreflection possible to suppress. For most scenes, strategy optimized for Interreflections provides better output, but in some edge cases where interreflections are caused by glossy material, Normal could provide more robust results.
confidence	0.0 .. 100.0	2.0	double	Controls the amount of output points based on point reliability. This enables the user to set preference based on the application. Some applications require a more complete output at the expense of lower precision. Other applications are meant to work with precise data only and need to filter out regions where the precision does not meet a certain threshold. Renamed to Max Inaccuracy in PhoXi Control GUI.
coordinate_space	['CameraSpace', 'MarkerSpace', 'RobotSpace', 'CustomSpace', 'TrackerSpace']	'CameraSpace'	string	CameraSpace: Coordinate space with origin in the camera of the Scanner. MarkerSpace: To align multiple scans in PhoXi Control, it is useful to use marker patterns. Marker patterns are available in Tools/Marker patterns. If you place a marker pattern below an object and set the marker space as your coordinate space, you can now move the Scanner to different locations with the point cloud automatically returning to the same coordinate system defined by the marker plate. RobotSpace: Coordinate space with the origin in the robot. Automatically set by Robot-Camera Calibration Tool. See the Photoneo website for more information. CustomSpace: Your custom-defined coordinate space.
custom_trans_rotation_matrix	-99999.0 .. 99999.0	0.0	double	Defines the rotation matrix to transform from camera space to custom space.
custom_trans_translation_vector	-99999.0 .. 99999.0	0.0	double	Defines the translation vector from camera space to custom space.
do_grab_abort	['enable', 'disable']	'enable'	string	`Unsupported command!` By default a new asynchronous grab command is automatically given to the acquisition device at the end of `grab_image_async`.
get_specific_frame_timeout	-3 .. 300000	10000	integer	This parameter sets the timoeut of the PhoXi API `GetSpecificFrame()` call.
grab_data_items	['Texture', 'PointCloud', 'NormalMap', 'DepthMap', 'ConfidenceMap']		string	The parameter controls the data returned by the operator `grab_data`
grab_timeout		5000	integer	`Unsupported command!` Desired timeout (milliseconds) for aborting a pending grab.
horizontal_resolution	[1, 2]	1	integer	Set value for horizontal resolution. 1: Use full resolution. 2: Use half resolution.
laser_power	0 .. 4095	4095	integer	Can be understood as amount of light emitted by the scanner. Recommended to decrease only when experiencing overexposure.
marker_scale	0.0 .. 99999.0	1.0	double	Enables the setting of the X and Y scale of the marker pattern. Use X or Y larger than 1 for upscaled marker patterns and smaller than 1 for downscaled marker patterns. The correct scale is when the origin of the coordinate system is placed in the center of the white circle in the marker pattern.
max_camera_angle	0.0 .. 90.0	90.0	double	Maximal angle between point normal and direction to camera.
max_halfway_angle		0.0	double	Maximal angle between normal and halfway vector.
max_projector_angle	0.0 .. 90.0	90.0	double	Maximal angle between point normal and direction to projector.
maximum_fps	0.0 .. 100.0	0.0	double	Useful for limiting the fps in freerun mode. If you want to allow a scan every 10 seconds, you can set Maximum FPS to 0.1. If you want 2 scans per second, set the value to 2.0.
min_halfway_angle	0.0 .. 90.0	0.0	double	Minimal angle between normal and halfway vector.
normals_estimation_radius	1 .. 4	2	integer	Defines the size of the area (in pixels) around a point. Pixels in this area take part in computation of the normal at this point.
recognize_markers	['enable', 'disable']	'disable'	string	When true, markers will be recognized in the scan. If Recognize Markers is set, you need to place a marker pattern to the scanning scene, otherwise, the resulting frame will be flagged as corrupted.
resolution	['2064x1544', '1032x772']	'2064x1544'	string	Resolution of the resulting image.
robot_trans_rotation_matrix	-99999.0 .. 99999.0	0.0	double	Defines the rotation matrix to transform from camera space to custom space.
robot_trans_translation_vector	-99999.0 .. 99999.0	0.0	double	Defines the translation vector from camera space to custom space.
scan_multiplier	1 .. 50	1	integer	Scan Multiplier allows to scan multiple times and merge the output to a single point cloud. This increases S/N ratio to ensure higher quality scan. It is useful in scenarios with high dynamic range, where increased Shutter Multiplier means oversaturation of some areas of the scan. It affects the scanning process and the final duration of the scan is multiplied by Scan Multiplier.
shutter_multiplier	1 .. 20	3	integer	Shutter Multiplier affects the duration of scanning by changing the number of repetitions of individual patterns. Higher number of Shutter Multiplier helps to scan darker materials, in situations with sharp scanning angle, or when the light pattern is reflected back only partially. In some cases, setting the value too low could result in underexposed images. Setting the value too high could result in overexposed images. It affects the scanning process and the final scanning time is multiplied by the value of Shutter Multiplier.
start_async_after_grab_async	['enable', 'disable']	'enable'	string	`Unsupported command!`
surface_smoothness	['Sharp', 'Normal', 'Smooth']	'Normal'	string	Defines the setting of smoothness of point cloud generation algorithm. Sharp - optimized for small feature retrieval. Higher noise on surfaces. Normal - standard sensor setting best for most scans. Smooth - edge preserving algorithm that smooths the surface, lowering down noise for expense for small features.
texture_source	['LED', 'Computed', 'Laser', 'Focus']	'LED'	string	Defines the used texture source. LED will capture an additional image with LED flash that offers a speckle less 2D image. Use this setting to achieve nice colored PointCloud. Computed is a texture computed from the structured patterns - no additional image is necessary. It has lower quality. Laser will trigger an additional image with laser flash. Use this setting to investigate light conditions in the scene. Focus will set a structured pattern as a texture. Useful for analyzing problems with signal contrast and the setup of the shutter parameters.
timeout	[0, -1, -2, -3]		integer	Defines the setting of timeout. 0: ZeroTimeout -1: Infinity -2: LastStored -3: Default
trigger_mode	[0, 1, 2, 3]		integer	Defines the setting of trigger mode. 0: Freerun 1: Software 2: Hardware 3: NoValue
use_grab_image_async_as_trigger_only	['enable', 'disable']	'enable'	string	Enables PhoXi parallel image acquisition. See PhoXi's `grab_image_async` and `grab_data_async`.
vertical_resolution	[1, 2]	1	integer	Set value for vertical resolution. 1: Use full resolution. 2: Use half resolution.
volatile	['enable', 'disable']	'disable'	string	`Unsupported command!`
wait_for_grabbing_end	['enable', 'disable']	'enable'	string	If `wait_for_grabbing_end` is enabled, the call will wait until the end of Device Grabbing. This is useful for synchronous data grabbing.

Parameters for get_framegrabber_param

Additional read-only parameters with the following postfixes may exist:

'_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 at least 4 elements, e.g., get_framegrabber_param(..,'shutter_multiplier_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 list of valid values for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'camera_only_mode_values',..) will return the output tuple ['enable', 'disable'].
'_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), and 'rw' (read/write).
'_category': These parameters provide the category of the corresponding parameter as a string.
'_visibility': These parameters provide the visibility of the corresponding parameter as a string.

All these postfixed parameter names are not returned when calling info_framegrabber(..,'parameters',..) and are used to enable an easy parameterization via generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

Parameter	Values	Default	Type	Kind	Description
3droi_camera_space_max	-99999.0 .. 99999.0	0.0	double	dynamic	Defines data cutting volumes in Camera space. Setting the minimal and maximal thresholds for components based on Camera Space cuts off data outside of this range. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Camera Space Min Z to 500 and Camera Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
3droi_camera_space_min	-99999.0 .. 99999.0	0.0	double	dynamic	Defines data cutting volumes in Camera space. Setting the minimal and maximal thresholds for components based on Camera Space cuts off data outside of this range. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Camera Space Min Z to 500 and Camera Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
3droi_point_cloud_space_max	-99999.0 .. 99999.0	0.0	double	dynamic	Defines data cutting volumes in Point Cloud space. Setting the minimal and maximal thresholds for components based on Point Cloud Space cuts off data outside of this range. Works differently than Camera Space ROI only when the Coordinate Space is other than Camera Space. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Point Cloud Space Min Z to 500 and Point Cloud Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
3droi_point_cloud_space_min	-99999.0 .. 99999.0	0.0	double	dynamic	Defines data cutting volumes in Point Cloud space. Setting the minimal and maximal thresholds for components based on Point Cloud Space cuts off data outside of this range. Works differently than Camera Space ROI only when the Coordinate Space is other than Camera Space. The filtration will only be applied if max > min and is applied individually for any dimension. E.g. you can specify Point Cloud Space Min Z to 500 and Point Cloud Space Max Z to 1000 - the data outside of this Z region will be filtered out and X, Y regions will be left unfiltered.
ambient_light_suppression	['enable', 'disable']	'disable'	string	pre-defined	Ambient light suppression samples the scene multiple times during one pattern exposure. These samples are thencombined and used to suppress the effect of ambient illumination by eliminating most of the shot noise caused by longer exposure of ambient light. Enabling the mode will set Shutter multiplier to fixed value of 2.
available_param_names	['<parameters>']			pre-defined	List of available parameters.
calibration_camera_matrix			double	dynamic	Camera matrix describes the mapping of 3D points in the world pace to the 2D points in the image plane.
calibration_distortion_coefficients			double	dynamic	Coefficients describing lens distortion of the camera.
calibration_focus_length			double	dynamic	Focal lenght of the camera.
calibration_pixel_size			double	dynamic	Pixel size of the camera.
calibration_volume_only	['enable', 'disable']	'disable'	string	pre-defined	By default the volume captured by the scanner is cut off by near and far planes of the recommended scanning range. Calibration Volume Only allows to switch off the cut. When off the application displays uncut data from the whole captured volume. When on the application displays data captured only in the recommended scanning volume of the scanner.
camera_only_mode	['enable', 'disable']	'disable'	string	pre-defined	Specifies a mode, where only the camera captures the frame. With Camera Only Mode, you can use the internal camera of the scanner to capture 2D images of the scene. These images can be read out as Texture. It is useful to either navigate the scanner around the scene, or to take a quick snapshot to look for changes in scene. It does not perform any computations necessary for 3D Scanning and has low latency.
coding_quality	['Ultra', 'High', 'Fast']	'High'	string	pre-defined	Approach to achieve subpixel accuracy: Fast - without subpixel accuracy High - sub-pixel accuracy Ultra - enhanced sub-pixel accuracy This parameter influences the processing time. Coding quality set to Ultra ensures in many cases best accuracy but fewer measured points.
coding_strategy	['Normal', 'Interreflections']	'Interreflections'	string	pre-defined	Coding strategy optimized for Interreflections uses advanced digital coding to make diffuse interreflection possible to suppress. For most scenes, strategy optimized for Interreflections provides better output, but in some edge cases where interreflections are caused by glossy material, Normal could provide more robust results.
confidence	0.0 .. 100.0	2.0	double	dynamic	Controls the amount of output points based on point reliability. This enables the user to set preference based on the application. Some applications require a more complete output at the expense of lower precision. Other applications are meant to work with precise data only and need to filter out regions where the precision does not meet a certain threshold. Renamed to Max Inaccuracy in PhoXi Control GUI.
coordinate_space	['CameraSpace', 'MarkerSpace', 'RobotSpace', 'CustomSpace', 'TrackerSpace']	'CameraSpace'	string	pre-defined	CameraSpace: Coordinate space with origin in the camera of the Scanner. MarkerSpace: To align multiple scans in PhoXi Control, it is useful to use marker patterns. Marker patterns are available in Tools/Marker patterns. If you place a marker pattern below an object and set the marker space as your coordinate space, you can now move the Scanner to different locations with the point cloud automatically returning to the same coordinate system defined by the marker plate. RobotSpace: Coordinate space with the origin in the robot. Automatically set by Robot-Camera Calibration Tool. See the Photoneo website for more information. CustomSpace: Your custom-defined coordinate space.
custom_trans_rotation_matrix	-99999.0 .. 99999.0	0.0	double	dynamic	Defines the rotation matrix to transform from camera space to custom space.
custom_trans_translation_vector	-99999.0 .. 99999.0	0.0	double	dynamic	Defines the translation vector from camera space to custom space.
get_specific_frame_timeout	-3 .. 300000	10000	integer	dynamic	This parameter sets the timoeut of the PhoXi API `GetSpecificFrame()` call.
grab_data_items	['Texture', 'PointCloud', 'NormalMap', 'DepthMap', 'ConfidenceMap']		string	pre-defined	The parameter controls the data returned by the operator `grab_data`. Default values are set according to the devices settings.
'grab_timeout'		5000	integer	dynamic	`Unsupported command!` Desired timeout (milliseconds) for aborting a pending grab.
laser_power	0 .. 4095	4095	integer	dynamic	Can be understood as amount of light emitted by the scanner. Recommended to decrease only when experiencing overexposure.
marker_scale	0.0 .. 99999.0	1.0	double	dynamic	Enables the setting of the X and Y scale of the marker pattern. Use X or Y larger than 1 for upscaled marker patterns and smaller than 1 for downscaled marker patterns. The correct scale is when the origin of the coordinate system is placed in the center of the white circle in the marker pattern.
max_camera_angle	0.0 .. 90.0	90.0	double	dynamic	Maximal angle between point normal and direction to camera.
max_halfway_angle		0.0	double	dynamic	Maximal angle between normal and halfway vector.
max_projector_angle	0.0 .. 90.0	90.0	double	dynamic	Maximal angle between point normal and direction to projector.
maximum_fps	0.0 .. 100.0	0.0	double	dynamic	Useful for limiting the fps in freerun mode. If you want to allow a scan every 10 seconds, you can set Maximum FPS to 0.1. If you want 2 scans per second, set the value to 2.0.
min_halfway_angle	0.0 .. 90.0	0.0	double	dynamic	Minimal angle between normal and halfway vector.
normals_estimation_radius	1 .. 4	2	integer	dynamic	Defines the size of the area (in pixels) around a point. Pixels in this area take part in computation of the normal at this point.
num_buffers		18	integer	dynamic	`Unsupported command!` Number of buffers used in the acquisition process. 1x for Texture 3x for PointCloud (XYZ) 3x for Normals (XYZ) 1x for DepthMap 1x for ConfidenceMap Two sets of each - front and back buffers.
recognize_markers	['enable', 'disable']	'disable'	string	pre-defined	When true, markers will be recognized in the scan. If Recognize Markers is set, you need to place a marker pattern to the scanning scene, otherwise, the resulting frame will be flagged as corrupted.
resolution	['2064x1544', '1032x772']	'2064x1544'	string	pre-defined	Resolution of the resulting image.
revision	'<revision>'		string	pre-defined	Revision number of the PhoXi interface.
robot_trans_rotation_matrix	-99999.0 .. 99999.0	0.0	double	dynamic	Defines the rotation matrix to transform from camera space to custom space.
robot_trans_translation_vector	-99999.0 .. 99999.0	0.0	double	dynamic	Defines the translation vector from camera space to custom space.
scan_multiplier	1 .. 50	1	integer	dynamic	Scan Multiplier allows to scan multiple times and merge the output to a single point cloud. This increases S/N ratio to ensure higher quality scan. It is useful in scenarios with high dynamic range, where increased Shutter Multiplier means oversaturation of some areas of the scan. It affects the scanning process and the final duration of the scan is multiplied by Scan Multiplier.
shutter_multiplier	1 .. 20	3	integer	dynamic	Shutter Multiplier affects the duration of scanning by changing the number of repetitions of individual patterns. Higher number of Shutter Multiplier helps to scan darker materials, in situations with sharp scanning angle, or when the light pattern is reflected back only partially. In some cases, setting the value too low could result in underexposed images. Setting the value too high could result in overexposed images. It affects the scanning process and the final scanning time is multiplied by the value of Shutter Multiplier.
start_async_after_grab_async	['enable', 'disable']	'enable'	string	pre-defined	`Unsupported command!`
surface_smoothness	['Sharp', 'Normal', 'Smooth']	'Normal'	string	pre-defined	Defines the setting of smoothness of point cloud generation algorithm. Sharp - optimized for small feature retrieval. Higher noise on surfaces. Normal - standard sensor setting best for most scans. Smooth - edge preserving algorithm that smooths the surface, lowering down noise for expense for small features.
texture_source	['LED', 'Computed', 'Laser', 'Focus']	'LED'	string	pre-defined	Defines the used texture source. LED will capture an additional image with LED flash that offers a speckle less 2D image. Use this setting to achieve nice colored PointCloud. Computed is a texture computed from the structured patterns - no additional image is necessary. It has lower quality. Laser will trigger an additional image with laser flash. Use this setting to investigate light conditions in the scene. Focus will set a structured pattern as a texture. Useful for analyzing problems with signal contrast and the setup of the shutter parameters.
timeout	[0, -1, -2, -3]		integer	pre-defined	Defines the setting of timeout. 0: ZeroTimeout -1: Infinity -2: LastStored -3: Default
trigger_mode	[0, 1, 2, 3]	1	integer	pre-defined	Defines the setting of trigger mode. 0: Freerun 1: Software 2: Hardware 3: NoValue
use_grab_image_async_as_trigger_only	['enable', 'disable']	'enable'	string	pre-defined	Enables PhoXi parallel image acquisition. See PhoXi's `grab_image_async and grab_data_async`.
volatile	['enable', 'disable']	'disable'	string	pre-defined	`Unsupported command!`
wait_for_grabbing_end	['enable', 'disable']	'enable'	string	pre-defined	If `wait_for_grabbing_end` is enabled, the call will wait until the end of Device Grabbing. This is useful for synchronous data grabbing.

Operator set_framegrabber_callback

Not supported by this interface.

Operator get_framegrabber_callback

Not supported by this interface.

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator grab_image

Used for synchronous grabbing.
PhoXi's grab_image starts a new synchronous grab. The interface converts the image from the device to the HALCON image format. It will return texture image.

Example:
grab_image (TextureImage, AcqHandle)

TextureImage: output
AcqHandle: handle acquired from open_framegrabber

Operator grab_image_async

Used for asynchronous grabbing.
PhoXi's grab_image_async returns an image and starts the next asynchronous grab. The interface converts the image from the device to the HALCON image format. 'MaxDelay' argument is used to set image's max age.

Example:
grab_image_async (TextureImage, AcqHandle, MaxDelay)

TextureImage: output
AcqHandle: handle acquired from open_framegrabber
MaxDelay: max image age

Special behaviour for PhoXi devices when use_grab_image_async_as_trigger_only is enabled:

these settings enable parallel image acquisition
grab_image_async is used only for image triggering (has no return values)
grab_data_async is used for retrieving the triggered frame
- this call returns a tuple: Texture, PointCloud, NormalMap, DepthMap, ConfidenceMap

Operator grab_image_start

Not supported by this interface.

Operator grab_data

Used for synchronous grabbing.
It will return images specified by the parameter 'grab_data_items'. See PhoXi's set_framegrabber_param and get_framegrabber_param. In order to retrieve certain data, use select_obj with corresponding indeces (important: order of objects must be preserved):

select_obj (input_value, texture, 1)
select_obj (input_value, point_cloud, 2)
select_obj (input_value, normals, 3)
select_obj (input_value, depth_map, 4)
select_obj (input_value, confidence_map, 5)

Example:
GrabDataItems:=['Texture', 'PointCloud', 'NormalMap', 'DepthMap', 'ConfidenceMap'] set_framegrabber_param (AcqHandle, 'grab_data_items', GrabDataItems) grab_data (ImageData, Region, Contours, AcqHandle, Data)

ImageData: output Region: output Contours: output AcqHandle: handle acquired from open_framegrabber Data: output

Parameter	Type	Count	Description
'image'			Depending on the parameter `'grab_data_items'` the following images can be returned: Texture (1 channel / 32bit) PointCloud (3 channels / 32bit) NormalMap (3 channels / 32bit) DepthMap (1 channel / 32bit) ConfidenceMap (1 channel / 32bit)
'contours'			Not used.
'region'			Not used.
'data'			Not used.

Operator grab_data_async

Used for asynchronous grabbing.
'MaxDelay' argument is used to set image's max age. See PhoXi's grab_data for return input/output.

ImageData: output Region: output Contours: output AcqHandle: handle acquired from open_framegrabber MaxDelay: max image age Data: output

Special behaviour for PhoXi devices when use_grab_image_async_as_trigger_only is enabled:

these settings enable parallel image acquisition
grab_image_async is used only for image triggering (has no return values)
grab_data_async is used for retrieving the triggered frame
- this call returns a tuple: Texture, PointCloud, NormalMap, DepthMap, ConfidenceMap

Operator close_framegrabber

This operator closes the device.
Internally, this closes the API connection and disconnects the device in PhoXi Control.

HDevelop Examples

For this interface there are the following example available:

example/hdevelop/phoxi_simple.hdev - A simple example to show the usage of the interface.
example/hdevelop/phoxi_params.hdev - An example to show which parameters can be set and get.

C++ Examples

example/cpp/PhoXiSimple - A simple example to show the usage of the interface.

C# Examples

example/c#/PhoXiSimple - A simple example to show the usage of the interface.

Error Codes

[10001] H_PHO_ERR_CONNECTION
- Scanner not connected
[10002] H_PHO_ERR_ACQUISITION
- Cannot start acquisition
[10011] H_PHO_ERR_TRIGGERNEG
- TriggerFrame returned negative number (see logs)
[10012] H_PHO_ERR_INVALIDFRAME
- Invalid PFrame object
[10021] H_PHO_ERR_DEVICEUNAVAILABLE
- Requested device is not in device list
[11001] H_PHO_ERR_CRLOGDIR
- Cannot create log folder: PhotoneoLogFiles/PhoHalconLogs
[11002] H_PHO_ERR_INITLOGGER
- Cannot initialize logger

Release Notes

Revision 1.2.14 (February 6, 2020)
Built with PhoXi API 1.2.14
Renamed Max Inaccuracy back to Confidence in documentation
Added CPP and C# examples
Included FindHalcon.cmake module
Added acquisition interface logging
Grabbing functions throwing exceptions on error
Introduced timeout parameter (FG_PARAM_GET_SPECIFIC_FRAME_TIMEOUT) - get_specific_frame_timeout
Fixed typo MaxProjectionAngle -> MaxProjectorAngle
Interface versioning corresponding to PhoXi API version
Revision 7.0.2 (July 1, 2019)
Built with PhoXi API 1.2.9
New parameters, updated documentation
Renamed 'Confidence' to 'Max Inaccuracy' in documentation
Disconnect call (close_framegrabber) closes API connections and disconnects the device from PhoXi Control
Updated examples
Added Getters and Setters for:
- calibration_volume_only, marker_scale, laser_power
Revision 7.0.1 (Oct 10, 2018)
Reimplemented PhoXi Image Acquisition Interface
Built with PhoXi API 1.2.6
Added examples: phoxi_simple.hdev and phoxi_params.hdev
Added Getters and Setters for:
- scan_multiplier, shutter_multiplier, resolution, camera_only_mode, maximum_fps, single_pattern_exposure
- custom_trans_rotation_matrix, custom_trans_translation_vector, robot_trans_rotation_matrix, robot_trans_translation_vector, coordinate_space, recognize_markers, save_transformation
Revision 6.x (Oct 25, 2016)
Initial 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.