Halcon Procedures

In Halcon, you can use various internal procedures (functions) to decompose the RGB image and to control registers that the GenTL driver opens.

You can import the procedures into your own code by selecting File > Insert Program > Insert Procedures and then choosing the example code Continuous_Acq.hdev under the Examples/Halcon directory.

The following table describes each of these procedures.

Halcon Procedures

Procedures

Description

set_framegrabber_param

Generic Halcon function to set parameters on the sensor. Can be used to set sensor-specific settings and execute specific commands. For a complete list of settings that can be changed, see below. In the generic form:

set_framegrabber_param( AcqHandle, ‘Name’, ‘Value’)

Parameters (Input)

AcqHandle: Acquisition handle created by open_framegrabber.

Name: The name of the parameter to set on the sensor.

Value: The parameter value to set on the sensor.

For full details on using this function, see XmlSetting and XmlCommand Parameters.

get_framegrabber_param

Generic Halcon function to get parameters on the sensor. Used in conjunction with set_framegrabber_param to set the path to the setting, after which the setting's value is retrieved with get_framegrabber_param. In the generic form:

get_framegrabber_param( AcqHandle, ‘Name’, ‘Value’)

Parameters

AcqHandle (input): Acquisition handle created by open_framegrabber.

Name (input): The name of the parameter to set on the sensor.

Value (output): The variable where parameter's value will be stored.

For full details on using this function, see XmlSetting and XmlCommand Parameters.

Go2GenTL_ParseData

The GenTL driver packs the height map, intensity and stamp information into a 16-bit RGB image. The function is used to extract data from the RGB image.

For details on how the information is packed in the data, see the sections under GenICam GenTL Driver.

The function accepts the image acquired from grab_image_async, and returns the height map, intensity and stamps.

Parameters: Image (input): RGB Image acquired by using grab_image_async.; HeightMap (output): The height map image.; Intensity (output): The intensity image.; Stamps (output): The stamps structure.; Index (input): The index of the scan to extract.; NumScans (output): The number of scans in the acquired image.
Example: Go2GenTL_ParseData(Image, HeightMap, Intensity, Stamps, 0, NumScans)

Go2GenTL_ParseStamps

The stamp information is encoded in the image and can be retrieved using the Go2GenTL_ParseData function. The function Go2GenTL_ParseStamps is used to extract the stamp information from the stamp structure.

For details on how the information is packed in the data, see the sections under GenICam GenTL Driver.

The function accepts the stamp structure acquired from the Go2GenTL_ParseData function, and returns the various values encoded in the stamps.

Parameters (Input): Stamps: The stamps structure acquired by using Go2GenTL_ParseData.
Parameters (Output): FrameCount: The number of frames.; Timestamp: The timestamp.; Encoder: The encoder position.; EncoderIndex: The last index of the encoder.; Inputs: The digital input states.; xOffset: The X offset in millimeters.; xResolution: The X resolution in millimeters.; yOffset: The Y offset in millimeters.; yResolution: The Y resolution in millimeters.; zOffset: The Z offset in millimeters.; zResolution: The Y resolition in millimeters.; zOffset: The Z offset in millimeters.; zResolution: The Z resolution in millimeters.; Width: The width (number of columns) of the image that contains the part. The part width can be less than the image width requested by the user.; Height: The height or length (number of rows) of the image that contains the part. The part length can be less than the image height requested by the user.; HasIntensity: Specifies if the intensity image is available. The intensity image is available if Acquire Intensity is enabled in the sensor's web interface.; NumScans: The number of scans in the acquired image.; SyncTimestamp: The PTP time stamp.; MeasurementIds: Array of every measurement's ID.; MeasurementValues: Array of every measurement's value.; MeasurementDecisions: Array of every measurement's decision.; MeasurementDecisionCodes: Array of every measurement's code.
Example: Go2GenTL_ParseStamps(Stamps, FrameCount, Timestamp, EncoderPosition, EncoderIndex, Inputs, xOffset, xResolution, yOffset, yResolution, zOffset, zResolution, Width, Length, HasIntensity, NumScans, SyncTimestamp, MeasurementIds, MeasurementValues, MeasurementDecisions, MeasurementDecisionCodes)

Go2GenTL_ResampleMode

Returns the resample mode.

Parameters (Input): AcqHandle: Acquisition handle created by open_framegrabber.
Parameters (Output): ResampleMode:
No - Resample is disabled.; Yes - Resample is enabled.; When resampling is enabled, the GenTL driver resamples the height map so that the pixel spacing is the same on the X and Y axis.
Example: Go2GenTL_ResampleMode (AcqHandle, ResampleMode)

Go2GenTL_ConfigFileName

Returns the current live sensor job file name.

Parameters (Input)

AcqHandle: Acquisition handle created by open_framegrabber.

Parameters (Output)

ConfigFile: The name of the job file. The file name includes the extension .job.

Example

Go2GenTL_ConfigFileName (AcqHandle, ConfigFile)

Go2GenTL_SetConfigFileName

Sets the sensor live configuration.

Parameters (Input)

AcqHandle: Acquisition handle created by open_framegrabber.

ConfigFile: The name of the job file. The file name should include the extension .job.

Example

Go2GenTL_SetConfigFileName (AcqHandle, 'test2.cfg')

Go2GenTL_Encoder

Returns the current encoder value. When this function is called, the GenTL driver retrieves the latest encoder value from the sensor. The value is returned as a two-element tuple. The first element is the least significant 32-bit value, and the second element is the most significant 32-bit value.

Parameters (Input)

AcqHandle: Acquisition handle created by open_framegrabber.

Parameters (Output)

EncoderValue: The current encoder value.

Example

Go2GenTL_Encoder(AcqHandle, EncoderValue)

Go2GenTL_ImageSize

Returns the size of the image returned by the GenTL driver.

Parameters (Input)

AcqHandle: Acquisition handle created by open_framegrabber.

Parameters (Output)

Width: The width of the image.

Height: The height of the image.

Example

Go2GenTL_ImageSize(AcqHandle, Width, Height)

To set the image size, you must directly modify Go2GenTL.xml, which is in the same directory as the sensor GenTL driver (Go2GenTL.cti).

Go2GenTL_CoordinateXYZ

Returns the real-world coordinates (X, Y, Z) of the part given the row and column position in the height map.

The values of the offset and resolution input parameters can be retrieved using Go2GenTL_ParseData.

Parameters (Input)

HeightMap: The height map image.

Row: The row in the height map.

Column: The column in the height map.

xOffset: The X offset in millimeters.

xResolution: The X resolution in millimeters.

yOffset: The Y offset in millimeters.

yResoluion: The Y resolution in millimeters.

zOffset: The Z offset in millimeters.

zResolution: The Z resolution in millimeters.

Parameters (Output)

coordinateXYZ: The real-world coordinates.

Go2GenTL_Exposure

Returns the current exposure.

Parameters (Input)

AcqHandle: Acquisition handle created by open_framegrabber.

Parameters (Output)

Exposure: The current exposure value (in µs). The value is returned as an integer. Decimals are truncated.

Example

Go2GenTL_Exposure(AcqHandle, exposure)

Go2GenTL_SetExposure

Sets the current exposure.

Parameters (Input)

AcqHandle: Acquisition handle created by open_framegrabber.

Exposure: The current exposure value (in µs), as an integer.

Example

Go2GenTL_SetExposure(AcqHandle, exposure)

XmlSetting and XmlCommand Parameters

Sensor Settings

You use the set_framegrabber_param and get_framegrabber_param functions to set and retrieve the values of advanced parameters on sensors, and additionally modify special settings and send commands at the driver level. (Examples are shown below and in Sample Program for Various GenTL Settings.)

When you set the second parameter of set_framegrabber_param to "XmlSetting", you can use the function to do the following:

Set the path to a setting you wish to set or get.
Set the value of a setting.
Set an attribute of a setting.

When you set the second parameter of set_framegrabber_param to "XmlCommand", you can send commands and change driver-level settings at the driver level.

Finally, when you retrieve the value of a sensor setting, you set the second parameter of get_framegrabber_param to "XmlSettingReturn".

For example, to get the value for a setting, use set_framegrabber_param repeatedly to set the XML path to the setting, by chunks of up to 30 characters, and retrieve the value into the passed variable in set_framegrabber_param. The following retrieves the value for the setting "Setup/Filters/XSmoothing/Window":

Copy

set_framegrabber_param(AcqHandle, 'XmlSetting', 'Setup/Filters/')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'XSmoothing/')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'Window')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', var)

To set a value, use set_framegrabber_param repeatedly to set the XML path to the setting, by chunks of up to 32 characters, add "=<value>", and end with an empty string.

The following sets the value of "Setup/Filters/XSmoothing/Window" to 5:

Copy

set_framegrabber_param(AcqHandle, 'XmlSetting', 'Setup/Filters/')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'XSmoothing/')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'Window=5')
set_framegrabber_param(AcqHandle, 'XmlSetting', '')

You can also optionally add the "\n" character to the end of the last line of the set operation:

Copy

set_framegrabber_param(AcqHandle, 'XmlSetting', 'Setup/Filters/')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'XSmoothing/')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'Window=5\n')

To set or get an attribute, use the same format, but use a space to delimit the attribute ('Setup/Filters/XSmoothing/Window min="0.044"').

For a set or a get, if an index or a parameter is required, use parentheses:

Copy

set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/ResetGocator(1)')
set_framegrabber_param(AcqHandle, 'XmlSetting', '')

GenTL Driver Settings and Commands

You can change settings or send commands at the driver level. These options always start with GenTL/, in contrast with the Setup/ node for configuring the sensor.

For example, to stop a sensor programmatically, you can do the following:

Copy

set_framegrabber_param(AcqHandle, 'XmlCommand', 'GenTL/StopGocator')
set_framegrabber_param(AcqHandle, 'XmlCommand', '')

You can also optionally add the "\n" character to the end of the last line of the set operation:

Copy

set_framegrabber_param(AcqHandle, 'XmlCommand', 'GenTL/StopGocator\n')

The following driver-level settings are available:

Driver-level settings
Setting	Comment
"GenTL/Buffers"	Read-Write. Gets/Sets the number of buffers to use in the acquisition pipeline.
"GenTL/Encoder"	Read-only. Gets the current encoder value.
"GenTL/IsResponsive"	Read-only. Gets the responsiveness of the sensor.
"GenTL/HasChanges"	Read-only. Indicates whether the sensor needs a GenTL/Refresh command (see See Driver-level commands).
"GenTL/Version"	Read-only. Returns the version of the GenTL driver.
"GenTL/StartStopControl"	Read-Write. Enables or disables the user defined control. Setting this value to 1 allows the user to start and stop manually the sensor, using the "GenTL/StartGocator" and "GenTL/StopGocator" commands.
"GenTL/ScheduledStart" "GenTL/SystemScheduledStart" "GenTL/SensorScheduledStart"	Read-only. Schedule a start when the stamp (in the current domain, can be time or encoder mode) is reached. Applies for all three "GenTL/XScheduledStart" commands.
"GenTL/State" "GenTL/State(id)"	Read-only. By default, gets the state of the main sensor. If an ID is provided, the state of the connected sensor is returned. Use ID=0 for the main sensor. Any buddy starts at ID=1. For a system with a main and 2 buddies, the indices can be from 0 to 2.
"GenTL/BuddyState" "GenTL/BuddyState(id)"	Read-only. By default, gets the state of the first buddy sensor. If an ID is provided, the state of the connected sensor is returned. Use ID=0 for the first buddy sensor. For a system with a main and 2 buddies, the indices can be 0 or 1.
"GenTL/BuddyAt" "GenTL/BuddyAt(id)"	Read-only. By default, gets the serial number of the first buddy sensor. If an ID is provided, the serial number of the connected sensor is returned. Use ID=0 for the first buddy sensor. For a system with a main and 2 buddies, the indices can be 0 or 1.
"GenTL/BuddyCount"	Read-only. Returns the number of buddy sensors. For a system with a main and 2 buddies, the function will return 2.
"GenTL/Main"	Read-only. Returns the serial number of the main sensor.
"GenTL/AlignResult"	Read-only. Returns the alignment result of the last "GenTL/Align" command (see See Driver-level commands).
"GenTL/LastResult"	Read-only. Returns the last result for any GenTL XmlCommand.
"GenTL/TransformX(id)" "GenTL/TransformY(id)" "GenTL/TransformZ(id)" "GenTL/TransformXAngle(id)" "GenTL/TransformYAngle(id)" "GenTL/TransformZAngle(id)"	Read-Write. Gets or sets the transformation value for a given transform of the specificed sensor ID.
"GenTL/TransformEncoderResolution"	Read-Write. Gets/Sets the encoder resolution for a sensor.

The following driver-level commands are available:

Driver-level commands
Setting	Comment
"GenTL/FlushOldBuffers"	Flushes the GenTL pipeline buffers. Can be used to ensure only a new surface captured, instead of getting the previously captured surfaces.
"GenTL/FlushGocatorBuffers"	Flushes the Gocator pipeline buffers. Can be used to ensure only a new surface captured, instead of getting the previously captured surfaces.
"GenTL/StartGocator"	In an enabled StartStopControl mode, starts the Gocator programmatically.
"GenTL/StopGocator"	In an enabled StartStopControl mode, stops the Gocator programmatically.
"GenTL/ResetGocator" "GenTL/ResetGocator(wait)"	By default, this call resets the Gocator without waiting. If the wait parameter is set to 1, the command will wait for the Gocator to be reset, and reconnects to it automatically if possible.
"GenTL/Align(timeout)"	Performs an alignment on the sensor, waiting for the given timeout in seconds.
"GenTL/ClearAlignment"	Clears the current alignment on the sensor.
"GenTL/ResetEncoder"	Resets the encoder. Note that this only works if the encoder is directly connected to the sensor, and may not work on encoders connected to a Master.
"GenTL/Reconnect"	Attempts to reconnect to the sensor, after it was disconnected or reset.
"GenTL/Refresh"	Updates the client state to reflect any changes that have occurred in the sensor network.
"GenTL/ClearData"	Clears the data on message queue of the Gocator.
"GenTL/SoftwareTrigger"	Triggers the Gocator for an acquisition, if it is setup to use Software Triggering.

Sample Program for Various GenTL Settings

Copy

* Connect to the sensor. This code is auto generated by the Image Acquisition dialog box. User can manually override the directory path by editing the line below.
* Set image type to 'rgb' if the format is 16-bit RGB. 'gray' if the format is 16-bit mono
open_framegrabber ('GenICamTL', 0, 0, 0, 0, 0, 0, 'progressive', 16, 'rgb', -1, 'false', 'default', '127.0.0.1:3190', 0, -1, AcqHandle)
 
* Example calls for configuring the sensor
* Go2GenTL_ResampleMode (AcqHandle, ResampleMode)
* Go2GenTL_ImageSize (AcqHandle, ImageWidth, ImageHeight)
* Go2GenTL_Encoder (AcqHandle, EncoderValue)
Go2GenTL_Exposure (AcqHandle, currentExposure)
Go2GenTL_SetExposure (AcqHandle, currentExposure + 20)
set_framegrabber_param (AcqHandle, 'grab_timeout', 100000)
* set_framegrabber_param (AcqHandle, 'XmlCommand', 'GenTL/ClearData\n')
 
* Note: Configuration name has to be less than 16 characters
* Go2GenTL_SetConfigFileName (AcqHandle, 'newExposure.job')
* Go2GenTL_ConfigFileName (AcqHandle, ConfigFile1)
 
* Other examples
* *Get fixed length
* set_framegrabber_param(AcqHandle, 'XmlSetting', 'Setup/SurfaceGener')
* set_framegrabber_param(AcqHandle, 'XmlSetting', 'ation/FixedLength/')
* set_framegrabber_param(AcqHandle, 'XmlSetting', 'Length')
* get_framegrabber_param(AcqHandle, 'XmlSettingReturn', var1)
* *Set fixed length
* set_framegrabber_param(AcqHandle, 'XmlSetting', 'Setup/SurfaceGener')
* set_framegrabber_param(AcqHandle, 'XmlSetting', 'ation/FixedLength/')
* set_framegrabber_param(AcqHandle, 'XmlSetting', 'Length=400')
* set_framegrabber_param(AcqHandle, 'XmlSetting', '')
 
* Version
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/Version')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', version)
 
* Transform
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformX(1)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', xOffset)
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformX(1)=0.01\n')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformX(1)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', xOffset)
 
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformYAngle(1)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', yAngle)
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformYAngle(1)=0.01\n')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformYAngle(1)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', yAngle)
 
* Encoder Resolution
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformEncoderResolution')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', encoderRes)
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformEncoder')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'Resolution=0.002\n')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/TransformEncoderResolution')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', encoderRes)
 
* Buddy List
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/BuddyCount')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', buddyCount)
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/BuddyAt(0)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', buddy0)
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/BuddyAt(1)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', buddy1)
 
* State
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/Refresh\n')
 
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/State')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', state0)
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/State(1)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', state1)
 
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/BuddyState')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', bstate0)
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/BuddyState(1)')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', bstate1)
 
* Alignment
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/ClearAlignment')
set_framegrabber_param(AcqHandle, 'XmlSetting', '')
 
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/AlignResult')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', alignResult)
 
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/Align(5)')
set_framegrabber_param(AcqHandle, 'XmlSetting', '')
 
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/AlignResult')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', alignResult)
 
* Reset
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/ResetGocator(1)\n')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/LastResult')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', lastResult)
 
* Responsiveness
set_framegrabber_param(AcqHandle, 'XmlSetting', 'GenTL/')
set_framegrabber_param(AcqHandle, 'XmlSetting', 'IsResponsive')
get_framegrabber_param(AcqHandle, 'XmlSettingReturn', isResponsive)
 
 
close_framegrabber (AcqHandle)