SDK 下载与编译

该部分旨在指导用户搭建 Percipio 深度相机应用开发的软件环境，即下载和编译 Percipio 软件开发包 PercipioDC Camport SDK（以下简称 Camport SDK）。

用户可以基于 Camport SDK，获取 深度图、红外图、彩色图 和 点云图，用于导航、避障、三维建模、手势识别等应用。

上位机开发环境

若需在上位机运行或开发上位机图像应用软件，请先配置上位机开发环境。

Linux 平台
Windows 平台
ROS 平台
第三方平台

Linux平台 (C++)

Linux SDK 支持 AArch64、ARMv7hf、RaspberryPi、i686 和 x86-64 硬件平台，并为开发者编译程序提供相应平台的库文件。Linux SDK 未提供可执行的应用程序，用户可通过编译示例代码来生成可执行的应用。

下面以 Ubuntu18.04 为例介绍在 Linux 平台为 Percipio 深度相机搭建开发环境的过程：

  1. 下载 Camport3 SDK

  2. 安装 USB 驱动

  3. 安装依赖

  4. 设置权限

  5. 编译

  6. 运行

下载 Camport3 SDK

选择以下任意方式，下载 Camport3 SDK：

  • 使用浏览器访问 https://github.com/percipioxyz/ 并下载 Camport3 SDK。

  • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

    git clone https://github.com/percipioxyz/camport3.git

Camport3 SDK 目录结构如下图所示：

Camport3 SDK目录结构

Camport3 SDK目录结构

Doc 目录

存放了 SDK API 参考文档。该文档是通过 Doxygen 生成的 PDF 文件，包括了类、结构和接口的描述信息。

include 目录

存放了用于调用动态库的头文件：

  • TYImageProc.h：图像后处理函数接口的头文件。

  • TYCoordinateMapper.h：图像空间转换的映射。

  • TYApi.h 文件：提供了用于配置深度相机、获取图像数据的全部 API。用户可以基于这些 API 开发自己的应用。

lib/linux 目录

存放了支持 Linux 操作系统的库文件，兼容 AArch64、ARMv7hf、RaspberryPi、i686 和 x86-64 硬件平台。

lib/win 目录

存放了支持 Windows 操作系统的库文件，兼容 x64 和 x86 硬件平台。

sample 目录

存放了可供用户编程参考的示例程序。关于示例程序，详情请参见 示例程序说明。

安装 USB 驱动

Camport SDK 默认使用 LibUSB 作为 USB 深度相机的用户态驱动库。使用 Percipio USB 深度相机前需要安装 LibUSB 软件。

sudo apt-get install libusb-1.0-0-dev

安装依赖

CMake

CMake 是一个跨平台的安装（编译）工具，可以用简单的语句来描述所有平台的安装（编译过程）。它能够输出各种各样的 makefile 或者 project 文件，能测试编译器所支持的 C++ 特性，类似 UNIX 下的 automake。只是 CMake 的组态档取名为 CMakeLists.txt。CMake 并不直接建构出最终的软件，而是产生标准的建构档（如 UNIX 的 Makefile 或 Windows Visual C++ 的 projects / workspaces），然后再以一般的建构方式使用。

Camport SDK 使用 CMake 来构建标准的工程，利用各平台的原生建构系统的能力，可适配不同的平台环境。

sudo apt-get install cmake

备注

Camport SDK 要求用户安装 CMake 2.8.0 及更高的版本。

OpenCV

Camport SDK 可通过 USB 接口或者以太网接口接收 Percipio 深度相机输出的深度数据。取得深度数据后，Camport SDK 中提供的示例程序使用 OpenCV 图像处理软件库进行深度数据的渲染。编译示例程序前，需要安装 OpenCV 图形处理软件库。

sudo apt-get install libopencv-dev

备注

  1. Camport SDK 要求用户安装 OpenCV 2.4.8 及更高版本。

  2. 如果目标应用程序不使用 OpenCV 进行图像显示或者其他图像处理计算，则无需安装 OpenCV。

设置权限

根据 Linux 系统的权限管理机制，默认情况下需要 root 权限才能访问 Percipio USB 深度相机，非 root 用户可以创建 udev rule 来修改设备权限。

在 etc/udev/rules.d 文件所在目录下，新建一个扩展名为 .rules 的规则文件（如 88-tyusb.rules），并把用户加入该文件中指定的组（如:tofu），重启 PC 后获得 USB 深度相机的访问权限。规则文件内容如下：

SUBSYSTEM== "usb",ATTRS{idProduct}=="1003",ATTRS{idVendor}=="04b4",GROUP="tofu",MODE="0666"

备注

规则文件名的开头须为数字 (0 ~ 99)，数字越大，优先级越高。访问 Percipio 网络深度相机 不需要 root 权限。

编译

进入 camport3 目录，执行以下命令编译示例代码。

sudo cp lib/linux/lib_x64/libtycam.so* /usr/lib/
cd sample
mkdir build
cd build
cmake ..
make

在 camport3/sample/build/bin 目录下生成若干编译生成的可执行文件。

运行

深度相机连接电脑后开始系统初始化，直到相机背面 Power 灯以 1Hz 的频率闪烁。相机初始化后，以 root 权限运行以下命令，即可接收并显示深度图像。

sudo ./SimpleView_FetchFrame

Linux 平台 (Python)

下载 SDK

  • 选择以下任意方式，下载 MultiLanguage SDK。

    • 在图漾官网下载中心下载：https://www.percipio.xyz/downloadcenter/。

    • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

      git clone https://github.com/alphaliang/pcammls.git

示例程序说明

示例程序存放在开发包根目录 python 文件夹内：

  • framefetch.py：该示例在自由采集模式下采集深度图和彩色图。

  • frame_fetchIR.py：该示例在自由采集模式下采集 IR 图。

  • frame_isp.py：该示例在软件层面对于彩色图像的 ISP 后处理，可将存在偏色的 RAW BAYER 图像处理成正常色彩空间的彩色图。

  • frame_registration.py：该示例用于采集 RGB-D 对齐图像。

  • frame_trigger.py：该示例用于设置相机工作在软触发模式下采集深度图。

  • multidevice_fetch.py：该示例设置多台相机进行图像采集。

  • point3d_fetch.py：该示例用于采集 3d 点云（未作显示），Log 信息显示点云个数和中心点云坐标（X, Y, Z）。

安装依赖

编译前，请先：

  1. 安装 python。

  2. 打开终端，运行以下命令安装 NumPy 和 OpenCV：

    pip install numpy
pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple

  3. 下载 SWIG 源码（https://www.swig.org/download.html）至本地，解压后切换至源码目录，依次执行以下命令：

    ./configure
make
sudo make install

编译

按照以下步骤，编译示例代码：

  1. 打开 pcammls 目录下 CMakeLists.txt，修改编译目标语言（PYTHON）、PYTHON 版本，如下图所示：

    ../_images/editcmakelistpythonlinux.png

  2. 在 pcammls 目录下打开终端并依次执行以下命令：

    mkdir build
cd build
cmake ..
make
sudo make install
    ../_images/pythonlinuxmake.png

  3. 在 pcammls/camport3 目录下打开终端并执行以下命令：

    sudo cp lib/linux/lib_x64/libtycam.so* /usr/lib/

编译后，根据界面提示切换至目录 /usr/local/PYTHON 并运行生成的 python 文件即可。

../_images/linuxrunpython.png

Windows 平台 (C++)

Windows SDK 支持 X86（32位）和 X64（64位）硬件平台，并提供支持 Window7 及以上版本操作系统的驱动文件。Windows SDK 包括一些直接可以执行的应用程序（例如查看深度图）和一些应用程序的示例代码。

下面以 Windows10 X64 位系统为例介绍在 Windows 平台为 Percipio 深度相机搭建开发环境的过程：

  1. 下载 Camport3 SDK

  2. 安装 USB 驱动

  3. 安装依赖

  4. 编译

下载 Camport3 SDK

选择以下任意方式，下载 Camport3 SDK：

  • 使用浏览器访问 https://github.com/percipioxyz/ 并下载 Camport3 SDK。

  • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

    git clone https://github.com/percipioxyz/camport3.git

Camport3 SDK 目录结构如下图所示：

Camport3 SDK目录结构

Camport3 SDK 目录结构

Doc 目录

存放了 SDK API 参考文档。该文档是通过 Doxygen 生成的 PDF 文件，包括了类、结构和接口的描述信息。

include 目录

存放了用于调用动态库的头文件：

  • TYImageProc.h：图像后处理函数接口的头文件。

  • TYCoordinateMapper.h：图像空间转换的映射。

  • TY_API.h 文件：提供了用于配置深度相机、获取图像数据的全部 API，用户可以基于这些 API 开发自己的应用。

lib/linux 目录

存放了支持 Linux 操作系统的库文件，兼容 AArch64、ARMv7hf、RaspberryPi、i686 和 x86-64 硬件平台。

lib/win 目录

存放了支持 Windows 操作系统的库文件，兼容 x64 和 x86 硬件平台。

sample 目录

存放了可供用户编程参考的示例程序。关于示例程序，详情请参见 示例程序说明。

安装 USB 驱动

  1. 使用 USB 线把 Percipio 深度相机与 Windows PC 连接后，右键点击系统桌面左下角的 开始，并在开始菜单中点击 设备管理器，设备管理器中可发现未识别的 USB 设备 PERCIPIO DEVICEEE，如下图所示：

未识别 USB 设备

未识别 USB 设备

  1. 右击该设备并选择 更新驱动程序。根据 PC 的 Windows 版本，选择 Camport3 软件开发包中 lib/win/driver 目录下的驱动，按照系统提示完成驱动安装。

Camport3设备驱动

Camport3设备驱动

驱动安装成功后，可以在设备管理器中发现 Percipio Device 设备。

Percipio Device 设备

Percipio Device 设备

安装依赖

CMake

CMake 是一个跨平台的安装（编译）工具，可以用简单的语句来描述所有平台的安装（编译过程）。它能够输出各种各样的 makefile 或者 project 文件，能测试编译器所支持的 C++ 特性，类似 UNIX 下的 automake。只是 CMake 的组态档取名为 CMakeLists.txt。CMake 并不直接建构出最终的软件，而是产生标准的建构档（如 UNIX 的 Makefile 或 Windows Visual C++ 的 projects / workspaces），然后再以一般的建构方式使用。

Camport SDK 使用 CMake 来构建标准的工程，利用各平台的原生建构系统的能力，可适配不同的平台环境。

备注

Camport SDK 要求用户安装 CMake 2.8.0 及更高的版本。

OpenCV

Camport SDK 可通过 USB 接口或者以太网接口接收 Percipio 深度相机输出的深度数据。取得深度数据后，Camport SDK 中提供的示例程序使用 OpenCV 图像处理软件库进行深度数据的渲染。编译示例程序前，需要安装 OpenCV 图形处理软件库。

备注

  1. Camport SDK 要求用户安装 OpenCV 2.4.8 及更高版本。

  2. 如果目标应用程序不使用 OpenCV 进行图像显示或者其他图像处理计算，则无需安装 OpenCV。

编译

编译前，请先：

  1. 安装 Visual Studio。

  2. 安装 依赖。

备注

  1. 安装 Visual Studio 时，需勾选 Visual C++ 库模块一并安装，否则无法编译成功。

  2. 若不会安装 Visual C++ 库，可联系 Percipio 售后支持。

编译步骤如下：

  1. 在 SDK sample 目录下创建 build 目录。

  2. 启动 cmake-gui。

  3. 指定源码目录到 sample，编译输出目录为 sample/build。

    wincompilestep2

  4. 点击 Configure，选择对应的 Visual Studio 版本并点击 Finish。

    wincompilestep2

  5. 在 OpenCV_DIR 一栏指定到 opencv/build 文件路径。

    wincompilestep3

  6. 在系统环境变量中配置 OpenCV 库的路径。

    具体步骤：进入 环境变量 对话框，选中 “Path” 一栏并点击 编辑，在 编辑环境变量 对话框中配置 OpenCV 库的路径。

    wincompilestep5

  7. 点击 Generate。

    wincompilestep4

  8. 点击 Open Project，打开工程。

    wincompilestep6

备注

此后可通过 camport3/sample/build 路径下的 Project.sln 或 ALL_BUILD.vcxproj 文件打开工程。

  1. 编译工程：在 Visual Studio 菜单栏依次点击 生成> 生成解决方法。

wincompilestep7

运行

深度相机连接 PC 后开始系统初始化，直到相机背面 Power 灯以 1Hz 的频率闪烁。在 Windows10 X64 系统中，运行开发包中 lib/win/hostapp/x64/SimpleView_FetchFrame.exe 可执行文件，即可获得深度图像。 或者将开发包中 lib/win/hostapp/x64/tycam.dll 拷贝到上述编译生成的文件夹 sample/build/bin/Release 中，并运行文件夹内的 SimpleView_FetchFrame.exe，也可获得深度图。

Windows 平台 (Python)

下载 SDK

选择以下任意方式，下载 MultiLanguage SDK。

  • 在图漾官网下载中心下载：https://www.percipio.xyz/downloadcenter/。

  • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

    git clone https://github.com/alphaliang/pcammls.git

示例程序说明

示例程序存放在开发包根目录 python 文件夹内：

  • framefetch.py：该示例在自由采集模式下采集深度图和彩色图。

  • frame_fetchIR.py：该示例在自由采集模式下采集 IR 图。

  • frame_isp.py：该示例在软件层面对于彩色图像的 ISP 后处理，可将存在偏色的 RAW BAYER 图像处理成正常色彩空间的彩色图。

  • frame_registration.py：该示例用于采集 RGB-D 对齐图像。

  • frame_trigger.py：该示例用于设置相机工作在软触发模式下采集深度图。

  • multidevice_fetch.py：该示例设置多台相机进行图像采集。

  • point3d_fetch.py：该示例用于采集 3d 点云（未作显示），Log 信息显示点云个数和中心点云坐标（X, Y, Z）。

安装依赖

编译前，请先：

  • 安装 Python。

  • 安装 NumPy 和 OpenCV。

    pip install numpy
pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple

  • 安装 SWIG（版本要求 4.0.1 及以上）。

    下载地址：https://www.swig.org/download.html

  • 安装 CMake（版本要求 3.15.0 及以上）。

    下载地址：https://cmake.org/download/

  • 安装 Visual Studio。

编译

按照以下步骤，编译示例代码：

  1. 配置环境变量：右键 此电脑，选择 属性 > 高级系统属性 > 环境变量，在 环境变量 页面中将本地 SWIG 的可执行文件路添加到系统变量的 Path 中。

    ../_images/setpathforswig.gif

  2. 打开 pcammls 目录下 CMakeLists.txt，修改文件中的编译目标语言（PYTHON）、 PYTHON 版本 、SWIG 的本地路径，如下图所示：

    ../_images/editcmakelistpython.png

  3. 在 pcammls 目录下创建一个新的文件夹，命名为 python_build_x64。

  4. 启动 cmake-gui，指定源码目录到 pcammls，指定编译输出目录到 pcammls/python_build_x64。

    ../_images/specifydirectorypython.png

  5. 点击 Configure，选择 Visual Studio 版本和 X86/X64 版本的设置。

    ../_images/clickcongifure_CP.png

  6. 点击 Generate。

  7. 点击 Open Project 打开工程后，在 Visual Studio 菜单栏中选择 Release 并依次点击 生成 > 生成解决方法。

    ../_images/pythonmake.png

编译后，将生成的动态库 pcammls.py、 _pcammls.pyd 以及 camport3 目录下的 tycam.dll 复制到 pcammls/python 目录下，打开 Windows PowerShell 并运行生成的 python 文件即可。

  • pcammls.py：python_build_x64/swig/swig/_output

  • _pcammls.pyd：python_build_x64/swig/Release

  • tycam.dll：camport3/lib/win/hostapp/x64

../_images/pythonrun.png

Windows 平台 (Csharp)

下载 SDK

选择以下任意方式，下载 MultiLanguage SDK。

  • 在图漾官网下载中心下载：https://www.percipio.xyz/downloadcenter/。

  • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

    git clone https://github.com/alphaliang/pcammls.git

示例程序说明

示例程序存放在开发包根目录 csharp 文件夹内：

  • fetch_frame.cs：该示例在自由采集模式下采集深度图和彩色图。

  • fetch_IR.cs：该示例在自由采集模式下采集 IR 图。

  • fetch_isp.cs：该示例在软件层面对于彩色图像的 ISP 后处理，可将存在偏色的 RAW BAYER 图像处理成正常色彩空间的彩色图。

  • fetch_registration.cs：该示例用于采集 RGB-D 对齐图像。

  • fetch_trigger.cs：该示例用于设置相机工作在软触发模式下采集深度图。

  • fetch_point3d.cs：该示例用于采集 3d 点云（未作显示），Log 信息显示点云个数和中心点云坐标（X,Y,Z）。

安装依赖

编译前，请先：

编译

按照以下步骤，编译示例代码：

  1. 配置环境变量：右键 此电脑，选择 属性 > 高级系统属性 > 环境变量，在 环境变量 页面中将本地 SWIG 的可执行文件路添加到系统变量的 Path 中。

    ../_images/setpathforswig.gif

  2. 打开 pcammls 目录下 CMakeLists.txt，修改文件中的编译目标语言（CSHARP）、本地安装的 .NET Framework 版本和 SWIG 的本地路径，如下图所示：

    ../_images/editcmakelistCsharp.png

  3. 在 pcammls 目录下创建一个新的文件夹，命名为 csharp_build_x64。

  4. 启动 cmake-gui，指定源码目录到 pcammls，指定编译输出目录到 pcammls/csharp_build_x64。

    ../_images/specifydirectoryCsharp.png

  5. 点击 Configure，选择 Visual Studio 版本和 X86/X64 版本的设置。

    ../_images/clickcongifure_CP.png

  6. 点击 Generate。

  7. 点击 Open Project 打开工程后，在 Visual Studio 菜单栏中选择 Release 并依次点击 生成 > 生成解决方法。

    备注

    修改了源码后进行编译时，需在 Visual Studio 菜单栏中选择 Release 并依次点击 生成 > 重新生成解决方法， pcammls/csharp_build_x64/Bin/Release 目录下生成的可执行文件才会更新。

    ../_images/Csharpmake.png

编译后，将 camport3/lib/win/hostapp/x64 目录下的动态库 tycam.dll 复制到 pcammls/csharp_build_x64/Bin/Release 目录下，打开 Windows PowerShell 并运行生成的可执行文件即可。

../_images/csharprun.png

ROS 平台

ROS（Robot Operating System，下文简称 ROS）是一个适用于机器人的开源的元操作系统。它提供了操作系统应有的服务，包括硬件抽象，底层设备控制，常用函数的实现，进程间消息传递，以及包管理。

搭建 ROS 开发环境

根据 Ubuntu 版本，安装对应的 ROS 开发平台。

  • Ubuntu16.04：ROS Kinetic

  • Ubuntu18.04：ROS Melodic

  • Ubuntu20.04：ROS Noetic

下载 Camport ROS SDK

ROS SDK 支持 ROS Kinetic、ROS Melodic 和 ROS Noetic 平台。

选择以下任意方式，下载 Camport ROS SDK：

  • 使用浏览器访问 https://github.com/percipioxyz/ 并下载 Camport ROS SDK。

  • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

    git clone https://github.com/percipioxyz/camport_ros.git

Camport ROS SDK 的目录如下图所示：

Camport ROS SDK目录

Camport ROS SDK 目录

  • percipio_camera：包括源文件和配置文件。

  • percipio_launch：launch 包。

编译

在开发包根目录下执行以下命令，进行编译：

catkin_make

小技巧

如果未安装 catkin 命令，需先安装 catkin。

编译后会生成 build 文件夹（包含中间文件）和 devel 文件夹（包含头文件、动/静态库、可执行文件）。

配置环境变量

在开发包根目录下执行以下命令，配置环境变量：

echo "source <开发包存放路径>/camport_ros/devel/setup.bash" >> ~/.bashrc

修改 Launch 配置

按照以下步骤，在 percipio.launch 文件中配置相机启动时加载的参数：

  1. 执行以下命令，打开 percipio.launch 文件：

cd src/percipio_launch/launch/
gedit percipio.launch

  1. 根据需要修改配置。

  • 在 default 中指定 相机 SN：

<arg name="device_id" default="207000106930" />

小技巧

device_id 默认值为 #1，表示默认打开找到的第一个相机。

  • 在 default 中设置左右红外图像曝光完全同步开关：

<arg name="color_depth_synchronization" default="true" />

  • 在 default 中设置深度图和彩色图对齐开关：

<arg name="depth_registration" default="true" />

备注

只有同时打开彩色图和深度图后，此项使能开关才会生效。对于没有 RGB 组件的相机此设置无效。

修改 Percipio.cfg 配置

Percipio.cfg 文件中的参数支持动态调节，修改 Percipio.cfg 参数最大值和最小值后，参见 运行 调出 rqt_reconfigure_Param 页面并进行调节。

  1. 在软件包根目录下执行以下命令，打开 Percipio.cfg 文件。

    cd src/percipio_camera/cfg/
gedit Percipio.cfg
    Percipio.cfg

  2. 在 gen.add() 中设置参数的最小值和最大值。

    小技巧

    1. gen.add(name, type, level, description, default, min, max) 表示属性名称、类型、优先级、描述、默认值、最小值、最大值。

    2. 布尔类型的值必须写成 True 或 False （首字母大写）。

    备注

    1. 若不知道相机属性的最小值和最大值，可通过以下方式查看相机支持的组件和属性：

      • 可运行 SDK 示例程序 DumpAllFeatures，在列出的信息中查看相机支持的组件和属性。

      • 可运行 SDK 示例程序 DumpAllFeatures -d，在生成 fetch_config.xml 文件中查看相机支持的组件和属性。

    2. 以下参数的设置范围可自定义：

      • depth_speckle_filter：斑点滤波开关。斑点滤波用于过滤深度图中的小块斑点噪声。

      • max_speckle_size：斑点噪声的最大尺寸。尺寸大于该设定值的斑点被认为不是噪声。建议设置范围为 [10,3000]。

      • max_speckle_diff：同块斑点中相邻像素的最大深度差值。若相邻像素的深度差值大于该设定值，则认为该相邻像素属于两块斑点。建议设置范围为 [10,1500]。

      • data_skip：跳帧。例如，图漾发布节点实际是 30fps，ROS 接收节点只想接收 10fps，此时可将 data_skip 设置为 3。建议设置范围为 [0,20]。

      • z_scaling：深度图中像素值的单位。建议设置范围为 [0,8]。

      • use_device_time：默认设置为 True，表示使用相机内部时间戳；设置为 False 时，表示使用 ROS 的时间戳。

  3. 执行以下命令，重新编译。编译后，Percipio.cfg 修改生效。

    catkin_make

订阅

在开发包根目录下执行以下命令，订阅服务：

roslaunch percipio_launch percipio.launch

备注

运行过程中，请勿关闭该服务终端。

运行

  1. 重新开一个终端，执行以下命令，运行 RViz：

    rosrun rviz rviz

  2. 添加图像显示。

    1. 在页面左侧 Global Options 设置项中设置 “Fixed Frame” 为 “camera_depth_frame”。

      Global Options 设置项

    2. 添加深度图显示。

      1. 点击 add, 添加 “Camera”，命名为 Depth Camera。

        添加 Depth Camera

      2. 在页面左侧新增的 Depth Camera 设置项中设置“Image Topic”为“/camera/depth/image”。

        添加 Depth Camera

    3. 添加彩色图显示。

      1. 点击 add, 添加 “Camera”，命名为 Color Camera。

      2. 勾选在页面左侧新增的 Color Camera，并在设置项中设置“Image Topic”为“/camera/rgb/image_raw”。

    4. 添加 IR 图显示。

      1. 点击 add, 添加 “Image”，命名为 IR Camera。

      2. 勾选在页面左侧新增的 IR Camera，并在设置项中设置“Image Topic”为“/camera/ir/image”。

    5. 添加点云图显示。

      1. 点击 add, 添加 “DepthCloud”，命名为 Point Cloud。

      2. 勾选在页面左侧新增的 Point Cloud，并在设置项中设置“Depth Map Topic”为“/camera/depth/image”。

  3. 根据成像情况，动态调试相机参数。

    执行以下命令，调出 rqt_reconfigure_Param 页面。选择 driver，并在页面中调节参数。

    rosrun rqt_reconfigure  rqt_reconfigure
    调节参数

多设备同时接入方案

  1. 编辑 .launch 文件。

    参考 percipio.launch 文件，创建多个 .launch。每个 .launch 文件中 “camera” 和 “device_id” 配置成不同值。例如，要同时运行两个设备，创建两个 .launch 文件 percipio_camera1.launch 和 percipio_camera2.launch。

    percipio_camera1.launch 内容如下：

    <arg name="camera" default="camera1">
......
<arg name="device_id" default="207000010443">
......

    percipio_camera2.launch 内容如下：

    <arg name="camera" default="camera2">
......
<arg name="device_id" default="207000010113">
......

  2. 在开发包根目录下执行以下命令，重新配置环境变量：

    source ./devel/setup.bash

  3. 通过运行命令 roslaunch percipio_launch percipio_camera1.launch 打开序列号为 207000010443 的设备。

    通过运行命令 roslaunch percipio_launch percipio_camera2.launch 打开序列号为 207000010113 的设备。

第三方平台（Halcon）

下载并安装 Halcon

在 Halcon 官网 (https://www.mvtec.com/downloads) 下载 Halcon (Windows 版) 安装包，并根据官方文档安装 Halcon。

重要

Image Acquisition Interfaces 安装包必须安装。若无特殊要求，建议勾选所有安装包并安装。

下载 SDK

备注

  • 若 Halcon 版本为 18.11.04.0 及以上，请根据以下步骤下载 Camport3_Halcon_gentl SDK。

  • 若 Halcon 版本低于 18.11.04.0，请至图漾 github 官方主页下载 Camport3_Halcon SDK。 本节并未介绍该 SDK 的使用方法，若有疑问，请联系图漾技术支持。

选择以下任意方式，下载图漾 Camport3_Halcon_gentl SDK。

  • 在图漾 github 官方主页下载：https://github.com/percipioxyz/。

  • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

    git clone https://github.com/percipioxyz/camport3_halcon_gentl.git

Camport3_Halcon_gentl SDK 目录结构如下图所示：

Halcon SDK 目录

Camport3_Halcon_gentl SDK 目录

samples 目录

存放了可供用户编程参考的示例程序。

  • check_status.hdev：该示例程序用于展示相机连接的状态。

  • fetchframe.hdev：该示例程序用于 1 台深度相机采集图像数据。

  • fetchframe_2cameras.hdev：该示例程序用于 2 台深度相机同时连续采集图像并输出图像数据。

  • fetchframe_RGBD.hdev：该示例程序用于获取 RGBD 深度彩色对齐图。

  • genicamtl_parameters.hdev：该示例程序用于枚举图漾支持设置的参数。

  • triggermode1.hdev：该示例程序用于设置深度相机工作在模式 1，相机收到软触发指令或硬触发信号后采集图像并输出图像数据。

其他

samples 同级目录下还包括：

  • percipio.cti：GenTL Producer 的实现文件

  • tycam.dll：GenTL Producer 依赖的图漾 SDK 的动态链接库

  • README.md：说明文档

配置环境变量

进入环境变量页面，新建一个环境变量。变量名为 GENICAM_GENTL64_PATH，变量值为 percipio.cti 的存储路径，即 Camport3_Halcon_gentl SDK 文件夹路径。重启电脑后，配置生效。

配置环境变量

配置环境变量

运行示例

以 207000144850 序列号相机为例，介绍如何在 Halcon 中运行相机，操作步骤如下：

  1. 发现相机。 在程序窗口输入以下代码并运行。

    info_framegrabber ('GenICamTL', 'info_boards', BoardInfo, BoardInfoValues)

    BoardInfoValues 一栏会显示所有可发现的设备。

  2. 打开相机并采集图像。 在程序窗口输入以下代码并运行。此处 ‘PercipioTL_DEV_207000144850’ 为举例说明，请替换成目标相机后再运行。

    open_framegrabber ('GenICamTL', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1, 'false', 'default', 'PercipioTL_DEV_207000144850', -1, -1, AcqHandle)
set_framegrabber_param(AcqHandle, 'SourceSelector', 'Source_Color')
set_framegrabber_param(AcqHandle, 'SourceMode', 'On')
set_framegrabber_param(AcqHandle, 'SourceSelector', 'Source_Depth')
set_framegrabber_param(AcqHandle, 'SourceMode', 'Off')
grab_data_async(Image, Region, Contours, AcqHandle, -1, Data)

    AcqHandle 一栏显示获取到的 handle。 图像变量 Image 和图形窗口显示采集到的彩色图。

  3. 根据相机属性读写参数，示例代码如下。关于相机属性，请参见 查看相机属性。

    get_framegrabber_param(AcqHandle, 'ImageMode_values', ImageModeValues)
set_framegrabber_param(AcqHandle, 'ImageMode', ImageModeValues[0])

查看相机属性

  1. 双击 samples 路径下的 genicamtl_parameters.hdev 文件。

  2. 在程序窗口修改需打开的相机的序列号后，点击运行按钮。此处 ‘PercipioTL_DEV_207000144850’ 为举例说明，请替换成目标相机后再运行。

    open_framegrabber ('GenICamTL', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1, 'false', 'default', 'PercipioTL_DEV_207000144850', -1, -1, AcqHandle)

    在 genicamtl_parameters.hdev 文件的同级目录下会生成 parameters_info.dat 参数文件。

  3. 打开 parameters_info.dat 文件后，可查看相机支持的属性列表。

小技巧

parameters_info.dat 文件说明

结构：参数名 + <前缀> + 当前值 + [参数范围]

第三方平台（VisionPro）

下载并安装 VisionPro

请至康耐视官网（https://www.cognex.cn/zh-cn/products/machine-vision/vision-software/visionpro-software）下载 VisionPro。

备注

VisionPro 9.0 版本经测试可正常打开图漾相机，建议使用图漾测试过的版本。

下载 VisionPro SDK

请至图漾官网下载中心（https://www.percipio.xyz/downloadcenter/）下载图漾 VisionPro SDK。

VisionPro SDK 目录结构如下图所示：

VisionPro SDK 目录

VisionPro SDK 目录

配置环境

  1. 右击 VisionPro 快捷方式图标，在弹出的快捷菜单中选择“打开文件所在的位置”，进入 Visionpro 安装目录。

  2. 将 PercipioCamera.dll、PercipioCameraExtern.dll、tycam.dll、opencv_world460.dll 拷贝至 VisionPro 安装目录 bin 文件夹。

  3. 将 PercipioCameraToolBlock.vtt 拷贝至 VisionPro 安装目录 bin/Templates/Tools 文件夹。

运行示例

该部分主要介绍如何在 VisionPro 中运行图漾相机，操作步骤如下：

  1. 双击运行 VisionPro 软件。

  2. 双击“Image Source”，进入 VisionPro(R) QuickBuild 作业编辑器 - CogJob1 页面。

    cogjob1

  3. 点击“显示 VisionPro 工具”图标，调出 VisionPro 工具 页面。

    PercipioCameraToolBlock

  4. 双击“PercipioCameraToolBlock”，添加至 ToolGroup 中。

    添加 PercipioCameraToolBlock

  5. 双击“PercipioCameraToolBlock”，在设置详情页选择“输入/输出”选项卡，并设置输入参数。

    设置相机序列号

    • CameraId：设置相机序列号。

    • Z：设置相机与投影平面在 Z 方向上的距离，单位 mm。将深度图向此投影平面做正交投影。结合该距离下的相机视野和深度图分辨率，可以求出单个像素大小 (mm) ，用于后续计算。

    • ScaleUnit：设置相机的 ScaleUnit 属性，以输出不同精度的深度值。

    • RegistrationMode：设置 RGBD 对齐开关。0：不对齐；1：rgb2depth；2：depth2rgb。

  6. 点击“运行”图标。在输出端口可查看相机采集的图像。

    运行结果

    之后根据实际需求添加其他 Tool，并将 PercipioCameraToolBlock 输出端口连接到其他工具的输入端口即可。

  7. 可选： 如对 PercipioCameraToolBlock 有二次开发需求，可点击“创建/编辑脚本”图标，并编辑脚本。

    运行结果

上位机与相机交叉编译开发环境

Percipio 网络深度相机支持用户在相机内部运行自己开发的嵌入式应用，用户可以充分利用相机内部的计算资源进行图像预处理或者应用逻辑处理。支持嵌入式应用的具体相机型号可咨询 Percipio 技术支持。

备注

USB 深度相机不支持用户在相机内部运行嵌入式应用。

示例程序编译

  1. 下载 Camport SOC SDK，链接：https://github.com/percipioxyz/camport3_soc.git

  2. 在 SDK 根目录下执行 ./build.sh，执行完成后， ./build/bin 目录下可以看到生成的可执行文件 RawFetchFrame。

  3. 通过 scp 或者 sftp 将可执行文件拷贝到相机的用户应用文件夹，请参考 应用安装。

用户程序编译

  1. 参考 SDK 的 ./Sample/RawFetchFrame，在 Sample 目录下创建用户程序目录后开发应用程序。

  2. 修改 ./Sample/CMakeLists.txt，在 ALL_SAMPLES 中增加用户程序目录路径。

  3. 执行 ./build.sh，执行完成后， ./build/bin 目录下生成可执行文件。

  4. 通过 scp 或者 sftp 将可执行文件拷贝到相机的用户应用文件夹，请参考 应用安装。

使用 Opencv的程序编译流程

  1. 参考 SDK 的 ./Sample/RawFetchFrame， 在 Sample 目录下创建使用 OpenCV 的程序目录后开发应用程序。

  2. 修改 ./Sample/CMakeLists.txt，在 ALL_SAMPLES 中增加使用 OpenCV 的程序目录路径。

  3. 执行 ./build.sh opencv，执行完成后， ./build/bin 目录下生成可执行文件。

  4. 通过 scp 或者 sftp 将可执行文件拷贝到相机的用户应用文件夹，同时，将需要的 OpenCV 库拷贝到相机，OpenCV 库在 ./ThirdPartyLib/Opencv-3.4/lib 目录下，请参考 应用安装。

程序和库文件的安装

  1. 通过 scp 或者 sftp 将需要安装的文件拷贝到相机上的 /mnt/ram 目录下：

    scp ur_FILES percipio@XXX.XXX.XXX.XXX:/mnt/ram

  2. 使用 putty 或者其他终端远程登录相机：

    ssh percipio@XXX.XXX.XXX.XXX

  3. 在相机内将压缩包解压，并将执行文件以及共享库等拷贝到 /usr/local 下相应的目录中：

    cd /mnt/ram
cp ur_ELFS_FILENNAME /usr/local/bin
cp ur_lib*.so /usr/local/lib/
cp ur*config /usr/local/etc

  4. 执行 sync 命令，将修改固化到 flash 中。

备注

  1. 拷贝过程分两步，首先务必要复制到 /mnt/ram 目录下，以防应用程序是压缩打包的文件，解压过程中文件系统空间不够而出错。

  2. 文件少的时候可以不使用用压缩文件，文件较多的时候建议要打包之后拷贝到相机上解压缩；目前相机支持 tar、 tar.gz、 tar.bz2、未加密的 zip 文件这几种压缩文件，分别使用 tar -xvf、 tar -xzvf、 tar -xjvf、 unzip 命令解压。

  3. 用户二次开发目录 /usr/local 的最大存储容量为 25MB。

  4. 文件解压缩后，务必复制到用户目录下，否则 /mnt/ram 中内容重启之后会丢失。

  5. 开发中使用的 libtycam.so 库文件，相机文件系统中已经包含，用户不必再次拷贝到 /usr/local/lib 下。

  6. 用户安装的应用程序或者脚本需要添加执行权限 chmod a+x ELFS_FILENNAME。

  7. XXX.XXX.XXX.XXX 为目标相机的 IP 地址。

设置程序开机启动

  1. 登录相机

    ssh percipio@XXX.XXX.XXX.XXX

  2. 修改启动脚本

    vi /usr/local/etc/start_app.sh

1 #!/bin/bash
2 # Created By:      Leon Zhou
3 # Created Time:    2019-04-26 20:29:12
4 # Modified Time:   2019-04-26 20:33:22
5 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/
6 export PATH=$PATH:/usr/local/sbin:/usr/sbin:/sbin
7
8 #Add your app start command below

    在第８行添加你的 app 的启动命令，例如：

    1 #!/bin/bash
2 # Created By:      Leon Zhou
3 # Created Time:    2019-04-26 20:29:12
4 # Modified Time:   2019-04-26 20:33:22
5 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/
6 export PATH=$PATH:/usr/local/sbin:/usr/sbin:/sbin
7
8 #Add your app start command below
9 /usr/loca/bin/your_app

  3. 在控制台执行 sync 指令写入存储系统，并重启设备。

警告

  1. 调试过程中若需要重启 gevcam，需要运行 killall percipio_gev_disd。

  2. 不要在启动脚本中添加 reboot 等类似的语句！

网络配置

  1. IP 设置

    系统默认使用 DHCP 模式动态获取 IP 地址。

    • 静态 IP 设置

      登录相机执行下方指令或者应用程序或者脚本中修改下方配置文件进行 IP 配置，不建议使用 ifconfig 或者其他方式直接修改 IP，避免相机 IP 管理混乱。此方法修改之后配置文件固化在相机中，在重启相机之后生效。

      echo "your_ip" > /etc/device_ip
echo "your_gw" > /etc/device_gw
echo "your_netmask" > /etc/device_netmask

    • 动态IP设置

    echo "" > /etc/device_ip
echo "" > /etc/device_gw
echo "" > /etc/device_netmask

    警告

    1. 请谨慎修改 IP 地址、子网掩码、网关；如果设置不正确的值，会导致无法连接相机。

    2. 务必在控制台执行 sync 指令把修改写入存储系统，并重启设备。

  2. NTP 服务器配置

    小技巧

    配置 NTP 服务器之前，需将相机的对时方式设置为 NTP 对时，详情请参见 对时设置。

    相机支持 NTP 时间同步，默认使用的 NTP 服务器为：’cn.ntp.org.cn’ ‘0.ubuntu.pool.ntp.org’ ‘1.ubuntu.pool.ntp.org’。

    如果用户已搭建了 NTP 服务器，可以执行下方指令将搭建 NTP 服务器的 IP 或者域名添加在 /etc/ntp_server 中：

    echo your_ntp_server > /etc/ntp_server