Welcome to SmartToF SDK User Guide!

概述

欢迎来到SmartToF模组的SDK文档，通过这个文档你可以了解到SmartToF系列模组配套SDK包含的内容、SDK中工具的使用方法、SmartToF模组 二次开发时的一般过程以及相关API的使用说明。

SmartToF模组介绍

SmartToF TC系列模组是数迹公司采用TOF技术开发的3D视觉模组，采用业界领先的传感器芯片，具有测量精度高、 抗干扰能力强、外观小巧等优点。模组可用于精确的人流统计、物流仓储、手势识别、机器人避障和车载控制等新兴技术领域。

SmarToF SDK介绍

SmartToF SDK是配套SmartToF系列模组进行开发的软件工具包，支持windows、linux、Android等主流平台，SDK的总体 架构图如下：

SDK中架构中的主要部分说明和特点如下图所示：

SDK中支持的多平台列表如下所示：

表1 SDK支持说明

内容	Windows	Linux	Android
核心API C库	*	*	*
Python	*	*
java	*	*	*
ROS		*
C#	*	*
MATLAB
USB driver	*	*	*
SmartTofAnalyzer	*
SmartTofCli	*	*
SmartTofViewer	*	*	*

SDK文档说明

本SDK文档说明是由数迹公司人员持续编写、校正、修改的，本文档主要包括四个部分，每个部分的内容根据实际 情况分布，每个部分的内容是相对直观的。

• 简介(Introduction) 部分概述了对SmartToF模组和SDK的总体介绍，列出了SDK的相关资源， 概述还包含了SmartToF模组的 基本开发流程。
• 快速入门(Quick Start) 部分包含使用平台快速搭建、工具的相关使用。
• 教程(Tutorial) 教程部分展示了在主要平台下配套SDK样例的使用和相关图示，样例中的部分代码可以作为二次开发时参考。
• 详细参考(Reference) 对SDK中核心API库、python、Java、C#、ros和Android等作了扩展说明，在进行模组的二次开发时， 如果需要了解详细的信息，可以从本章内容中找到。

基本开发流程

开发流程框图

在对Smartof模组进行二次开发时，一般的开发流程图如下

开发流程说明

模组基本性能评估

在获得SmartToF模组后，使用SDK中tools目录下提供的SmartToFViewer工具进行被测物体的实时显示。显示时根据被测 物体的远近、运动状态等调节SmartToFViewer上的相关参数，通过显示效果评估模组的成像质量、深度距离的精确度等信息。 如果要评估模组的点云效果，需要在开启SmartToFViewer的同时开启SmartToF_PCLViewer。

模组样例集成开发

通过使用SmartToFViewer进行模组的评估，能够基本了解模组的一些参数和滤波功能，后续可以按照 教程(Tutorial) 的说明 熟悉和运行SDK中提供的样例。掌握自己所要使用的开发平台和语言环境下使用SDK的主要步骤,参考样例代码,代码中相关的API详细 说明参考 核心API 中的对应章节,编写集成自己的测试样例进行模组数据的采集和显示。

• C/C++的用户参考 C/C++ 的相关样例和编译运行C/C++样例的方法。
• Python用户参考 Python 的相关样例和运行样例方法。
• Java用户参考 Java 的basic和basicUI样例以及运行样例的方法。
• C#用户参考 C# 的basic和basicUI样例以及运行样例的方法。

模组算法评估开发

为了方便快捷的使用smarttof模组进行算法开发，SmartToF SDK提供了一套完整的开发流程说明，将整个开发流程分为录像文件获取、 离线算法评估、在线算法评估、实际平台应用等四个阶段，每一阶段的具体说明如下。

录像文件获取

算法评估的基础是建立在完整准确的数据之上，针对前期没有模组进行数据采集或者不确定采集的图像数据是否正确的情况下， 可以先期通过smarttofviewer的录像功能进行获取，也可以通过dmcam-cli工具的rx命令采集，或者直接向数迹公司FAE获取，后续通过数迹公司网站下载(下载地址后续会公布)。如何使用Smarttofviewer的录像功能录制录像文件 参考 SmartToFViewer录像功能 中的工具说明,使用dmcam-cli工具的rx命令采集保存文件参考 help rx 帮助说明。

离线算法评估

在获得录像文件后，通过调用 dmcam_dev_open_by_uri 接口打开录像文件，将录像文件模拟成标准的模组DMCAM设备。然后在获得的录像文件上加载运行评估算法， 对比算法加入后运行的实际效果，如要对原始深度数据进行滤波，可以加入常用的中值或者双边滤波，也可以是改进后的深度滤波，通过滤波前后的图像效果评估算法效果。 这种离线算法评估解决了部分用户在没有模组或者未能正常采集模组数据的情况下，能够正常进行算法评估开发的相关工作。

在线算法评估

进行在线算法评估时，需要打开实际的SmartToF设备，打开设备的API不再跟打开录像文件时的API相同，为 dmcam_dev_open 接口。经过前期在离线录像文件上的算法评估，基本确定被评估算法的效果，判断评估算法是否达到设计要求，后续就是在模组上进行 动态的实际效果的算法评估。在采集SmartToF模组实时数据的同时加入前面离线评估的算法处理，实时观察和评测算法在pc上的 实际效果，最终确定在SmartToF上使用的算法是否达到使用要求。

Tip

离线算法评估和在线算法评估的的主要区别就是打开的设备不同，离线算法评估打开的是由录像文件模拟的设备，在线算法评估打开的是真实的模组设备。 打开设备时的调用API也不相同，离线算法打开录像文件时调用的接口是 dmcam_dev_open_by_uri, 在线算法打开正常模组时调用 dmcam_dev_open 接口。

实际平台应用

前期的离线算法评估和在线算法评估主要是基于PC平台，在实际应用中，SmartToF模组可能需要被运行在各种不同的嵌入式平台。 这时需要在对应的平台上运行相应的SmartToF的库，同时将前面的评估算法移植到对应的平台，并根据平台对算法进行相应的 优化，最后在实际的嵌入式平台上进行应用的开发。

SmartToF SDK 配置需求

最低配置

x86或x64平台最低配置

CPU	Intel Atom X5-8350
内存	2GB
接口	USB2.0

ARM平台最低配置

CPU	Cortex-A7
内存	256M DDR3 RAM
接口	USB2.0

推荐配置

x86或x64平台推荐配置

CPU	Intel Core i5
内存	4GB
接口	USB2.0

ARM平台推荐配置

CPU	Cortex-A53
内存	512M DDR3 RAM
接口	USB2.0

SmartToF SDK运行要求

Windows下

数据接口	USB2.0
操作系统	Windows 7 / 10(32位和64位)
编译器	Visual Studio 2013或以上
编程语言	C/C++,C#,Java,Python

Linux下

数据接口	USB2.0
操作系统	Ubuntu 14.04 / 18.04(64位)
编译器	GCC 4.8或者更高
编程语言	C/C++,C#,Java,Python

模组连接

windows下模组连接

在windows下连接使用模组时，需要安装模组的usb驱动，模组的一般安装流程如下：

模组准备

模组套件包括TC系列模组、MicroUSB线和电源（部分型号无需电源）如表2所示

表2 模组套件

1	TC系列模组
2	Micro USB电缆
3	12V 电源

模组安装

在windows系统下，运行SDK中windows/drivers目录下的smarttof_usb_install.exe程序进行驱动的安装，正常安装过程如下图所示

驱动正常安装后，将USB电缆连接模组和PC,打开设备管理器中可以看到模组的设备名，如下图所示

linux下模组连接

libusb的安装

在使用Linux的发行版ubuntu14和ubuntu16时，默认自带libusb，无需安装usb驱动，如果需要重装libusb, 删除原来的libusb后，在终端中重新输入命令进行安装:

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

然后运行SDK目录边tool/SmartTofViewer目录下的smartTOFViewer工具查看设备是否连接正常，正常连接如下图 所示显示设备号

libusb权限修改

为了便于每次使用模组时，不用重复输入密码，需要给usb增加相应的规则，SDK中已经提供规则设置脚本， 只要运行在linux/lib目录下的setup.sh脚本，运行脚本过程如下图

工具初步使用

SDK配套SmartToFViewer显示评估工具和dmcam-cli命令行工具，分别在SDK中的tools目录下， SmartToFViewer同时提供smartTOF_PCLViewer点云显示工具。

SmartToFViewer使用

SmartToFViewer可以直接用来评估被测物体图像，并通过UI设置模组相关参数， 查看模组的相关信息和工作状态，SmartToFViewer在模组usb正常安装时即可使用。

SmartToFViewer界面介绍

SmartToFViewer打开后的整体预览如下，SmartToFViewer主要包括图像显示区、 基础参数区、filter设置区、信息区以及模组的开启关闭：

SmartToFViewer采集显示

双击运行SmartToFViewer工具，点击选择设备，如果同时连接多台模组，会列出设备列表， 左击选择要使用的设备后点击图中的OK按钮，如下图：

选取设备后点击 开始 按钮就可以采集图像显示了，默认视图模型为深度图-彩色编码，如下图 所示，图中显示了物体的深度距离信息。 拖动或者点击界面上的相关按钮，可以对模组的采集参数设置和滤波功能使能，具体参考详细 说明中的SmartToFViewer的详细说明。

SmartToFViewer录像功能

SmartToFViewer支持录像功能，录制的视频文件可以作为离线算法评估的图像数据。Viewer打开 后选择好设备后，点击图中的 录像设置 选项卡，并勾选 录像使能，选择录像文件的保存 地址，如下图：

Caution

在 录像设置 选项卡下还有个 OpenNI格式兼容 选项，该选项功能说明如下

• 使能模式下，如果用NiViewer播放录像文件时，输出深度图和灰度图
• 不使能模式下，用NiViewer播放录像文件时，输出4DCS(tof芯片的raw数据)的原始图像。

点击SmartToFViewer上的 结束 则停止录像，并将oni格式的录像文件保存到刚才选择的地址。

SmartToFViewer播放录像文件

打开SmartToFViewer，点击 打开回放 按钮，选择保存的录像文件，选中后SmartToFViewer右 下角的USB设备号变成录像的文件名，如下图所示

如果要开启点云图，则需要同时开启SmartToFViewer和SmartToF_PCLViewer：如下图

dmcam-cli命令行工具使用

SDK中的dmcam-cli工具是方便用户在二次开发时进行诊断和测试使用，主要包括以下几个功能：

• 硬件设备信息获取
• 硬件参数设置
• 数据采集和保存
• 固件更新

dmcam-cli基本信息获取

dmcam-cli通常通过命令行参数方式、脚本文件方式、交互模式与硬件设备进行交互，如下图展示了命令行 参数模式和交互模式获取设备信息：

dmcam-cli的其他具体功能介绍请参考 详细参考(Reference) 中SDK工具详细说明。

C/C++

教程部分主要展示了在不同开发语言等环境下各个样例的运行结果以及如何运行各个样例的方法。

采集

SDK中提供了基本采集、参数设置、滤波使能、保存录像文件等四个基本样例， 基本覆盖了在模组二次开发中常用的一些 核心API 使用，可以作为用户进行开发时 的基本参考。

运行sample_capture_frames采集样例程序如图.

样例中为先对模组进行采集前基本设置，然后开启采集，每次获取10帧,然后进行深度和 灰度等计算，设置的采集总帧数为100帧，采集完成后停止采集。采集样例中包括了dmcam_cap_config_set用 于采集前的配置，dmcam_cap_start开始采集，dmcam_cap_get_frames获取 采集数据,dmcam_frame_get_distance等主要采集接口。

参数设置

sample_set_param样例主要展示了对模组参数设置的一般方法， 主要参数包模设置模组的积分时间、采集帧率、调制频率等，运行 的样例程序结果如图。

模组参数相关接口包括模组参数的设置和获取，参数设置在调用dmcam_dev_open接口打开设备后可以 进行设置，参数设置通过调用dmcam_param_batch_set,参数获取通过调用dmcam_param_batch_get。

滤波

SDK中包括了对模组进行幅值滤波、深度滤波、自动曝光、运动模式等多种滤波功能， sample_filer样例主要展示了使能模组滤波功能的相关使能设置和关闭设置。

运行sample_filter样例的程序如图

开启滤波功能调用的主要API为dmcam_filter_enable,进行滤波功能设置时，有些需要 设置参数值，详细参考 模组参数和滤波类型说明 模组参数和滤波类型说明以及代码示例。

录像

SDK中提供了支持录像的功能，利用保存的录像文件可以进行前期的算法开发，保存的录像文件格式为ONI格式， 在使用dmcam_cap_config进行采集前的设置时，指定保存的录像文件名。

运行sample_save_replay保存录像样例程序如图

运行录像文件样例会生成一个名为sample_replay.oni的文件，可以直接通过SmartToFViewer工具进行 回放，SmartToFViewer工具的详细使用参考 SmartToFViewer使用说明。

编译生成

在windows下生成vs工程

1. 在windows/samples/c下新建文件夹vsbuild

2. 使用命令行工具或者msys2下mingw工具，进入vsbuild使用cmake生成vs工程，具体命令如下:

   cd vsbuild
   
   cmake .. -G "Visual Studio 12 2013"  //根据自身所装的vs版本
   

3. 生成工程后打开dmcam_c_sample.sln,编译生成C样例的可执行文件。

生成的VS工程如下图：

成功生成VS工程后，使用VS打开工程，生成解决方案，下图展示了生成解决方案后，运行sample_capture_frames程序

其他生成的几个sample程序同样可以运行，运行效果跟windows生成的可执行文件效果一样，具体可查看下面的附图。

在windows下生成可执行文件

1. 在windowssamplesc下新建文件夹build

2. 进入build使用cmake生成可执行文件，具体命令参考如下:

   cd build
   
   cmake .. -G "MSYS Makefiles"
   
   make -j
   

3. 编译生成可执行文件后可双击运行

生成可执行文件后，在build文件夹下显示如下图所示的可执行文件：

C++的样例程序的使用跟C一样，具体过程可以参考以上C的使用过程。

Python

最简采集

SDK中提供了基于python下开发的样例，包括了基本采集、基本参数设置和 采集显示，覆盖了python下进行模组二次开发中的一些 核心API 的使用，可以作 为用户进行开发时的基本参考。

运行python的sample_basic.py采集程序:

python sampe_basic.py

基本采集程序运行的结果如下图

参数设置

sample_param.py样例主要展示了对模组参数进行设置的一般方法， 包括模组参数的的设置和读取。

运行python的sample_param.py程序:

python sample_param.py

参数设置程序运行结果如下图

采集UI显示

SDK中提供了在python下使用pygame等模块进行采集图像的显示，如sample_gui_pygame.py.

运行python中的sample_gui_pygame.py程序:

python sample_gui_pygame.py

程序运行结果如下图

运行

运行Python样例需要安装对应Python版本的dmcam包、 numpy、matplotlib、pygame、Pyqtgraph等包。其中dmcam包是SmartToF模组设备相关的驱动包，已上传pypi网站。

运行python样例相关包的安装

1. dmcam库的安装

   dmcam包从1.60后开始，已经上传python各版本对应的whl包到Pypi网站， 如要更新安装最新的dmcam包，安装命令如下:

   pip install -U dmcam
   

   如果要安装指定版本的dmcam,则需加上版本号，如安装版本号为1.57.7:

   pip install dmcam==1.57.7
   

   安装dmcam包的结果如下图：

   

2. 样例其他库的安装

   安装numpy、matplotlib、pygame、PyQt5、pyqtgraph,可以通过以下命令安装:

   pip install -r requirement.txt
   

   Note

   在python2.7或者python3.4环境下安装PyQt5可能回导致失败，可以换成安装PyQt4

python相关包安装好后，就可以运行指定的样例。

C#

最简采集

SDK中提供了sampleBasic和sampleBasicUi两个基本展示样例， 展示了在C#中使用如何使用SDK的相关接口进行模组的采集。

运行sample_basic样例的运行结果如下图

采集UI显示

sampleBasicUi采集显示样例展示了在调用SDK中的采集接口 进行采集的同时将采集图像显示出来，运行结果和gui界面如下图

编译生成

windows平台

1. 命令行进入到windowssamplescsharp目录运行下面的命令,<BUILD_TYPE>可以是Release或者Debug:

   mkdir build
   cd build
   cmake .. -G "Visual Studio 12 2013"         //根据自身所装的vs版本
   cd ..
   cmake --build ./build --config <BUILD_TYPE>
   

在build文件下生成了sample_basic.exe和sample_ui.exe两个可执行文件，如下图

Linux平台

1. 在linux下需要安装mono用于C#的编译扩展:

   sudo apt-get install mono-complete
   

2. 进入到linux/sample/chsarp目录下，运行下面命令:

   mkdir build
       cd build
       cmake .. –DCMAKE_BUILD_TYPE=Debug
       cd ..
       cmake –build build
   

在build文件下生成了sample_basic.exe和sample_ui.exe两个可执行文件，如下图

Java

最简采集

SDK中提供了Java的basic和basicUi两个基本展示样例， 展示了在Java下如果调用SmartToF的 核心API 进行模组的采集。

运行basic的程序运行结果如下图

采集UI显示

Java basicUi采集显示样例展示了在使用Java时调用SDK中的采集接口 进行采集的同时将图像显示出来，样例运行的结果如下图

编译生成

windows平台

1. 将SDK中windows/java目录下对应位数的java包和windowslib下对应得libdmcam.dll拷贝到windows/samples/java目录

2. 运行javac命令进行编译:

   javac –cp dmcam.jar .\com\smarttof\dmcam\sample\sampleBasic.java
   javac –cp dmcam.jar .\com\smarttof\dmcam\sample\sampleBasicUi.java
   

   编译成功后，在windows/samples/java/com/smarttof/dmcam/sample下有相应的class文件生成

在windows/samples/java目录中java命令运行:

java –cp dmcam.jar com.smarttof.dmcam.sample.sampleBasic

在windows/samples/java目录中java命令运行:

java –cp dmcam.jar com.smarttof.dmcam.sample.sampleBasicUi

linux平台

1. 在linux下安装openjdk-7-jdk用于java扩展:

   sudo apt-get install openjdk-7-jdk
   

2. 在SDK中的linux/java目录下的对应位数的java包拷贝到linux/samples/java目录，

3. 运行javac命令进行编译:

   javac –cp .:dmcam.jar ./com/smarttof/dmcam/sample/sampleBasic.java
   javac –cp .:dmcam.jar ./com/smarttof/dmcam/sample/sampleBasicUi.java
   

   编译成功后，在linux/samples/java/com/smarttof/dmcam/sample下有相应的class文件生成

在linux/samples/java目录中java目录运行，如果有些动态库没有找到，需要指定LD_LIBRARY_PATH:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd) java –cp .:dmcam.jar com.smarttof.dmcam.sample.sampleBasic

在linux/samples/java目录中java目录运行，如果有些动态库没有找到，需要指定LD_LIBRARY_PATH:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd) java –cp .:dmcam.jar com.smarttof.dmcam.sample.sampleBasicUi

ROS

ROS包中主要包括了ros系统对smarttof API的封装， 分为dmcam_ros和cloud_viewer两个包，dmcam_ros包 用来采集与显示深度、灰度数据和动态修改参数，cloud_viewer用来 显示点云数据。

ROS深度显示

1. 开启ROS环境:

   roscore&
   

2. 进入ros所在文件夹初始化环境变量:

   source ./devel/setup.bash
   

3. 运行launch文件:

   roslaunch dmcam_ros start.launch
   

4. 显示深度图命令:

   rosrun image_view image_view image:=/smarttof/image_dist
   

   深度图像显示如下：

   

ROS灰度显示

1. 开启ROS环境:

   roscore&
   

2. 进入ros所在文件夹初始化环境变量:

   source ./devel/setup.bash
   

3. 运行launch文件:

   roslaunch dmcam_ros start.launch
   

4. 显示灰度图命令:

   rosrun image_view image_view image:=/smarttof/image_gray
   

   灰度图像显示如下：

   

ROS点云显示

cloud_viewer是一个简单的使用smarttof ros来显示点云数据的样例， 这个样例简单的实现了怎么从smarttof ros发布的话题pointcloud中获取点云数据并显示出来。

1. 开启ROS环境:

   roscore&
   

2. 进入ros所在文件夹初始化环境变量:

   source ./devel/setup.sh
   

3. 运行launch文件:

   roslaunch cloud_viewer start.launch
   

4. 显示点云图像

   

5. 通过鼠标中间的滑轮和鼠标左键调整点云显示图像，最终效果如图

   

ROS下使用模组环境搭建

Ubuntu下安装ros

ubuntu下安装ros过程如下：

1. 打开命令行终端，进入SDK中的ros文件夹中，运行如下命令:

   sudo chmod 755 install_ros.sh
   ./install_ros.sh
   

2. 出现如下图所示的安装选择版本，手动输入版本名称后按回车开始安装，Ubuntu14.04推荐使用indigo，Ubuntu16.04推荐使用kinetic。

   

ROS环境配置

每次使用ROS系统前需要初始化安装版本的环境变量， 以Kinetic为例，Kinetic默认安装在/opt/ros/kinetic/目录下， 该环境变量配置文件位置/opt/ros/kinetic/setup.bash,每次使用前需要初始化ros环境，命令如下:

source /opt/ros/kinetic/setup.bash

为了简化配置环境变量的过程，可以选择把环境变量的配置放在~/.bashrc文件中， 这样每次打开一个新终端的时候，ROS的环境变量会自动配置好:

echo "source /opt/ros/kinetic/setup.bash" >> ~/.bashrc

SmartToF ros包编译

1. 进入ros所在目录，通过ls命令查看目录中文件如下:

   install_ros.sh  Makefile  src
   

2. 使用catkin_make(Makefile中实现了catkin_make使用的步骤，也可以使用make命令来编译):

   source /opt/ros/kinetic/setup.bash(未在bashrc中设置初始化环境需要这一步)
   catkin_make
   

3. 编译完成后会生成devel和build目录，通过ls命令查看编译生成的文件:

   build  devel  install_ros.sh  Makefile  src
   

4. 初始化devel中的环境变量:

   source devel/setup.bash
   

ROS rviz工具使用

rviz是ros自带的一个图形化工具，可以方便的对ros的程序进行图形化操作，整体界面如下图所示 ：

界面主要分为左侧的显示设置区域，中间的大的显示区域和右侧的视角设置区域。 最上面是和导航相关的几个工具。最下面是ros状态相关的一些数据的显示。

rviz使用前准备

1. 开启ROS环境:

   Roscore&
   

2. 进入ros所在文件夹初始化环境变量:

   source ./devel/setup.bash
   

3. 运行launch文件:

   roslaunch dmcam_ros start.launch
   

rviz显示深度图像

1. 打开一个终端，运行rviz:

   rviz
   

2. 选中add，By topic中选中image_dist下的Image，最后确认添加，如下图所示：

   

3. 显示效果如下图所示：

   

rviz显示点云图像

1. 打开一个终端，运行rviz:

   rviz
   

2. 选中add，byTopic中选中pointcloud下的PointCloud2，最后确认添加.

   

3. 在rviz左上角的displays区域，修改GlobalOptions下的变量FixedFrame值为dmcam_ros，点云显示如下图

   

ROS 滤波

滤波功能的使用

1. 打开一个滤波功能，如DMCAM_FILTER_ID_AUTO_INTG:

   rosservice call /smarttof/change_filter "filter_id:
   'DMCAM_FILTER_ID_AUTO_INTG'
   filter_value: 0"
   

2. 关闭一个滤波功能，如DMCAM_FILTER_ID_AUTO_INTG:

   rosservice call /smarttof/disable_filter "filter_id:
   'DMCAM_FILTER_ID_AUTO_INTG'"
   

详细的ROS API介绍请前往ROS扩展

Openni2

Niviewer采集显示

SmartToF SDK目前提供了支持OpenNI2的Windows平台相关驱动库， 通过将SDK中openni2包中的libdmcam.dll、smarttof.dll、smarttof.lib、smarttof.pdb等库 拷贝到OpenNI2安装路径下的Tools/OpenNI2/Drivers下，如下图

转到Tools目录，管理员运行Tools下NiViewer.exe程序，显示结果如下图

最简采集

SmartToF SDK还提供了使用OpenNI的基础的采集和参数设置样例：

进入SDK中的openni2目录下的Smarttof_OpenNI_Sample/Smarttof_OpenNI_Sample,打开VS工程如下图

编译生成main.cpp,生成后运行结果如下图

参数设置

将Openni2采集样例中改为sample_set_param.cpp加入编译，编译生成后运行结果如下图

Android

APP采集显示

SDK中的Android/tools目录下提供了Android的apk安装包和生成apk的Eclipse工程， 使用Android手机安装好APK后，连接模组即可采集显示。

1. 软件安装

   安装apk时手机的系统要求Android 4.2.3以上，并且安装时选择允许USB权限。

2. 硬件连接

   手机连接模组时，除了需要手机和模组外，通常还需要准备一根手机的OTG连接线，OTG线 一端连接手机，并将模组原来连接PC的那端连接OTG线。手机和OTG如下图

   

3. 运行样例

   打开手机上的SmartToFViewer软件，界面如下图

   

   点击开始采集按钮即可进行采集演示，采集显示如下图

   

工具详细说明

SmartToFViewer使用说明

简介

SmartToFViewer是一款可视化工具，可以用来快速评估模组效果，熟悉不同参数对显示效果影响，并确定最佳参数辅助实际开发使用。

主要支持功能如下:

• 设备选择、打开、关闭等
• 显示图像深度图、灰度图等
• 配合PCLViewer显示点云图
• 查看物体和模组摄像头间距离
• 查看模组信息及工作状态
• 设置常用参数
• 设置滤波特性
• 设置运动模式
• 录像及回放录像

界面介绍

SmartToFViewer打开后的整体预览如下，SmartToFViewer界面主要包括图像显示区、基础参数区、录像设置区、filter设置区、信息区以及模组的开启关闭：

SmartToFViewer功能区说明如下图：

详细使用说明

设备选择、开始、结束

选择设备（适用于多个设备接入情形，打开GUI时候，会提示选择，如果只接入一个设备，可以直接点击”开始“），点击“选择设备”按钮，如下图

点击“开始“后，图像区显示采集图像，默认开启为深度图模式，在图像显示区下面显示深度信息，结束采集点击”结束“按钮。

图像显示切换

通过基础参数区修改视图类型，可以选择查看灰度图、深度图等四种模式，如灰度图

PCLViewer显示点云图

如果要开启点云图，则需要同时开启SmartToFViewer和SmartToF_PCLViewer：如下图

查看模组信息及工作状态

模组信息及工作状态可以参考下图

基础参数说明

通过Smartviewer可以直观的调节帧率、曝光时间、幅值滤波等，基础参数区的详细说明如下图

如曝光时间一般在物体不过曝的情况下尽量调大，但不能过曝，过曝部分会呈现紫色如下图：

filter功能说明

SmartTofViewer的filter功能区主要开启模组相关的滤波功能，滤波功能的具体描述如下图：

运动模式

对于运动速度比较快物体，正常模式图像会有类似拖影、重叠的运动模糊现象，可以勾选“运动模式0”或者“运动模式1” 使能运动模式，减小运动模糊现象，如下图

录像与回放

运行启动SmartTofViewer，切换到“录像设置”菜单，勾选“录像使能”，弹出保存文件名字及目录对话框，保存录像文件，如下图

点击开始，此时采集的图像将会保存到本地文件，运行如下图，点击“结束”按钮，停止录像

播放录像文件，点击“打开回放”，选择刚录制的文件，如下图

点击“开始”，运行效果如下图

Caution

录像文件下，“调制频率” 、“运动模式0”、 “运动模式1”、“HDR”、“曝光时间”设置调整无效

SmartToFCli使用说明

工具概述

SDK中的dmcam-cli工具是方便用户在二次开发时进行诊断和测试使用，工具几乎覆盖了dmcam库的所有API支持，可以通过dmcam-cli工具制作批处理脚本，设计自己想要的场景，获取对应的数据。 主要包括以下几个功能：

• 查看可用设备列表
• 硬件设备信息获取
• 目标寄存器配置
• 常用参数读取及设置
• 不同类型图像数据采集和保存
• 设备复位
• 设备固件更新

工作方式

dmcam-cli可以通过命令行与硬件设备进行交互，一般通过下面三种方式使用：

• 命令行参数方式：具体参数定义参见下面 详细命令
• 脚本文件方式: 参见 详细命令 中‘-s, –script <file>’选项。
• 交互模式：参见 详细命令 中’-i, –interactive’选项，默认启动进入交互模式。

下图是命令行参数模式和交互模式的参考使用截图

Tip

在windows下，直接双击运行dmcam-cli.exe,默认进入交互模式。

详细命令

下表列出了dmcam所有的命令和参数，并展示了样例的基本使用方法。更详细的说明可输入–help和–help-interactive参数进行查看。

命令列表

Script mode functions	options	appended options	example
指定设备	-d, --device <device>		dmcam-cli.exe --print info --device 0
set verbosity	-v, --verbosity <level>		dmcam-cli.exe --print info --device 0 -v critical
枚举设备	-l, --list		dmcam-cli.exe -l
复位设备	-r, --reset		dmcam-cli.exe -r
执行 interactive mode command, 可多次使用	-e, --exec <command>		dmcam-cli.exe -e "print info" -e "print frame_format"
Run provided script	-s, --script <file>		dmcam-cli.exe -s script.txt
进入 interactive mode	-i, --interactive		dmcam-cli.exe -i
print cli version	--version		dmcam-cli.exe --version
print cli help info	-h, --help		dmcam-cli.exe --help
show interactive mode help info	--help-interactive		dmcam-cli.exe --help-interactive
固件升级	-f, --flash-MCU-firmware <file>		dmcam-cli.exe --flash-MCU fw_mcu.bin
写寄存器	--regwr	--target <target> --base <base> --value <val>	dmcam-cli.exe --regwr --target tfc_tg --base 0x100 --value 0xaa dmcam-cli.exe --regwr --target tfc_tg --base 0x100 --value "0xaa 0xbb 0xcc" dmcam-cli.exe --regwr --target tfc_tg --base 0x100 --value test.bin
读寄存器	--regrd	--target <target> --base <base>	dmcam-cli.exe --regrd --target tfc_tg --base 0x100 dmcam-cli.exe --regrd --target tfc_tg --base 0x100 --cnt 5 dmcam-cli.exe --regrd --target tfc_tg --base 0x100 --cnt 5 --value test1.bin
写参数	--set <param>	[--param <param>] --value <val>	dmcam-cli.exe --set mode --value 1
读参数	--print <param>	[--param <param>]	dmcam-cli.exe --print mode
以下为交互模式
查看命令帮助信息	help <cmd>		help rx
设备列表	list
固件升级	flash <target> <version>		flash mcu fw_mcu.bin
写寄存器	regwr <target> <base> [<&file> | <P0> <P1>… <P4n>]		regwr mcu 0x11 test.bin regwr tfc_de 0x10 0x11 0x12 13
读寄存器	regrd <parameter> <base> [cnt] [&file]		regrd mcu 0x01 5 regrd tfc_de 0x10 test2.bin
写参数	set <parameter> <arguments>		set frequency 1 set frame_format 1 set frame_rate 30 set intg_time 30
读参数	print/p [parameter]		print print info print mode print frequency print format print frame_rate print roi
采集固定数量的frame到文件	rx <data src> <&file> <frame count>		rx raw raw.bin 10 rx depth depth.bin 10
采集固定数量数据到buffer	read <frame count>		read 5
同print info	info		info
显示所有version信息	version		version
采集指定时间距离数据	capture <option> <args>		capture -c start
filter参数配置	filter <id> <enabled> [args]		filter <ID_AMP> 1 40
复位命令	reset <target>		reset sys
others			cls quit help h rx echo who am i

Caution

针对TC系列模组,谨慎涉及寄存器的读写操作，误读写可能产生不可预知的问题。

查看可用设备信列表

当设备连接后，可以通过dmcam-cli -d命令查看可用设备列表，命令如下:

dmcam-cli -l

输出结果如下:

4 dmcam device found
[0]: Type=USB  BUS:PORT:ADDR=07:04:03
[1]: Type=USB  BUS:PORT:ADDR=07:03:04
[2]: Type=ETH IP=192.168.1.38 CID=0xfbf056c1
[3]: Type=ETH IP=192.168.1.53 CID=0xf2a4fa3e

硬件设备信息获取

当设备连接后，可以通过dmcam-cli交互模式的print命令进行硬件设备信息获取，命令格式如下:

p [parameter]

常用参数设置

当设备连接后，可以通过dmcam-cli交互模式的set命令设置硬件参数，命令格式如下:

set <parameter> <arguments>

可以通过下面命令查看set命令有哪些参数可以设置及参数含义，命令如下，结果见下图:

help set

不同类型图像数据采集和保存

当设备连接后，可以通过dmcam-cli交互模式的rx命令进行数据采集，并将数据存入指定文件，采集的数据格式包括原始数据、深度数据、灰度数据和点云数据，命令格式如下:

rx  <data src> <&file> <frame count>

保存或者打印指定区域像素点距离信息

当设备连接后，可以通过dmcam-cli交互模式的capture命令进行数据采集，并将数据存入指定文件，或者打印出来，采集的数据格式包括温度，距离，幅值，命令格式如下,详细使用可参考help cap:

cap -s 10  -p 119,159,120,160 -c start

Caution

cap命令支持多条输入，比如cap -o 0 回车，cap -f test.csv回车，但必须所有参数选项都放在-c start 之前

设备复位

当设备连接后，可以通过dmcam-cli交互模式的reset命令复位设备，命令格式如下:

reset <target>

测试结果如下图

固件更新

固件更新的详细内容参考 SDK固件升级

C/C++核心库(libdmcam)参考

核心API

dmcam.h

SmartToF SDK中的所有核心API都在dmcam.h中说明，详见本章内容。

DM’s camera device API.

Detail Decsription starts here

Functions

__API void dmcam_init(const char * log_fname)

Init the DM camera layer. It should be called before any dmcam API is invoked.

Parameters

• log_fname: [in] specified log file name of dmcam layer. if NULL, the default log (dmcam_YYYYMMDD.log) is used.

__API void dmcam_uninit(void)

Uninit the DM camera layer.

__API void dmcam_log_cfg(dmcam_log_level_e console_level, dmcam_log_level_e file_level, dmcam_log_level_e usb_level)

Set the logging configuration for dmcam layer.

Parameters

• console_level: [in] specified dmcam_log_level_e, the console log whose log level bellow this value will be suppressed.
• file_level: [in] specified dmcam_log_level_e, the file log whose log level bellow this value will be suppressed.
• usb_level: [in] specified dmcam_log_level_e, the usb log whose log level bellow this value will be suppressed.

__API void dmcam_path_cfg(const char * path)

Setting where to save calibration data

Return

__API void

Parameters

• path:

__API char* dmcam_path_get(void)

Getting calibration data path

Return

_API char*

__API const char* dmcam_error_name(int error_code)

covert specified error code into error string

Return

const char*

Parameters

• error_code:

__API int dmcam_dev_list(dmcam_dev_t * dev_list, int dev_list_num)

list the dmcam device and fill into dmcam_dev_t array.

Return

int [out] number of dmcam device found

Parameters

• dev_list: [out] device list array to be filled.
• dev_list_num: [in] capacity of device list

__API dmcam_dev_t* dmcam_dev_open(dmcam_dev_t * dev)

open specified dmcam device. if the device is not specified, it’ll try to open the first dmcam device

Return

dmcam_dev_t* NULL = open device failed.

Parameters

• dev: [in] specified dmcam device which is usally get from dmcam_dev_list. if Null, the first dmcam device will be opened.

__API dmcam_dev_t* dmcam_dev_open_by_fd(int fd)

open specified dmcam device with specified fd. this is useful for android usb device.

Return

dmcam_dev_t* return opened device. NULL = open device failed.

Parameters

• fd: [in] specified fd

__API dmcam_dev_t* dmcam_dev_open_by_uri(const char * uri_str)

open specified dmcam device with specified uri.

Return

dmcam_dev_t* NULL = open device failed.

Parameters

• uri_str: [in] specified URI. Following URI are supported: USB device URI: usb://bus:port or usb://bus:port:dev_addr Ethernet device URI: eth://hwid:token or eth://hwid:token FILE device URI: file://filename or filename

__API void dmcam_dev_close(dmcam_dev_t * dev)

Close specified dmcam device.

Parameters

• dev:

__API const char* dmcam_dev_get_uri(dmcam_dev_t * dev, char * uri_str, int uri_str_len)

get URI of specified device.

Return

const char* [out] uri string. If null, get uri failed.

Parameters

• dev: [in] specified device after dmcam_dev_open
• uri_str: [in] uri string buffer
• uri_str_len: [in] uri string buffer len

__API bool dmcam_dev_reset(dmcam_dev_t * dev, dmcam_dev_rst_e target)

Reset specified target on the dev

Return

bool [out] true = reset ok.

Parameters

• dev: [in] dmcam device handler
• target: [in] reset taget defined in dmcam_dev_rst_e

__API bool dmcam_reg_batch_write(dmcam_dev_t * dev, dmcam_dev_reg_e target, uint32_t reg_base, const uint32_t * reg_vals, uint16_t reg_vals_len)

Batch write registers of specified target on the device.

Return

bool [out] true = write ok.

Parameters

• dev: [in] dmcam device handler
• target: [in] specified target defined in dmcam_dev_reg_e
• reg_base: [in] base address of the registers
• reg_vals: [in] register values to be written. All register value is denoted as UINT32
• reg_vals_len: [in] count of values in reg_vals

__API bool dmcam_reg_batch_read(dmcam_dev_t * dev, dmcam_dev_reg_e target, uint32_t reg_base, uint32_t * reg_vals, uint16_t reg_vals_len)

Batch read registers of specified target on the device.

Return

bool [out] true = read ok.

Parameters

• dev: [in] dmcam device handler
• target: [in] specified target defined in dmcam_dev_reg_e
• reg_base: [in] base address of the registers
• reg_vals: [out] register values to be filled. All register value is denoted as UINT32
• reg_vals_len: [in] count of values in reg_vals

__API bool dmcam_param_batch_set(dmcam_dev_t * dev, const dmcam_param_item_t * param_items, int item_cnt)

Batch write generic parameters to specified device.

Return

bool [out] true = operation is ok.

Parameters

• dev: [in] dmcam device handler
• param_items: [in] dmcam_param_item_t is used to denotes generic parameter:
  • param_id[in]: defined in dmcam_dev_param_e to identify the parameters.
  • param_vals[in]: denotes the generic value (max = 16bytes)
  • param_vals_len[in]: denotes the length of value.
• item_cnt: [in] count of params in param_items

__API bool dmcam_param_batch_get(dmcam_dev_t * dev, dmcam_param_item_t * param_items, int item_cnt)

Batch read generic parameters from specified device.

Return

bool [out] true = operation is ok.

Parameters

• dev: [in] dmcam device handler
• param_items: [in/out] dmcam_param_item_t is used to denotes generic parameter:
  • param_id[in]: defined in dmcam_dev_param_e to identify the parameters.
  • param_vals[out]: denotes the generic value (max = 16bytes) filled by this function
  • param_vals_len[out]: denotes the length of value filled by this function.
• item_cnt: [in] count of params in param_items

__API bool dmcam_cap_config_set(dmcam_dev_t * dev, const dmcam_cap_cfg_t * cfg)

Set specified capture configuration for specified device. This api is available from v1.58 to replace dmcam_cap_set_frame_buffer

Return

bool [out] true = set OK.

Parameters

• dev: [in] specified dmcam device
• cfg: [in] specified capture configuration

__API void dmcam_cap_config_get(dmcam_dev_t * dev, dmcam_cap_cfg_t * cfg)

Get capture configuration of specified device

Parameters

• dev: [in] specified dmcam device
• cfg: [out] capture configuration to be filled

__API bool dmcam_cap_set_frame_buffer(dmcam_dev_t * dev, uint8_t * frame_buf, uint32_t frame_buf_size)

set frame buffer during capturing.

Return

bool [out] return true = set ok.

Parameters

• dev: [in] dmcam device handler
• frame_buf: [in] framebuffer assigned by user. if null, the frame_buf will be alloced internally
• frame_buf_size: [in] frame buffer size, which will be rouned to frame size boundary.

__API void dmcam_cap_set_callback_on_frame_ready(dmcam_dev_t * dev, dmcam_cap_frdy_f cb)

register frame ready callback function

Parameters

• dev: [in] dmcam device handler
• cb: [in] callback function in following format: void (dmcam_cap_frdy_f)(dmcam_dev_t, dmcam_frame_t)

__API void dmcam_cap_set_callback_on_error(dmcam_dev_t * dev, dmcam_cap_err_f cb)

register error callback function. It’s invoked when some error occurs during the capturing process.

Parameters

• dev: [in] dmcam device handler
• cb: [in] callback function in following format: void (dmcam_cap_err_f)(dmcam_dev_t, int errno);

__API bool dmcam_cap_snapshot(dmcam_dev_t * dev, uint8_t * frame_data, uint32_t frame_dlen, dmcam_frame_t * frame)

Take a snapshot and fill frame data into specified frame. If the device is capturing, the snapshot will return the latest image{} or it’ll auto start/snapshot/stop

Return

bool return true = ok

Parameters

• dev: [in] dmcam device handler
• frame_data: [out] frame data
• frame_dlen: [in] frame buffersize should be large enough to containing one frame.
• frame: [out] frame_t filled during snapshot. it can be null

__API bool dmcam_cap_is_ongoing(dmcam_dev_t * dev)

Check whether the device is in capturing state.

Return

bool [out] true = device in capturing state

Parameters

• dev: [in] dmcam device handler

__API bool dmcam_cap_start(dmcam_dev_t * dev)

start device capturing.

Return

bool return true = ok

Parameters

• dev: [in] dmcam device handler

__API bool dmcam_cap_stop(dmcam_dev_t * dev)

stop device capturing.

Return

bool return true = ok

Parameters

• dev: [in] dmcam device handler

__API int dmcam_cap_get_frames(dmcam_dev_t * dev, uint32_t frame_num, uint8_t * frame_data, uint32_t frame_dlen, dmcam_frame_t * first_frame_info)

Get specified number of frames into specified user buffer. This function may be blocking wait on the frame stream. if enough frames data are collected or any error happends, it’ll returns.

Return

int [out] return the number for ready frames collected. On error the errono is returned. (errno < 0)

Parameters

• dev: [in] dmcam device handler
• frame_num: [in] number of frames to be captured.
• frame_data: [out] frame data filled curing capturing.
• frame_dlen: [in] frame_data buffer size in bytes.
• first_frame_info: [out] first frame attributes. It can be NULL

__API int dmcam_cap_get_frame(dmcam_dev_t * dev, uint8_t * frame_data, uint32_t frame_dlen, dmcam_frame_t * frame_info)

get one frame into specified buffer. this function is non-blocking, if no frame is ready, it returns 0

Return

int return 0 if not frame is ready, else return 1

Parameters

• dev: [in] dmcam device handler
• frame_data: [out] frame data to be filled, it can be NULL
• frame_info: [out] frame attributes. It can be NULL

__API int dmcam_firmware_upgrade(dmcam_dev_t * dev, uint8_t type, uint16_t version, const char * file_name)

Firmware upgrade for different type target.

Return

int

Parameters

• dev[in]:dmcam: device handler
• type[in]:firmware: type
• version[in]:firmware: version
• file_name[in]:firmware: name

__API int dmcam_data_download(dmcam_dev_t * dev, char * name, uint8_t type, uint16_t version, uint32_t addr)

__API int dmcam_data_upload(dmcam_dev_t * dev, uint8_t type, const char * file_name)

__API int dmcam_frame_get_distance(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

alias for dmcam_frame_get_dist_f32

__API int dmcam_frame_get_dist_f32(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

convert to distance data to float32 from raw frame data.

Return

int [out] return the number for distance points in dst

Parameters

• dev: [in] specified dmcam device
• dst: [out] distance buffer. The unit of distance is in meters (float32)
• dst_len: [in] distance buffer length in number of float
• src: [in] raw frame data buffer
• src_len: [in] raw frame data length in byte
• finfo: [in] raw frame information

__API int dmcam_frame_get_dist_u16(dmcam_dev_t * dev, uint16_t * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

convert to distance data in uint16 from raw frame data.

Return

int [out] return the number for distance points in dst

Parameters

• dev: [in] specified dmcam device
• dst: [out] distance buffer. The unit of distance is in millimeter (uint16)
• dst_len: [in] distance buffer length in number of uint16
• src: [in] raw frame data buffer
• src_len: [in] raw frame data length in byte
• finfo: [in] raw frame information

__API int dmcam_frame_get_gray(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

alias for dmcam_frame_get_gray_f32

__API int dmcam_frame_get_gray_f32(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

get gray data in float32 from raw frame data.

Return

int [out] return the number for gray points in dst

Parameters

• dev: [in] specified dmcam device
• dst: [out] gray buffer. The gray value denotes the amplitude. (float32 in [0, 2048.0) )
• dst_len: [in] distance buffer length in number of float
• src: [in] raw frame data buffer
• src_len: [in] raw frame data length in byte
• finfo: [in] raw frame information

__API int dmcam_frame_get_gray_u16(dmcam_dev_t * dev, uint16_t * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

get gray data in uint16_t from raw frame data.

Return

int [out] return the number for gray points in dst

Parameters

• dev: [in] specified dmcam device
• dst: [out] gray buffer. The gray value denotes the amplitude. (uint16_t in [0, 2048))
• dst_len: [in] distance buffer length in number of uint16_t
• src: [in] raw frame data buffer
• src_len: [in] raw frame data length in byte
• finfo: [in] raw frame information

__API int dmcam_frame_get_pcl(dmcam_dev_t * dev, float * pcl, int pcl_len, const float * dist, int dist_len, int img_w, int img_h, const dmcam_camera_para_t * p_cam_param)

get point cloud data from distance data. The distance data is usually calcuated using dmcam_frame_get_dist_f32.

Return

int [out] return number of points in point cloud buffer. Note: n points means 3*n floats. N should be img_w * img_h

Parameters

• dev: [in] specified dmcam device
• pcl: [out] point clound buffer. each 3 element consists a (x,y,z) point, output is in (w,h,3) demension. point in value (0,0,0) is invalid
• pcl_len: [in] point cloud float element count
• dist: [in] distance image data buffer. The unit of distance is meter (float)
• dist_len: [in] distance image data count (in sizeof(float))
• img_w: [in] distance image width in pixel
• img_h: [in] distance image height in pixel
• p_cam_param: [in] user specified camera lens parameter. if null, the internal camera parameter is used.

int dmcam_frame_get_pcl_xyzd(dmcam_dev_t * dev, float * pcl, int pcl_len, const float * dist, int dist_len, int img_w, int img_h, bool pseudo_color, const dmcam_camera_para_t * p_cam_param)

get point cloud data from distance data. The distance data is usually calcuated using dmcam_frame_get_distance.

Return

int [out] return number of points in point cloud buffer. Note: n points means 4*n floats. N should be img_w * img_h

Parameters

• dev: [in] specified dmcam device
• pcl: [out] point clound buffer. each 4 element consists a (x,y,z,d) point. (x,y,z) is coordinate, d is distance or pseudo-color. output is in (w,h,4) demension. point in value (0,0,0) is invalid
• pcl_len: [in] point cloud float element count
• dist: [in] distance image data buffer. The unit of distance is meter (float)
• dist_len: [in] distance image data count (in sizeof(float))
• img_w: [in] distance image width in pixel
• img_h: [in] distance image height in pixel
• pseudo_color: [in] if true, d is pseudo uint32 rgb color value; if false, d is the distance in meter
• p_cam_param: [in] user specified camera lens parameter. if null, the internal camera parameter is used.

__API int dmcam_filter_enable(dmcam_dev_t * dev, dmcam_filter_id_e filter_id, dmcam_filter_args_u * filter_arg, uint32_t reserved)

Enable filter controller setting for raw data processing

Return

int 0 = OK, otherwise failed.

Parameters

• dev: [in] dmcam device handler
• filter_id: [in]:defined in dmcam_filter_id_e to identify the filter
• filter_arg: [in] filter control args
• reserved: [in] reserved for future use. User should set to 0

__API int dmcam_filter_disable(dmcam_dev_t * dev, dmcam_filter_id_e filter_id)

Disable filter controller setting for raw data processing

Return

int 0 = OK, otherwise failed.

Parameters

• dev: [in] dmcam device handler
• filter_id: [in] defined in dmcam_filter_id_e to identify the filter

__API int dmcam_cmap_dist_f32_to_RGB(uint8_t * dst, int dst_len, const float * src, int src_len, dmcam_cmap_outfmt_e outfmt, float range_min_m, float range_max_m)

convert dist_f32 image (pixel in meter) to pesudo-RGB points with specified pixel format

Return

int [out] the count of pseudo RGB points

Parameters

• dst: [out] pseudo-RGB point buffer
• dst_len: [in] point buffer size in bytes
• src: [in] float points buffer
• src_len: [in] count of float points
• outfmt: [in] pixel format of the pseudo-RGB
• min_val: [in] minimum range of source point
• max_val: [in] max range of source point

__API int dmcam_cmap_float(uint8_t * dst, int dst_len, const float * src, int src_len, dmcam_cmap_outfmt_e outfmt, float range_min_m, float range_max_m)

__API int dmcam_cmap_dist_u16_to_RGB(uint8_t * dst, int dst_len, const uint16_t * src, int src_len, dmcam_cmap_outfmt_e outfmt, uint16_t range_min_mm, uint16_t range_max_mm)

convert dist_u16 image (pixel in milimeter) to pesudo-RGB points with specified pixel format

Return

int [out] the count of pseudo RGB points

Parameters

• dst: [out] pseudo-RGB point buffer
• dst_len: [in] point buffer size in bytes
• src: [in] dist_u16 image buffer
• src_len: [in] count of u16 points
• outfmt: [in] pixel format of the pseudo-RGB
• min_val: [in] minimum range of source point
• max_val: [in] max range of source point

__API int dmcam_cmap_gray_u16_to_IR(uint8_t * dst, int dst_len, const uint16_t * src, int src_len, int balance)

convert gray_u16 image to IR image whose pixel is in [0~255]

Return

int [out] the count of IR image

Parameters

• dst: [out] IR image buffer
• dst_len: [in] IR image buffer size in bytes
• src: [in] gray_u16 image
• src_len: [in] count of u16 points in gray_u16 image
• balance: [in] [-1024, 1024] -> [darkest, brightest]

__API int dmcam_cmap_gray_f32_to_IR(uint8_t * dst, int dst_len, const float * src, int src_len, int balance)

convert gray_f32 image to IR image whose pixel is in [0~255]

Return

int [out] the count of IR image

Parameters

• dst: [out] IR image buffer
• dst_len: [in] IR image buffer size in bytes
• src: [in] gray_f32 image
• src_len: [in] count of f32 points in gray_f32 image
• balance: [in] [-1024, 1024] -> [darkest, brightest]

__API int dmcam_file_open(const char * fname, const char * mode)

open specified file and get file descriptor for dmcam_frame_save_xxx apis.

Return

int [out] file descriptor. < 0 = failed

Parameters

• fname: [in] specified filename

__API void dmcam_file_close(int fd)

close specified file descriptor

Parameters

• fd: [in] specified file descriptor

__API bool dmcam_frame_save_raw(int fd, dmcam_frame_save_fmt_t save_fmt, const uint16_t * raw, int raw_len, int img_w, int img_h, int dcs_cnt, const char * raw_tag)

save specified raw data (in uin16_t) with specified pixcel width and height to file with specified saving format.

Return

bool [out] true = save raw frame ok, false = fail

Parameters

• fd: [in] specified file handler
• save_fmt: [in] file saving format defined in dmcam_frame_save_fmt_t. only followin format is supported: DMCAM_FRAME_SAVE_UINT32 DMCAM_FRAME_SAVE_UINT16
• raw: [in] raw data
• raw_len: [in] number of raw data (in count of uint16_t)
• img_w: [in] dist data pixel width
• img_h: [in] dist data pixel height
• dcs_cnt: [in] dist data dcs sub-frame count
• raw_tag: [in] any string. if want to used by replay, specify (dmcam_t*)dev->product string here.

__API bool dmcam_frame_save_distance(int fd, dmcam_frame_save_fmt_t save_fmt, const float * dist, int dist_len, int img_w, int img_h)

save specified distance data (in float32, unit: meter) with specified pixcel width and height to file with specified saving format.

Return

bool [out] true = save distance frame ok, false = fail

Parameters

• fd: [in] specified file handler
• save_fmt: [in] file saving format defined in @ dmcam_frame_save_fmt_t. only followin format is supported: DMCAM_FRAME_SAVE_FLOAT32 DMCAM_FRAME_SAVE_UINT32 DMCAM_FRAME_SAVE_UINT16
• dist: [in] distance data (in float32, unit: meter)
• dist_len: [in] number of distance data (in count of float)
• img_w: [in] dist data pixel width
• img_h: [in] dist data pixel height

__API bool dmcam_frame_save_gray(int fd, dmcam_frame_save_fmt_t save_fmt, const float * src, int src_len, int img_w, int img_h)

save specified gray data (in float32) with specified pixcel width and height to file with specified saving format.

Return

bool [out] true = save distance frame ok, false = fail

Parameters

• fd: [in] specified file handler
• save_fmt: [in] file saving format defined in dmcam_frame_save_fmt_t. only followin format is supported: DMCAM_FRAME_SAVE_UINT16 DMCAM_FRAME_SAVE_UINT8
• src: [in] gray data (in float32)
• src_len: [in] number of distance data (in count of float)
• img_w: [in] dist data pixel width
• img_h: [in] dist data pixel height

__API int dmcam_frame_load_raw(int fd, uint16_t * dst, int dst_len, int * dst_w, int * dst_h, int * dst_dcsn, char * dst_tag, int dst_tag_len)

load one raw frame from specified file fd.

Return

int [out] length of loaded raw data (in count of sizeof(uint16))

Parameters

• fd: [in] specified data file fd. The fd related file is always saved by dmcam_frame_save_raw api
• dst: [out] raw
• dst_len: [in] dst buffer length (in count of sizeof(uint16_t))
• dst_w: [out] raw frame pixel width
• dst_h: [out] raw frame pixel height
• dst_dcsn: [out] raw dcs cnt per frame
• dst_tag: [out] raw data tag string
• tag_len: [in] raw data tag buffer size

__API int dmcam_frame_load_distance(int fd, float * dst, int dst_len, int * dst_w, int * dst_h)

load one distance frame from specified file fd.

Return

int [out] length of loaded distance data (in count of sizeof(float))

Parameters

• fd: [in] specified data file fd. The fd related file is always saved by dmcam_frame_save_distance api
• dst: [out] distance in float (unit: meter)
• dst_len: [in] dst buffer length (in count of sizeof(float))
• dst_w: [out] distance frame pixel width
• dst_h: [out] distance frame pixel height

__API int dmcam_frame_load_gray(int fd, float * dst, int dst_len, int * dst_w, int * dst_h)

load one gray frame from specified file fd.

Return

int [out] length of loaded gray data (in count of sizeof(float))

Parameters

• fd: [in] specified data file fd. The fd related file is always saved by dmcam_frame_save_gray api
• dst: [out] gray in float (unit: meter)
• dst_len: [in] dst buffer length (in count of sizeof(float))
• dst_w: [out] gray frame pixel width
• dst_h: [out] gray frame pixel height

模组参数和滤波类型说明

SmartToF中主要通过模组参数设置和滤波功能设置来控制模组采集时的功能配置， 所有的模组参数项和滤波功能项定义都在SDK中的dmcam.h头文件中。

模组参数说明

模组参数枚举类型定义:

typedef enum {
        PARAM_DEV_MODE = 0,
        PARAM_MOD_FREQ,

        PARAM_INFO_VENDOR,
        PARAM_INFO_PRODUCT,
        PARAM_INFO_CAPABILITY,
        PARAM_INFO_SERIAL,
        PARAM_INFO_VERSION,   //HW&SW info
        PARAM_INFO_SENSOR,    //part version, chip id, wafer id

        PARAM_INFO_CALIB,     //get calibration info
        PARAM_ROI,            //ROI set/get
        PARAM_FRAME_FORMAT,   //frame information,eg.dcs1for gray,4 dcs for distance
        PARAM_ILLUM_POWER,    //illumination power set/get
        PARAM_FRAME_RATE,     //frame rate set/get
        PARAM_INTG_TIME,      //integration time set/get
        PARAM_PHASE_CORR,     //phase offset correction
                                                  //PARAM_SWITCH_MODE, /*>swith mode use[gray,3d]*/
        PARAM_TEMP,           //<Get camera temperature--------------
        PARAM_HDR_INTG_TIME,  //<Setting HDR integration time param
        PARAM_SYNC_DELAY,     //<delay ms for sync use
        PARAM_ENUM_COUNT,
}dmcam_dev_param_e;

模组参数枚举类型说明

参数名	取值范围	说明
PARAM_DEV_MODE	不用设置	用户无需设置此参数
PARAM_MOD_FREQ	12M、24M、36M 单位Hz	频率要对应校准数据
PARAM_INFO_VENDOR	不用设置	默认Digtal Miracle
PARAM_INFO_PRODUCT	不用设置	模组名称，如TC-E2-1.0
PARAM_INFO_CAPABLITY	不用设置
PARAM_INFO_SERIAL	不用设置	3个uint32_t类型数字
PARAM_INFO_VERSION	不用设置	包括软件和硬件版本信息
PARAM_INFO_CALIB	不用设置	包含校准相关信息
PARAM_ROI	320*240 320*160
PARAM_FRAME_FORMART	2,4	默认模式是2，运动模式1需设置为4
PARAM_ILLUM_POWER	暂不用设置
PARAM_FRAME_RATE	1-36	通常取值5、10、20、30
PARAM_INTG_TIME	0us-1500us	如果超过最大范围，对模组可能造成损坏
PARAM_PHASE_CORR	暂不支持设置
PARAM_TEMP	只读	分别读取传感器上下面左右部分温度和灯板的温度
PARAM_HDR_INTG_TIME	0-1500	取值同PARAM_INTG_TIME，设置不为0时则开启HDR模式
PARAM_SYNC_DELAY	0ms-6ms

模组滤波类型说明

模组滤波类型包括深度滤波、幅值滤波、自动曝光、运动模式等，具体 定义如下:

typedef enum {
        DMCAM_FILTER_ID_LEN_CALIB,    /**>lens calibration*/
        DMCAM_FILTER_ID_PIXEL_CALIB,  /**>pixel calibration*/
        DMCAM_FILTER_ID_MEDIAN,       /**>Median filter for distance data*/
        DMCAM_FILTER_ID_RESERVED,        /**>Gauss filter for distance data*/
        DMCAM_FILTER_ID_AMP,          /**>Amplitude filter control*/
        DMCAM_FILTER_ID_AUTO_INTG,    /**>auto integration filter enable : use sat_ratio to adjust */
        DMCAM_FILTER_ID_SYNC_DELAY,   /**> sync delay */
        DMCAM_FILTER_ID_TEMP_MONITOR, /**>temperature monitor */
        DMCAM_FILTER_ID_HDR,          /**>HDR mode */
        DMCAM_FILTER_ID_OFFSET,       /**> set offset for calc distance */
        DMCAM_FILTER_ID_SPORT_MODE,   /**> set sport mode */
        //-------------------
        DMCAM_FILTER_CNT,
}dmcam_filter_id_e;

模组滤波类型说明

滤波功能ID	说明
DMCAM_FILTER_ID_LEN_CALIB	镜头校准ID
DMCAM_FILTER_ID_PIXEL_CALIB	像素校准ID
DMCAM_FILTER_ID_MEDIAN	深度滤波ID
DMCAM_FILTER_ID_AMP	最小幅值滤波ID
DMCAM_FILTER_ID_AUTO_INTG	自动曝光ID
DMCAM_FILTER_ID_SYNC_DELAY	软件多模组串扰ID
DMCAM_FILTER_ID_HDR	HDR功能ID
DMCAM_FILTER_ID_OFFSET	距离偏移功能ID
DMCAM_FILTER_ID_SPORT_MODE	运动模式功能ID 非运动模式:全分辨率，4xDCS,18ms模糊 运动模式0：垂直分辨率减半，4xDCS,6ms模糊 运动模式1：垂直分辨率减半，2xDCS,无模糊,噪声高(竖条纹) 运动模式2：全分辨率，2xDCS,6ms模糊，噪声高(竖条纹)

关于帧率和运动模式的详细说明

TC/TCM-E3是专门满足高帧率应用的模组，最高帧率可达120帧，运动模式是为了消除运动模糊影响，他们的 关系如下表

模组频率关系

模组型号	模式	设置帧率fps范围	设置为fps时的实际帧率	运动模糊度	深度图画幅	深度图精度
TC/TCM-E2	正常模式 Normal mode	1-30	fps	21ms	320*240全画幅	正常精度(4*DCS计算)
TC/TCM-E2	运动模式0 Sport mode 0	1-30	fps	7ms	垂直分辨率减半：320*120(输出差值320*240)	正常精度(4*DCS计算)
TC/TCM-E2	运动模式1 Sport mode 1	1-30	fps	0ms	垂直分辨率减半：320*120(输出差值320*240)	精度减半(2*DCS计算)
TC/TCM-E3	正常模式 Normal mode	1-30	fps<20:fps fps>=20:fps*4	21ms	320*240全画幅	正常精度(4*DCS计算)
TC/TCM-E3	运动模式0 Sport mode 0	1-30	fps*2	7ms	垂直分辨率减半：320*120(输出差值320*240)	正常精度(4*DCS计算)
TC/TCM-E3	运动模式1 Sport mode 1	1-30	fps*4	0ms	垂直分辨率减半：320*120(输出差值320*240)	精度减半(2*DCS计算)

参数和滤波代码示例

模组参数和滤波类型说明 已经介绍了模组相关的参数和滤波功能ID, 下面将说明如何设置及获取模组参数以及使能关闭模组的相关 滤波功能。

模组参数设置和读取

下面以设置和读取模组的曝光时间为例：

• 进行参数设置:

  dmcam_param_item_t wparam;
  uint16_t intg_time = 100;                       //表示设置积分的大小 范围为0-1500
  memset(&wparam,0,sizeof(wparam));
  wparam.param_id = PARAM_INTG_TIME;      //表示设置的参数为积分时间
  wparam.param_val_len = sizeof(intg_time);
  wparam.param_val.intg.intg_us = intg_time;
  assert(dmcam_param_batch_set(dev,&wparam,1));   //调用API进行单个参数设置
  
  dmcam_param_item_t wparam;
  uint16_t intg_hdrtime = 700;            //表示设置HDR的积分时间的大小
  memset(&wparam,0,sizeof(wparam));
  wparam.param_id = PARAM_HDR_INTG_TIME;  //表示设置的参数为积分时间
  wparam.param_val_len = sizeof(intg_time);
  wparam.param_val.intg.intg_us = intg_hdrtime;
  assert(dmcam_param_batch_set(dev,&wparam,1));   //调用API进行单个参数设置
  

Tip

如果hdr的积分时间设置了不为0，则开启了模组的HDR模式,上面两个积分时间中，下面的HDR的积分要比上面的HDR设的大。

• 进行参数的读取:

  dmcam_param_item_t rparam;
  memset(&rparam,0,sizeof(rparam));
  rparam.param_id = PARAM_INTG_TIME;      //表示要读取的参数项为积分时间
  assert(dmcam_param_batch_get(dev,&rparam,1));   //调用API获取单个参数
  

其他模组参数的设置获取参照上面积分时间的设置获取。

滤波功能开启和关闭

• 像素校准，开启后用于深度数据的矫正:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_PIXEL_CALIB; //像素校准
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//开启像素校准
  dmcam_filter_disable(dev,DMCAM_FILTER_ID_PIXEL_CALIB); //关闭像素校准
  

• 深度滤波，开启后用于对深度数据滤波:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_MEDIAN;   //深度滤波
  witem.median_ksize = 3; //深度滤波通常设置值
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//开启深度滤波
  dmcam_filter_disable(dev,DMCAM_FILTER_ID_MEDIAN);       //关闭深度滤波
  

• 幅值滤波，开启后过滤质量差的点:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_AMP;      //最小幅值滤波
  witem.min_amp = 30;     //设置的最小幅值滤波的阈值
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//开启最小幅值滤波
  dmcam_filter_disable(dev,DMCAM_FILTER_ID_AMP);  //关闭最小幅值滤波
  

• HDR模式，设置一大一小两个积分时间，确保同一个模组在测量远近不同的物体时不会过曝:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_HDR;      //HDR 模式
  witem.intg.intg_3d = 100;       //HDR 模式时小的曝光时间
  witem.intg.intg_3dhdr = 700;  //HDR 模式时大的曝光时间
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u)); //开启HDR模式
  

Tip

开启HDR模式的另一种方法是可以直接通过设置HDR的曝光时间不为0， 如上面设置积分的样例，两种方法都需要HDR的积分时间设置的比另一个积分时间大。

• 自动积分时间，开启后根据被测物体的距离自动调整曝光时间大小:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_AUTO_INTG;        //自动曝光
  witem.sat_ratio = 5;//自动曝光时设置的值
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//开启自动曝光
  dmcam_filter_disable(dev,DMCAM_FILTER_ID_AUTO_INTG);    //关闭自动曝光
  

• 多模组串扰消除，开启消除或者减小多模组同时开启时的串扰:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_SYNC_DELAY;        //串扰延时
  witem.sync_delay = 0;   //延时时间设为0时为随机时间
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//开启串扰延时
  dmcam_filter_disable(dev,DMCAM_FILTER_ID_SYNC_DELAY);   //关闭串扰延时
  

• 运动模式0，帧格式要设置为2:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_SPORT_MODE;        //运动模式0
  dmcam_param_item_t wparam;
  uint32_t set_format = 2;        //表示要设置的帧格式为2
  memset(&wparam,0,sizeof(wparam));
  wparam.param_id = PARAM_FRAME_FORMAT;   //表示设置的参数为帧格式
  wparam.frame_format.format = set_format;        //设置的帧格式为2
  wparam.param_val_len = sizeof(set_format);
  assert(dmcam_param_batch_set(dev,&wparam,1));   //调用API进行帧格式参数设置
  witem.sport_mode = 0;   //设置运动模式为0
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//开启运动模式0
  dmcam_filter_disable(dev,DMCAM_FILTER_ID_SPORT_MODE);//关闭运动模式0
  

• 运动模式1，帧格式要设置为4:

  dmcam_filter_args_u witem;
  dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_SPORT_MODE;        //运动模式1
  dmcam_param_item_t wparam;
  uint32_t set_format = 4;        //表示要设置的帧格式为4
  memset(&wparam,0,sizeof(wparam));
  wparam.param_id = PARAM_FRAME_FORMAT;   //表示设置的参数为帧格式
  wparam.frame_format.format = set_format;        //设置的帧格式为4
  wparam.param_val_len = sizeof(set_format);
  assert(dmcam_param_batch_set(dev,&wparam,1));   //调用API进行帧格式参数设置
  witem.sport_mode = 1;   //设置运动模式为1
  dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//开启运动模式1
  //关闭运动模式1时，帧格式要先恢复到2
  set_format = 2;         //帧格式要恢复设置为2
  wparam.frame_format.format = set_format;        //设置的帧格式的值为2
  wparam.param_id = PARAM_FRAME_FORMAT;   //表示设置的参数为帧格式
  wparam.param_val_len = sizeof(set_format);
  assert(dmcam_param_batch_set(dev,&wparam,1));   //调用API进行帧格式参数设置2
  dmcam_filter_disable(dev,DMCAM_FILTER_ID_SPORT_MODE);//关闭运动模式1
  

录像生成与读取回放代码说明

在模组的算法评估中，评估前的一个主要准备工作就是录像文件的 获取，在SmartToFViewer中已经介绍如何获取通过SmartToFViewer进行 录像以及播放，这里介绍如何通过程序进行录像和读取录像文件，以及主要 API的介绍。

录像文件的设置

是否保存录像文件以及录像文件保存何种数据主要通过在程序中设置 dmcam_cap_cfg_t 的数据 结构，具体代码如下

 /* set capture config */
dmcam_cap_cfg_t cap_cfg = {
 .cache_frames_cnt = FRAME_BUF_FCNT, /* FRAME_BUF_FCNT frames can be cached in frame buffer*/
 .on_error = NULL,      /* No error callback */
 .on_frame_ready = NULL, /* No frame ready callback*/
 .en_save_replay = false, /* false save raw data stream to replay file */
 .en_save_dist_u16 = false, /* disable save dist stream into replay file */
 .en_save_gray_u16 = false, /* disable save gray stream into replay file*/
 .fname_replay = NULL, /* replay filename */
};

上述结构体参数中跟录像文件相关的主要是 en_save_replay en_save_dist_u16 en_save_gray_u16 这几个 参数，这几个参数的具体说明如下：

• 支持SmartToF SDK标准回放

  如果只要支持SmartToF SDK标准的回放，只要将上述的 en_save_replay 设置为 true,其他两个设置为 false.

• 兼容OpenNI工具的回放(如NiViewer)

  支持OpenNI工具的回放，如NiViewer的播放，这时需要将 en_save_replay 设置 false, en_save_dist_u16 和 en_save_gray_u16 都 设置为 true 或者任意一个设置 true,如果都设置为使能，则表示存储深度图和灰度图，其中一个使能则使能 en_save_dist_u16 为深度图， 使能 en_save_gray_u16 则表示保存的为灰度图。

录像文件的读取

SmartToF 的录像文件”xxx.oni”可以被模拟成标准的DMCAM设备,可以通过 dmcam_dev_open_by_uri 函数打开， 如文件名为”test.oni”,则读取文件名代码如下

dev = dmcam_dev_open_by_uri("test.oni")         //or file://test.oni

Caution

模拟dmcam设备和真实dmcam设备的由主要以下区别

• 模拟设备时，凡是SDK中基于原始DCS数据的处理均可调节和叠加，例如:深度滤波、最小幅值滤波、像素校准、镜头校准等。
• 模拟设备时，采集DCS原始数据的相关参数再模拟设备中调节是无效的，例如曝光时间，HDR功能等。

Python扩展

dmcam python扩展概述

python 扩展的安装

dmcam 提供了基于标准python wheel的扩展，该扩展可以通过pip直接进行安装，支持Windows和Linux的36位和64位环境，详见 Pypi项目主页 。安装命令为:

pip install -U dmcam

python API 说明

Python中的模组API和C库中 dmcam.h 中定义的API基本一一对应。

• python扩展中默认的包名为: dmcam 。 可通过 import 直接导入:

  import dmcam
  

• API命名映射关系(C->Python)： dmcam_xxxxx(…) -> dmcam.xxxxx(…) 。 例如 dmcam_dev_open 被映射为 dmcam.dev_open

• 结构体映射关系(C->Python): dmcam_xxxxx -> dmcam.xxxx() 。 结构体被映射为Python中的一个类。例如通过如下方式创建一个 dmcam_frame_info_t 结构体:

  finfo = dmcam.frame_info_t()
  

• NULL 被映射为 None 。例如:

  dmcam.init(None) # dmcam_init(NULL)
  

• 以下Python接口和C的API有差异，需要注意。

  dmcam.dev_list()

  Python中对C接口进行了简化，可以直接通过下列方式获取设备列表。其返回值为 dmcam.dev_t() 的列表。使用样例如下:

  devs = dmcam.dev_list()
  if devs is None:
     print(" No device found")
  else:
     print("found %d device" % len(devs))
     print(" Device URIs:")
     for i, d in enumerate(devs):
         print("[#%d]: %s" % (i, dmcam.dev_get_uri(d, 256)[0]))
  

  dmcam.param_batch_set(dev, dict)

  Python中对C接口进行了简化，直接传递一个`dict`, 而不必构造比较复杂的 dmcam_param_item_t 结构体及其长度参数。 使用样例如下:

  wparams = {
      dmcam.PARAM_FRAME_RATE: dmcam.param_val_u(),
      dmcam.PARAM_INTG_TIME: dmcam.param_val_u(),
  }
  wparams[dmcam.PARAM_FRAME_RATE].frame_rate.fps = 15
  wparams[dmcam.PARAM_INTG_TIME].intg.intg_us = 1000
  
  if not dmcam.param_batch_set(dev, wparams):
      print(" set parameter failed")
  

  dmcam.param_batch_get(dev, list)

  Python中对C接口进行了简化，直接传递需要获取参数的`list`, 而不必构造比较复杂的 dmcam_param_item_t 结构体及其长度参数。 使用样例如下:

  # get intg from device
  param_vals = dmcam.param_batch_get(dev, [dmcam.PARAM_INTG_TIME])  # type: list[dmcam.param_val_u]
  param_intg_us = param_vals[0].intg.intg_us
  

  dmcam.set_callback_on_frame_ready 和 dmcam.set_callback_on_error

  由于Python回调函数和C的差异。关于采集过程中回调函数的设置, 目前，python只支持通过上述两个接口分别设置 frame_ready 和 error 两种类型的回调。 不支持通过 dmcam.cap_config_set(dev, cap_cfg_t) 中的 cap_cg_t 进行回调函数的设置。 使用样例如下:

  def on_frame_rdy(dev, f):
      print("cap: idx=%d, num=%d" % (f.frame_fbpos, f.frame_count))
  
  def on_cap_err(dev, errnumber, errarg):
      print("caperr: %s" % dmcam.error_name(errnumber))
  
  cap_cfg = dmcam.cap_cfg_t()
  cap_cfg.cache_frames_cnt = 10  # frame buffer = 10 frames
  cap_cfg.on_frame_ready = None  # callback should be set by dmcam.cap_set_callback_on_frame_ready
  cap_cfg.on_cap_err = None      # callback should be set by dmcam.cap_set_callback_on_error
  cap_cfg.en_save_dist_u16 = False  # save dist into ONI file: which can be viewed in openni
  cap_cfg.en_save_gray_u16 = False  # save gray into ONI file: which can be viewed in openni
  cap_cfg.en_save_replay = False  # save raw into ONI file:  which can be simulated as DMCAM device
  cap_cfg.fname_replay = os.fsencode("replay_dist.oni")
  
  dmcam.cap_config_set(dev, cap_cfg)
  
  dmcam.cap_set_callback_on_frame_ready(dev, on_frame_rdy)
  dmcam.cap_set_callback_on_error(dev, on_cap_err)
  

下表列出了一些常用的API接口对比：

python调用接口对比

C库核心函数	python调用函数
dmcam_init	dmcam.init
dmcam_dev_list	dmcam.dev_list
dmcam_dev_open	dmcam.dev_open
dmcam_dev_close	dmcam.dev_close
dmcam_cap_config_set	dmcam.cap_config_set
dmcam_cap_set_callback_on_error	dmcam.cap_set_callback_on_error
dmcam_param_batch_set	dmcam.param_batch_set
dmcam_cap_get_frames	dmcam.cap_get_frames
dmcam_frame_get_distance	dmcam.frame_get_distance
dmcam_frame_get_gray	dmcam.frame_get_gray

python中参数设置和滤波相关

这里介绍在python中相关参数的设置读取和滤波功能的开启关闭。

python下参数设置和读取

• 单个参数设置，如设置帧格式:

  wparams_fmt = {dmcam.PARAM_FRAME_FORMAT: dmcam.param_val_u()}
  wparams_fmt[dmcam.PARAM_FRAME_FORMAT].frame_format.format = 2
  if not dmcam.param_batch_set(dev, wparams_fmt):
          log.error(" frame format failed")
  

• 单个参数读取，如读取积分时间:

  param_val = dmcam.param_batch_get(dev, [dmcam.PARAM_INTG_TIME])
  param_intg_us = param_val.intg.intg_us
  

python下滤波功能开启和关闭

• 像素校准，用于深度数据校正:

  drnu_param = dmcam.filter_args_u()
  drnu_param.case_idx = 0  #  12MHz calibaration
  dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_PIXEL_CALIB, drnu_param, 0)      #使能像素校准
  
  dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_PIXEL_CALIB)    #关闭像素校准
  

• 深度滤波，用于深度数据滤波:

  filter_param = dmcam.filter_args_u()
  filter_param.median_ksize = 3           # 深度滤波通常设置值
  dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_MEDIAN, filter_param, sys.getsizeof(filter_param))       #使能深度滤波
  
  dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_MEDIAN) #关闭深度滤波
  

• 幅值滤波，用于过滤质量差的点:

  amp_min_val = dmcam.filter_args_u()
  amp_min_val.min_amp = 30        #设置最小幅值滤波的阈值
  dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_AMP, amp_min_val, sys.getsizeof(amp_min_val))    #使能幅值滤波
  
  dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_AMP)             #关闭幅值滤波
  

• 自动积分时间，开启模组根据被测物自动调整曝光时间:

  intg_auto_arg = dmcam.filter_args_u()
  intg_auto_arg.sat_ration = 5    #自动曝光设置的值
  dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_AUTO_INTG, intg_auto_arg, sys.getsizeof(intg_auto_arg))  #开启自动曝光
  
  dmcam.filter_disable(dev,DMCAM_FILTER_ID_AUTO_INTG)             #关闭自动曝光
  

• 运动模式0，帧格式设置2:

  dmfilter = dmcam.filter_args_u()
  
  wparams_fmt = {dmcam.PARAM_FRAME_FORMAT: dmcam.param_val_u()}
  wparams_fmt[dmcam.PARAM_FRAME_FORMAT].frame_format.format = 2   #要设置帧格式为2
  dmcam.param_batch_set(dev, wparams_fmt)         #进行帧格式参数设置
  
  dmfilter.sport_mode = 0         #设置运动模式为0
  dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE, dmfilter, 0)         #开启运动模式0
  
  dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE)             #关闭运动模式0
  

• 运动模式1，帧格式设置4:

  dmfilter = dmcam.filter_args_u()
  
  wparams_fmt = {dmcam.PARAM_FRAME_FORMAT: dmcam.param_val_u()}
  wparams_fmt[dmcam.PARAM_FRAME_FORMAT].frame_format.format = 4 #要设置的帧格式为4
  dmcam.param_batch_set(dev, wparams_fmt)  #进行帧格式设置
  
  dmfilter.sport_mode = 1         #设置运动模式为1
  dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE, dmfilter, 1)         #开启运动模式1
  
  #关闭运动模式1时，帧格式要先恢复到2
  wparams_fmt = {dmcam.PARAM_FRAME_FORMAT: dmcam.param_val_u()}
  wparams_fmt[dmcam.PARAM_FRAME_FORMAT].frame_format.format = 2 #恢复帧格式为2
  dmcam.param_batch_set(dev, wparams_fmt)  #进行帧格式设置
  
  dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE)             #关闭运动模式1
  

C#扩展说明

dmcam C#扩展概述

dmcam 提供的C#扩展可方便基于.net C#的开发人员基于 SmartToF 相机进行快速的二次开发。本文档主要描述C#扩展的安装以及API和C的关联和区别。

C#扩展的安装

• Window
  • 支持的系统：
    • Windows 7/8/10 32bit/64bit
    • .Net framework >= 3.5
  • C#扩展动态库包括：
    • dmcam_csharp.dll: C# 扩展动态库，可导入C# 工程.
    • dmcam_csharp_adapter.dll: C# dmcam的扩展适库配
    • libdmcam.dll: dmcam core lib
  • 安装方式
    • 将以上dll加入PATH路径或复制到执行文件目录。
    • C# 工程中引用 dmcam_csharp.dll
• Linux
  • 支持的系统：
    • Linux 64bit (Ubuntu 14.04/16.04 tested)
    • Mono
  • C#扩展动态库包括：
    • dmcam_csharp.dll: C# 扩展动态库，可导入C# 工程.
    • dmcam_csharp_adapter.so: C# dmcam的扩展适配库
    • libdmcam.so: dmcam core lib
  • 安装方式
    • 设置 LD_LIBRAYR_PATH 包含上述so/dll目录, 或将动态库放入系统库目录下，例如： /usr/local/lib/

C# API 说明

C#中的模组API和C库中 dmcam.h 中定义的API基本一一对应。

• C#扩展默认的名字空间为: com.smarttof 。 可通过 using 方式导入:

  using com.smarttof;
  namespace sampleBasic {
  public class sampleBasic{
      public static void Main(string[] argv) {
          dmcam.init(null);
          /* ... */
          dmcam.uninit();
  }
  

• API命名映射关系(C->C#)： dmcam_xxxxx(…) -> dmcam.xxxxx(…) 。 例如 dmcam_dev_open 被映射为 dmcam.dev_open

• 结构体映射关系(C->C#): dmcam_xxxxx -> xxxx() 。 结构体被映射为C#中的一个类。例如通过如下方式创建一个 dmcam_frame_info_t 结构体:

  finfo = new frame_info_t()
  

• NULL 被映射为 null 。例如:

  dmcam.init(null) // dmcam_init(NULL)
  

• 以下C#接口和C的API有差异，需要注意。

  dmcam.dev_list()

  C#中通过如下方式获取设备列表。其返回值为就绪设备数量。使用样例如下:

  dmcamDevArray devs = new dmcamDevArray(16);
  int cnt = dmcam.dev_list(devs.cast(), 16);
  
  Console.Write("found {0} device\n", cnt);
  

  dmcam.param_batch_set()

  C#中设置参数相对C比较复杂一些, 需要构造param_item_t实例。 具体使用样例如下:

  param_item_t p_fps = new param_item_t();
  p_fps.param_id = dev_param_e.PARAM_FRAME_RATE;
  p_fps.param_val.frame_rate.fps = 15;
  
  param_item_t p_intg = new param_item_t();
  p_intg.param_id = dev_param_e.PARAM_INTG_TIME;
  p_intg.param_val.intg.intg_us = 1000;
  
  dmcamParamArray wparams = new dmcamParamArray(2);
  wparams.setitem(0, p_fps);
  wparams.setitem(1, p_intg);
  
  if (!dmcam.param_batch_set(dev, wparams.cast(), 2)) {
      Console.WriteLine(" set param failed\n");
  }
  

  dmcam.param_batch_get(dev, list)

  C#中设置参数相对C比较复杂一些, 需要构造param_item_t实例。 具体使用样例如下:

  param_item_t r_fps = new param_item_t();
  r_fps.param_id = dev_param_e.PARAM_FRAME_RATE;
  param_item_t r_intg = new param_item_t();
  r_intg.param_id = dev_param_e.PARAM_INTG_TIME;
  
  dmcamParamArray rparams = new dmcamParamArray(2);
  rparams.setitem(0, r_fps);
  rparams.setitem(1, r_intg);
  
  if (!dmcam.param_batch_get(dev, rparams.cast(), 2)) {
      Console.WriteLine(" get param failed\n");
  } else {
      Console.WriteLine("fps = {0}, intg = {1}",
              (int)rparams.getitem(0).param_val.frame_rate.fps,
              (int)rparams.getitem(1).param_val.intg.intg_us);
  }
  

  dmcam.set_callback_on_frame_ready 和 dmcam.set_callback_on_error

  C#扩展中不支持回调函数。采集时，可以参考如下设置：

  cap_cfg_t cfg = new cap_cfg_t();
  cfg.cache_frames_cnt = 10;
  cfg.on_error= null;
  cfg.on_frame_ready= null;
  cfg.en_save_replay= 0;
  cfg.en_save_dist_u16= 0;
  cfg.en_save_gray_u16= 0;
  cfg.fname_replay= null;
  
  dmcam.cap_config_set(dev, cfg);
  

Java 扩展说明

dmcam Java扩展概述

dmcam 提供的Java扩展可方便基于Java的开发人员基于 SmartToF 相机进行快速的二次开发。本文档主要描述Java扩展的安装以及API和C的关联和区别。

Java扩展的安装

• Window 平台
  • 支持的系统：
    • Windows 7/8/10 32bit/64bit
    • JDK >= 1.8
  • Java扩展动态库包括：
    • dmcam.jar: Java 扩展动态库，可导入Java 工程.
    • dmcam_java.dll: Java dmcam的扩展适配库
    • libdmcam.dll: dmcam core lib
  • 安装方式
    • 将以上dll加入PATH路径或复制到执行文件目录。
    • Java 工程中引用 dmcam.jar
• Linux
  • 支持的系统：
    • Linux 64bit (Ubuntu 14.04/16.04 tested)
    • Open JDK >= 7
  • Java扩展动态库包括：
    • dmcam.jar: Java 扩展动态库，可导入Java 工程.
    • libdmcam_java.so: Java dmcam的扩展适配库
    • libdmcam.so: dmcam core lib
  • 安装方式
    • 设置 LD_LIBRAYR_PATH 包含上述so/dll目录, 或将动态库放入系统库目录下，例如： /usr/local/lib/

Java API 说明

Java中的模组API和C库中 dmcam.h 中定义的API基本一一对应。

• Java扩展默认的名字空间为: com.smarttof.dmcam 。 可通过 import 方式导入:

  import com.smarttof.dmcam.*;
  
  public class sampleBasic{
      public static void main(String[] args) {
      dmcamDevArray devs = new dmcamDevArray(16);
              int cnt = dmcam.dev_list(devs.cast(), 16);
  }
  

• API命名映射关系(C->Java)： dmcam_xxxxx(…) -> dmcam.xxxxx(…) 。 例如 dmcam_dev_open 被映射为 dmcam.dev_open

• 结构体映射关系(C->Java): dmcam_xxxxx -> xxxx() 。 结构体被映射为Java中的一个类。例如通过如下方式创建一个 dmcam_frame_info_t 结构体:

  finfo = new frame_info_t()
  

  Caution

  Java扩展加载时候会自动调用 dmcam.init(null)， 释放的时候会自动调用 dmcam.uninit()。因此不必在程序中使用 dmcam.init() 和 dmcam.uninit()

• 访问结构体的成员变量： obj.field -> obj.getField()/setField 。 成员变量的访问需通过成员变量名对应的 get/set 方法进行。例如：

  cap_cfg_t cfg = new cap_cfg_t();
  cfg.setCache_frames_cnt(10);  // cfg.cache_frame_cnt = 10
  cfg.setOn_error(null);        // cfg.on_error = NULL
  /* ... */
  

• NULL 被映射为 null 。例如:

  dmcam.dev_open(null) // dmcam_dev_open(NULL)
  

• 以下Java接口和C的API有差异，需要注意。

  dmcam.dev_list()

  Java中通过如下方式获取设备列表。其返回值为就绪设备数量。使用样例如下:

  dmcamDevArray devs = new dmcamDevArray(16);
  int cnt = dmcam.dev_list(devs.cast(), 16);
  
  System.out.printf("found {0} device\n", cnt);
  

  dmcam.param_batch_set()

  Java中设置参数相对C比较复杂一些, 需要构造param_item_t实例。 具体使用样例如下:

  int pwr_percent = 100;
  param_item_t wparam = new param_item_t();
  dmcamParamArray wparams = new dmcamParamArray(1);
  
  wparam.setParam_id(dev_param_e.PARAM_ILLUM_POWER);
  wparam.getParam_val().getIllum_power().setPercent((short) pwr_percent);
  
  wparams.setitem(0, wparam);
  if (!dmcam.param_batch_set(dev, wparams.cast(), 1)) {
      System.out.printf(" set illu_power to %d %% failed\n", pwr_percent);
  }
  

  dmcam.param_batch_get(dev, list)

  Java中获取参数相对C比较复杂一些, 需要构造param_item_t实例。 具体使用样例如下:

  param_item_t r_fps = new param_item_t();
  r_fps.setParam_id(dev_param_e.PARAM_FRAME_RATE);
  param_item_t r_intg = new param_item_t();
  r_intg.setParam_id(dev_param_e.PARAM_INTG_TIME);
  
  dmcamParamArray rparams = new dmcamParamArray(2);
  rparams.setitem(0, r_fps);
  rparams.setitem(1, r_intg);
  
  if (dmcam.param_batch_get(dev, rparams.cast(), 2)) {
      System.out.printf("fps = %d, intg = %d",
              (int)rparams.getitem(0).getParam_val().getFrame_rate().getFps(),
              (int)rparams.getitem(1).getParam_val().getIntg().getIntg_us());
  }
  

  dmcam.set_callback_on_frame_ready 和 dmcam.set_callback_on_error

  Java扩展中不支持回调函数。采集时，可以参考如下设置：

  cap_cfg_t cfg = new cap_cfg_t();
  cfg.setCache_frames_cnt(10);
  cfg.setOn_error(null);
  cfg.setOn_frame_ready(null);
  cfg.setEn_save_replay((short)0);
  cfg.setEn_save_dist_u16((short)0);
  cfg.setEn_save_gray_u16((short)0);
  cfg.setFname_replay(null);
  
  dmcam.cap_config_set(dev, cfg);
  

Android扩展说明

dmcam Android扩展概述

dmcam 提供的Android扩展可方便Android开发人员基于 SmartToF 相机进行快速的二次开发,本文档主要描述Android扩展的使用以及API和C的关联和区别。

Android扩展的安装

• 支持的系统：
  • Android 4.4.2
• Android扩展动态库包括(ARM V5和ARM V7架构)
  • libdmcam.so: dmcam core lib
  • libdmcam_java.so: Java dmcam的扩展适配库
  • dmcam_android.jar: android 扩展动态库，可导入Android 工程
  • libusb1.0.so: usb设备驱动库
• 安装方式
  • 将以上的所有so库加入到Android工程下的libs
  • Android工程下再加入 dmcam.jar

Android API 说明

Android的app开发是基于Java语言的，所以Android中的主要API说明和Java中的 API说明基本一致，都和C库中的 dmcam.h 中定义的API基本一一对应。

• Android中扩展的默认名字空间为: com.smarttof.dmcam 。 可通过 import 方式导入：

  import com.smarttof.dmcam.*;
  
  public boolean devSetFrameRate(dev_t dev, int fps){
          if (dev == null)
                  return false;
  
          param_item_t wparam = new param_item_t();
          dmcamParamArray wparams = new dmcamParamArray(1);
  
          wparam.setParam_id(dev_param_e.PARAM_FRAME_RATE);
          wparam.getParam_val().getFrame_rate().setFps(fps);
  
          wparams.setitem(0, wparam);
          logUI("DMCAM",
                          String.format("set fps = %d\n", wparams.getitem(0)
                                          .getParam_val().getFrame_rate().getFps()));
          if (!dmcam.param_batch_set(dev, wparams.cast(), 1)) {
                  logUI("DMCAM", String.format(" set fps to %d failed\n", fps));
                  return false;
          }
          return true;
  }
  

• Android中的调用的API和Java中调用的API基本相同，映射关系都如: dmcam_xxxxx(…) -> dmcam.xxxxx(…) 。 例如 dmcam_dev_close 被映射为 dmcam.dev_close

• 结构体映射关系： dmcam_xxxxx -> xxxxx() 。结构体被映射为java中的一个类。例如通过如下方式创建一个 dmcam_param_item_t 结构体:

  wparam = new param_item_t();
  

  Caution

  在Android中打开设备时调用的API为 dmcam.dev_open_by_fd,不是其他环境下的 dmcam.dev_open

• 访问结构体的成员变量： obj.field -> obj.getField()/setField 。 成员变量的访问需通过成员变量名对应的 get/set 方法进行。例如：

  cap_cfg_t cfg = new cap_cfg_t();
  cfg.setCache_frames_cnt(10);  // cfg.cache_frame_cnt = 10
  cfg.setOn_error(null);        // cfg.on_error = NULL
  /* ... */
  

• NULL 被映射为 null 。例如:

  cfg.setOn_error(null);
  

• 以下是在Android中调用API与C中的一些区别，需要注意。

  dmcam.dev_open_by_fd()

  在Android下打开设备，需要调用专为Android设计的API dmcam.dev_open_by_fd(),具体使用样例如下：

  UsbDeviceConnection connection = usbManager.openDevice(usbDevice);
  fd = connection.getFileDescriptor();
  dev = dmcam.dev_open_by_fd(fd);
  

  dmcam.param_batch_set()

  需要构造param_item_t实例，具体样例如下:

  param_item_t wparam = new param_item_t();
      dmcamParamArray wparams = new dmcamParamArray(1);
  
      wparam.setParam_id(dev_param_e.PARAM_INTG_TIME);
      wparam.getParam_val().getIntg().setIntg_us(expoUs);
  
      wparams.setitem(0, wparam);
      if (!dmcam.param_batch_set(dev, wparams.cast(), 1)) {
                    logUI("DMCAM",
                                    String.format(" set exposure to %d us failed\n", expoUs));
                    return false;
      }
  

  dmcam.param_batch_get()

  获取参数也要构造实例，具体样例如下:

  param_item_t r_fps = new param_item_t();
  r_fps.setParam_id(dev_param_e.PARAM_FRAME_RATE);
  
  dmcamParamArray rparam = new dmcamParamArray(1);
  rparam.setitem(0,r_fps);
  
  if (dmcam.param_batch_get(dev, rparam.cast(), 1)) {
        logUI("DMCAM",
                        String.format(" get frame_rate %d fps\n",  (int)rparam.getitem(0).getParam_val().getFrame_rate().getFps()));
  }
  

  dmcam.set_callback_on_frame_ready 和 dmcam.set_callback_on_error

  Android扩展中不支持回调函数。采集时，可以参考如下设置：

  cap_cfg_t cfg = new cap_cfg_t();
  cfg.setCache_frames_cnt(10);
  cfg.setOn_error(null);
  cfg.setOn_frame_ready(null);
  cfg.setEn_save_replay((short)0);
  cfg.setEn_save_dist_u16((short)0);
  cfg.setEn_save_gray_u16((short)0);
  cfg.setFname_replay(null);
  
  dmcam.cap_config_set(dev, cfg);
  

ROS扩展

ROS 设计介绍

ROS概述

SDK ROS中提供的功能是在ROS的基础上对Dmcam API的封装，当我们调用ROS API的时候，会相应的通过dmcam的api来与模组进行交互。

ROS框架

ROS中的API与dmcam中的API对应关系图如下：

ROS API 说明

dmcam_ros发布的话题

1. /smarttof/image_dist

   使用命令	rosrun image_view image_view image:=/smarttof/image_dist
   功能描述	从image_dist发布的话题中获取深度数据

2. /smarttof/image_gray

   使用命令	rosrun image_view image_view image:=/smarttof/image_gray
   功能描述	从image_gray发布的话题中获取灰度数据

3. /smarttof/camera_info

   使用命令	rosrun image_view image_view image:=/smarttof/camera_info
   功能描述	从camera_info发布的话题中打印摄像头的信息

4. /smarttof/pointcloud

   使用命令	rosrun image_view image_view image:=/smarttof/pointcloud
   功能描述	从rviz中显示通过pointcloud发布的话题中的点云数据

dmcam_ros发布的服务

1. /smarttof/change_power

   使用命令	rosservice call /smarttof/change_power “power_value:<value>”
   功能描述	动态修改PARAM_ILLUM_POWER的值
   函数参数	value值默认为0

2. /smarttof/change_intg

   使用命令	rosservice call /smarttof/change_intg “intg_value:<value>”
   功能描述	动态修改PARAM_INTG_TIME的值，PARAM_INTG_TIME为积分时间
   函数参数	积分时间的value值范围为0-1500

3. /smarttof/change_mod_freq

   使用命令	rosservice call /smarttof/ change_mod_freq “mod_freq_value:<value>”
   功能描述	动态修改PARAM_MOD_FREQ的值，PARAM_MOD_FREQ为时钟频率
   函数参数	value值目前固定为12MHz

4. /smarttof/change_frame_rate

   使用命令	rosservice call /smarttof/ change_frame_rate “frame_rate_value:<value>”
   功能描述	动态修改PARAM_FRAME_RATE的值，PARAM_FRAME_RATE为帧率
   函数参数	vallue的范围为10-30

5. /smarttof/change_sync_delay

   使用命令	rosservice call /smarttof/ change_sync_delay “sync_delay_value:<value>”
   功能描述	动态修改PARAM_SYNC_DELAY的值，PARAM_SYNC_DELAY为同步延时时间
   函数参数	value值0为自动，1-10为指定范围

6. /smarttof/change_filter

   使用命令	rosservice call /smarttof/change_filter “filter_id: ‘<id>’filter_value:<value>”
   功能描述	打开filter_id中指定id值的滤波功能
   函数参数	filter_id中的id值可以设置为
   	DMCAM_FILTER_ID_LEN_CALIB //镜头校准
   	DMCAM_FILTER_ID_PIXEL_CALIB //像素校准
   	DMCAM_FILTER_ID_RESERVED //暂不支持
   	DMCAM_FILTER_ID_AMP //幅值滤波器
   	DMCAM_FILTER_ID_AUTO_INTG //积分时间
   	DMCAM_FILTER_ID_SYNC_DELAY //暂不支持
   	DMCAM_FILTER_ID_TEMP_MONITOR //暂不支持
   	DMCAM_FILTER_ID_HDR //HDR模式
   	DMCAM_FILTER_ID_OFFSET //距离偏移
   	DMCAM_FILTER_ID_SPORT_MODE //运动模式
   	DMCAM_FILTER_ID_SYS_CALIB //暂不支持
   	DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB //暂不支持
   	目前仅DMCAM_FILTER_ID_AMP中需要设置filter_value的value值，范围为0-100
   	其它filter_value中的value值默认为0即可

7. /smarttof/disable_filter

   使用命令	rosservice call /smarttof/disable_filter “filter_id: ‘<id>’”
   功能描述	关闭filter_id中id值的滤波功能
   函数参数	filter_id中的id值可以设置为
   	DMCAM_FILTER_ID_LEN_CALIB //镜头校准
   	DMCAM_FILTER_ID_PIXEL_CALIB //像素校准
   	DMCAM_FILTER_ID_RESERVED //暂不支持
   	DMCAM_FILTER_ID_AMP //幅值滤波器
   	DMCAM_FILTER_ID_AUTO_INTG //积分时间
   	DMCAM_FILTER_ID_SYNC_DELAY //暂不支持
   	DMCAM_FILTER_ID_TEMP_MONITOR //暂不支持
   	DMCAM_FILTER_ID_HDR //HDR模式
   	DMCAM_FILTER_ID_OFFSET //距离偏移
   	DMCAM_FILTER_ID_SPORT_MODE //运动模式
   	DMCAM_FILTER_ID_SYS_CALIB //暂不支持
   	DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB //暂不支持

OpenNI2扩展

OpenNI2驱动说明

为了支持OpenNI2中的框架实现对SmartToF模组的调用，SDK中提供了相应支持的驱动库samrttof.dll, 该驱动依循OpenNI2在OniDriverAPI.h中的定义，主要包括了DriverService、DriverBase、DeviceBase、StreamBase 这几个类别，smarttof.dll的驱动源码在SDK中一同发布。

SmartToF模组的设置

SmartToF中的所有相关的参数设置和滤波功能的使用都通过smarttofStream类中的setProperty函数执行，根据setProperty 中的propertyId进行对应得设置。

下表列出了property的属性ID:

功能ID	说明
PROPERTY_ID_PARAM_SET	模组参数设置ID
PROPERTY_ID_PARAM_GET	模组参数获取ID
PROPERTY_ID_FILTER_LEN_CALIB_ENABLE	镜头滤波使能
PROPERTY_ID_FILTER_LEN_CALIB_DISABLE	镜头滤波关闭
PROPERTY_ID_FILTER_PIXEL_CALIB_ENABLE	像素滤波使能
PROPERTY_ID_FILTER_PIXEL_CALIB_DISABLE	像素滤波关闭
PROPERTY_ID_FILTER_AMP_CALIB_ENABLE	幅值滤波使能
PROPERTY_ID_FILTER_AMP_CALIB_DISABLE	幅值滤波关闭
PROPERTY_ID_FILTER_AUTO_INTG_ENABLE	自动曝光使能
PROPERTY_ID_FILTER_AUTO_INTG_DISABLE	自动曝光关闭
PROPERTY_ID_FILTER_TEMP_MONITOR_ENABLE	温度监控使能
PROPERTY_ID_FILTER_TEMP_MONITOR_DISABLE	温度监控关闭
PROPERTY_ID_FILTER_HDR_ENABLE	HDR功能使能
PROPERTY_ID_FILTER_HDR_DISABLE	HDR功能关闭

OpenNI2下模组设置示例代码

OpenNI2下可以通过setProperty将以上列表中的属性ID设置到SmartToF模组中去， 具体设置的代码示例可以参考下面的设置积分时间代码:

dmcam_param_item_t wparam;  //setting integration time
wparam.param_id = PARAM_INTG_TIME;
wparam.param_val.intg.intg_us = intg;
wparam.param_val_len = sizeof(wparam.param_val.intg.intg_us);
depth.setProperty(PROPERTY_ID_PARAM_SET, (void *)&wparam, sizeof(wparam));

获取模组设置的代码如下:

dmcam_param_item_t rparam;  //getting framerate
rparam.param_id = PARAM_FRAME_RATE;
rparam.param_val_len = sizeof(rparam.param_val.frame_rate.fps);
depth.getProperty(PROPERTY_ID_PARAM_GET, &rparam);
printf("frame rate:%d fps\n", rparam.param_val.frame_rate.fps);