set_framegrabber_param

This operator is used to set interface parameters or to write directly into the NxLib API Tree.

Parameters

set_framegrabber_param (AcqHandle, Parameter, Value)

Parameter

Description

AcqHandle

An acquisition handle obtained via ‘ open_framegrabber’.

Parameter

This can either be an interface parameter or an item path for direct tree item access.

Value

A variable or constant to be written to the item.

Halcon Interface Parameters

Parameter

Values

Type

Description

‘auto_grab_data’

‘true’, ‘false’, 0, 1

string, integer

Set the ‘auto_grab_data’ flag for the given handle.

‘parallel_execution’

‘true’, ‘false’, 0, 1

string, integer

Set the ‘parallel_execution’ flag for the given handle.

‘do_open_tcp_port’

<port>

integer

Opens a TCP port.

Note: Only one port can be open per NxLib instance.

‘do_close_tcp_port’

[]

Closes open TCP port.

‘do_execute’

<command>

string

Executes ‘<command>’ in the NxLib. More information about this parameter can be found here.

Note: When parallel execution is disabled, this parameter is only supported on handles referencing the tree’s root node.

‘do_set_parameters’

JSON parameters or a path to a JSON file

string

Load a parameter set for the camera. The argument can either be a JSON string that is applied to the camera’s Parameters node or a path to a JSON file (specified with a ‘file://’ prefix).

See the how-to on camera parameter files for an example.

‘generate_regions’

‘true’, ‘false’, 0, 1

string, integer

Set the ‘generate_regions’ flag for the given handle.

‘grab_data_items’

[‘<binary_node_path>’]

string, tuple

List of binary nodes which will be provided when using ‘grab_data’ on the given handle.

‘replace_nans’

‘true’, ‘false’, 0, 1

string, integer

Set the ‘replace_nans’ flag for the given handle.

‘export_debug_buffer’

[‘append’or’replace’, <file_path>]

[string, string]

Export all buffered debug information into a file.
  - ‘append’ (default): Appends the retrieved output to the file.
  - ‘replace’ (default): The file will be overwritten when it already exists.

Note

do_set_parameters will only overwrite the Parameters node of the camera.

Tree Item Access

set_framegrabber_param(AcqHandle, ItemPath, Value)
set_framegrabber_param(AcqHandle, ItemPath, [TypeSpecifier, Value])

Parameter

Values

Description

AcqHandle

An acquisition handle obtained via open_framegrabber’.

ItemPath

A path to a tree item to be written. The item path is relative to the path with which the handle is associated.

TypeSpecifier

‘string’, ‘json’, ‘apply’, ‘image’

A string specifying how the Value is to be interpreted and stored. For further information read the section below.

‘string’: Specifies that Value is a plain string to be stored at the specified item. ‘json’: Specifies that Value is a string to be interpreted as JSON. The resulting JSON item(s) will be stored at/below the item specified by ItemPath. ‘apply’: Same as ‘json’, but the resulting JSON structure will be written with the parameter onlyWriteableNodes == true in nxLibSetJson. This should be used to apply saved parameter subtrees. Non-writable nodes will be skipped without notice. ‘image’: Used to write an image into a binary node.

Note: Only images of the same dimension as the image already in the node can be used.

Value

A variable or constant to be written to the item.

Interpretation of parameter format

When setting a tree item with ‘ set_framegrabber_param’, the HALCON parameter types int and double are written as JSON type Number.

But a HALCON string as parameter could have different meanings:

  • It could be a string that should be set on the specified item

  • It could be a JSON representation to be stored in the specified item

  • It could be a JSON representation to be ‘applied’ at the specified item, skipping read-only nodes without raising an error

When specifying a string parameter, the order of interpretation is as follows:

  • Try to interpret the given string as JSON. If successful, store the given JSON structure at the specified item.

  • If the JSON interpretation failed, store the string in the specified item

The interpretation can be specified explicitly using the TypeSpecifier parameter.

Example

* Open default stereo camera
open_framegrabber('Ensenso-NxLib', 0, 0, 0, 0, 0, 0, 'default', 0, 'Raw', -1, 'false', 'Stereo', '', 0, 0, AcqHandle)

* Open and close TCP port 24000
set_framegrabber_param (AcqHandle, 'do_open_tcp_port', 24000)
set_framegrabber_param (AcqHandle, 'do_close_tcp_port', [])

* Set a Handle Parameter
set_framegrabber_param (AcqHandle, 'replace_nans', 'false')
set_framegrabber_param (AcqHandle, 'grab_data_items', ['Images/DisparityMap','Images/PointMap'])

* Load a parameter set
set_framegrabber_param (AcqHandle, 'do_set_parameters', 'file:///path/to/settings.json')

* Tree Access
set_framegrabber_param (AcqHandle, 'Parameters/Capture/AutoExposure', 'false')
set_framegrabber_param (AcqHandle, 'Parameters/Capture/Exposure', 5)
* with JSON string
set_framegrabber_param (AcqHandle, 'Parameters', ['apply','{"Capture":{"AutoExposure":false, "Exposure":5}}'])

* Write an image into a binary node
read_image(Image, 'example.png')
obj_to_integer (Image, 1, -1, SurrogateTuple)
set_framegrabber_param(AcqHandle, '/Images/Raw/Left', ['image', SurrogateTuple])