Home / HALCON 12,13,18,19,20,21

Image Acquisition PhoXi

Interface: PhoXi
Revision: 1.7.3
Date: 2021-12-24
HALCON Version: 12,21

General

This page provides the documentation of the HALCON image acquisition PhoXi.
Examples are in directory:

System Requirements

System requirements:

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', 0, 0, 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', 0, 0, 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', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
HorizontalResolution [0, 1, 2] 1 integer
  • 0 for pre-set resolution
  • 1 for full resolution (2064x1544)
  • 2 for half resolution (1032x772)
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
VerticalResolution [0, 1, 2] 1 integer
  • 0 for pre-set resolution
  • 1 for full resolution (2064x1544)
  • 2 for half resolution (1032x772)
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ImageWidth 0 .. width 0 integer Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ImageHeight 0 .. height 0 integer Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
StartRow 0 .. width 0 integer Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
StartColumn 0 .. height 0 integer Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
Field 'default' string Ignored.
  • ('PhoXi', 0, 0, 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', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ColorSpace ['default', 'gray', 'raw', 'rgb'] 'default' string Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
Generic -1.0 double Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
ExternalTrigger ['true', 'false'] 'false' string Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
CameraType ['default', 'auto', 'pal', 'ntsc'] 'default' string Ignored.
  • ('PhoXi', 0, 0, 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 ABC-xxx) or value from DeviceInfo array (see PhoXi's info_framegrabber with 'device' parameter)
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
Port [<ports>] -1 integer Ignored.
  • ('PhoXi', 0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'default', 'device', -1, -1)
LineIn -1 integer Ignored.
  • ('PhoXi', 0, 0, 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.
phoxi_camera_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.
camera_exposure 10.24 .. 40.96 10.24 double Time of acquisition.
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.
camera_output_topology ['Regular grid', 'Irregular grid', 'Raw'] 'Regular grid' string Output Topology defines the structure of the output 3D point cloud.
camera_sampling_topology ['Standard'] 'Standard' string Sampling Topology defines the topology of sensor pixels used for 3D data computation.
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.
hardware_trigger ['enable', 'disable'] 'disable' string
hardware_trigger_signal ['Falling', 'Rising', 'Both'] 'Falling' string
horizontal_resolution [1, 2] 1 integer Set value for horizontal resolution.
  • 1: Use full resolution.
  • 2: Use half resolution.
interreflection_filtering ['enable', 'disable'] 'disable' string Enables automatic interreflections filtering. Turning this setting on will change Coding Strategy to Interreflections.
interreflection_filtering_strength 0.01 .. 0.99 0.5 double Defines strength for Interreflection Filter from 0.01 to 0.99. The stronger the filter, the more points are filtered out.
laser_power 0 .. 4095 4095 integer Can be understood as amount of light emitted by the scanner.
Recommended to decrease only when experiencing overexposure.
led_power 0 .. 4095 4095 integer
marker_scale 0.0 .. 1.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 .. 90.0 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.
operation_mode ['Camera', 'Scanner', '2D'] 'Scanner' string
projection_offset_left 0 .. 512 0 integer It determines the number of projection columns that are cut off from left side of the projection.
The total width of the projection is 512 columns
projection_offset_right 0 .. 512 0 integer It determines the number of projection columns that are cut off from right side of the projection.
The total width of the projection is 512 columns
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.
scanner_exposure 10.24 .. 40.96 10.24 double Time of acquisition.
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.
single_pattern_exposure 10.24 .. 100.352 20.57 double Single Pattern Exposure is the duration of projection of one pattern. This value is in milliseconds.
Higher value slows down the movement of the mirror in the projection unit, thus pattern is projected longer.
Setting this value higher may be useful when scanning dark or very shiny objects, or when there is another source of strong light and the projected pattern might not be easily visible
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 ['Freerun', 'Software'] 'Software' string
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:

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.
phoxi_camera_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.
camera_exposure 10.24 .. 40.96 10.24 double dynamic Time of acquisition.
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.
camera_output_topology ['Regular grid', 'Irregular grid', 'Raw'] 'Regular grid' string pre-defined Output Topology defines the structure of the output 3D point cloud.
camera_sampling_topology ['Standard'] 'Standard' string pre-defined Sampling Topology defines the topology of sensor pixels used for 3D data computation.
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.
device_type ['PhoXi3DScan', 'MotionCam-3D'] 'PhoXi3DScan' string pre-defined
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', 'EventMap'] 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.
hardware_trigger ['enable', 'disable'] 'disable' string pre-defined
hardware_trigger_signal ['Falling', 'Rising', 'Both'] 'Falling' string pre-defined
interreflection_filtering ['enable', 'disable'] 'disable' string pre-defined Enables automatic interreflections filtering. Turning this setting on will change Coding Strategy to Interreflections.
interreflection_filtering_strength 0.01 .. 0.99 0.5 double dynamic Defines strength for Interreflection Filter from 0.01 to 0.99. The stronger the filter, the more points are filtered out.
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.
led_power 0 .. 4095 4095 integer dynamic
marker_scale 0.0 .. 1.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
  • 1x for EventMap

Two sets of each - front and back buffers.
operation_mode ['Camera', 'Scanner', '2D'] 'Scanner' string pre-defined
projection_offset_left 0 .. 512 0 integer dynamic It determines the number of projection columns that are cut off from left side of the projection.
The total width of the projection is 512 columns
projection_offset_right 0 .. 512 0 integer dynamic It determines the number of projection columns that are cut off from right side of the projection.
The total width of the projection is 512 columns
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.
scanner_exposure 10.24 .. 40.96 10.24 double dynamic Time of acquisition.
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.
single_pattern_exposure 10.24 .. 100.352 20.57 double dynamic Single Pattern Exposure is the duration of projection of one pattern. This value is in milliseconds.
Higher value slows down the movement of the mirror in the projection unit, thus pattern is projected longer.
Setting this value higher may be useful when scanning dark or very shiny objects, or when there is another source of strong light and the projected pattern might not be easily visible
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 ['Freerun', 'Software'] 'Software' string pre-defined
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)

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)

Special behaviour for PhoXi devices when use_grab_image_async_as_trigger_only is enabled:

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

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

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)
  • EventMap (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.

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

Special behaviour for PhoXi devices when use_grab_image_async_as_trigger_only is enabled:

Operator close_framegrabber

This operator closes the device.

HDevelop Examples

For this interface there are the following example available:

C++ Examples

C# Examples

Error Codes

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.
acqdump 1.4 / hdoc 2.5 / Generated: Tuesday 12/28/2021 17:28 +01:00