快速入门

本文档旨在指导用户创建图漾三维智能相机应用开发的软硬件环境, 通过一个简单的例子来说明如何使用PercipioDC Camport SDK, 包括下载sdk、配置、编译等步骤。

概述

图漾三维智能相机采用独立知识产权的主动双目视觉技术, 获取比传统双目视觉更多的景深细节和更强的环境适应性。获取到的数据信息, 可帮助机器人、工业、商业和消费等多个领域实现智能化。

图漾为用户提供完整的软件、硬件资源进行多场景的智能化应用系统开发。图漾所研发的深度相机和参考应用软件可以帮助用户快速开发行业应用解决方案, 满足用户对测量、抓取、监控等应用的需求。

工作原理

图漾三维智能相机以 FPGA 系统为计算平台, 使用并口或低压差分接口接收两路红外图像及 RGB 图像数据后, 利用三角测距原理进行高速计算, 获取视野范围内各点的深度数据信息, 并实现深度数据和 RGB 数据的点对点对齐, 然后把深度数据和 RGB 数据经 USB 接口或者以太网接口上传给外部主机。

图漾三维智能相机支持通过 USB 接口或者以太网接口接收上位机指令, 实现软件指令触发图像集成; 带硬件触发接口的图漾三维智能相机可支持外部硬件信号触发, 接受外部信号源的硬件触发信号, 按照触发信号的触发频率实时抓取图像并输出计算后的深度图像。

三维智能相机架构

图漾三维智能相机架构

特性描述

主动双目技术

图漾三维智能相机包括双目红外摄像头、彩色摄像头和光学增强系统, 采用自主知识产权的主动双目技术, 能够获得比传统双目视觉更多的景深细节, 具有比单目结构光更强的环境光抗干扰能力, 并能够在主动双目和被动双目模式下自动切换。

多设备同步

在触发模式下,图漾三维智能相机可由硬件信号触发控制进行单帧拍摄, 级联多台设备的触发信号可以实现多设备同步拍摄功能。

Note

更多关于触发模式的介绍, 请参考 触发设置

嵌入式计算

图漾三维智能相机集成了嵌入式计算视觉处理器,输出计算后的深度数据, 无需上位机参与计算。

室内外自适应

普通双目方案不适于在昏暗环境下以及被测对象特征不明显的场景。结构光方案虽适用于普通弱光环境,但是在强光下,结构光图案会被干扰,测量效果受损。图漾产品采用主动双目方案, 对光照可以实现自适应, 在室内外均能呈现很好的物体识别能力, 并能够获得比传统立体视觉更多的景深细节。

部分设备可以根据工作环境光线(830 nm)亮度, 主动动态调整光学增强系统亮度或者图像传感器的曝光参数, 以在室内外获取优化后的成像效果。 用户可以根据图漾三维智能相机输出的亮度直方图数据信息, 使用软件 API 动态调整深度模组激光器亮度或者图像传感器的曝光参数, 以获取更好的三维图像数据。

Note

关于曝光设置, 请参考 曝光设置

彩色图和深度图对齐

由 SDK 数据接口获取的彩色图像数据, 可以实现与深度图像的逐点对齐。

工业三防

图漾工业级三维相机可防溅、抗水、防尘, 在受控实验室条件下经测试, 其效果达到 IEC 60529 标准 IP65级别。

Note

防溅、抗水、防尘功能并非永久有效, 防护性能可能会因日常磨损而下降。由于浸入液体而导致的损坏不在保修范围之内。

硬件准备

图漾的 SDK 需要配合图漾三维智能相机使用。目前 SDK 的版本支持图漾所有在售型号的三维相机, 请下载《图漾产品选型手册》选购产品。
关于图漾三维智能相机的型号和参数介绍请见官方网站:http://www.percipio.xyz/product/depthhttp://www.percipio.xyz/rgbd

USB深度相机

连接方式1,
相机通过USB线缆直接接入到计算机USB2.0接口或者USB3.0接口。
usb连接方式1

USB连接方式1

连接方式2,
相机通过USB线缆接入到USB HUB,USB HUB计入到计算机USB2.0接口或者USB3.0接口。当连接多个相机时,为确保相机供电,需要使用能够满足供电要求的有源HUB。
usb连接方式2

USB连接方式2

GigE深度相机

图漾以太网深度相机需要采用外部电源供电,部分型号相机同时支持POE供电。深度相机默认使用DHCP方式从服务器动态获取IP地址。

动态IP地址模式

网络连接方式1,
计算机网卡设为自动获取IP模式(DHCP);
相机通过千兆以太网线缆直接接入到计算机千兆以太网接口;
相机上电启动后约1分钟,计算机和相机可以成功协商获得 169.154.0.0/16 网段的IP地址。
确认相机和计算机已经获得IP地址后, 通过SDK的示例程序 ListDevice 可以枚举相机, SimpleView_FetchFrame.exe -id <设备号> 查看图像。设备号可从设备标签上获得,也可从枚举结果中获得。
网络连接方式1

网络连接方式1

网络连接方式2,
计算机网卡设为自动获取IP模式(DHCP);
相机和计算机通过千兆以太网线缆同时接入同一台千兆以太网交换机;
上电启动后,计算机和相机可以成功协商获得 169.154.0.0/16 网段的IP地址。
确认相机和计算机已经获得IP地址后, 通过SDK的示例程序 ListDevice 可以枚举相机, SimpleView_FetchFrame.exe -id <设备号> 查看图像。设备号可从设备标签上获得,也可从枚举结果中获得。
网络连接方式2

网络连接方式2

网络连接方式3,
计算机网卡设为自动获取IP模式(DHCP);
相机和计算机通过千兆以太网线线缆同时接入同一台千兆以太网交换机, 该交换机接入支持DHCP服务功能的路由器,或者在局域网内开通DHCP服务器。
上电启动后,计算机和相机可以从DHCP地址服务器获得IP地址。
确认相机和计算机已经获得IP地址后, 通过SDK的示例程序 ListDevice 可以枚举相机, SimpleView_FetchFrame.exe -id <设备号> 查看图像。设备号可从设备标签上获得,也可从枚举结果中获得。
网络连接方式3

网络连接方式3

静态IP地址模式

首先,把深度相机与计算机通过千兆以太网线缆直接连接,或者相机与计算机同时接入同一台千兆以太网交换机。
然后,使用 SDK 提供的工具应用 ForceDeviceIP 为设置相机静态IP地址。需注意相机静态IP地址需要和配置计算机IP地址在同一网段, 否则无法进行设备枚举和图像传输。
确认相机和计算机已经获得IP地址后, 通过SDK的示例程序 ListDevice 可以枚举该相机, SimpleView_FetchFrame.exe -id <设备号> 查看图像。设备号可从设备标签上获得,也可从枚举结果中获得。
设置临时静态IP:
ForceDeviceIP.exe <MAC> <IP> <Netmask> <Gateway>
其中,<MAC>可从设备标签上获得,格式一般为:xx:xx:xx:xx:xx:xx,该指令执行后,网络相机IP地址会修改为指令指定的IP地址,即时生效; 相机断电重启后,恢复原有配置。
示例:
ForceDeviceIP.exe 68:f7:56:36:90:a3 192.168.1.160 255.255.255.0 192.168.1.1
设置永久静态IP:
ForceDeviceIP.exe <MAC> <IP> <Netmask> <Gateway> -set
其中,<MAC>可从设备标签上获得,格式一般为:xx:xx:xx:xx:xx:xx,该指令执行后,网络相机IP地址会修改为指令指定的IP地址,即时生效; 相机断电重启后,IP地址保持为指令配置的地址不变。
示例:
ForceDeviceIP.exe 68:f7:56:36:90:a3 192.168.1.160 255.255.255.0 192.168.1.1 -set
清除静态IP:
ForceDeviceIP.exe <MAC> <IP> <Netmask> <Gateway> -clear
其中,<MAC>可从设备标签上获得,格式一般为:xx:xx:xx:xx:xx:xx,该指令执行后,会清空网络相机IP配置,恢复为DHCP动态获取方式; 相机断电重启后,以DHCP方式申请IP。
示例:
ForceDeviceIP.exe 68:f7:56:36:90:a3 192.168.1.160 255.255.255.0 192.168.1.1 -clear

SDK 介绍

PercipioDC Camport3 SDK(以下简称 Camport SDK)是基于图漾三维智能相机的软件开发包, 该开发包适用于Windows、Linux(OpenNI2) 、Android 和 ROS 平台, 为应用开发者提供了一系列友好的 API 和简单的应用示例程序。用户可以基于该开发包, 获取深度数据信息、灰度图像信息和点云数据, 用于三维建模、导航、避障、手势识别等应用。

兼容平台

Windows SDK

Windows SDK 支持 X86(32 位)和 X64(64 位)硬件平台, 并提供支持Window7 及以上版本操作系统的驱动文件。Windows SDK 为用户提供了一些直接可以执行的应用程序(例如查看深度图), 也为开发者提供了一些应用程序的示例代码。

Linux SDK

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

Android SDK

Android SDK 支持 ARMV7 硬件平台和 Android 4.4系统, 并提供相应平台的库文件。Android SDK 为用户提供可执行的应用程序, 也为开发者提供了一些应用程序的示例代码。

OpenNI2 SDK

OpenNI2 SDK 基于 Linux SDK 开发, 提供相应平台的库文件。安装使用 OpenNI2 SDK 前, 需要根据平台安装相应的 Linux SDK。

ROS SDK

ROS SDK 支持 ROS Indigo 平台, 并提供相应平台的库文件。在使用 ROS SDK 前需要首先安装 OpenNI2 SDK。

安装 SDK

Camport SDK 的使用流程如下图所示。

Camport SDK开发环境搭建

Camport SDK开发环境搭建

下载 SDK

使用浏览器访问 http://github.com/percipioxyz/下载对应平台的软件压缩包, 或者使用git指令获取本地副本。
打开终端, 切换到你要存放 SDK 的工作目录, 使用 git clone 命令克隆远程仓库:
Windows和Linux平台共用一套 SDK 软件:
或者Android平台:
或者OpenNI支持包:
或者ROS Indigo平台:

目标平台的 SDK 支持包将会下载到当前目录下。

Linux平台

下面以Ubuntu14.04为例介绍Linux平台图漾三维智能相机开发环境搭建的过程。

Camport3 SDK

Camport3 SDK 适用于 Windows 和 Linux(Ubuntu14.04)平台, 下载后可以看到目录结构如下图所示。

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 目录

可供用户编程参考的程序样例。

  • ListDevices 枚举主机连接的全部图像深度相机。
  • DumpAllFeatures 枚举设备支持的各个组件和属性、属性的读写权限、数据范围、以及各个属性与组件的隶属关系等信息。
  • ForceDeviceIP 强制设置网络深度相机的IP地址。
  • LoopDetect 针对环境不稳定等因素造成的数据连接异常,提供异常处理流程示例。
  • SimpleView_FetchFrame 从相机获取图像数据,并在数据获取线程中使用OpenCV渲染显示的过程。
  • SimpleView_Callback 从相机获取图像数据,并在独立的数据处理线程(防止堵塞图像数据获取)中使用OpenCV渲染显示的过程。
  • SimpleView_FetchHisto 获取图像亮度数据直方图。
  • SimpleView_MultiDevice 同时连接多设备进行图像获取的示例程序。
  • SimpleView_Point3D 3D点云数据的获取示例。
  • SimpleView_Registration 获取设备的内参、外参、深度图像、彩色图像, 实现深度图和彩色图像对齐的示例。
  • SimpleView_TriggerDelay 延时触发图像捕获的示例程序。用户可以指定相机在接收到触发信号并等待特定延时之后进行图像捕获。
  • SimpleView_TriggerMode0 设置相机为连续曝光并持续输出深度图的工作模式。
  • SimpleView_TriggerMode1 设置相机为触发模式,相机收到(软件、硬件)触发信号后,进行曝光集成并输出深度图的工作模式。
  • SimpleView_TriggerMode_M2S1 示例实现了两个设备进行同步触发采集的功能。配置一台相机设备工作在模式2,收到上位机发送的软件触发信号后,通过硬件TRIGGER OUT接口输出触发信号并进行一次图像采集;配置另一台相机工作在模式1,相机收到另一台相机的硬件触发信号后,进行曝光集成并输出深度图。
  • SimpleView_TriggerMode_M3S1 示例实现了两个设备按照特定频率进行同步触发采集的功能。配置一台相机设备工作在模式3,通过硬件TRIGGER OUT接口按照指定周期 输出触发信号并进行图像采集;配置另一台相机工作在模式1,相机收到另一台相机的硬件触发信号后,进行曝光集成并输出深度图。

权限设置

根据 Linux 系统的权限管理机制, 默认情况下需要 root 权限才能操作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"

Note

规则文件名的开头须为数字(0 ~ 99), 数字越大, 优先级越高。访问网络接口图漾三维智能相机不需要root权限。

安装依赖

LibUSB

Camport SDK 默认使用 liusb 作为 USB 深度摄像头的用户态驱动库。如果使用图漾USB接口三维智能相机,则需要安装 Libusb 软件。:

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

Camport SDK 可通过 USB 或者以太网接口接收三维智能相机输出的深度数据。 取得深度数据后, Camport SDK 中提供的示例程序使用 OpenCV 图像处理软件库进行深度数据的渲染显示。 编译示例程序前,需要安装 OpenCV 图形处理软件库(示例程序使用 OpenCV2.4.8 可直接编译运行)。如果目标应用程序不使用 OpenCV 进行图像显示或者其他图像处理计算,则无需安装该图形处理库。

sudo apt-get install libcv-dev

编译

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

sudo cp lib/linux/lib_x64/libtycam.so /usr/lib/
cd sample
mkdir build
cd build
cmake ..
make
在 camport3/sample/build/bin 目录下生成若干编译生成的可执行文件。

深度摄像头连接 PC,待摄像头完成系统初始化,背面 LED 灯保持稳定闪烁状态后,以 root 权限运行如下命令,即可接收并显示深度图像。

sudo ./SimpleView_FetchFrame

Note

运行应用程序后,如果提示”Couldn’t open device, some information will be missing, ret: -3”, 请检查系统的访问权限配置是否正确。

Windows平台

下面以 Windows10 X64 位系统为例介绍 Windows 平台图漾三维智能相机开发环境搭建的过程。

Camport3 SDK

Camport3 SDK 适用于 Windows 和 Linux(Ubuntu14.04)平台, 下载后可以看到目录结构如下图所示。

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 目录

可供用户编程参考的程序样例。

  • ListDevices

枚举主机连接的全部图像深度相机。

  • DumpAllFeatures

枚举设备支持的各个组件和功能属性,以及各个功能属性支持的读写、数据范围等信息。

  • ForceDeviceIP

强制设置网络深度相机的IP地址。

  • LoopDetect

针对环境不稳定等因素造成的数据连接异常,提供异常处理流程示例。

  • SimpleView_FetchFrame

从相机获取图像数据,并在数据获取线程中使用OpenCV渲染显示的过程。

  • SimpleView_Callback

从相机获取图像数据,并在独立的数据处理线程(防止堵塞图像数据获取)中使用OpenCV渲染显示的过程。

  • SimpleView_FetchHisto

获取图像亮度数据直方图。

  • SimpleView_MultiDevice

同时连接多设备进行图像获取的示例程序。

  • SimpleView_Point3D

3D点云数据的获取示例。

  • SimpleView_Registration

获取设备的内参、外参、深度图像、彩色图像并进行深度图和彩色图像对齐的示例。

  • SimpleView_TriggerDelay

延时触发图像捕获的示例程序。用户可以指定相机在接收到触发信号并等待特定延时之后进行图像捕获。

  • SimpleView_TriggerMode0

设置相机为连续曝光并持续输出深度图的工作模式。

  • SimpleView_TriggerMode1

设置相机为触发模式,相机收到(软件、硬件)触发信号后,进行曝光集成并输出深度图的工作模式。

  • SimpleView_TriggerMode_M2S1

示例实现了两个设备进行同步触发采集的功能。配置一台相机设备工作在模式2,收到上位机发送的软件触发信号后,通过硬件TRIGGER OUT接口输出触发信号并进行一次图像采集;配置另一台相机工作在模式1,相机收到另一台相机的硬件触发信号后,进行曝光集成并输出深度图。

  • SimpleView_TriggerMode_M3S1

示例实现了两个设备按照特定频率进行同步触发采集的功能。配置一台相机设备工作在模式3,通过硬件TRIGGER OUT接口按照指定周期 输出触发信号并进行图像采集;配置另一台相机工作在模式1,相机收到另一台相机的硬件触发信号后,进行曝光集成并输出深度图。

安装USB驱动

  1. 使用 USB 线把图漾三维智能相机与 Windows PC 连接后, 右键点击系统桌面左下角的【开始】, 并在开始菜单中点击【设备管理器】, 设备管理器中可发现未识别的USB设备 PERCIPIO DEVICEEE, 如下图所示。
未识别USB设备

未识别USB设备

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

Camport3设备驱动

  1. 驱动成功安装后, 在设备管理器中, 可以发现 Percipio Device 设备。
图漾三维智能相机设备

图漾三维智能相机设备

Note

新版本 Windows10 系统默认不能安装未经微软签名的驱动程序. 安装图漾智能相机驱动前, 需要禁用驱动程序强制签名。请参考微软帮助系统完成禁用驱动签名。

运行

深度摄像头连接 PC 后开始系统初始化, 直到摄像头背面 LED 灯保持持续闪烁状态。 在Windows10 X64系统中, 运行开发包中 lib/win/hostapp/x64/SimpleView_FetchFrame.exe 可执行文件, 即可看到渲染显示的深度图像。

Android平台

Camport3 Android SDK

Camport3 Android SDK 的目录如图所示。

Camport Android SDK目录

Camport Android SDK目录

lib 目录

存放 Android 平台的库文件, 支持的 ARM 平台有arm64-v8a、armeabi-v7a、armeabi,共计3类。

sample 目录

– Simple_FetchFrame 目录:存放 Camport-FetchFrame 程序的源代码,可以编译 Console 应用程序或者apk。

– binary_for_arm64-v8a 目录:存放可执行的 Console 应用程序和apk。

– binary_for_armeabi-v7a 目录:存放可执行的 Console 应用程序和apk。

— binary_for_armeabi 目录:存放可执行的 Console 应用程序和apk。

编译

  1. 搭建 Android 的开发环境。
  2. 下载 Android 版本的 OpenCV SDK。
  3. 复制相关代码到开发环境。
  4. 开始编译 SDK。

Note

Camport_FetchFrame.apk 基于 OpenCV 开发, 编译源码需要 OpenCV Android SDK 配合, 具体安装步骤请参考 OpenCV 官网。

运行示例

硬件准备
  1. 使用 USB 连接线将 PC 与 Android 设备连接。
  2. 使用 USB 连接线将摄像头与 Android 设备连接。
运行

Camport3 Android SDK 为用户提供的示例应用(此处以armeabi-v7a平台为例):

1. 通过 adb 复制 lib/armeabi/armeabi-v7a/ 目录下的库文件到 /system/lib/ 下。
2. 进入 SDK 的 sample/binary_for_armeabi-v7a 目录。
3. 如需运行 Camport_FetchFrame.apk。
  • 通过 adb 安装 Campor_FetchFrame.apk 和 OpenCV_2.4.9_Manager_2.18_armeabi.apk。
  • 在 Android 桌面打开 camport_fetchframe即可看到相机输出的深度图像。
4. 如需运行 SimpleView_FetchFrame
  • 复制 sample/binary_for_ARMV7/SimpleView_FetchFrame 到 Android 设备的 /data 目录。在命令行执行以下命令即可看到相机输出的深度图像。
/data/SimpleView_FetchFrame

Note

根据 Linux 系统的权限管理机制, 默认情况下需要 root 权限才能操作USB接口三维智能相机, 非 root 用户可以创建udev rule 来修改设备权限,可参考 权限设置 。Android平台可以使用此方式进行权限设置, 也可以使用Android API申请设备权限。

OpenNI套件

OpenNI(开放自然交互)是一个多语言,跨平台的框架,它定义了编写应用程序,并利用其自然交互的API。OpenNI的主要目的是要形成一个标准的API,来搭建视觉和音频传感器与视觉和音频感知中间件通信的桥梁。

Linux环境下,成功安装Camport3 SDK后,从图漾官方链接下载并安装Camport3 OpenNI2 SDK,可以实现图漾三维智能相机和OpenNI的对接。

Camport3 OpenNI2 SDK

Camport3 OpenNI2 SDK 的目录图所示。

Camport OpenNI2 SDK目录

Camport3 OpenNI2 SDK目录

图漾科技提供各个平台的二进制安装包, 按照平台配置情况安装相应开发包, 即可支持 OpenNI2 开发环境。该开发包根目录下的 Percipio.ini 复制到 /etc/openni2 目录, Camport3 OpenNI2 SDK通过读取该文件的配置来设置三维智能相机输出的深度和彩色图像数据分辨率, 相机默认输出的深度和彩色图像数据分辨率是640x480。

安装

以X86 平台为例

sudo dpkg -i libopenni2-0_2.2.0.33+dfsg-4_i386.deb
sudo dpkg -i libopenni2-dev_2.2.0.33+dfsg-4_i386.deb

Note

安装后未能通过OpenNI接口接收深度图像数据时, 可尝试运行开发包内的SimpleRead_**应用, 验 Linux 基础环境下的数据通路是否正常。

ROS 平台

ROS(Robot Operating System, 下文简称“ROS”)是一个适用于机器人的开源的元操作系统。 它提供了操作系统应有的服务, 包括硬件抽象, 底层设备控制, 常用函数的实现, 进程间消息传递, 以及包管理。通过 OpenNI2 框架, 图漾三维智能相机可充分接入 ROS 系统。

Camport ROS SDK

Camport ROS SDK依赖于OpenNI2 SDK, 需按照上一节安装 OpenNI2 支持软件包。Camport ROS SDK 的目录如下图所示。

Camport ROS SDK目录

Camport ROS SDK目录

  • openni2_camera: ROS 调用 OpenNI2 的封装层。
  • openni2_launch: 打开 OpenNI2 设备并获取深度和颜色数据应用。
  • depthimage_to_laserscan: 打开 OpenNI2 设备并获取线性深度数据应用。

编译 ROS SDK

在开发包根目录下执行以下命令即可完成编译,

$catkin_make

配置环境变量

$echo ”source ~/camport_ros/devel/setup.bash” >> ~/.bashrc
$source ~/.bashrc

运行

  • 在 RVIZ 中查看 Depth Camera。

执行如下命令:

$roscore
$roslaunch openni2_launch openni2.launch
$rosrun rviz rviz

在 RVIZ 的 /camera/image/depth 目录下添加深度图像视图, 可查看三维空间视图。

  • 在 RVIZ 中查看从深度图中仿真出的 Laser Scan 图像。

执行如下命令:

$roscore
$roslaunch depthimage_to_laserscan depthimage_to_laserscan.launch
$rosrun rviz rviz

在 RVIZ 的 /scan/LaserScan 目录下添加激光扫描视图, 可查看模拟线激光视图。

应用开发

使用 SDK 提供的 API 开发应用的基础流程如下图所示, 该流程适用于所有应用平台。

流程图

SDK 应用开发流程图

SDK 应用开发流程图

流程说明

  1. 初始化 API。
  2. 操作设备。
  • 获取设备列表。

初次获取设备信息时可以通过 selectDevice() 查询已连接的设备。在已知设备 ID 的情况下, 可以不调用该函数查询。

  • 打开设备。

通过 TYOpenInterface() 打开对应的接口, 然后使用 TYOpenDevice 接口函数打开指定 ID 的设备。

  1. 操作组件。
  • 查询组件状态。

使用 TYGetComponentIDs() 可查询所有支持的组件; 使用 TYGetEnabledComponents() 查询使能状态的组件。

  • 配置组件。

每个设备打开后都必须配置组件, 默认情况下只有虚拟组件 TY_COMPONENT_DEVICE 是使能状态。多个设备可以通过 位或 方式同时使能。代码示例如下:

int32_t componentIDs = TY_COMPONENT_DEPTH_CAM | TY_COMPONENT_RGB_CAM;
TYEnableComponents(hDevice, componentIDs );
  1. 操作参数。
  • 查询指定参数的信息。

通过填充结构体 TY_FEATURE_INFO 来获取指定组件的指定参数的信息。如果该组件不包含所指定的参数,则 TY_FEATURE_INFO 中 isValid 值为 false。也可以通过 TYGetIntRange 等具体参数类型的 API 接口查询指定功能参数的信息。

  • 配置参数。

配置参数的 API 按照参数的数据类型分类, 如 TYSetInt,TYSetEnum 和 TYSetFloat 等。

cams[i].tag = std::string(cams[i].sn) + "_master";
TY_TRIGGER_PARAM param;
param.mode = TY_TRIGGER_MODE_M_SIG;
ASSERT_OK(TYSetStruct(cams[i].hDev, TY_COMPONENT_DEVICE, TY_STRUCT_TRIGGER_PARAM, (void*)&param, sizeof(param)));
  1. 给驱动程序分配 framebuffer。
  • 指定输出图像的种类、分辨率规格。
LOGD("=== Configure feature, set resolution to 640x480.");
int err = TYSetEnum(cams[i].hDev, TY_COMPONENT_DEPTH_CAM, TY_ENUM_IMAGE_MODE, TY_IMAGE_MODE_DEPTH16_640x480);
ASSERT(err == TY_STATUS_OK || err == TY_STATUS_NOT_PERMITTED);
  • 查询当前配置下每个 framebuffer 的大小。
uint32_t frameSize;
ASSERT_OK( TYGetFrameBufferSize(cams[i].hDev, &frameSize) );
LOGD("     - Get size of framebuffer, %d", frameSize);
  • 分配 framebuffer 并压入驱动内的缓冲队列。

按照实际查询函数返回的 framebuffer 的大小分配两组 Buffer 空间,并传递给底层驱动缓冲队列。

驱动内部维护一个缓冲队列(buffer queue), 每帧数据传出时会将填充好的 buffer 作 dequeue 操作, 并完全传出给用户使用。用户完成该帧图像数据处理后,需做 enqueue 动作以返还该 Buffer 给驱动层缓冲队列。用户需要保证新的一帧数据到来时驱动的缓冲队列 buffer queue 不为空, 否则该帧数据将被丢弃。

LOGD("     - Allocate & enqueue buffers");
cams[i].fb[0] = new char[frameSize];
cams[i].fb[1] = new char[frameSize];
LOGD("     - Enqueue buffer (%p, %d)", cams[i].fb[0], frameSize);
ASSERT_OK( TYEnqueueBuffer(cams[i].hDev, cams[i].fb[0], frameSize) );
LOGD("     - Enqueue buffer (%p, %d)", cams[i].fb[1], frameSize);
ASSERT_OK( TYEnqueueBuffer(cams[i].hDev, cams[i].fb[1], frameSize) );
  1. 启动采集。
  2. 主动获取帧数据(包含图像数据的 buffer 传出给用户,由用户处理)。
  3. 解析数据帧,依据用户需要完成特定图像处理。
  4. 返还数据帧 Buffer 给底层驱动缓冲队列。
  5. 依据用户需求选择是否停止图像采集。
  6. 关闭设备和接口。
  7. 释放 API 和 存储资源。