C++¶

本章介绍如何在 Windows 系统中使用 CMake 配置 Mech-Eye API 的 C++ 例程，并使用 Visual Studio 构建例程。

例程简介
使用前提
构建及运行例程

例程简介 ¶

例程分为 6 类：Basic、Advanced、Util、Laser、UHP 和 Halcon。

Basic 例程：与连接和基础采集相关。
Advanced 例程：与高级采集技巧相关。
Util 例程：与获取相机信息及设置参数相关。
Laser 例程：仅适用于 Laser，LSR 和 DEEP 系列相机。
UHP 例程：仅适用于 UHP 系列相机。
Halcon 例程：通过 Mech-Eye API 获取HALCON可读取的点云。

Basic
- ConnectToCamera：连接相机。
- ConnectAndCaptureImage：连接相机并获取 2D 图、深度图及点云数据。
- CaptureColorMap：从相机获取并保存 2D 图。
- CaptureDepthMap：从相机获取并保存深度图。
- CapturePointCloud：使用单个曝光时间采集图像，生成并保存白色点云和彩色点云。
- CaptureHDRPointCloud：使用多个曝光时间采集图像，生成并保存白色点云和彩色点云。
- CapturePointCloudROI：获取并保存感兴趣区域内的白色点云和彩色点云。
- CapturePointCloudFromTextureMask：从覆盖掩膜的 2D 图和深度图生成并保存白色点云和彩色点云。
Advanced
- CaptureCloudFromDepth：从 2D 图与深度图生成并保存点云。
- CaptureSequentiallyMultiCamera：使用多台相机按序获取并保存 2D 图、深度图及点云。
- CaptureSimultaneouslyMultiCamera：使用多台相机同时获取并保存 2D 图、深度图及点云。
- CaptureTimedAndPeriodically：在设定时间内，定时获取并保存 2D 图、深度图和点云。
Util
- GetCameraIntri：获取并打印相机内参。
- PrintDeviceInfo：获取并打印相机型号、序列号、固件版本等信息。
- SetDepthRange：设置相机深度范围。
- SetParameters：设置相机参数。
- SetUserSets：执行参数组相关功能，如获取参数组名称，修改参数组名称，保存参数组参数信息等。通过参数组可以保存一组参数值并快速应用。
Laser
- SetLaserFramePartitionCount：将投影仪视野分为多个分区，结构光一次投射到一个分区。整个视野的输出由所有分区的图像融合而成。
- SetLaserFrameRange：设置结构光投射范围，整个视野范围从 0 到 100。
- SetLaserFringeCodingMode：设置结构光样式的编码模式。
- SetLaserPowerLevel：设置激光器的输出功率（最大输出功率的百分比），影响激光强度。
UHP
- SetUHPCaptureMode：设置采集模式（分为：2D 相机 1，2D 相机 2 及同时使用两个 2D 相机并融合输出）。
- SetUHPFringeCodingMode：设置结构光样式的编码模式。
Halcon
- CaptureHalconPointCloud ：从相机获取点云数据，通过HALCON C++接口转换并保存点云。

使用前提 ¶

使用 Mech-Eye API 的 C++ 例程，需先满足以下使用前提：

正确连接相机和工控机。
安装必需软件。
安装例程依赖的可选软件，并添加相关的环境变量。

必需软件和可选软件及其安装注意事项，详见以下小节。

安装必需软件
安装可选软件
添加环境变量

安装必需软件 ¶

使用 Mech-Eye API 的 C++ 例程，必须安装 Mech-Eye SDK、CMake 及 Visual Studio。

安装最新版本的 Mech-Eye SDK

请根据 Mech-Eye SDK 설치 가이드 安装或升级 Mech-Eye SDK。

安装CMake（3.2 或以上版本）

下载 CMake：下载 Windows x64 Installer 右侧的安装包。

$MechEyeAPI\Samples\CppWindows\img/cmake_download.png$
安装时，请选择以下两个选项，以将 CMake 添加至环境变量，并创建 CMake 的桌面快捷方式。
- Add CMake to the system PATH for all users
- Create Cmake Desktop Icon

$MechEyeAPI\Samples\CppWindows\img/cmake_1.png$

安装Visual Studio（2015 或以上版本）

下载 Visual Studio 安装包。
安装时，勾选 桌面应用和移动应用 分类中的以下两个工作负荷，再点击安装。
- 使用 C++ 的桌面开发
- 通用 Windows 平台开发

힌트

安装完成后，请重启工控机或 PC。如仍需安装可选软件，可在添加环境变量后再重启。

安装可选软件 ¶

部分例程中的功能依赖以下第三方软件库。如需使用下表中列出的例程，则必须安装其依赖的软件。

OpenCV：3.4.5 或以上版本
PCL：1.12.1 版本

참고

Visual Studio 2015 不支持 PCL。
HALCON：20.11 或以上版本

주의

如未安装可选软件，则配置例程前必须执行禁用不需要的例程（可选）中的操作。

依赖第三方软件库的例程详见下表。

例程	OpenCV	PCL	HALCON
CaptureColorMap	√
CaptureDepthMap	√
CapturePointCloud		√
CaptureHDRPointCloud		√
CapturePointCloudROI		√
CapturePointCloudFromTextureMask		√
CaptureCloudFromDepth		√
CaptureTimedAndPeriodically	√	√
CaptureSimultaneouslyMultiCamera	√	√
CaptureSequentiallyMultiCamera	√	√
CaptureHalconPointCloud			√

安装 OpenCV

下载并安装 OpenCV。请记录 OpenCV 的安装路径。
将 OpenCV 添加至环境变量。详见下一节添加环境变量。

安装 PCL

打开 PCL 下载页面，单击 PCL 1.12.1 下的 Assets，并下载 PCL-1.12.1-AllInOne-msvc2019-win64.exe。
运行 PCL-1.12.1-AllInOne-msvc2019-win64.exe 安装 PCL。安装时，请选择 Add PCL to the system PATH for all users, 以将 PCL 添加至环境变量。

$MechEyeAPI\Samples\CppWindows\img/pcl_2.png$

힌트

安装过程中，可能弹出如下报错：

Warning! PATH too long installer unable to modify PATH!

此情况下，需安装完成后手动将 PCL 添加至系统变量。详见下一节添加环境变量。
将 PCL 依赖的 OpenNI2 添加至环境变量。详见下一节添加环境变量。

安装 HALCON

安装 HALCON 20.11 或以上版本。需确保 HALCON 的证书在有效期内。

添加环境变量 ¶

如需使用依赖 OpenCV 或 PCL 的例程，请根据以下步骤添加相关的环境变量。

右键单击桌面上的 此电脑 ，选择属性。
选择 高级系统设置，再在弹出的 系统属性 窗口单击环境变量，进入 环境变量 界面。
双击 Path 变量进入 编辑环境变量 页面。单击右上角新建，依次添加以下路径。添加完成后，单击右下角确定。
- PCL 相关：C:\Program Files\OpenNI2\Tools
- OpenCV 相关：xxx\OpenCV\build\x64\vc14\bin
- OpenCV 相关：xxx\OpenCV\build\x64\vc14\lib
如安装 PCL 时弹出报错，则需添加以下路径：
- xxx\PCL 1.12.1\bin
- xxx\PCL 1.12.1\3rdParty\VTK\bin

힌트

添加环境变量后，请重启工控机或 PC，否则可能导致添加的环境变量不生效。

构建及运行例程 ¶

您可以一次性构建全部例程，也可以仅构建单独一个例程。

禁用不需要的例程（可选）
使用 CMake 配置例程
使用 Visual Studio 构建例程
运行例程

禁用不需要的例程（可选）¶

주의

未安装可选软件的情况下一次性构建全部例程时，必须进行该节的操作。否则使用 CMake 配置例程时将报错。

如不需要使用依赖 OpenCV、PCL 或 HALCON 的例程，在一次性构建全部例程前，需对 CMakeLists 文件进行编辑，禁用这些例程。

打开 xxx\Mech-Eye SDK-x.x.x\API\samples 路径下的 CMakeLists.txt。
编辑 option 语句：找到以 option 开头的行，将行末的 ON 改为 OFF，可禁用依赖该行提及软件的例程。

示例：不需要构建依赖 HALCON 的例程，则将以 option(USE_HALCON 开头的行末尾的 ON 改为 OFF。
保存修改后，关闭 CMakeLists.txt。

使用 CMake 配置例程 ¶

右键单击 CMake 并选择 以管理员身份运行。
输入源码路径与构建目录路径。
- 如需一次性构建所有例程，请输入如下路径。
Where is the source code

xxx\Mech-Eye SDK-x.x.x\API\samples

Where to build the binaries

xxx\Mech-Eye SDK-x.x.x\API\samples\build
- 如需单独构建某一例程，请输入如下路径。将路径中的 Category 替换为例程所在类别的名称，将 SampleName 替换为例程名称。
Where is the source code

xxx\Mech-Eye SDK-x.x.x\API\samples\Category\SampleName

Where to build the binaries

xxx\Mech-Eye SDK-x.x.x\API\samples\Category\SampleName\build
单击 Configure，进入配置页面。选择 Visual Studio 的版本，然后单击 Finish。配置成功后，日志最末行将显示 Configuring done。

$MechEyeAPI\Samples\CppWindows\img/configuration_1.png$
单击 Generate 生成解决方案。生成成功后，日志最末行将显示 Generating done。然后，单击 Open Project，使用 Visual Studio 打开解决方案。

使用 Visual Studio 构建例程 ¶

在 Visual Studio 工具栏中，将解决方案配置从 Debug 改为 Release 模式。
在 解决方案资源管理器 窗口中右键单击顶端的 解决方案 “xxx”，并选择 生成解决方案。每个例程会生成对应的 exe 格式可执行文件，保存在 Release 文件夹中，位于在 CMake 中输入的 Where to build the binaries 目录下。

运行例程 ¶

您可以在 Visual Studio 中直接运行例程，也可以双击运行例程的可执行文件。

在 Visual Studio中运行例程

在 解决方案资源管理器 窗口中右键单击想要运行的例程，并选择 设为启动项目。
单击工具栏中的本地 Windows 调试器即可在 Visual Studio 中运行例程。

例程运行过程中，请根据提示输入待连接相机的编号 (device index)，并按回车键连接相机。
如例程保存了图像或点云，将在 build 文件夹中得到保存的文件（即在 CMake 中输入的 Where to build the binaries 目录）。

运行例程可执行文件

进入在 CMake 中输入的 Where to build the binaries 目录，打开其中的 Release 文件夹。
运行与例程同名的 exe 文件。

例程运行过程中，请根据提示输入待连接相机的编号 (device index)，并按回车键连接相机。
如例程保存了图像或点云，将在 Release 文件夹中得到保存的文件。

Where is the source code	xxx\Mech-Eye SDK-x.x.x\API\samples
Where to build the binaries	xxx\Mech-Eye SDK-x.x.x\API\samples\build

Where is the source code	xxx\Mech-Eye SDK-x.x.x\API\samples\Category\SampleName
Where to build the binaries	xxx\Mech-Eye SDK-x.x.x\API\samples\Category\SampleName\build