Capture Settings in HALCON

Introduction

When you use a Zivid camera through the GenICam GenTL interface in HALCON, every Zivid capture setting is exposed as a GenICam feature node. You configure and read these nodes in HDevelop with set_framegrabber_param and get_framegrabber_param, or browse them visually in the HDevelop Image Acquisition Assistant.

This page explains:

  • How to configure capture settings

  • How to discover which settings a connected camera exposes

  • How the Zivid SDK settings map to GenICam node names

Note

We recommend configuring capture settings from a .yml settings file (see Configuring settings from a YML file (recommended) below) rather than setting individual nodes. This ensures a single source of truth for your settings and is the only way to configure settings with no individual GenICam node, such as the 2D Color setting.

To learn what the individual settings do, see Camera Settings.

Inspecting the available and active settings

Figuring out which capture settings are available, and which are currently set, is the part that is least obvious in HALCON. There are two ways to do it.

Using the HDevelop Image Acquisition Assistant

In HDevelop, open Assistants → Open New Image Acquisition and connect to the Zivid device. The Parameters tab shows the full GenICam feature tree for the connected camera, where you can read and edit every available setting interactively. This is the quickest way to explore what a given camera model supports.

Programmatically

To enumerate the settings from code, query the interface and the connected camera:

* Parameters exposed by the GenICam GenTL interface
info_framegrabber ('GenICamTL', 'parameters', Information_parameters, ValueList_parameters)
info_framegrabber ('GenICamTL', 'parameters_readonly', Information_parameters_readonly, ValueList_parameters_readonly)

* All node names available on the connected camera
get_framegrabber_param (AcqHandle, 'available_param_names', Value_available_param_names)

Once you have the node names, read the current value of any of them with get_framegrabber_param, for example:

get_framegrabber_param (AcqHandle, 'Engine', CurrentEngine)
get_framegrabber_param (AcqHandle, 'SamplingColor', CurrentSamplingColor)

The QuerySettingsAndParameters.hdev sample enumerates the interface parameters and reads a range of camera, device, and stream nodes.

Note

The per-acquisition settings (Aperture, ExposureTime, Gain, and Brightness) belong to the acquisition list used in HDR captures, not to a single flat value. When settings are loaded from a .yml file, that file remains the source of truth; use the nodes above for inspection and debugging. Some nodes also have model-specific limits and options, so the available parameters can differ between camera models.

Configuring individual settings nodes (advanced)

You can also configure each setting by writing its GenICam node directly. This is useful for small adjustments or when generating settings programmatically, but for full settings we recommend loading a YML file.

The per-acquisition settings are configured through the multi-acquisition list. Switch to HDR mode, reset any previous acquisitions, then add one acquisition per exposure:

set_framegrabber_param (AcqHandle, 'AcquisitionMode', 'MultiAcquisitionFrame')
set_framegrabber_param (AcqHandle, 'ResetAcquisitions', 1)

set_framegrabber_param (AcqHandle, 'Aperture', 5.66)
set_framegrabber_param (AcqHandle, 'ExposureTime', 6500)
set_framegrabber_param (AcqHandle, 'Brightness', 1.8)
set_framegrabber_param (AcqHandle, 'Gain', 1.0)
set_framegrabber_param (AcqHandle, 'AddAcquisition', 1)

The remaining settings (engine, sampling, region of interest, filters, and color) are global and set once:

set_framegrabber_param (AcqHandle, 'Engine', 'stripe')
set_framegrabber_param (AcqHandle, 'SamplingColor', 'rgb')
set_framegrabber_param (AcqHandle, 'ProcessingFiltersSmoothingGaussianEnabled', 1)
set_framegrabber_param (AcqHandle, 'ProcessingFiltersSmoothingGaussianSigma', 1.5)

The CaptureHDRCompleteSettings.hdev sample configures every available node explicitly and is the most complete reference for the node names.

Mapping Zivid SDK settings to GenICam nodes

The GenICam node names are a flattened form of the Zivid SDK Settings tree: take the full setting path, drop the Settings root, and concatenate the remaining names in PascalCase. For example, Settings/Processing/Filters/Smoothing/Gaussian/Sigma becomes ProcessingFiltersSmoothingGaussianSigma.

The table below maps the most commonly used settings.

Zivid SDK setting

GenICam node name

Settings/Engine

Engine

Settings/Sampling/Color

SamplingColor

Settings/Sampling/Pixel

SamplingPixel

Settings/Acquisition/Aperture

Aperture

Settings/Acquisition/ExposureTime

ExposureTime

Settings/Acquisition/Brightness

Brightness

Settings/Acquisition/Gain

Gain

Settings/RegionOfInterest/Box/Enabled

RegionOfInterestBoxEnabled

Settings/RegionOfInterest/Box/PointO

RegionOfInterestBoxPointOX/OY/OZ

Settings/RegionOfInterest/Box/PointA

RegionOfInterestBoxPointAX/AY/AZ

Settings/RegionOfInterest/Box/PointB

RegionOfInterestBoxPointBX/BY/BZ

Settings/RegionOfInterest/Box/Extents

RegionOfInterestBoxExtentsMin/Max

Settings/RegionOfInterest/Depth/Enabled

RegionOfInterestDepthEnabled

Settings/RegionOfInterest/Depth/Range

RegionOfInterestDepthRangeMin/Max

Settings/Processing/Filters/Smoothing/Gaussian/Enabled

ProcessingFiltersSmoothingGaussianEnabled

Settings/Processing/Filters/Smoothing/Gaussian/Sigma

ProcessingFiltersSmoothingGaussianSigma

Settings/Processing/Filters/Noise/Removal/Enabled

ProcessingFiltersNoiseRemovalEnabled

Settings/Processing/Filters/Noise/Removal/Threshold

ProcessingFiltersNoiseRemovalThreshold

Settings/Processing/Filters/Noise/Suppression/Enabled

ProcessingFiltersNoiseSuppressionEnabled

Settings/Processing/Filters/Noise/Repair/Enabled

ProcessingFiltersNoiseRepairEnabled

Settings/Processing/Filters/Outlier/Removal/Enabled

ProcessingFiltersOutlierRemovalEnabled

Settings/Processing/Filters/Outlier/Removal/Threshold

ProcessingFiltersOutlierRemovalThreshold

Settings/Processing/Filters/Reflection/Removal/Enabled

ProcessingFiltersReflectionRemovalEnabled

Settings/Processing/Filters/Cluster/Removal/Enabled

ProcessingFiltersClusterRemovalEnabled

Settings/Processing/Filters/Hole/Repair/Enabled

ProcessingFiltersHoleRepairEnabled

Settings/Processing/Resampling/Mode

ProcessingResamplingMode

Settings/Processing/Color/Balance/Red

ProcessingColorBalanceRed

Settings/Processing/Color/Balance/Green

ProcessingColorBalanceGreen

Settings/Processing/Color/Balance/Blue

ProcessingColorBalanceBlue

For the complete list of node names available on your camera, use available_param_names as described in Inspecting the available and active settings, or browse the feature tree in the HDevelop Image Acquisition Assistant.

Warning

The 2D Color setting (Settings/Color) has no individual GenICam node and can only be configured by loading a YML file.