快速入门¶
本文档旨在指导用户创建图漾三维智能相机应用开发的软硬件环境， 通过一个简单的例子来说明如何使用PercipioDC Camport SDK, 包括下载sdk、配置、编译等步骤。
概述¶
图漾三维智能相机采用独立知识产权的主动双目视觉技术, 获取比传统双目视觉更多的景深细节和更强的环境适应性。获取到的数据信息, 可帮助机器人、工业、商业和消费等多个领域实现智能化。
图漾为用户提供完整的软件、硬件资源进行多场景的智能化应用系统开发。图漾所研发的深度相机和参考应用软件可以帮助用户快速开发行业应用解决方案, 满足用户对测量、抓取、监控等应用的需求。
工作原理¶
图漾三维智能相机以 FPGA 系统为计算平台, 使用并口或低压差分接口接收两路红外图像及 RGB 图像数据后, 利用三角测距原理进行高速计算, 获取视野范围内各点的深度数据信息, 并实现深度数据和 RGB 数据的点对点对齐, 然后把深度数据和 RGB 数据经 USB 接口或者以太网接口上传给外部主机。
图漾三维智能相机支持通过 USB 接口或者以太网接口接收上位机指令, 实现软件指令触发图像集成; 带硬件触发接口的图漾三维智能相机可支持外部硬件信号触发, 接受外部信号源的硬件触发信号, 按照触发信号的触发频率实时抓取图像并输出计算后的深度图像。
图漾三维智能相机架构
特性描述¶
图漾三维智能相机包括双目红外摄像头、彩色摄像头和光学增强系统， 采用自主知识产权的主动双目技术, 能够获得比传统双目视觉更多的景深细节, 具有比单目结构光更强的环境光抗干扰能力, 并能够在主动双目和被动双目模式下自动切换。
在触发模式下，图漾三维智能相机可由硬件信号触发控制进行单帧拍摄, 级联多台设备的触发信号可以实现多设备同步拍摄功能。
图漾三维智能相机集成了嵌入式计算视觉处理器，输出计算后的深度数据, 无需上位机参与计算。
普通双目方案不适于在昏暗环境下以及被测对象特征不明显的场景。结构光方案虽适用于普通弱光环境，但是在强光下，结构光图案会被干扰，测量效果受损。图漾产品采用主动双目方案, 对光照可以实现自适应, 在室内外均能呈现很好的物体识别能力, 并能够获得比传统立体视觉更多的景深细节。
部分设备可以根据工作环境光线(830 nm)亮度, 主动动态调整光学增强系统亮度或者图像传感器的曝光参数, 以在室内外获取优化后的成像效果。 用户可以根据图漾三维智能相机输出的亮度直方图数据信息， 使用软件 API 动态调整深度模组激光器亮度或者图像传感器的曝光参数， 以获取更好的三维图像数据。
Note
关于曝光设置, 请参考 曝光设置 。
由 SDK 数据接口获取的彩色图像数据, 可以实现与深度图像的逐点对齐。
图漾工业级三维相机可防溅、抗水、防尘, 在受控实验室条件下经测试, 其效果达到 IEC 60529 标准 IP65级别。
Note
防溅、抗水、防尘功能并非永久有效, 防护性能可能会因日常磨损而下降。由于浸入液体而导致的损坏不在保修范围之内。
硬件准备¶
USB深度相机¶
USB连接方式1
USB连接方式2
GigE深度相机¶
图漾以太网深度相机需要采用外部电源供电，部分型号相机同时支持POE供电。深度相机默认使用DHCP方式从服务器动态获取IP地址。
动态IP地址模式¶
网络连接方式1
网络连接方式2
网络连接方式3
静态IP地址模式¶
SDK 介绍¶
PercipioDC Camport3 SDK(以下简称 Camport SDK)是基于图漾三维智能相机的软件开发包, 该开发包适用于Windows、Linux(OpenNI2) 、Android 和 ROS 平台, 为应用开发者提供了一系列友好的 API 和简单的应用示例程序。用户可以基于该开发包, 获取深度数据信息、灰度图像信息和点云数据, 用于三维建模、导航、避障、手势识别等应用。
兼容平台¶
Windows SDK 支持 X86(32 位)和 X64(64 位)硬件平台, 并提供支持Window7 及以上版本操作系统的驱动文件。Windows SDK 为用户提供了一些直接可以执行的应用程序(例如查看深度图), 也为开发者提供了一些应用程序的示例代码。
Linux SDK 支持 AArch64,ARMv7hf,RaspberryPi,i686 和 x86-64 硬件平台, 并为开发者编译程序提供相应平台的库文件。Linux SDK 不提供可执行的应用程序, 通过编译示例代码来生成可执行的应用。
Android SDK 支持 ARMV7 硬件平台和 Android 4.4系统, 并提供相应平台的库文件。Android SDK 为用户提供可执行的应用程序, 也为开发者提供了一些应用程序的示例代码。
OpenNI2 SDK 基于 Linux SDK 开发, 提供相应平台的库文件。安装使用 OpenNI2 SDK 前, 需要根据平台安装相应的 Linux SDK。
ROS SDK 支持 ROS Indigo 平台, 并提供相应平台的库文件。在使用 ROS SDK 前需要首先安装 OpenNI2 SDK。
安装 SDK¶
Camport SDK 的使用流程如下图所示。
Camport SDK开发环境搭建
下载 SDK¶
目标平台的 SDK 支持包将会下载到当前目录下。
Linux平台¶
下面以Ubuntu14.04为例介绍Linux平台图漾三维智能相机开发环境搭建的过程。
Camport3 SDK¶
Camport3 SDK 适用于 Windows 和 Linux（Ubuntu14.04）平台, 下载后可以看到目录结构如下图所示。
Camport3 SDK目录结构
存放 SDK API 参考文档, 该文档内容包括类、结构和接口的描述信息, 格式为使用 Doxygen 生成的PDF文件。
- – TYImageProc.h
- 图像后处理函数接口的头文件。
- – TYCoordinateMapper.h
- 图像空间转换的映射。
- – TYApi.h 文件
- 提供了控制配置摄像头、获取图像数据的全部 API, 用户可以基于这些 API 开发自己的应用。
支持 Linux 操作系统的库文件, 兼容 AArch64,ARMv7hf,RaspberryPi,i686 和 x86-64 硬件平台。
支持 Windows 操作系统的库文件, 兼容 x64 和 x86 硬件平台。
可供用户编程参考的程序样例。
- 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，相机收到另一台相机的硬件触发信号后，进行曝光集成并输出深度图。
权限设置¶
SUBSYSTEM== "usb",ATTRS{idProduct}=="1003",ATTRS{idVendor}=="04b4",GROUP="tofu",MODE="0666"
Note
规则文件名的开头须为数字(0 ~ 99), 数字越大, 优先级越高。访问网络接口图漾三维智能相机不需要root权限。
安装依赖¶
Camport SDK 默认使用 liusb 作为 USB 深度摄像头的用户态驱动库。如果使用图漾USB接口三维智能相机，则需要安装 Libusb 软件。:
sudo apt-get install libusb-1.0-0-dev
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
深度摄像头连接 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目录结构
存放 SDK API 参考文档, 该文档内容包括类、结构和接口的描述信息, 格式为使用 Doxygen 生成的PDF文件。
- – TYImageProc.h
- 图像后处理函数接口的头文件。
- – TYCoordinateMapper.h
- 图像空间转换的映射。
- – TY_API.h 文件
- 提供了控制配置摄像头、获取图像数据的全部 API, 用户可以基于这些 API 开发自己的应用。
支持 Linux 操作系统的库文件, 兼容 AArch64,ARMv7hf,RaspberryPi,i686 和 x86-64 硬件平台。
支持 Windows 操作系统的库文件, 兼容 x64 和 x86 硬件平台。
可供用户编程参考的程序样例。
- 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驱动¶
- 使用 USB 线把图漾三维智能相机与 Windows PC 连接后, 右键点击系统桌面左下角的【开始】, 并在开始菜单中点击【设备管理器】， 设备管理器中可发现未识别的USB设备 PERCIPIO DEVICEEE， 如下图所示。
未识别USB设备
- 右键单击该设备选择更新设备驱动。 根据PC机的 Windows 版本， 选择 Camport3 软件开发包中 lib/win/driver 目录下的驱动, 按照系统提示完成驱动安装。
Camport3设备驱动
- 驱动成功安装后， 在设备管理器中, 可以发现 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目录
存放 Android 平台的库文件, 支持的 ARM 平台有arm64-v8a、armeabi-v7a、armeabi，共计3类。
– Simple_FetchFrame 目录:存放 Camport-FetchFrame 程序的源代码，可以编译 Console 应用程序或者apk。
– binary_for_arm64-v8a 目录:存放可执行的 Console 应用程序和apk。
– binary_for_armeabi-v7a 目录:存放可执行的 Console 应用程序和apk。
— binary_for_armeabi 目录:存放可执行的 Console 应用程序和apk。
编译¶
- 搭建 Android 的开发环境。
- 下载 Android 版本的 OpenCV SDK。
- 复制相关代码到开发环境。
- 开始编译 SDK。
Note
Camport_FetchFrame.apk 基于 OpenCV 开发, 编译源码需要 OpenCV Android SDK 配合, 具体安装步骤请参考 OpenCV 官网。
运行示例¶
- 使用 USB 连接线将 PC 与 Android 设备连接。
- 使用 USB 连接线将摄像头与 Android 设备连接。
Camport3 Android SDK 为用户提供的示例应用（此处以armeabi-v7a平台为例）:
- 通过 adb 安装 Campor_FetchFrame.apk 和 OpenCV_2.4.9_Manager_2.18_armeabi.apk。
- 在 Android 桌面打开 camport_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 的目录图所示。
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目录
- openni2_camera: ROS 调用 OpenNI2 的封装层。
- openni2_launch: 打开 OpenNI2 设备并获取深度和颜色数据应用。
- depthimage_to_laserscan: 打开 OpenNI2 设备并获取线性深度数据应用。
配置环境变量¶
$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 应用开发流程图
流程说明¶
- 初始化 API。
- 操作设备。
- 获取设备列表。
初次获取设备信息时可以通过 selectDevice() 查询已连接的设备。在已知设备 ID 的情况下, 可以不调用该函数查询。
- 打开设备。
通过 TYOpenInterface() 打开对应的接口, 然后使用 TYOpenDevice 接口函数打开指定 ID 的设备。
- 操作组件。
- 查询组件状态。
使用 TYGetComponentIDs() 可查询所有支持的组件; 使用 TYGetEnabledComponents() 查询使能状态的组件。
- 配置组件。
每个设备打开后都必须配置组件, 默认情况下只有虚拟组件 TY_COMPONENT_DEVICE 是使能状态。多个设备可以通过 位或 方式同时使能。代码示例如下:
int32_t componentIDs = TY_COMPONENT_DEPTH_CAM | TY_COMPONENT_RGB_CAM;
TYEnableComponents(hDevice, componentIDs );
- 操作参数。
- 查询指定参数的信息。
通过填充结构体 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*)¶m, sizeof(param)));
- 给驱动程序分配 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) );
- 启动采集。
- 主动获取帧数据（包含图像数据的 buffer 传出给用户，由用户处理）。
- 解析数据帧，依据用户需要完成特定图像处理。
- 返还数据帧 Buffer 给底层驱动缓冲队列。
- 依据用户需求选择是否停止图像采集。
- 关闭设备和接口。
- 释放 API 和 存储资源。