使用 HALCON 控制相机

本章介绍使用 HALCON 软件控制（连接、配置和使用）Mech-Eye 工业级 3D 相机。HALCON 软件支持通过 GigE Vision2 协议与相机进行连接。本章主要内容包含：

使用前提

  • 相机和工控机已正确连接 。

    提示

    Nano 和 Pro XS 相机推荐与工控机直接连接，不使用交换机。

  • 工控机上已安装 HALCON 20.11 或以上。

  • 工控机上已安装 Mech-Eye SDK 2.0.0 或以上。

    提示

    相机固件版本与软件版本一致时，才可使用 Mech-Eye SDK。如需升级固件版本，请参考 升级相机固件。

  • 相机与工控机 IP 地址在同一网段。

    提示

    建议将相机与工控机设置为静态 IP 地址，IP 地址设置请参考 使用 Mech-Eye Viewer 设置 IP 地址 。

安装 HALCON 软件后，您可以通过以下方式控制相机。

使用 HALCON 助手控制相机

使用 HALCON 中的图像采集助手可快速连接相机、采集图像和调节参数。

在工控机上运行 HALCON 软件，选择 助手 ‣ 打开新的 Image Acquisition ，即可打开图像采集助手。

连接相机

  1. 在助手窗口的 资源 选项卡中， 选择 图像获取接口 ， 并从下拉菜单中选择 GigEVision2 。

    ../../_images/choose_gigevision2.png

    提示

    如下拉菜单中无 GigEVision2 选项，表明 GigEVision2 图像获取接口未安装。请参考 HALCON 的 安装指南 ，通过 MVTec 软件管理器（SOM）安装接口。

  2. 在 连接 选项卡中，选择 设备 ，单击 连接 可连接相机。

    ../../_images/connect_the_camera.png

    提示

    • 相机连接成功，连接 按钮变为 断开 ；如无变化，则为连接失败。如需断开与相机的连接，在 连接 选项卡中单击 断开 按钮。

    • 如相机已被连接，则连接一定不成功。请检查相机是否被其他客户端连接，相机断开连接后，再使用 HALCON 连接。

    • 设备 中的相机显示名称较长，可使用 Mech-Eye Viewer 连接相机后， 自定义相机显示名称 ，便于查找需要连接的相机。推荐设置为英语名称。

采集图像

相机连接后，在 连接 选项卡中单击 采集 即可进行单次图像采集。

注解

如相机采图时间较长，工控机可以 开启巨型帧功能 。

您也可以进行多次或连续图像采集，为此需先调节 AcquisitionMode 参数的值。

  • 进行多次图像采集：

    1. 切换至 参数 选项卡，将 AcquisitionMode 参数设置为 MultiFrame 。

    2. 单击右上角的 刷新 后，在 AcquisitionFrameCount 中设置需进行的图像采集次数。

    3. 切换至 连接 选项卡，单击 实时 进行图像采集。

    4. 设定次数的图像采集完成后，实时 按钮变为 停止 。单击 停止 停止图像采集。

  • 进行连续图像采集：

    1. 切换至 参数 选项卡，将 AcquisitionMode 参数设置为 Continuous 。

    2. 切换至 连接 选项卡，单击 实时 进行图像采集。

    3. 实时 按钮变为 停止 。单击 停止 停止图像采集。

注解

  • AcquisitionMode 参数设置为 MultiFrame 或 Continuous 时，仍可单击 采集 进行单次图像采集。

  • AcquisitionMode 参数设置为 SingleFrame 时，只可进行单次图像采集。

选择数据类型

相机连接后，默认采集的数据类型是 2D 图。您可通过调节 DeviceScanType 参数选择要获取的数据类型（2D 图或深度图）。

  1. 单击 参数 选项卡，将 DeviceScanType 参数设置为需要的数据类型。数据类型说明如下：

    值

    数据类型

    Areascan

    2D 图

    Areascan3D

    深度图（包含深度信息的 2D 图）

  2. 进行图像采集，获取所选的数据类型。

提示

勾选 参数 选项卡右上角的 更新图像，调节参数后 Canvas 窗口中的图像将自动更新。

设置采集区域

相机连接后，如需对获取的图像进行裁剪，可通过调整 Height、 Width、 OffsetX 和 OffsetY 四个参数设置采集区域。

请按照如下步骤设置采集区域：

  1. 选择需要设置采集区域的数据类型。

  2. 单击 采集 进行单次图像采集，确认当前图像。

  3. 切换至 参数 选项卡，调节 Height、 Width、 OffsetX 和 OffsetY 参数。下图展示这四个参数及其所定义的采集区域（橙色方框）与原始图像的关系。

    ../../_images/set_capture_region_1.png

    • Width ： 采集区域宽度

    • Height ：采集区域高度

    • OffsetX ：采集区域左上角的 x 坐标（原始图像左上角坐标为 (0, 0) ）

    • OffsetY ：采集区域左上角的 y 坐标

    注解

    以上四个参数的设置需满足如下要求：

    • （Width + OffsetX）不超过原始图像的宽度

    • （Height + OffsetY）不超过原始图像的高度

    原始图像的宽度和高度可在 只读参数 的 WidthMax 和 HeightMax 中查看（需将 可视度 设为 专家 或以上）。

  4. 再次进行图像采集，确认裁剪结果。

    提示

    勾选 参数 选项卡右上角的 更新图像，调节参数后 Canvas 窗口中的图像将自动更新。

  5. 切换至 代码生成 选项卡，单击 插入代码 生成相应的代码。

  6. 如需为另一数据类型设置采集区域：

    1. 在当前助手窗口中断开相机连接。

    2. 打开一个新的助手窗口并连接相机。

    3. 选择另一数据类型并重复上述步骤。

注解

  • 上述四个采集区域参数不会被保存至参数组中。如相机断电，其参数值将被重置。如需记录其参数值，请生成并保存代码。

  • 更改 DeviceScanType 和 Scan3DBinningEnable 参数也将重置上述采集区域参数的值。

采集区域与 Scan3DROI 的区别

Mech-Eye 工业级 3D 相机还提供了另外一组用于设置感兴趣区域的参数： Scan3DROILeft、 Scan3DROITop、 Scan3DROIHeight 和 Scan3DROIWidth （统称为“Scan3DROI”）。

采集区域参数和 Scan3DROI 的区别如下表。请根据需求选择要使用的参数。

采集区域

Scan3DROI

不可保存至参数组，相机断电将重置参数值

可保存至参数组

2D 图和深度图均可设置

2D 图不可设置

对图像进行裁剪

不对图像进行裁剪

只可在HALCON中设置

可用 Mech-Eye Viewer 中的可视化工具设置

调节参数

如获取的数据不满足需求，可调节相应参数。

提示

  • 相机支持参数组功能，通过切换参数组可以快速切换相机的参数配置。相机参数需要在指定的参数组下设置。

  • 如果需要增加或删除参数组，请通过 Mech-Eye Viewer 配置。使用 Mech-Eye Viewer 配置完参数组后，在 HALCON 参数 选项卡下，单击右上角的 刷新 按钮读取相机最新配置。

执行如下步骤调节参数：

  1. 相机连接后，单击 参数 选项卡，将 UserSetSelector 参数设置为要修改的参数组。

    ../../_images/select_parameter_group.png

  2. 找到 UserSetLoad 参数，单击右侧的 应用 读取配置。

    注解

    如单击 应用 后，各参数的值未更新，请再次单击。

  3. 找到需要修改的参数，并修改参数值。

  4. 找到 UserSetSave 参数，单击右侧的 应用 保存配置。

  5. 切换至 代码生成 选项卡，单击 插入代码 生成相应的代码。

参考信息：

  • 关于 GenICam 支持的相机参数的描述和解释，请下载和查阅 GenICam 参数说明。

  • GenICam 支持的相机参数 与 Mech-Eye Viewer 提供的参数基本上一一对应。关于参数的对应关系，请参见 GenICam 支持的相机参数 。

  • 设置 自动曝光感兴趣区域、 深度设置 及 感兴趣区域 等相机参数时，通常需要借助可视化工具进行不断调整从而获取理想的值。由于 HALCON 并未提供辅助参数设置的可视化工具，您可以借助 Mech-Eye Viewer 的可视化设置工具来设置这些参数。详细信息请查看 借助 Mech-Eye Viewer 为 GenICam 客户端设置相机参数 。

    提示

    使用 Mech-Eye Viewer 连接相机前，需断开相机与 HALCON 的连接。如连接不成功，请关闭 HALCON 软件后，再重新连接。

使用 HALCON 例程控制相机

为方便使用，本公司在 GitHub 上提供了 HALCON 例程。该例程可用于连接相机、采集数据、修改参数并保存数据。用户可以直接使用或者根据实际需要进行修改以满足项目需求。

注解

HALCON 例程使用 C++ 语言编写，可以在 HALCON 软件的 HDevelop 集成开发环境中直接运行。

运行例程

  1. 获取 HALCON 例程 ，依次单击 Code ‣ Download ZIP 即可下载。

  2. 使用以下任一方式在 HALCON 中打开例程。

    • 运行 HALCON，将例程拖拽至 HALCON 的 程序窗口 中。

    • 选中例程，右键选择 打开方式 ，单击 HDevelop 完成。

  3. 使用以下任一方式获取可连接相机列表。

    • 在 程序窗口 选中 info_framegrabber 算子所在的行，单击工具栏中的 step_over 按钮。

    • 在 程序窗口 选中 info_framegrabber 算子所在的行，单击键盘上的 F6 运行。

    提示

    获取可连接相机列表可以在 变量窗口 中 控制变量 区域的 DeviceInfos 变量中查看。

  4. 使用以下任一方式在 HALCON 例程中切换相机。

    • 根据相机 unique_name 切换相机。

      (1) 双击 控制变量 区域的 DeviceInfos ，可查看所有可连接的相机。

      ../../_images/camera_information_1.png

      (2) 选中相机并双击，复制 unique_name: 的相机名。

      ../../_images/camera_information_3.png

      (3) 定位至 tuple_regexp_select 算子所在的行，将 MechEye 替换为 unique_name 。

    • 根据相机序号切换相机。

      (1) 双击 控制变量 区域的 DeviceInfos ，可查看所有可连接的相机。

      ../../_images/camera_information_1.png

      (2) 每个序号对应不同的相机，查看需连接相机的序号。

      ../../_images/camera_information_2.png

      注解

      相机序号对应的相机是会变化的。

      (3) 定位至 open_framegrabber 命令，将 MechEyeCameraInfos[X] 中的 X 替换为序号，运行例程，即可连接对应的相机。

  5. 使用以下任一方式在 HALCON 中运行例程。

    • 单击工具栏中的 run 按钮。

    • 单击键盘上的 F5 运行例程。

  6. 运行结束后，在例程文件夹内查看本次运行获取的 2D 图和点云数据结果，默认保存文件名为 image2d.bmp 和 PointCloud.ply。

提示

  • 例程运行结束后需单击工具栏中的 reset 重置程序执行，否则将导致 Mech-Eye Viewer 无法连接到相机。

  • 图形窗口显示点云后，需单击该窗口中的 Continue 继续执行。否则，程序会卡在 visualize_object_model_3d 算子中。

  • 如相机采图时间较长，可为工控机 开启巨型帧功能 。

  • 网络较差导致数据丢失时，可以使用如下指令增大最大允许丢失包数。 ParameterValues 替换为新的最大允许丢失包数。

    set_framegrabber_param (AcqHandle, '[Stream]GevStreamMaxPacketGaps', ParameterValues)

例程说明

连接相机：

info_framegrabber ('GigEVision2', 'device', Info, DeviceInfos)
tuple_regexp_select (DeviceInfos, 'MechEye', MechEyeCameraInfos)
open_framegrabber ('GigEVision2', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1, 'false', 'default', MechEyeCameraInfos[0],   0, -1, AcqHandle)

采集：

grab_image (Image2d, AcqHandle)
grab_data (Image3d, Region, Contours, AcqHandle, ObjectModel3D)

获取参数：

get_framegrabber_param (AcqHandle, 'available_param_names', ParameterValues)

设置参数：

本例程的参数包含：2D 参数、3D 参数、感兴趣区域、深度范围及点云设置。

  • 2D 参数：

    * Switch to the 2D scanning mode.
set_framegrabber_param (AcqHandle, 'DeviceScanType', 'Areascan')
set_framegrabber_param (AcqHandle, 'AcquisitionMode', 'SingleFrame')

get_framegrabber_param (AcqHandle, 'Width', Width)
get_framegrabber_param (AcqHandle, 'Height', Height)
get_framegrabber_param (AcqHandle, 'PixelFormat', PixeLFormat)

* Set the 2D scanning parameters.
set_framegrabber_param (AcqHandle, 'Scan2DExposureMode', 'Timed')
set_framegrabber_param (AcqHandle, 'Scan2DExposureTime', 100)

  • 3D 参数：

    * Switch to the 3D scanning mode:
set_framegrabber_param (AcqHandle, 'DeviceScanType', 'Areascan3D')

* Open the 3D object model generator.
set_framegrabber_param (AcqHandle, 'create_objectmodel3d', 'enable')
set_framegrabber_param (AcqHandle, 'add_objectmodel3d_overlay_attrib', 'enable')

get_framegrabber_param (AcqHandle, 'Width', Width)
get_framegrabber_param (AcqHandle, 'Height', Height)
get_framegrabber_param (AcqHandle, 'PixelFormat', PixeLFormat)

* Set the 3D scanning exposure time parameter.
set_framegrabber_param (AcqHandle, 'Scan3DExposureCount', 1)
set_framegrabber_param (AcqHandle, 'Scan3DExposureTime', 8)

  • 深度范围：

    * Set the 3D scanning depth range parameter(unit: mm).
set_framegrabber_param (AcqHandle, 'DepthLowerLimit', 1)
set_framegrabber_param (AcqHandle, 'DepthUpperLimit', 3000)

  • 点云：

    * Set the 3D scanning point cloud filter parameter.
set_framegrabber_param (AcqHandle, 'CloudOutlierFilterMode', 'Normal')
set_framegrabber_param (AcqHandle, 'CloudSmoothMode', 'Normal')

保存：

  • 2D 图：

    * Acquire the 2D image from the camera.
grab_image (Image2d, AcqHandle)

* Save the 2D image result in "Image2d.bmp"
write_image( Image2d , 'bmp' , 0 , 'Image2d' )

  • 点云：

    * Acquire the 3D data from the camera.
grab_data(Image3d, Region, Contours, AcqHandle, ObjectModel3D)

get_object_model_3d_params(ObjectModel3D, 'num_points', NumOfPoints)

if(NumOfPoints != 0)
    * Save the point cloud result in "PointCloud.ply"
    write_object_model_3d (ObjectModel3D, 'ply', 'PointCloud.ply', [], [])
endif

断开连接：

clear_object_model_3d (ObjectModel3D)
close_framegrabber (AcqHandle)

注解

以 * 开头的均为描述内容。

调节参数

如获取的数据不满足需求，可调节相应参数。

提示

  • 相机支持参数组功能，通过切换参数组可以快速切换相机的参数配置。相机参数需要在指定的参数组下设置。

  • 如果需要增加或删除参数组，请通过 Mech-Eye Viewer 配置。

执行如下步骤调节参数：

  1. 使用以下算子获取相机的参数组列表。

    get_framegrabber_param (AcqHandle, 'UserSetSelector_values', ParameterValues)

  2. 在 控制变量 区域的 ParameterValues 中，查看所有的参数组名称。

  3. 使用以下算子选择要修改的参数组。 UserSetSelector 和 UserSetLoad 为相机参数，分别用于选择和加载参数组。 ParameterGroupName 替换为实际参数组名称。

    set_framegrabber_param (AcqHandle, 'UserSetSelector','ParameterGroupName')
set_framegrabber_param (AcqHandle, 'UserSetLoad','ParameterGroupName')

  4. 使用以下算子获取指定参数的值。 ParameterName 替换为实际相机参数名称。 ParameterValues 是保存获取参数值的变量，可以根据需要调整。注意变量不需要置于引号内。

    get_framegrabber_param (AcqHandle, 'ParameterName', ParameterValues)

  5. 在 控制变量 区域的 ParameterValues 中，查看该参数的值。

  6. 使用以下算子修改参数设置。 ParameterName 替换为实际相机参数名称， NewParameterValue 替换为新的参数值。

    set_framegrabber_param (AcqHandle, 'ParameterName', 'NewParameterValue')

  7. 使用以下算子将参数设置修改保存到参数组中。 UserSetSave 为相机参数，用于保存参数设置到参数组。 ParameterGroupName 替换为实际参数组名称。

    set_framegrabber_param (AcqHandle, 'UserSetSave', 'ParameterGroupName')

参考信息：

  • 关于 GenICam 支持的相机参数的描述和解释，请下载和查阅 GenICam 参数说明。

  • GenICam 支持的相机参数 与 Mech-Eye Viewer 提供的参数基本上一一对应。关于参数的对应关系，请参见 GenICam 支持的相机参数 。

  • 设置 自动曝光感兴趣区域、 深度设置 及 感兴趣区域 等相机参数时，通常需要借助可视化工具进行不断调整从而获取理想的值。由于 HALCON 并未提供辅助参数设置的可视化工具，您可以借助 Mech-Eye Viewer 的可视化设置工具来设置这些参数。详细信息请查看 借助 Mech-Eye Viewer 为 GenICam 客户端设置相机参数 。

    提示

    使用 Mech-Eye Viewer 连接相机前，需断开相机与 HALCON 的连接。如连接不成功，请关闭 HALCON 软件后，再重新连接。