• Linux with kernel 2.6 (or higher).
• A working installation of GStreamer 1.0 multimedia library with all required kernel modules for the acquisition hardware to be used and at least the base plugins from GStreamer.
• In some cases, the user running HALCON will need to be in the video group in order to be able to access some devices (e.g. V4L2 devices).
• HALCON image acquisition interface hAcqGStreamer.so or hAcqGStreamerxl.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.
• GenICam version 3.0.2 . The corresponding files are part of the HALCON runtime installation and are located in the directory genicam within the HALCON base directory %HALCONROOT%.

• Linux: Extract the archive containing the interface files to the HALCON base directory $HALCONROOT.

• Support of building and running a GStreamer pipeline using launcher syntax.
• Grabbing from multiple pipelines.
• Flexible device lookup and connection options.
• Synchronous and asynchronous grabbing.
• Support of callbacks for feature change notifications.
• Software control of appsink plugin parameters using GenApi.
• Support for the following GStreamer pixel formats: GRAY8, GRAY16_LE, BGR, RGB, BGRA, RGBA, YUY2, bggr, grbg, rggb, gbrg, UYVY and IYU1.

• No external triggering.

• Call info_framegrabber with 'info_boards' or 'device' parameter to discover the available devices and use the obtained string in open_framegrabber. In this case, the interface will try to generate a compatible pipeline with the available information. However, this does not always work as expected and the initialization may fail due to incompatibilities between plugins in the suggested pipeline.
• Directly specify the pipeline on open_framegrabber. This is the recommended way for most use cases. When using it, immediate feedback is provided in case of failure. The way to provide the string in open_framegrabber is to prepend the pipeline with #PIPE#, as it can be seen in the following small example:

   
  #PIPE# videotestsrc ! video/x-raw,format=RGB ! appsink 
  

  All pipeline strings given to the interface must use the appsink plugin at the end of the pipeline. The interface will try to find this element in the pipeline and use it to get the frames from the stream. If the appsink plugin is not found, an error will be raised. If needed, use a color conversion plugin or specify the format for the PAD to use one of the pixel formats supported by the interface.
  All the configuration of the acquisition must be provided using the pipeline string. The GStreamer interface does not allow to reconfigure individual elements of the pipeline. If you need to modify a property of the pipeline, you will have to specify the pipeline again and create it anew. For this reason, features such as Width, Height and PixelFormat are marked as read only. Notable exceptions to this are the MaxBuffers and DropBuffers features, that are properties of the appsink plugin and that can be changed at runtime.
  
  

• This interface uses GenApi version version.genapi, for more details refer to the GenICam homepage. The corresponding files are part of the HALCON runtime installation and are located in the directory genicam within the HALCON base directory %HALCONROOT% or $HALCONROOT, respectively. This version is the same as the officially released version at the time of writing.
• The HALCON GStreamer interface sets all necessary environment variables on its own and ignores other installed GenICam packages by default.
  If you want to use another GenICam package, you need to set the environment variable HALCON_USE_EXTERNAL_GENAPI. This skips the step of setting all necessary variables and paths internally, so you have to make sure they are set correctly. Please note that it might not be possible to use different GenApi versions with different interfaces at the same time and that you must use the required GenApi version for this interface.
• The caching of device XML files is activated to speed up processing, writing to a temporary directory subject to availability of %TEMP%, %TMP%, $TMPDIR, /tmp or %HALCONROOT%.
• The remote device control features as well as the GHACHI Producer control features of this interface are controlled via GenApi.

• Features of the connected device ("remote device"), typically a camera, are usually loaded directly from the connected device.
• Features of the GHACHI Producer are exposed through a set of GenICam description files, one for each internal entity to control the device tree:
  • The "system" – representing the overall behavior of the acquisition interface
  • The interface used to connect the device to the system.
  • A proxy (called "local device") to the device, controlling the GHACHI Producer view of the device.
  • The data stream used for the acquisition (if the device provides any data streams).

 
RemoteFile=%PATH_TO_GENICAM_FILE_OF_THE_DEVICE% 
SystemFile=%PATH_TO_GENICAM_FILE_OF_THE_SYSTEM_MODULE% 
InterfaceFile=%PATH_TO_GENICAM_FILE_OF_THE_INTERFACE_MODULE% 
DeviceFile=%PATH_TO_GENICAM_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamFile=%PATH_TO_GENICAM_FILE_OF_THE_STREAM_MODULE% 

• Internal parameters of the HALCON GStreamer image acquisition interface itself. These are named following the "underscore" naming style, e.g., color_space, and are all lowercase.
• GenICam-based parameters of the device, usually a camera, use by convention the "CamelCase" style, e.g., ExposureTime.
• GenICam-based parameters of the individual GHACHI Producer modules (system, interface, device and data stream) use by convention the same style but are prefixed with the module name in square brackets. Beware that the system and interface modules might potentially be shared by multiple opened devices, so changing their configuration might have side effects on other connections as well. The following prefixes are used:
  • "[System]", e.g., [System]TLVendorName.
  • "[Interface]", e.g., [Interface]InterfaceType.
  • "[Device]", e.g., [Device]DeviceID.
  • "[Stream]", e.g., [Stream]StreamBufferHandlingMode.

• IInteger – integer value, mapped directly to HALCON's integer parameter type. It will also accept real parameters and when the GenICam feature in question is identified to be an IP or MAC address, the string representation of the address will also be accepted. It should be highlighted that a problem can occur when running HALCON on a 32-bit platform (where integer parameters are 32-bit wide) and accessing a GenICam feature that is naturally 64-bit. In such cases the full range of the feature will not be available to the application and its value might be truncated. Also the sign of the parameter might be misinterpreted. To solve this problem, the parameter 'split_param_values_into_dwords' can be used. This maps the 64-bit IInteger value into two 32-bit integer values and vice versa.
• IFloat – floating point value, mapped directly to HALCON's real parameter type. It will also accept integer parameters.
• IString – string value, mapped directly to HALCON's string parameter type.
• IBoolean – boolean type is handled through HALCON's integer parameters, a value of 0 (zero) means logical false, other values mean logical true.
• IEnumeration – enumeration is a type that allows selecting from a set of values that are primarily identified by their name (the values are called 'enum entries'). Enumerations are interfaced through HALCON's string parameter type, while the enum entry names are used as the parameter values.
• ICommand – The command type allows to "execute" actions. To execute a command, use set_framegrabber_param with an integer parameter of any value (the value is ignored). Some commands' execution might take longer time and the command provides feedback when it is done. To query the status, use get_framegrabber_param for that command. It will return an integer value of 1 if it "is done" (command execution has finished), 0 if it has not finished yet. Note that if some other features are designed to be dependent on the command, querying the "is done" status might be essential to get the depending features invalidated (and updated with new values) as soon as the command execution finishes.
• IRegister – The register data type is used for plain memory blobs that cannot be mapped to any other data type. They are interfaced through HALCON's string parameter type, the register value is the hexadecimal string representation of the register's memory.

 
RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE% 
SystemPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_SYSTEM_MODULE% 
InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_INTERFACE_MODULE% 
DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_STREAM_MODULE% 

• The application (you) explicitly changed that feature.
• Another feature has changed and the notified feature "depends" on the changed feature (the dependencies are defined in the GenICam description file).
• Access mode or current range for the feature has changed.
• As a result of regular "polling" in case of uncached features.
• As a result of device event delivery if the feature is connected to that event.
• As a result of new buffer delivery for features corresponding to chunk data.

• Some parameters depend on special conditions, e.g., a valid buffer or another parameter activated. After opening the camera these conditions may not yet be fulfilled, so the depending parameters are not shown. By using the 'Refresh' button, all parameters are read again and the depending parameters should appear if the conditions are fulfilled then.
• There are also some parameters regarding the image size and the payload size, which can only be changed if no acquisition takes place. The safest way to ensure this is to apply the action parameter 'do_abort_grab'. Please note that 'Update Image' has to be disabled first.
• The behavior of allowing changes to parameters while streaming is active depends on the capabilities of the device. It is possible that some cameras give you control over, e.g., the exposure time, while streaming and others do not.

Following transformations from the camera color space (see also PFNC) to the interface color space (see also 'color_space' parameter in this document) are supported:

• Bayer pattern to 'rgb':
  

  Bayer_LMMN R G1 G2 B ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

  Bayer_NMML B G1 G2 R ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

  with G = (G1 + G2) / 2.

• Y'CbCr to 'rgb' (Note: gamma correction is not considered):
  

  R = Y' + 1.4020 * (Cr- M)
G = Y' - 0.34414 * (Cb- M) -0.71414 * (Cr- M)
B = Y' + 1.7720 * (Cb - M)

• RGB to 'yuv' ('yuv' corresponds to Y'CbCr of PFNC, Note: gamma correction is not considered):
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B
Cb = -0.16874 * R - 0.33126 * G + 0.5 * B + M
Cr = 0.5 * R - 0.41869 * G - 0.08131 * B + M

• RGB to 'gray':
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B

Parameters for open_framegrabber