Welcome to SmartToF SDK User Guide!¶

Introduction¶

SDK Overview¶

Welcome to the SDK document of the SmartToF module. Through this document, you can :

Know SDK Components

Use SmartToF series modules

Use the tools in the SDK

Secondary develop based on SmartToF module

SmartToF series module introduction¶

SmartToF TC(QVGA) and TS(VGA) series modules are developed by Data Miracle which using industry-leading sensor chip, with high measurement accuracy, Strong anti-interference ability, compact appearance and other advantages. The module can be used in emerging technologies such as accurate people flow statistics, logistics storage, gesture recognition, robot obstacle avoidance, and vehicle control.

SDK supported modules table:

Contents	TC-E2	TC-E3	TC-E4	TS-S3
Hardware version	30	30	30	30
Software version	>=172	>=172	>=168	>=206
Agent&Bootloader version	>=148	>=148	>=148	>=101

SmarToF SDK Introduction¶

SmartToF SDK is a software toolkit developed with SmartToF series modules，supports platforms such as windows、linux、Android and so on，SDK’s components like follows：

Core Library Main Function Specification¶

Sensor control & Depth calculation	Sensor register read/write	Supported
	Depth mode	High precision mode (8xQuads, for TC-S series) Normal mode (4xQuads) Motion reduction mode (2xQuads)
	Modulation frequency	TC-S series: single frequency mode: 10~100MHz in 1MHz resolution dual frequency mode: any frequency pair between 10~100MHz TC-E series: Fixed frequency 12MHz, 24MHz, 36MHz
	Exposure time	TC-S series : Single exposure time: 1~1000us in 1us resolution Dual exposure time(HDR): any exposure time beween 1~1000us TC-E series: Single exposure time: 1~1500us in 1us resolution Dual exposure time(HDR): any exposure time beween 1~1500us
	ROI	Supported
	Binning	TC-S series 1x1,2x2,4x4,8x8; TC-E series:1x1,2x2,2x4
	compensation	Global linear compensation
		non-uniform pixel compensation
		Cyclical error compensation
		Frequency drift compensation
		Temperature compensation
		Lens calibration
		Ambient light compensation
3D image processing	Spatial filters	Fly noise filter
		Fill hole filter
		Fast bilateral filter
		Fast median filter
		Confidence/Amplitude filter
	Temporal filters	hysteresis noise filter
	Temporal filters	IIR low pass filter
	Pesudo-color convertion	60+ color palette
		Depth image to RGB24/BGR24/RGBA32/BGRA32
		IR image to RGB24/GRAY8
		Histogram-equalization on depth and IR Pesudo-color image
	Compression& decompression	support lossless compression/decompression
	Point cloud	Support depth image to point colud convertion with each point in (x,y,z), (x,y,z,d), (x,y,z,IR)
Recording & replaying	Recoding	Support OpenNI compatible ONI file format.
		Support record all parameter setting during capturing
		Support embedded calibration data inside record file
	Replaying	Replay file is emulated as SmartTOF Virtual device. All image processing function can be changed on-the-fly using replay files

Multiple platform & Multiple dev language¶

All language extensions have 100% C-API coverage
All tools and samples are cross-platform

High performance¶

Key algorithms are optimized under PC, ARM and DSP platforms with SSE2, ARM-NEON and DSP instructions.

SmarToFViewer Introduction¶

Use case
- Camera evaluation
- Application scenario recording
Main Function
- Depth/IR/PCL image visualization
- Recording and replay
- Camera parameter adjusting
  - ROI&BINNING
  - HDR
  - FPS&Frequency
- Image filter enable/disable
- 3D pointcloud view

Commandline tool Introduction¶

Use case
- Camera diagnostic、testing、benchmarking、calibration
- Manufacturing auto testing
Main Function
- Device enumeration
- Device firmware upgrade
- Device parameter set/get
- Low-level register read/write
- Depth/IR/PCL image capturing and saving
Working mode
- Shell argument mode
- Shell interactive mode
- Scripts mode

SDK document introduction¶

This SDK document description is continuously written, corrected, and modified by Digital Trace staff. The document consists of four main sections. The content of each part is allocated according to the actual situation. The content of each section is relatively intuitive.

Introduction introduced overview of SmartToF module and SDK, list the SDK’s related resources including SmartToF modules Basic development process
Quick Start provided methods on how to setup develop platform and usage of some tools.
Tutorial shows usage of SDK samples in different platform, including some pictures, codes in sample is helpful for secondary development.
Reference provided introduction of C API lib、python、Java、C#、ros and Android extension，if you want to get more detailed information during secondary development, please read this chapter carefully.

Basic development process¶

Development process diagram¶

In the secondary development of Smartof modules, the general development flowchart is as follows:

Development process description¶

Module basic performance evaluation¶

After obtaining the SmartToF module, use the SmartToFViewer tool provided in the tools directory of the SDK to display the measured object in real time. According to the distance and movement of the measured object during display, adjust related parameters on SmartToFViewer, and evaluate the imaging quality and depth distance accuracy of the module through the display effect evaluation module. If you want to evaluate the point cloud effect of the module, you need to enable SmartToF_PCLViewer at the same time you enable SmartToFViewer.

Module sample integrated development¶

After using SmartToFViewer， you will know some parameters and filters influence on module’s image display，you can follow instruduction in Tutorial ,read and run examples provided by SDK, Master the main steps of using the SDK under the development platform and language environment you want to use, refer to the sample code, and the relevant API in the code is detailed in chapter Core API , write and integrate your own test samples to collect and display module data.

Users using C/C++ refer to samples in C/C++ .
Users using Python refer to samples in Python .
Users using Java refer to samples in Java .
Users using C# refer to samples in C# .

Module algorithm evaluation development¶

In order to use smarttof module for algorithm development conveniently and quickly, SmartToF SDK provides a complete set of development process descriptions， Dividing the entire development process into :

Get video file

Offline algorithm evaluation

Online algorithm evaluation

Practical platform application

The detailed description is as follows:

Get Video file¶

The basis of the algorithm evaluation is based on complete and accurate data. In the case that there is no module in the previous period for data collection or if the collected image data is not correct, It can be obtained through the smarttofviewer’s recording function in advance, or through the rx command of the dmcam-cli tool, or directly from the digital trace company FAE, and then downloaded through the Data Miracle company website (the download address will be announced later). How to use Smarttofviewer’s video function to record video files reference tools instruduction in SmartToFViewer video function , using dmcam-cli tools’s “rx” command save video please run help rx command to get help.

Offline algorithm evaluation¶

After obtaining the video file, open the video file by calling the interface dmcam_dev_open_by_uri and then Then load and run the evaluation algorithm on the obtained video file. Compare the actual effect of the algorithm after it is added. If you want to filter the original depth data, you can add commonly used median or bilateral filtering, or you can use improved depth filtering, and evaluate the effect of the algorithm by the image effects before and after filtering. This offline algorithm evaluation solves some users’ normal work of algorithm evaluation and development when there is no module or the module data cannot be collected normally.

Online algorithm evaluation¶

When performing online algorithm evaluation, you need to open the actual SmartToF device. The API for opening the device is no longer the same as the API for opening the recording file, using dmcam_dev_open interface. After the previous algorithm evaluation of the offline video file, the effect of the evaluation algorithm is basically determined, and it is determined whether the evaluation algorithm meets the design requirements. This is followed by a dynamic actual algorithm evaluation on the module. While adding the offline evaluation algorithm processing, collect real-time data of the SmartToF module, and observe and evaluate the actual effect of the algorithm on the PC in real time. Finally, determine whether the algorithm used on SmartToF meets the requirements.

Tip

The main difference between the offline algorithm evaluation and the online algorithm evaluation is that the opened devices are different. The offline algorithm evaluation opens the device simulated by the video file, and the online algorithm evaluation opens the real module device. The calling API when opening the device is also different. The interface called when the offline algorithm opens the recording file is dmcam_dev_open_by_uri , Online algorithm develop opened a real device using dmcam_dev_open interface。

Practical platform application¶

Previous offline algorithm evaluation and online algorithm evaluation were mainly based on the PC platform. In practical applications, SmartToF modules may need to run on various embedded platforms. At this time, it is necessary to run the corresponding SmartToF library on the corresponding platform, at the same time, transplant the previous evaluation algorithm to the corresponding platform, and optimize the algorithm according to the platform. Finally, application development is performed on the actual embedded platform.

Quick start¶

SmartToF SDK Configuration requirements¶

Minimum configuration¶

Minimum configuration for x86 or x64 platforms¶
CPU	Intel Atom X5-8350
RAM	2GB
Interface	USB2.0

Minimum configuration for ARM platform¶
CPU	Cortex-A7
RAM	256M DDR3 RAM
Interface	USB2.0

Recommended configuration¶

Recommended configuration for x86 or x64 platforms¶
CPU	Intel Core i5
RAM	4GB
Interface	USB2.0

Recommended configuration for ARM¶
CPU	Cortex-A53
RAM	512M DDR3 RAM
Interface	USB2.0

SmartToF SDK operational requirements¶

Windows¶
Interface	USB2.0
OS	Windows 7 / 10(32bit and 64bit)
Compiler	Visual Studio 2013 and above
programming language	C/C++,C#,Java,Python

Linux¶
Interface	USB2.0
OS	Ubuntu 14.04 / 18.04(64 bit)
Compiler	GCC 4.8 and above
programming language	C/C++,C#,Java,Python

Module connection¶

Module connection under windows¶

When connecting and using the module under Windows, you need to install the module’s USB driver. The general installation process of the module is as follows：

Module preparation¶

Module kit includes TC/TS series module, USB cable and power supply (some models do not require power supply) as shown in Table 2, take TC series module as an example:

Table2 Module kit¶
1	TC series module
2	Micro USB cable
3	12V power adapter

Module installation¶

In the Windows system, run the smarttof_usb_install.exe program in the windows / drivers directory of the SDK to install the driver. The normal installation process is shown in the following figure.

After the driver is installed normally, connect the USB cable to the module and PC, and open the device manager to see the device name of the module, as shown in the figure below.

Module connection under linux¶

libusb installation¶

If you using linux release version ubuntu14 and ubuntu16, libusb was installed by default.If you need install libusb, remove libusb installed, and type the following command

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

Then run the smartTOFViewer tool in the tool / SmartTofViewer directory under the SDK directory to check whether the device is connected properly. The normal connection displays the device number as shown in the figure below.

Change libusb permissions¶

Add a new usb rule for module to avoid input password every time open module, run setup.sh scripts in “linux/lib” folder, result like follows:

Preliminary use of tools¶

The SDK provides the SmartToFViewer display evaluation tool and the dmcam-cli command line tool, which are respectively located in the tools directory in the SDK. SmartToFViewer also provides smartTOF_PCLViewer pointcloud display tool.

SmartToFViewer usage¶

SmartToFViewer can be directly used to evaluate the image of the measured object, and set the module related parameters through the UI. View the module’s related information and working status, SmartToFViewer can be used when the module usb is installed normally.

SmartToFViewer interface introduction¶

The overall preview after SmartToFViewer is opened is as follows. SmartToFViewer mainly includes an image display area, Basic parameter area, advanced parameter area, filter setting area, information area, and opening and closing of the module:

SmartToFViewer acquisition display¶

Double-click to run the SmartToFViewer tool, click to select the device. If multiple modules are connected at the same time, the device list will be listed. Left click to select the device you want to use and click the OK button in the picture, as shown below：

After selecting the device, click the Start button to capture the image for display. The default view model is depth map-color coding, as shown in the figure below, which shows the depth and distance information of the object. Drag or click the relevant button on the interface to enable the acquisition parameter setting and filtering function of the module. For details, please refer to the detailed description of SmartToFViewer in the detailed description.

SmartToFViewer video function¶

SmartToFViewer support recording function，recorded video files can be used as image data for offline algorithm evaluation. After the Viewer is opened, select the device, click the Recorder setting tab in the figure, and check the Recording Enable to select the storage location of the recording file, as shown below:

Caution

There is also an OpenNI compatible option under the Recording Settings tab. The function description of this option is as follows:

In the enabled mode, if NiViewer is used to play the video file, the depth map and grayscale map are output
In the disabled mode, when playing a video file with NiViewer, the original image of 4DCS (raw data of the tof chip) is output.

Click Stop on SmartToFViewer to stop recording and save the oni format video file to the location you just selected.

SmartToFViewer plays video files¶

Open SmartToFViewer, click the `` Open Replay `` button, select the saved video file, The USB device number in the lower corner becomes the file name of the video, as shown below:

If you want to turn on point clouds, enable the “PCL” checkbox on “SmartTofVeiw” as shown below:

dmcam-cli command line tool usage¶

The dmcam-cli tool in the SDK is convenient for users to diagnose and test during secondary development. It mainly includes the following functions：

Obtaining device information
Hardware parameter setting
Data acquisition and storage
Firmware update

dmcam-cli basic information acquisition¶

dmcam-cli usually interacts with devices through command line parameter mode, script file mode, and interactive mode. The following figure shows the command line parameter mode and interactive mode to obtain device information.：

Please refer to dmcam-cli for other specific functions Reference

Firmware upgrade overview¶

Module firmware refers to the main control MCU running in the module, which mainly controls the acquisition method of the TOF chip and obtains the original data of the TOF chip. In order to cope with the new features of the new SDK and modify the bugs of the original version, the module firmware needs to be upgraded.

Firmware upgrade instructions¶

Upgrade package¶

Each version of the SDK includes a firmware folder, which contains two folders, windows and linux. According to the corresponding system during the upgrade, enter the corresponding folder. The firmware folder is shown below：

Upgrade method¶

Enter the corresponding system upgrade package directory, such as running fw_upgrade_win.bat script under windows, under linux Then run the fw_upgrade_linux.sh script, such as the screenshot of the upgrade under windows as shown below：

Upgrade verification¶

After the upgrade, you need to confirm whether the upgrade was successful. Open the SmartToF Viewer in the SDK to check the upgraded firmware version.

In addition to SmartToF Viewer, you can also run the dmcam-cli tool, and enter interactive mode by default. Enter the info command and press Enter to display the module information. Check whether the version number after the MCU Firmware Version is the firmware that needs to be upgraded. Version number, as shown below：

Others¶

Upgrade Document Revision History¶

Table1 Firmware Upgrade Document Revision History¶
Version	Date	description
0.1	3/15/2018	First edition
1.0	11/3/2018	Take the firmware upgrade package as an illustration

C/C++¶

The tutorial section mainly shows the running results of each sample in different development languages and other environments, and how to run each sample.

Image Acquisition¶

The SDK provides four basic examples: basic acquisition, parameter setting, filter enable, and saving video files. Basically covers some interfaces commonly used in the secondary development of modules Core API, can be used as a reference for users when developing.

Run sample_capture_frames to collect image sample program as shown in figure:

In the sample, the basic settings of the module are set before acquisition, and then the acquisition is started, and 10 frames are acquired each time, and then the depth and grayscale calculations are performed. The total number of frames is set to 100 frames, and the acquisition is stopped after the acquisition is completed. The capture sample includes dmcam_cap_config_set for configuration before collection，dmcam_cap_start，dmcam_cap_get_frames ,dmcam_frame_get_distance interfaces and so on.

Parameter settings¶

The sample_set_param example mainly shows the general method for setting module parameters. The main parameters of the module are integration time, acquisition frame rate, modulation frequency, etc. The sample program results are shown in the figure:

Module parameter related interfaces include the setting and acquisition of module parameters. Parameter settings can be set after calling the dmcam_dev_open interface to open the device. Parameter settings are called by calling dmcam_param_batch_set, and parameters are obtained by calling dmcam_param_batch_get.

Filter¶

The SDK includes a variety of filtering functions such as amplitude filtering, depth filtering, automatic exposure, and motion mode for the module. The sample_filter sample mainly shows the related enable settings and disable settings of the filter function of the module.

The program running the sample_filter sample is shown in Figure

The main API for calling the filtering function is dmcam_filter_enable, When setting the filter function, some need set the parameter value, refer to Parameters and filter module parameter and filter type description and code example.

Video¶

The SDK provides a video recording function. You can use the saved video file to carry out previous algorithm development. The format of the saved video file is ONI format. When you use config to perform the settings before acquisition, specify the name of the saved video file.

run sample_save_replay to save the video sample program as shown in the figure:

Running the sample_save_replay will generate a file named sample_replay.oni，it can be played back through the SmartToFViewer tool. For detailed usage of the SmartToFViewer tool, please refer to SmartToFViewer Instructions.

Building the sample¶

Generate vs progect under windows¶

Generate vs progect under windows

create vsbuild folder under windows/samples/c
using command line tools or using mingw under msys2,enter vsbuild and using cmake command to generate VS project，detail command like follows:
```
cd vsbuild

cmake .. -G "Visual Studio 12 2013"  //according to your VS version
```

The generated VS project is shown below

Open dmcam_c_sample.sln, compile to generate C excutable program.

VS project and version show as table 3-1：

Table3-1 VS version¶

Version

Number

Visual Studio 2005

8

Visual Studio 2008

9

Visual Studio 2010

10

Visual Studio 2012

11

Visual Studio 2013

12

Visual Studio 2015

14

Visual Studio 2017

15

After successfully generating the VS project, use VS to open the project and generate the solution. The following figure shows the sample_capture_frames program after generating the solution

Generate excutable program under windows

Create build folder under windowssamplesc
Enter build folder and generate excutable file via cmake，detail’s command are as follows:
```
cd build

cmake .. -G "MSYS Makefiles"

make -j
```
Run excutable via double click it

Run in linux

Copy libdmcam.so to /usr/lib
Open terminal，install cmake:
```
sudo apt-get install cmake
```
Create build folder under linux/sample/c，and run the following commands:
```
cd build
cmake .. -G "Unix Makefiles"
make -j
```

After generating the executable file, the executable file shown in the following figure is displayed under the build folder:

Run the excutable program

C++ Sample process¶

C++ Samples please refer to C Samples.

Python¶

Simple capture sample¶

The SDK provides samples developed based on python, including basic acquisition, basic parameter settings, and image data acquisition and display, covering some of the secondary development of modules under python Core API, can be used as Basic reference when developing for users.

Run the sample_basic.py acquisition program for python:

python sampe_basic.py

The results of running the basic acquisition program are shown below.

Parameter setting¶

The sample_param.py example mainly shows the general method for setting module parameters. Including setting and reading of module parameters.

Run sample_param.py program:

python sample_param.py

The result of running the parameter setting program is shown below:

UI display¶

The SDK provides sample display examples of using pygame and other modules to collect images under python, such as sample_gui_pygame.py.

Run sample_gui_pygame.py:

python sample_gui_pygame.py

The results of the program run as shown below:

Runnning example¶

To run the Python samples, you need to install the dmcam package corresponding to the Python version, numpy, matplotlib, pygame, Pyqtgraph and other packages. The dmcam package is the driver package related to the SmartToF module device, which has been uploaded to the pypi website.

Install the packages needed to run the python samples¶

Installation of dmcam library
The dmcam package has been uploaded to the WHL package corresponding to each version of Python to the Pypi website since 1.60，to update and install the latest dmcam package, the installation command is as follows:
pip install -U dmcam
If you want to install the specified version of dmcam, you need to add the version number, for example, the installed version number is 1.57.7:
pip install dmcam==1.57.7
The result of installing the dmcam package is as follows：
Installation of other libraries that the sample depends on
Install numpy、matplotlib、pygame、PyQt5、pyqtgraph, can be installed by:
pip install -r requirement.txt

Note

Installing PyQt5 in python2.7 or python3.4 environment may cause failure. You can install PyQt4 instead.

After the Python related packages are installed, you can run the specified samples

C#¶

Image Acquisition¶

The SDK provides two basic display examples, sampleBasic and sampleBasicUi, showing how to use the SDK’s related interface to obtain module data in C#.

The result of running the sample_basic sample is shown below:

UI display¶

sampleBasicUi example shows that when the acquisition interface in the SDK is called for acquisition, the image is displayed at the same time. The running result and the GUI interface are as shown below.

Compile and generate¶

Windows platform¶

From the command line, go to the windows samples csharp directory and run the following command. <BUILD_TYPE> can be Release or Debug:

mkdir build
cd build
cmake .. -G "Visual Studio 12 2013"         //VS version installed
cd ..
cmake --build ./build --config <BUILD_TYPE>

Generated two sample_basic.exe and sample_ui.exe executable files under the build file, as shown below:

Linux platform¶

Compiling C# extensions under linux requires installing mono
```
sudo apt-get install mono-complete
```

Go to the linux/sample/chsarp directory and run the following command:

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

Generated two sample_basic.exe and sample_ui.exe executable files under the build file, as shown below:

Java¶

Image Acquisition¶

The SDK provides two basic display examples, basic and basicUi, showing how to use the SDK’s related interface to obtain module data in Java.

The result of running the basic sample is shown below:

UI display¶

Java basicUi image acquisition and display example shows that when using Java to call the acquisition interface in the SDK for acquisition, the image is displayed at the same time. The result of the sample operation is shown below:

Compile and generate¶

Windows platform¶

Copy the java package corresponding to the number of bits in the windows/java directory in the SDK and the corresponding libdmcam.dll in windows lib to the windows / samples / java directory

Run javac command to compile:

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

After compiling successfully, the corresponding class file is generated under windows/samples/java/com/smarttof/dmcam/sample.

Run java command in windows/samples/java directory:

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

Run java command in windows/samples/java directory:

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

linux platform¶

Install openjdk-7-jdk for java extension under linux:
```
sudo apt-get install openjdk-7-jdk
```
Copy the corresponding number of java packages in the linux/java directory in the SDK to the linux/samples/java directory.

Run javac command to compile:

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

    After compiling successfully, the corresponding class files are generated under linux/samples/java/com/smarttof/dmcam/sample.

Run java in the linux/samples/java directory. If some dynamic libraries are not found, you need to specify LD_LIBRARY_PATH:

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

Run java in the linux/samples/java directory. If some dynamic libraries are not found, you need to specify LD_LIBRARY_PATH:

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

ROS¶

The ROS package mainly includes the ros system’s encapsulation of the smarttof API. Divided into dmcam_ros and cloud_viewer packages, dmcam_ros package used to collect and display depth and grayscale data and dynamically modify parameters. Cloud_viewer is used to display point cloud data.

ROS depth map display¶

Open ROS environment:
```
roscore&
```
Enter the folder where ros is located to initialize the environment variables:
```
source ./devel/setup.bash
```
Run the launch file:
```
roslaunch dmcam_ros start.launch
```

Show depth map command:

rosrun image_view image_view image:=/smarttof/image_dist

The depth image is shown below：

ROS grayscale display¶

Open ROS environment:
```
roscore&
```
Enter the folder where ros package is located to initialize the environment variables:
```
source ./devel/setup.bash
```
Run the launch file:
```
roslaunch dmcam_ros start.launch
```

Show grayscale command:

rosrun image_view image_view image:=/smarttof/image_gray

The grayscale image is shown below：

ROS pointcloud display¶

cloud_viewer is a simple example of using smarttof ros to display pointcloud data, this sample simply implements how to get pointcloud data from the pointcloud topic published by smarttof ros and display it

Open ROS environment:
```
roscore&
```
Enter the folder where ros package is located to initialize the environment variables:
```
source ./devel/setup.sh
```
Run the launch file:
```
roslaunch cloud_viewer start.launch
```
Display pointcloud image
Use the wheel in the middle of the mouse and the left mouse button to adjust the point cloud to display the image. The final effect is shown in the figure.

Environment setup using modules in ROS environment¶

Install ros under Ubuntu¶

The process of installing ros under ubuntu is as follows：

Open a command line terminal, enter the ros folder in the SDK, and run the following command:
```
sudo chmod 755 install_ros.sh
./install_ros.sh
```
The installation selection version prompt appears as shown in the figure below. Manually enter the version name and press Enter to start the installation. Indigo is recommended for Ubuntu 14.04, and Kinetic is recommended for Ubuntu 16.04.

ROS environment configuration¶

The environment variables of the installed version need to be initialized before each use of the ROS system， Take Kinetic as an example， Kinetic is installed in the /opt/ros/kinetic/ by default. The environment variable configuration file location is /opt/ros/kinetic/setup.bash. You need to initialize the ros environment before each use. The command is as follows:

source /opt/ros/kinetic/setup.bash

In order to simplify the process of configuring environment variables, you can choose to place the configuration of environment variables in the ~/.bashrc file， This way, every time you open a new terminal, the ROS environment variables will be automatically configured.:

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

SmartToF ros package compilation¶

Enter the directory where ros is located, and use the ls command to view the files in the directory as follows:
```
install_ros.sh  Makefile  src
```

Use catkin_make(The steps used by catkin_make are implemented in the Makefile, you can also use the make command to compile):

source /opt/ros/kinetic/setup.bash(This step is required without initializing the environment in bashrc)
catkin_make

After the compilation is complete, the devel and build directories will be generated. Use the ls command to view the generated files:
```
build  devel  install_ros.sh  Makefile  src
```
Initialize environment variables in devel folder:
```
source devel/setup.bash
```

Use of ROS rviz tool¶

rviz is a graphical tool that comes with ros, which can conveniently perform graphical operations on the ros program. The overall interface is shown in the figure below:

The interface is mainly divided into a display setting area on the left, a large display area in the middle, and a viewing angle setting area on the right. At the top are several tools related to navigation. The bottom is the display of some data related to ros status.

rviz preparation before use¶

Open ROS environment:
```
Roscore&
```
Enter the folder where ros package is located to initialize the environment variables:
```
source ./devel/setup.bash
```
Run the launch file:
```
roslaunch dmcam_ros start.launch
```

rviz display depth image¶

Open a terminal and run rviz:
```
rviz
```
Select add, select Image under image_dist in the By topic, and finally confirm the addition, as shown in the figure below:：
The display effect is shown in the following figure:

rviz display pointcloud image¶

Open a terminal and run rviz:
```
rviz
```
Select add, select PointCloud2 under pointcloud in byTopic, and finally confirm the addition.
In the displays area in the upper left corner of rviz, modify the value of the FixedFrame variable under GlobalOptions to dmcam_ros. The point cloud is displayed as shown below.

Filter setting under ROS¶

Use of filtering functions¶

Enable a filter function，for example DMCAM_FILTER_ID_AUTO_INTG:

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

Disable a filter function，如DMCAM_FILTER_ID_AUTO_INTG:

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

For detailed introduction of ROS API, please go to ROS extension chapter.

Openni2¶

Niviewer image display¶

SmartToF SDK currently provides related driver libraries for Windows platforms supporting OpenNI2， Copy libdmcam.dll、smarttof.dll、smarttof.lib、smarttof.pdb under SDK’s openni2 folder to OpenNI2 install Tools/OpenNI2/Drivers folder，as shown below:

Go to the Tools directory, the administrator runs the NiViewer.exe program under Tools, and the results are shown below:

Simple capture example¶

SmartToF SDK also provides basic acquisition and parameter setting examples using OpenNI：

Enter Smarttof_OpenNI_Sample/Smarttof_OpenNI_Sample under the openni2 directory in the SDK, and open the VS project as shown below:

Compile and generate main.cpp, and run the result after the generation as shown below:

Parameter settings¶

Change the Openni2 sample to sample_set_param.cpp and add it to the compile. The result after compiling and running is shown below

Android¶

APP instructions¶

The Android / tools directory in the SDK provides the Android apk installation package and the Eclipse project that generates the apk. After using your Android phone to install the APK, connect the module and run app to see the image.

Software Installation

When installing the apk, the phone’s system requires Android 4.2.3 and above, and you choose to allow USB permissions during installation.
Hardware connection

When the mobile phone is connected to the module, in addition to the mobile phone and the module, it is usually necessary to prepare an OTG cable for the mobile phone. Connect one end to the mobile phone, and connect the end of the module to the PC to the OTG cable. Mobile phone and OTG as shown below:
Run the sample

Open SmartToFViewer software on the phone, the interface is as shown below:

Click the start acquisition button to perform the acquisition demo. The acquisition display is as shown below:

Tool’s instructions¶

SmartToFViewer Instructions¶

Overview¶

SmartToFViewer is a visualization tool that can be used to quickly evaluate the effects of the module, familiarize the effects of different parameters on the display effect, and determine the best parameters to assist the actual development and use.

The main support functions are as follows:

Device selection, on, off, etc.

Display depth map, grayscale map, etc.

Display pointcloud map with PCLViewer

View the distance between the object and the module camera

View module information and working status

Set common parameters

Set filtering characteristics

Set sport mode

Video and playback video

Graphical interface introduction¶

The overall preview after SmartToFViewer is opened is as follows， SmartToFViewer interface mainly includes:

Capture control area

Image display area

Basic setting area

Advaced setting area

Video setting area

Information area

Detailed instructions¶

Name	Function description
“Start &Stop” button	Start and stop acquire image
Select Device	List all device and choose one to use
Open Replay	Choose record file to replay
Device state	Indicate camera state, including Ready, Busy, Open failed, Capturing state
HW/SW information	Indicate camera hardware and software version, production series
Temperature	Camera internal temperature
Frame rate	Current frame rate and total frame count
Pixels distance information	[pixel axis, distance, average distance, std. error @percent, pixel amplitude]
Image display area	Display enhanced depth map, gray map, and color depth map
Menu bar	see the following chapter
Scenario	Frame rate, modulation frequency, binning setting. Details see list after click ComBox
View/Color Map	List all supported map and color mode
PCL	Selected will active PCL Viewer window
Exposure time	First exposure time(TC-E 0~1500us, TC-S 0~1000us), can be adjust during capture
HDR exposure time	Second exposure time(TC-E 0~1500us, TC-S 0~1000us) in HDR mode, can be adjust during capture, should bigger than the first exposure time
Min-Amp filter	Adjust confidence threshold value via scroll bar
Flying noise Filter	Adjust filter parameter via scroll bar
Smooth Filter	Adjust filter parameter via scroll bar
Range minimum	The depth map minimum range
Range maximum	The depth map maximum range
Auto Exposure	Enable/Disable auto exposure
VFlip	Image flip setting
HDR	Enable/Disable HDR mode
Lens_calib	Enable/Disable Lens distortion calibration
Pixels_Clib	Enable/Disable pixels calibration
DepthFilter	Enable/Disable depth image filter
SportMode0/1	Enable/Disable motion blur eliminate mode （Only support TC-E series module）

Recording and setting¶

Name	Function description
Record Enable	Enable Recording
OpenNI compatible	Enable record file compatible OpenNI recorder format
Repeat Playing	Display enhanced depth map, gray map, and color depth map
	Save path setting

Run SmartTofViewer, switch to the “Recorder Setting” menu, check “Record Enable”, and pop up the save file name and directory dialog box to save the video file, as shown below:

Click “Start”, the captured image will be saved to a local file at this time, run as shown below, click the “Stop” button to stop recording:

Play the video file, click “Open Replay”, select the file you just recorded, as shown below:

Click “Start”, the effect is as shown below:

Caution

In the video file replay mode, the adjustments of the “modulation frequency”, “sport mode 0”, “sport mode 1”, “HDR”, and “exposure time” settings are invalid.

Advaced setting area¶

Name	Function description
Fmt	frame format
Distance offset	overall pixels distance offset
illumination power	illumination power(Only for TC-S3 HW30, SW>205, BTL>101)

SmartToFCli instructions¶

Overview¶

The dmcam-cli tool in the SDK is convenient for users to diagnose and test during secondary development. The tool covers almost all the API support of the dmcam library. You can use the dmcam-cli tool to make batch scripts and design your own scenarios. Get the corresponding data. Including the following functions：

View a list of available devices
Obtaining device information
Destination register configuration
Read and set common parameters
Acquisition and storage of different types of image data
Device reset
Device firmware update

Operating mode¶

dmcam-cli can interact with hardware devices through the command line. Generally, it is used in the following three ways：

Command line parameter mode：See below for specific parameter definitions Detailed command
Script file mode: refer to ‘-s, –script <file>’ option in Detailed command
Interactive mode：refer to ‘-i, –interactive’ option in Detailed command

The following figure is a reference screenshot of the command line parameter mode and interactive mode.

Tip

Under windows, double-click to run dmcam-cli.exe directly, and enter interactive mode by default.

Detailed command¶

The following table lists all dmcam commands and parameters, and shows the basic usage of the sample. For more detailed instructions, you can enter –help and –help-interactive parameters to view.

Command list¶
Script mode functions	options	appended options	example
Designated device	`-d, --device <device>`		`dmcam-cli.exe --print info --device 0`
set verbosity	`-v, --verbosity <level>`		`dmcam-cli.exe --print info --device 0 -v critical`
Enumerating devices	`-l, --list`		`dmcam-cli.exe -l`
Reset device	`-r, --reset`		`dmcam-cli.exe -r`
Interactive mode command, supports multiple executions.	`-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`
Enter 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`
Firmware upgrade	`-f, --flash-MCU-firmware <file>`		`dmcam-cli.exe --flash-MCU fw_mcu.bin`
Write register	`--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`
Read register	`--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 parameter	`--set <param>`	`[--param <param>] --value <val>`	`dmcam-cli.exe --set mode --value 1`
Get parameter	`--print <param>`	`[--param <param>]`	`dmcam-cli.exe --print mode`

The following is the interactive mode
View command help information	`help <cmd>`		`help rx`
Device List	`list`
Firmware upgrade	`flash <target> <version>`		`flash mcu fw_mcu.bin`
Write register	`regwr <target> <base> [<&file> \| <P0> <P1>… <P4n>]`		`regwr mcu 0x11 test.bin` `regwr tfc_de 0x10 0x11 0x12 13`
Read register	`regrd <parameter> <base> [cnt] [&file]`		`regrd mcu 0x01 5 regrd tfc_de 0x10 test2.bin`
Set parameter	`set <parameter> <arguments>`		`set frequency 1 set frame_format 1 set frame_rate 30 set intg_time 30`
Get parameter	`print/p [parameter]`		`print` `print info` `print mode` `print frequency` `print format` `print frame_rate` `print roi`
Collect a fixed number of frames data to a file	`rx <data src> <&file> <frame count>`		`rx raw raw.bin 10` `rx depth depth.bin 10`
Collect a fixed amount of data into the buffer	`read <frame count>`		`read 5`
The same as print info	`info`		`info`
Display all version information	`version`		`version`
Collect data at specified time and distance	`capture <option> <args>`		`capture -c start`
Filter parameter configuration	`filter <id> <enabled> [args]`		`filter <ID_AMP> 1 40`
Reset command	`reset <target>`		`reset sys`
others			`cls` `quit` `help` `h rx` `echo who am i`

Caution

For the TC series modules, the read and write operations of the registers are cautious. Misreading and writing may cause unpredictable problems.

View a list of available device information¶

After the device is connected, you can use the dmcam-cli -l command to view the list of available devices. The command is as follows:

dmcam-cli -l

The output is as follows:

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

Obtaining hardware device information¶

After the device is connected, you can use the print command of the dmcam-cli interactive mode to obtain hardware device information. The command format is as follows:

p [parameter]

Common parameter settings¶

After the device is connected, you can set the hardware parameters through the set command of the dmcam-cli interactive mode. The command format is as follows:

set <parameter> <arguments>

You can use the following command to view which parameters can be set and their meanings. The command is as follows. The result is shown in the figure below.:

help set

Acquisition and storage of different types of image data¶

After the device is connected, you can use the dmcam-cli interactive mode rx command to collect data and save the data into the specified file. The collected data format includes raw data, depth data, grayscale data, and point cloud data. The command format is as follows:

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

Save or print the pixel distance information of the specified area¶

After the device is connected, you can use the capture command of the dmcam-cli interactive mode to collect data and save the data into a specified file or print it out. The format of the collected data includes temperature, distance, amplitude, and the command format is as follows. See help cap :::

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

Device reset¶

After the device is connected, you can reset it using the reset command of the dmcam-cli interactive mode. The command format is as follows:

reset <target>

The test results are shown below:

Firmware upgrade¶

Reference for detailed firmwareupgrade

C/C++ core library(libdmcam)¶

Core API¶

dmcam.h¶

All core APIs in the SmartToF SDK are described in dmcam.h, see this chapter for details.

DM’s camera device API.

Detail Decsription starts here

Defines

include¶

DM_NAME¶

DM_VERSION_MAJOR¶

DM_VERSION_MINOR¶

DM_VERSION_REV¶

DM_VERSION_STR¶

DMCAM_ERR_CAP_FRAME_DISCARD¶

DMCAM_ERR_CAP_WRONG_STATE¶

DMCAM_ERR_CAP_CANCEL¶

DMCAM_ERR_CAP_TIMEOUT¶

DMCAM_ERR_CAP_STALL¶

DMCAM_ERR_CAP_ERROR¶

DMCAM_ERR_CAP_EOF¶

DMCAM_ERR_CAP_UNKNOWN¶

DM_SEEK_SET¶

DM_SEEK_CUR¶

DM_SEEK_END¶

API_DEPRECATED_FOR(f)¶

API_DEPRECATED¶

Typedefs

typedef struct dmcam_cap dmcam_param_cap_t¶

typedef void(* dmcam_cap_frdy_f)(dmcam_dev_t *dev, dmcam_frame_t *frame)¶: camera frame ready function prototype

typedef bool(* dmcam_cap_err_f)(dmcam_dev_t *dev, int err, void *err_args)¶: camera frame error function prototype

typedef struct dmcam_cmap_cfg dmcam_cmap_cfg_t¶

Enums

dmcam_dev_if_e¶

camera interface enum

Values:

0¶

DEV_IF_ETH¶

DEV_IF_FILE¶

99¶

dmcam_log_level_e¶

log levels

Values:

0

LOG_LEVEL_DEBUG¶

LOG_LEVEL_INFO¶

LOG_LEVEL_WARN¶

LOG_LEVEL_ERROR¶

LOG_LEVEL_NONE¶

dmcam_dev_rst_e¶

Values:

0

1¶

2¶

3¶

4¶

5¶

8¶

DEV_RST_CNT¶

dmcam_dev_mode_e¶

Values:

0

DEV_MODE_DFU¶

8

DEV_MODE_DATA_UP¶

dmcam_dev_reg_e¶

Values:

0

1

2

4

5

dmcam_frame_mode_e¶

Values:

0: gray

1: dist DCS*2, sine mode,with pi delay

2: single MGX dist DCS*4, sine mode,with pi dealy

3: dist DCS*1, PN mode,without pi delay

4: dist DCS*1,no sine mode,without pi delay

5: single MGX, dist DCS*4, PN mode,with pi delay

6¶: dist DCS*2, PN mode,with pi delay

7¶: single MGX dist DCS*2, PN mode,with out pi dealy

8: single MGX dist DCS*2, nosine mode,with out dealy

0x0A¶: phase frame data

FRAME_FMT_GRAY¶: reserved

FRAME_FMT_LOSSY¶: reserved

0x0D¶: reserved

0x0E¶: reserved

0X0F¶: HDR mode

0X10¶: QI packed mode

0X11¶: Dual frequency QI packed mode

FRAME_FMT_CNT¶

dmcam_dev_param_e¶

dmcam param ID

Values:

0

PARAM_MOD_FREQ¶: modulation frequency

PARAM_INFO_VENDOR¶: production vendor information

PARAM_INFO_PRODUCT¶: production information

PARAM_INFO_CAPABILITY¶: production capability

PARAM_INFO_SERIAL¶: porduction serials id

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_TEMP¶: <Get camera temperature———–

PARAM_HDR_INTG_TIME¶: <Setting HDR integration time param

PARAM_SYNC_DELAY¶: <delay ms for sync use

PARAM_SYS_CALIB_COEFF¶: system calibration coefficent

PARAM_SYNC_SYS_TIME¶: set/get module time

PARAM_AMBIENT_LIGHT_COEFF¶: set ambient light calibration coeff.

PARAM_DUAL_MOD_FREQ¶: set mod_freq

PARAM_INFO_LENS¶: Get lens param

PARAM_FLIP¶: image flip

PARAM_RESERVED¶: rererved

PARAM_INFO_CALIB_FREQ¶: calibration information

PARAM_DEL_CALIB_DATA¶: Delete calibration data

PARAM_ENUM_COUNT¶

dmcam_bin_data_type_e¶

Values:

BIN_DATA_TYPE_MCU¶

BIN_DATA_TYPE_TFC¶

BIN_DATA_TYPE_CALIB¶

dmcam_binning_mode_e¶

binning mode

Values:

DM_BINNING_1X1¶

DM_BINNING_2X2¶

DM_BINNING_4X4¶

DM_BINNING_8X8¶

DM_BINNING_2X4¶

DM_BINNING_CNT¶

dmcam_frame_fmt_e¶

Framae data format

Values:

0: distance data without calibration

DM_FRAME_FMT_DISTANCE¶: distance with calibration

DM_FRAME_FMT_GRAY¶: Confidence data

DM_FRAME_FMT_PCLOUD¶: pointcloud data

DM_FRAME_FMT_RGB¶: reserved

dmcam_filter_id_e¶

filter ID

Values:

DMCAM_FILTER_ID_LEN_CALIB¶: lens calibration

DMCAM_FILTER_ID_PIXEL_CALIB¶: pixel calibration

DMCAM_FILTER_ID_DEPTH_FILTER¶: Depth filter

DMCAM_FILTER_ID_RESERVED¶: RESERVED

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_ID_SYS_CALIB¶: using system calibration param

DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB¶: using ambient light calib calibration param

DMCAM_FILTER_ID_FLYNOISE¶: fly noise filter

DMCAM_FILTER_ID_TEMP_CALIB¶

DMCAM_FILTER_ID_DEPTH_FILTER: MEDIAN is replaced with depth filter

DMCAM_FILTER_CNT¶

dmcam_cmap_palette_e¶

Values:

0

DMCAM_CMAP_HSV¶

DMCAM_CMAP_BWR¶

DMCAM_CMAP_JET¶

DMCAM_CMAP_GIST_RAINBOW¶

DMCAM_CMAP_RAINBOW¶

DMCAM_CMAP_SPECTRAL¶

DMCAM_CMAP_VIRIDIS¶

DMCAM_CMAP_INFERNO¶

DMCAM_CMAP_PLASMA¶

DMCAM_CMAP_MAGMA¶

DMCAM_CMAP_BLUES¶

DMCAM_CMAP_BUGN¶

DMCAM_CMAP_BUPU¶

DMCAM_CMAP_GNBU¶

DMCAM_CMAP_GREENS¶

DMCAM_CMAP_GREYS¶

DMCAM_CMAP_ORANGES¶

DMCAM_CMAP_ORRD¶

DMCAM_CMAP_PUBU¶

DMCAM_CMAP_PUBUGN¶

DMCAM_CMAP_PURD¶

DMCAM_CMAP_PURPLES¶

DMCAM_CMAP_RDPU¶

DMCAM_CMAP_REDS¶

DMCAM_CMAP_YLGN¶

DMCAM_CMAP_YLGNBU¶

DMCAM_CMAP_YLORBR¶

DMCAM_CMAP_YLORRD¶

DMCAM_CMAP_AFMHOT¶

DMCAM_CMAP_AUTUMN¶

DMCAM_CMAP_BONE¶

DMCAM_CMAP_COOL¶

DMCAM_CMAP_COPPER¶

DMCAM_CMAP_GIST_HEAT¶

DMCAM_CMAP_GRAY¶

DMCAM_CMAP_HOT¶

DMCAM_CMAP_PINK¶

DMCAM_CMAP_SPRING¶

DMCAM_CMAP_SUMMER¶

DMCAM_CMAP_WINTER¶

DMCAM_CMAP_BRBG¶

DMCAM_CMAP_COOLWARM¶

DMCAM_CMAP_PIYG¶

DMCAM_CMAP_PRGN¶

DMCAM_CMAP_PUOR¶

DMCAM_CMAP_RDBU¶

DMCAM_CMAP_RDGY¶

DMCAM_CMAP_RDYLBU¶

DMCAM_CMAP_RDYLGN¶

DMCAM_CMAP_SEISMIC¶

DMCAM_CMAP_GIST_EARTH¶

DMCAM_CMAP_TERRAIN¶

DMCAM_CMAP_OCEAN¶

DMCAM_CMAP_GIST_STERN¶

DMCAM_CMAP_BRG¶

DMCAM_CMAP_CMRMAP¶

DMCAM_CMAP_CUBEHELIX¶

DMCAM_CMAP_GNUPLOT¶

DMCAM_CMAP_GNUPLOT2¶

DMCAM_CMAP_GIST_NCAR¶

DMCAM_CMAP_NIPY_SPECTRAL¶

DMCAM_CMAP_FLAG¶

DMCAM_CMAP_PRISM¶

DMCAM_CMAP_COUNT¶

dmcam_cmap_outfmt_e¶

DMCAM color map output format definition

Values:

DMCAM_CMAP_OUTFMT_RGB¶

DMCAM_CMAP_OUTFMT_RGBA¶

DMCAM_CMAP_OUTFMT_BGR¶

DMCAM_CMAP_OUTFMT_COUNT¶

dmcam_frame_save_fmt_t¶

Values:

0

DMCAM_FRAME_SAVE_UINT32¶

DMCAM_FRAME_SAVE_UINT16¶

DMCAM_FRAME_SAVE_UINT8¶

Functions

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. if empty string “” is used, no log will generated

void dmcam_uninit(void)¶: Uninit the DM camera layer.

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.

void dmcam_path_cfg(const char * path)¶

Setting where to save calibration data

Return

void

Parameters

path:

char* dmcam_path_get(void)¶

Getting calibration data path

Return: _API char*

const char* dmcam_error_name(int error_code)¶

covert specified error code into error string

Return

const char*

Parameters

error_code:

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

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.

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

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

void dmcam_dev_close(dmcam_dev_t * dev)¶

Close specified dmcam device.

Parameters

dev:

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

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

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

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

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

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

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

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

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)

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);

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

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

bool dmcam_cap_start(dmcam_dev_t * dev)¶

start device capturing.

Return

bool return true = ok

Parameters

dev: [in] dmcam device handler

bool dmcam_cap_stop(dmcam_dev_t * dev)¶

stop device capturing.

Return

bool return true = ok

Parameters

dev: [in] dmcam device handler

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

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

int dmcam_cap_save_frame(dmcam_dev_t * dev, const uint8_t * frame_data, uint32_t frame_dlen, const dmcam_frame_info_t * frame_info)¶

save specified raw frame data into replay file. This function is only functional when en_save_replay and en_save_manually in dmcam_cap_cfg_t is set to true.

Return

int return 0 if saving is ok, else return negative number

Parameters

dev: [in] dmcam device handler
frame_data: [in] raw frame data to be saved.
frame_dlen: [in] raw frame data len
frame_info: [in] frame info of the raw frame data

int dmcam_cap_seek_frame(dmcam_dev_t * dev, int frame_cnt_offset, int whence)¶

seek frame inside replay device. it only has effect on replay file simulated dmcam device. it’ll return -1 if dev is not a replay device.

Return

int return the current frame pos (0 = at the beginning, 1 = at the end of first frame). -1 = failed.

Parameters

dev: [in] dmcam device handler
frame_cnt_offset: [in] specified frames to seek afterward or forward. negative value = seek forward
whence: [in] SEEK_SET: beginning of the replay. SEEK_CUR: current frame of the replay. SEEK_END: end of the replay.

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

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

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

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

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

convert to raw distance data in uint16 from raw frame data. the raw distance is calculated without any calibration and pixel reorder.

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

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

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

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

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

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

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) dimension and in meter unit. 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_dist_f32.

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 in meter unit, d is distance in meter unit or pseudo-color. output is in (w,h,4) dimension. 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 (can be retrieve by (uint32)pcl[4*i + 3]); 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.

int dmcam_frame_get_pcl_xyzi(dmcam_dev_t * dev, float * pcl, int pcl_len, const float * dist, int dist_len, const float * gray, int gray_len, int img_w, int img_h, int16_t ir_balance, const dmcam_camera_para_t * p_cam_param)¶

get point cloud data from distance data and gray(confid) data

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,i) point. (x,y,z) is coordinate in meter unit, IR value can be get from i by ((uint32_t)i) 0xff . output is in (w,h,4) dimension. point with (x,y,z)=(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))
gray: [in] gray image data buffer.
gray_len: [in] gray image data count (in sizeof(float))
img_w: [in] distance image width in pixel
img_h: [in] distance image height in pixel
ir_balance: [in] [-1024, 1024] -> [darkest, brightest]
p_cam_param: [in] user specified camera lens parameter. if null, the internal camera parameter is used.

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

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

bool dmcam_cmap_palette_set(dmcam_cmap_palette_e cm)¶

set default color palette used inside dmcam_cmap_ apis.

Return

bool true = set is ok. false = set failed

Parameters

cm: [in] color palette

dmcam_cmap_palette_e dmcam_cmap_palette_get(void)¶

get default color palette currently used.

Return: dmcam_cmap_palette_e current color palette

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, const dmcam_cmap_cfg_t * cfg)¶

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
range_min_m: [in] minimum range of source point
range_max_m: [in] max range of source point
cfg: [in] refer dmcam_cmap_cfg_t. if NULL, default config is used.

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, const dmcam_cmap_cfg_t * cfg)¶

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
range_min_mm: [in] minimum range of source point
range_max_mm: [in] max range of source point
cfg: [in] refer dmcam_cmap_cfg_t. if NULL, default config is used.

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]

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]

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

void dmcam_file_close(int fd)¶

close specified file descriptor

Parameters

fd: [in] specified file descriptor

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.

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

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

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

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

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

bool dmcam_get_lens_param(dmcam_dev_t * dev, dmcam_camera_para_t * param, uint8_t id)¶

get lens calibration data from calibration data

Return

bool[out] true=ok, false=failed

Parameters

dev[in]device: handler
: param
[int]iddefualt: use 0

struct dmcam_dev_if_info_usb¶

Public Members

uint8_t usb_bus_num¶

uint8_t usb_port_num¶

uint8_t usb_dev_addr¶

uint8_t usb_speed¶

struct dmcam_dev_if_info_eth¶

Public Members

uint8_t dmcam_dev_if_info_eth::addr[16]

uint8_t dmcam_dev_if_info_eth::reserved[16]

uint32_t token¶

uint32_t cid¶

struct dmcam_dev_if_info_fil¶

Public Members

void* fd¶

char* fname¶

struct dmcam_dev_if_info_t¶

Public Members

dmcam_dev_if_e type¶

struct dmcam_dev_if_info_usb usb¶

struct dmcam_dev_if_info_eth eth¶

struct dmcam_dev_if_info_fil fil¶

union dmcam_dev_if_info_t::@0 info¶

union dmcam_dev_ver_u¶

Public Members

uint16_t dmcam_dev_ver_u::version[4]

uint16_t hw_ver¶

uint16_t sw_ver¶

uint16_t sw2_ver¶

uint16_t hw2_ver¶

struct dmcam_dev_ver_u::@1 ver¶

struct dmcam_dev_t¶

#include <dmcam.h>

dmcam device structure. It describes device usb port info, device info

Public Members

void* handler¶

dmcam_dev_if_info_t if_info¶

char dmcam_dev_t::product[32]

char dmcam_dev_t::vendor[32]

char dmcam_dev_t::serial[32]

uint64_t dev_id¶: device uniq id

dmcam_dev_ver_u version¶

char* expath¶: extract path to store calibration data,can be set by dmcam_path_cfg

void* lock¶: device lock

void* user_data0¶: used internally for python extension

void* user_data1¶: used internally for python extension

uint8_t init_flag¶: struct init flag

uint8_t alloc_flag¶: malloc flag used internally

uint8_t api_flag¶: sync between frame wait/get and normal api

struct dmcam_camera_para_t¶

#include <dmcam.h>

camera parameters

Public Members

float cx¶: center point x

float cy¶: center point y

float fx¶: focal length x

float fy¶: focal length y

float dmcam_camera_para_t::dcoeff[5]: distortion coef

struct dmcam_param_roi_t¶

#include <dmcam.h>

Frame size and Max frame size can be get from paramter interface using the PRAM_INFO_ROI parameter.

Note: : For PARAM_INFO_ROI, it’s format like follows. (srow,scol)_ _ _ _ _ _ _ _ _ | | | ROI | |_ _ _ _ _ _ _ _ _| (erow,ecol) frame size = (ecol - scol) * (erow - srow) * pixel_width;frame roi value

Public Members

uint16_t srow¶: start address for row,multiple of 16

uint16_t erow¶: end address for row,multiple of 16

uint16_t scol¶: start address for columon,multiple of 16

uint16_t ecol¶: end address for columon,multiple of 16

uint8_t binning¶: binning mode for some sensor

uint32_t max_fsize¶: MAX frame size

struct dmcam_cap¶

Public Members

uint16_t max_frame_width¶

uint16_t max_frame_height¶

uint16_t max_frame_depth¶

uint16_t max_fps¶

uint16_t max_intg_us¶

uint8_t illum_board_type¶

uint8_t sensor_board_type¶

union dmcam_param_val_u¶

#include <dmcam.h>

dmcam param value

Public Members

uint8_t dmcam_param_val_u::raw[18]

uint32_t dev_mode¶

uint32_t mod_freq¶: system calibration frequency

uint32_t calib_data_type¶

char dmcam_param_val_u::info_vendor[18]: camera vendor information

char dmcam_param_val_u::info_product[18]: camera production information

uint16_t ambient_light_coeff¶

dmcam_param_cap_t info_capability¶: device capablity

uint32_t dmcam_param_val_u::serial[3]: serials numbers

struct dmcam_param_val_u::@2 info_serial¶

uint16_t hw_ver¶: hardware1 version

uint16_t sw_ver¶: firmware1 version

uint16_t sw2_ver¶: firmware2 version

uint16_t hw2_ver¶: hardware2 version

struct dmcam_param_val_u::@3 info_version¶

uint32_t format¶: frame format

struct dmcam_param_val_u::@4 frame_format¶

uint32_t fps¶: frame rate

struct dmcam_param_val_u::@5 frame_rate¶

uint8_t random_delay_en¶

uint16_t delay¶

struct dmcam_param_val_u::@6 sync_delay¶

dmcam_param_roi_t roi¶: image roi

uint8_t percent¶: illumination power

struct dmcam_param_val_u::@7 illum_power¶

uint16_t intg_us¶: first integration time(normal mode or HDR mode)

struct dmcam_param_val_u::@8 intg¶

uint16_t intg_3dhdr¶: second integration time in HDR mdoe

struct dmcam_param_val_u::@9 intg_hdr¶

uint16_t corr1¶

uint16_t corr2¶

struct dmcam_param_val_u::@10 phase_corr¶

int16_t tl_cal¶

int16_t tr_cal¶

int16_t bl_cal¶

int16_t br_cal¶

int16_t ib_cal¶

struct dmcam_param_val_u::@11 temp¶

uint8_t valid¶

data is valid;1==valid

1:coeff is valid; 0: coeff in not valid

uint8_t flag¶: 0:no compression used;1:zip compression used

uint32_t ID¶: data info, version

uint32_t timestamp¶: calibration date

uint32_t fsize¶: head+data+paddingsize

uint32_t datasize¶: data size

struct dmcam_param_val_u::@12 cinfo¶: calibration info

uint16_t part_ver¶: chip part version

uint16_t chip_id¶: chip id

uint16_t wafer_id¶: wafer id

struct dmcam_param_val_u::@13 chip_info¶

float offset¶: system calib offset

float coeff¶: system calib coeff

uint32_t random_freq¶: random frequency

uint8_t frm_format¶: calibration frame format

struct dmcam_param_val_u::@14 sys_calib_coeff¶

uint32_t sec¶

uint32_t us¶

struct dmcam_param_val_u::@15 sync_time¶

uint32_t mod_freq0¶: modulation frequency0

uint32_t mod_freq1¶: modulation frequency1

struct dmcam_param_val_u::@16 dual_freq¶

float cx¶: center point x

float cy¶: center point y

float fx¶: focal length x

float fy¶: focal length y

struct dmcam_param_val_u::@17 lens_param¶

uint8_t total_cnt¶: calibration frequency count

uint8_t remain_cnt¶

uint8_t dmcam_param_val_u::freq[4]

struct dmcam_param_val_u::@18 calib_freq¶

struct dmcam_param_item_t¶

#include <dmcam.h>

param data struct

Public Members

dmcam_dev_param_e param_id¶: param id

uint8_t param_val_len¶: param length

dmcam_param_val_u param_val¶: param value

struct dmcam_frame_info_t¶

#include <dmcam.h>

Used for store frame information

Public Members

uint32_t frame_size¶: frame size in bytes

uint16_t frame_format¶: frame format code (sensor dependent)

uint16_t frame_idx¶: frame index

uint32_t width¶: image width

uint32_t height¶: image height

uint8_t depth¶: reserved

uint8_t pixel_format¶: internal use

uint16_t priv_code¶: internal use

int16_t temp0¶

int16_t temp1¶: sensor and illumination board temperature

uint32_t rx_ts¶: frame rx unix timestamp

uint32_t rx_us¶: frame rx microseconds

struct dmcam_frame_t¶

#include <dmcam.h>

frame data struct

Public Members

dmcam_frame_info_t frame_info¶: frame informatin

void* frame_data¶: frame data pointer

struct dmcam_cap_cfg_t¶

#include <dmcam.h>

capture configuration params

Public Members

uint32_t cache_frames_cnt¶: max frame count in frame buffer (cache)

dmcam_cap_frdy_f on_frame_ready¶: callback when frame is ready in the frame buffer; invoked in dmcam_cap_get_frames

dmcam_cap_err_f on_error¶: callback when error happens during capturing; invoked in dmcam_cap_get_frames

uint8_t en_save_manually¶: if set to 1, saving is manually controlled by dmcam_cap_save_frame/dist/gray

uint8_t en_save_replay¶: enable saving replay file during capturing. saving happens in dmcam_cap_get_frames

uint8_t en_save_dist_u16¶: enable saving dist_u16 file during capturing. saving happends in dmcam_cap_get_dist_xx

uint8_t en_save_gray_u16¶: enable saving gray_u16 file during capturing. saving happends in dmcam_cap_get_gray_xx

char* fname_replay¶: replay file name

uint8_t en_fdev_rewind¶: only used when type of the device is reaply-file. if true, capture will auto rewind when the EOF of file is met

union dmcam_filter_args_u¶

#include <dmcam.h>

filter args

Public Members

uint16_t raw¶

uint8_t case_idx¶: User Scenario index

uint32_t lens_id¶: DMCAM_FILTER_ID_LEN_CALIB parameter: length index

uint16_t min_amp¶: DMCAM_FILTER_ID_AMP parameter: Min amplitude threshold

uint16_t sat_ratio¶: DMCAM_FILTER_ID_AUTO_INTG parameter: saturation ratio threshold

uint16_t sync_delay¶: DMCAM_FILTER_ID_SYNC_DELAY parameter: sync delay: 0 = random delay, 1 = specified delay in ms

int16_t temp_threshold¶: DMCAM_FILTER_ID_TEMP_MONITOR paramter: Temperature threshold for temperature monitor

uint16_t intg_3d¶: intg_3d: exposure time 0

uint16_t intg_3dhdr¶: intg_3dhdr: exposure time 1

struct dmcam_filter_args_u::@19 intg¶: DMCAM_FILTER_ID_HDR paramter

uint8_t median_ksize¶: DMCAM_FILTER_ID_MEDIAN paramter: DEPRECATED, please use DMCAM_FILTER_ID_DEPTH_FILTER

int32_t offset_mm¶: DMCAM_FILTER_ID_OFFSET paramter : offset in mm for DMCMA_FILTER_ID_OFFSET filter

uint8_t sport_mode¶: DMCAM_FILTER_ID_SPORT_MODE parameter: 0 = high motion mode, 1 = extrem high motion mode

uint16_t k_ambient_light¶: DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB kcoeff of ambient light calibration

uint8_t col_reduction¶: column binning:0 no binning, 1 by half

uint8_t row_reduction¶: row binning: 0 no binning, 1 by half, 2 a quarter

struct dmcam_filter_args_u::@20 binning_info¶

uint8_t depth_filter_mode¶: 0xF0 = filter strength controlled by depth_filter_strength Other values = filter controlled automatically

uint8_t depth_filter_strength¶: DMCAM_FILTER_ID_DEPTH_FILTER strength: [0, 31]

struct dmcam_filter_args_u::@21 dmcam_filter_args_u::@22¶

uint8_t fly_noise_threshold¶: fly noise threshold 0~255

struct dmcam_filter_args_u::@23 dmcam_filter_args_u::@24¶

struct dmcam_cmap_cfg¶

Public Members

dmcam_cmap_palette_e color_palette¶

uint8_t histeq_en¶

Parameters and filter¶

SmartToF mainly uses the module parameter settings and filter function settings to control the function settings of the module during collection, All module parameter items and filtering function item definitions are in the dmcam.h header file in the SDK.

Module parameter description¶

Module parameter enum type definition

 /**dmcam param ID*/
 typedef enum {
   PARAM_DEV_MODE=0,      /**< device work mode*/
   PARAM_MOD_FREQ,          /**< modulation frequency*/
   PARAM_INFO_VENDOR,      /**< production vendor information*/
   PARAM_INFO_PRODUCT,     /**< production information*/
   PARAM_INFO_CAPABILITY,  /**< production capability*/
   PARAM_INFO_SERIAL,      /**< porduction serials id*/
   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_TEMP,             /**< <Get camera temperature--------------*/
   PARAM_HDR_INTG_TIME,    /**< <Setting HDR integration time param*/
   PARAM_SYNC_DELAY,       /**< <delay ms for sync use*/
   PARAM_SYS_CALIB_COEFF,      /**< system calibration coefficent*/
   PARAM_SYNC_SYS_TIME,       /**< set/get module time*/
   PARAM_AMBIENT_LIGHT_COEFF, /**< set ambient light calibration coeff. */
   PARAM_DUAL_MOD_FREQ,       /**< set mod_freq */
   PARAM_INFO_LENS,           /**< Get lens param */
   PARAM_FLIP,                /**< image flip*/
   PARAM_RESERVED,            /**< rererved*/
   PARAM_INFO_CALIB_FREQ,     /**< calibration information*/
   PARAM_DEL_CALIB_DATA,      /**< Delete calibration data*/
   PARAM_ENUM_COUNT,
 }dmcam_dev_param_e;

Module parameter enum type description

Parameter name	Ranges	Description
PARAM_DEV_MODE		reserved
PARAM_MOD_FREQ	TC-E2,3,4(12,24,36MHZ) TS-3 (10~100MHz)	Frequency should correspond to calibration data
PARAM_INFO_VENDOR	readonly	Digtal Miracle
PARAM_INFO_PRODUCT	readonly	Module name，for example TC-E2-1.0
PARAM_INFO_CAPABLITY	readonly
PARAM_INFO_SERIAL	readonly	unique data
PARAM_INFO_VERSION	readonly	Software and hardware version
PARAM_INFO_SENSOR	readonly	sensor ID
PARAM_INFO_CALIB	readonly	Query calibration data information
PARAM_ROI	320240 320160
PARAM_FRAME_FORMART	TC-E2,3,4 (2,4) TC-S3 15,16,17	TC-E2,3,4 default 2, sport mode1 is 4 TC-S3 default 16
PARAM_ILLUM_POWER		Only TC-S3.1 support
PARAM_FRAME_RATE	1~30	TC-S3 Dual frequency and HDR mode frame rate will be halved
PARAM_INTG_TIME	TC-E series 0-1500 TC-S series 0~1000	exposure time in normal mode
PARAM_PHASE_CORR		reserved
PARAM_TEMP	readonly	Read sensor temperature and illumination board temperature separately
PARAM_HDR_INTG_TIME	TC-E series 0-1500 TC-S series 0~1000	exposure time in HDR mode
PARAM_SYNC_DELAY	0ms-6ms	reserved
PARAM_SYS_CALIB_COEFF		reserved
PARAM_SYNC_SYS_TIME		reserved
PARAM_AMBIENT_LIGHT_COEFF		reserved
PARAM_DUAL_MOD_FREQ	TC-S series 10~100MHz	Only supported TC-S series module
PARAM_INFO_LENS		lens calibration information
PARAM_FLIP		reserved
PARAM_INFO_CALIB_FREQ		Get calibrated frequency list
PARAM_DEL_CALIB_DATA		Delete calibration data and only support in TC-S series modules

Module filter type description¶

Module filtering types include depth filtering, amplitude filtering, automatic exposure, sports mode, etc. defined as follows

/** filter ID  */
typedef enum {
  DMCAM_FILTER_ID_LEN_CALIB,    /**< lens calibration*/
  DMCAM_FILTER_ID_PIXEL_CALIB,  /**< pixel calibration*/
  DMCAM_FILTER_ID_DEPTH_FILTER,  /**< Depth filter */
  DMCAM_FILTER_ID_RESERVED,        /**< RESERVED */
  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_ID_SYS_CALIB,   /**< using system calibration param */
  DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB,   /**< using ambient light calib calibration param */
  DMCAM_FILTER_ID_FLYNOISE,   /**< fly noise filter */

  DMCAM_FILTER_ID_TEMP_CALIB,/*Temperature calibration*/
  DMCAM_FILTER_ID_MEDIAN = DMCAM_FILTER_ID_DEPTH_FILTER,  /**<  MEDIAN is replaced with depth filter */
  DMCAM_FILTER_CNT,
}dmcam_filter_id_e;

Note

For the parameter value corresponding to each ID, please refer to the filter setting example.

Filter ID	Description
DMCAM_FILTER_ID_LEN_CALIB	lens calibration enable/disable ID
DMCAM_FILTER_ID_PIXEL_CALIB	pixel calibration enable/disable ID
DMCAM_FILTER_ID_DEPTH_FILTER	Depth filter
DMCAM_FILTER_ID_RESERVED	RESERVED
DMCAM_FILTER_ID_AMP	Amplitude filter control, ranges 0~100
DMCAM_FILTER_ID_AUTO_INTG	auto integration filter enable
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 calculate distance
DMCAM_FILTER_ID_SPORT_MODE	set sport mode , for TC-E series module: No sport mode 18ms motion blur ,4xDCS `sport_mode` = 0 ,6ms motion blur ,2xDCS `sport_mode` = 1 , no motion blur, 2xDCS high nosies `sport_mode` = 2 , 6ms motion blur,2xDCS high nosies
DMCAM_FILTER_ID_SYS_CALIB	using system calibration parameter
DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB	using ambient light calibration parameter,reserved
DMCAM_FILTER_ID_FLYNOISE	fly noise filter
DMCAM_FILTER_ID_TEMP_CALIB	Temperature calibration
DMCAM_FILTER_ID_MEDIAN	MEDIAN is replaced with depth filter, discarded

Detailed description of frame rate and sport mode¶

TC / TCM-E3 is a module specifically designed for high frame rate applications. The highest frame rate can reach 120 frames. The motion mode is to eliminate the effects of motion blur, their relationship is as follows:

Module series	Mode	fps ranges	Real fps	motion blur	Depth resolution	Depth map accuracy
TC-E2	Normal mode	1-30	fps	21ms	320x240	Normal precision(calculated by 4xDCS)
TC-E2	sport mode 0	1-30	fps	7ms	Vertical resolution halved ：320x120( output the interpolation 320x240)	Normal precision(calculated by 4xDCS)
TC-E2	Sport mode 1	1-30	fps	0ms	Vertical resolution halved ：320x120( output the interpolation 320x240)	Half accuracy (calculated by 2xDCS)
TC-E3	Normal mode	1-30	fps(fps<20) fpsx4(fps >=20)	21ms	320x240	Normal precision(calculated by 4xDCS)
TC-E3	Sport mode 0	1-30	fpsx2	7ms	Vertical resolution halved ：320x120( output the interpolation 320x240)	Normal precision(calculated by 4xDCS)
TC-E3	Sport mode 1	1-30	fpsx4	0ms	Vertical resolution halved ：320x120( output the interpolation 320x240)	Half accuracy (calculated by 2xDCS)

Parameters and filtering code examples¶

The module-related parameters and filtering function ID have been introduced in Parameters and filter The following will explain how to set and get the module parameters and enable and disable the module filter function.

Module parameter setting and reading¶

Below is an example of setting and reading the exposure time of the module:

parameter setting:

dmcam_param_item_t wparam;
uint16_t intg_time = 100;                       //set first exposure time
memset(&wparam,0,sizeof(wparam));
wparam.param_id = PARAM_INTG_TIME;      //Parameter setting is exposure time
wparam.param_val_len = sizeof(intg_time);
wparam.param_val.intg.intg_us = intg_time;
assert(dmcam_param_batch_set(dev,&wparam,1));   //Call API for single parameter setting

dmcam_param_item_t wparam;
uint16_t intg_hdrtime = 700;            //set second exposure time for setting HDR
memset(&wparam,0,sizeof(wparam));
wparam.param_id = PARAM_HDR_INTG_TIME;  //Parameter setting is HDR exposure time
wparam.param_val_len = sizeof(intg_time);
wparam.param_val.intg.intg_us = intg_hdrtime;
assert(dmcam_param_batch_set(dev,&wparam,1));   //Call API for single parameter setting

Tip

If the integration time of HDR is not set to 0, the module’s HDR mode is turned on. In HDR mode, the second integration time must be set larger than the first integration time.

parameter reading:

dmcam_param_item_t rparam;
memset(&rparam,0,sizeof(rparam));
rparam.param_id = PARAM_INTG_TIME;      //Indicates that the parameter item to be read is the integration time
assert(dmcam_param_batch_get(dev,&rparam,1));   //Call the API to get a single parameter

For the setting and acquisition of other module parameters, refer to the setting and acquisition of the exposure time above.

Filter enable and disable¶

Pixel calibration, used for correction of depth data after turning on:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_PIXEL_CALIB; //pixel calibration
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//enable pixel calibration
dmcam_filter_disable(dev,DMCAM_FILTER_ID_PIXEL_CALIB); //disable pixel calibration

Depth filtering, used to filter depth data when turned on:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_MEDIAN;   //depth filter item
//witem.median_ksize = 3;            //default value
witem.depth_filter_mode = 0xf0;  //default value
witem.depth_filter_strength = 1; //ranges 0~100
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//enable filter
dmcam_filter_disable(dev,DMCAM_FILTER_ID_MEDIAN);//disable filter

Amplitude filtering, filtering points with poor quality after turning on:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_AMP;      //amplitude filter item
witem.min_amp = 30;     //Set the minimum amplitude filtering threshold
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//enable filter
dmcam_filter_disable(dev,DMCAM_FILTER_ID_AMP);  //disable filter

HDR mode，set two integration times to ensure that the same module will not overexpose when measuring different objects near and far:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_HDR;      //HDR mode
witem.intg.intg_3d = 100;                //HDR small exposure time in HDR mode
witem.intg.intg_3dhdr = 700;         //HDR large exposure time in mode
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u)); //enable HDR

Tip

Another way to turn on HDR mode is to directly set the exposure time of HDR to other than 0, As in the example of setting the integration above, both methods require the integration time of HDR to be set greater than the integration time of the other

Automatic integration time, automatically adjust the exposure time according to the distance of the measured object after turning on:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_AUTO_INTG;        //Automatic exposure item
witem.sat_ratio = 5;//Automatic exposure threshold value
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//enable
dmcam_filter_disable(dev,DMCAM_FILTER_ID_AUTO_INTG);    //disable

Multi-module interference cancellation, turn on to eliminate or reduce interference when multiple modules are turned on at the same time:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_SYNC_DELAY;        //interference delay item
witem.sync_delay = 0;   //0 means a random delay
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//enable
dmcam_filter_disable(dev,DMCAM_FILTER_ID_SYNC_DELAY);   //enable

Sports mode 0, frame format should be set to 2:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_SPORT_MODE;
dmcam_param_item_t wparam;
uint32_t set_format = 2;        //set frame format to 2
memset(&wparam,0,sizeof(wparam));
wparam.param_id = PARAM_FRAME_FORMAT;   //frame format item
wparam.frame_format.format = set_format;
wparam.param_val_len = sizeof(set_format);
assert(dmcam_param_batch_set(dev,&wparam,1));
witem.sport_mode = 0;   //set sport mode to 0
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//enable sport mode 0
dmcam_filter_disable(dev,DMCAM_FILTER_ID_SPORT_MODE);//disable sport mode 0

Sport mode 1, frame format should be set to 4:

dmcam_filter_args_u witem;
dmcam_filter_id_e filter_id = DMCAM_FILTER_ID_SPORT_MODE;
dmcam_param_item_t wparam;
uint32_t set_format = 4;
memset(&wparam,0,sizeof(wparam));
wparam.param_id = PARAM_FRAME_FORMAT;
wparam.frame_format.format = set_format;
wparam.param_val_len = sizeof(set_format);
assert(dmcam_param_batch_set(dev,&wparam,1));
witem.sport_mode = 1;
dmcam_filter_enable(dev,filter_id,&witem,sizeof(dmcam_filter_args_u));//enable sport mode 1
//After close sport mode 1 ,should set frame format back to 2
set_format = 2;
wparam.frame_format.format = set_format;
wparam.param_id = PARAM_FRAME_FORMAT;
wparam.param_val_len = sizeof(set_format);
assert(dmcam_param_batch_set(dev,&wparam,1));
dmcam_filter_disable(dev,DMCAM_FILTER_ID_SPORT_MODE);

Video save and replay instructions¶

In the algorithm evaluation of the module, one of the main preparations before the evaluation is the acquisition of video files. In SmartToFViewer, we have introduced how to obtain it through SmartToFViewer. Record and play, here introduces how to record and read video files through the program, as well as the main introduction to the API

Settings for video files¶

Whether to save the video file and what kind of data the video file saves are mainly set in the program dmcam_cap_cfg_t structure, the specific code is as follows

 /* 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 */
};

Among the above structure parameters, the parameters related to the video file are en_save_replay en_save_dist_u16 en_save_gray_u16 , ，the specific descriptions of these parameters are as follows：

Support SmartToF SDK standard playback

If you only need to support SmartToF SDK standard playback, just set the above en_save_replay to true and the other two to false
OpenNI-compatible playback (such as NiViewer)

Support playback of OpenNI tools, such as NiViewer playback.In this case, you need to set en_save_replay to false, en_save_dist_u16 and en_save_gray_u16. Set to true or any one of the settings true, if both are set to enable, it means to store the depth map and grayscale map, and one of them is enabled to enable en_save_dist_u16 as the depth map, Enabling en_save_gray_u16 means that the saved image is grayscale.

Reading of video files¶

SmartToF video file “xxx.oni” can be simulated as a standard DMCAM device and can be opened by the dmcam_dev_open_by_uri function, If the file name is “test.oni”, the code to read the file name is as follows.

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

Caution

The main differences between analog dmcam devices and real dmcam devices are as follows:

When simulating equipment, all processing based on the original DCS data in the SDK can be adjusted and superimposed, such as: depth filtering, minimum amplitude filtering, pixel calibration, lens calibration, etc.
When simulating a device, adjusting related parameters of the DCS raw data is not effective in simulating the device, such as exposure time, HDR function, etc.

Python extension¶

dmcam python extension overview¶

Installation of python extension¶

dmcam provides extensions based on the standard python wheel，the extension can be installed directly via pip and supports 36-bit and 64-bit environments for Windows and Linux，see Pypi project homepage .The installation command is:

pip install -U dmcam

python API Description¶

The API in Python corresponds to the API defined in ** dmcam.h ** in the C library.

The default package name in the python extension is: dmcam. Can be imported directly via import:
```
import dmcam
```
API name mapping(C->Python)： dmcam_xxxxx(…) -> dmcam.xxxxx(…) . For example dmcam_dev_open is mapped to dmcam.dev_open
Structure mapping(C->Python): dmcam_xxxxx -> dmcam.xxxx() . Structure is mapped to a class in Python. For exaample, create dmcam_frame_info_t structure:
```
finfo = dmcam.frame_info_t()
```
NULL is mapped to None.For example
```
dmcam.init(None) # dmcam_init(NULL)
```
The following Python interfaces are different from the C APIs.
dmcam.dev_list()
The C interface is simplified in Python. You can get the device list directly in the following ways. Its return value is 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)

The C interface is simplified in Python, passing a dict directly, without having to construct a more complex dmcam_param_item_t structure and its length parameters. Use example like below ::

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)
The C interface is simplified in Python. You can directly pass a list that needs to get parameters without having to construct a more complex dmcam_param_item_t structure and its length parameters. Use example like below
# 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 and dmcam.set_callback_on_error

Due to the differences between Python callback functions and C. Regarding the setting of callback functions in the acquisition process, currently, Python only supports setting two types of callbacks, frame_ready and error, through the above two interfaces. Setting of the callback function via cap_cg_t in dmcam.cap_config_set (dev, cap_cfg_t) is not supported. Use example like below

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)

The following table lists some common API interface comparisons：

C and python interface comparison¶
C library API	python API
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

Parameter setting and filter setting in python¶

Here we will introduce the setting and reading of parameters in python.

Parameter setting and filter setting¶

Set one parameter，such as setting the frame format:

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")

Get one parameter，Eg.Read integration time:

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

Filter enable and disable¶

Pixel calibration for depth data correction

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)      #enable pixel calibration

dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_PIXEL_CALIB)    #disable pixel calibration

Depth filtering for depth data filtering:

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))       #enable depth filter

dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_MEDIAN) #disable depth filter

Amplitude filtering for filtering poor quality points:

amp_min_val = dmcam.filter_args_u()
amp_min_val.min_amp = 30        #Set threshold for minimum amplitude filtering
dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_AMP, amp_min_val, sys.getsizeof(amp_min_val))    #enable amplitude filter

dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_AMP)             #disable amplitude filter

Automatic integration time, open the module to automatically adjust the exposure time according to the measured object:

intg_auto_arg = dmcam.filter_args_u()
intg_auto_arg.sat_ration = 5    #Value of the auto exposure setting
dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_AUTO_INTG, intg_auto_arg, sys.getsizeof(intg_auto_arg))  #Turn on automatic exposure

dmcam.filter_disable(dev,DMCAM_FILTER_ID_AUTO_INTG)             #Turn off automatic exposure

sport mode 0，set frame format to 2(Only for TC-E series):

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   #set frame format value 2
dmcam.param_batch_set(dev, wparams_fmt)         #set frame format

dmfilter.sport_mode = 0         #set sport mode value to 0
dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE, dmfilter, 0)         #open sport mode 0

dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE)             #close sport mode 0

sport mode 1，set frame format to 2(Only for TC-E series):

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 #set frame format value to 4
dmcam.param_batch_set(dev, wparams_fmt)  #set frame format

dmfilter.sport_mode = 1         #set sport mode value 1
dmcam.filter_enable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE, dmfilter, 1)         #open sport mode 1

#when close sport mode 1，please switch frame format to 2
wparams_fmt = {dmcam.PARAM_FRAME_FORMAT: dmcam.param_val_u()}
wparams_fmt[dmcam.PARAM_FRAME_FORMAT].frame_format.format = 2 #set frame format to 2
dmcam.param_batch_set(dev, wparams_fmt)  #set frame format

dmcam.filter_disable(dev, dmcam.DMCAM_FILTER_ID_SPORT_MODE)             #close sport mode 1

C# extension instructions¶

dmcam C# extension overview¶

The C# extension provided by dmcam makes it easy for developers based on .net C# to perform rapid secondary development based on SmartToF cameras. This document mainly describes the installation of C# extensions and the associations and differences between C# API and C API.

C# extension installation¶

Window
- Supported systems：
  - Windows 7/8/10 32bit/64bit
  - .Net framework >= 3.5
- C# extended dynamic library includes：
  - dmcam_csharp.dll: C# extended dynamic library for importing C# projects
  - dmcam_csharp_adapter.dll:C# dmcam extended suitable library configuration
  - libdmcam.dll: dmcam core lib
- Installation method
  - Add the above dll to the PATH or copy it to the executable file directory.
  - C# project references dmcam_csharp.dll
Linux
- Supported systems：
  - Linux 64bit (Ubuntu 14.04/16.04 tested)
  - Mono
- C# extended dynamic library includes
  - dmcam_csharp.dll: C# extended dynamic library for importing C# projects.
  - dmcam_csharp_adapter.so: C# dmcam extended suitable library configuration
  - libdmcam.so: dmcam core lib
- Installation method
  - Setting LD_LIBRAYR_PATH contains the above so/dll folder, or put the dynamic library in the system library directory, such as： /usr/local/lib/

C# API description¶

The module API in C# corresponds to the API defined in ** dmcam.h ** in the C library.

The default namespace for C# extensions is: com.smarttof . Can be imported via using:

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

API name mapping(C->C#)： dmcam_xxxxx(…) -> dmcam.xxxxx(…) .For example dmcam_dev_open is mapped to`dmcam.dev_open`
Structure mapping(C->C#): dmcam_xxxxx -> xxxx() . Structure is mapped to a class in C#, For example, create a dmcam_frame_info_t structure as follows:
finfo = new frame_info_t()
NULL is mapped to null, For example:
dmcam.init(null) // dmcam_init(NULL)

There are differences between the following C# interfaces and C APIs, you need to pay attention:

dmcam.dev_list()

In C#, the device list is obtained as follows. The return value is the number of ready devices. Use example like below:

dmcamDevArray devs = new dmcamDevArray(16);
int cnt = dmcam.dev_list(devs.cast(), 16);

Console.Write("found {0} device\n", cnt);

dmcam.param_batch_set()

Setting parameters in C# is a bit more complicated than C, and you need to construct a param_item_t instance. The specific usage example is as follows:

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)

Setting parameters in C# is a bit more complicated than C, and you need to construct a param_item_t instance. The specific usage example is as follows.

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 and dmcam.set_callback_on_error

C# extensions do not support callback functions. When capturing, you can refer to the following settings:

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 extension instructions¶

dmcam Java extension overview¶

The Java extension provided by dmcam makes it easy for developers based on Java to perform rapid secondary development based on SmartToF cameras. This document mainly describes the installation of Java extensions and the associations and differences between Java API and C API.

Java extension installation¶

Window
- Supported systems：
  - Windows 7/8/10 32bit/64bit
  - JDK >= 1.8
- Java extended dynamic library includes：
  - dmcam.jar: Java extended dynamic library for importing Java projects.
  - dmcam_java.dll: Java dmcam extended suitable library configuration
  - libdmcam.dll: dmcam core lib
- Installation method
  - Add the above dll to the PATH or copy it to the executable file directory.
  - Java project references dmcam.jar
Linux
- Supported systems：
  - Linux 64bit (Ubuntu 14.04/16.04 tested)
  - Open JDK >= 7
- Java extended dynamic library includes：
  - dmcam.jar: Java extended dynamic library for importing Java projects.
  - libdmcam_java.so: Java dmcam extended suitable library configuration
  - libdmcam.so: dmcam core lib
- Installation method
  - Setting LD_LIBRAYR_PATH contains the above so/dll folder, or put the dynamic library in the system library directory, such as： /usr/local/lib/

Java API description¶

The module API in Java corresponds to the API defined in ** dmcam.h ** in the C library.。

The default namespace for Java extensions is: com.smarttof.dmcam. Can be imported via 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 name mapping(C->Java)： dmcam_xxxxx(…) -> dmcam.xxxxx(…) .For example dmcam_dev_open is mapped to dmcam.dev_open
Structure mapping(C->Java): dmcam_xxxxx -> xxxx() 。 . Structure is mapped to a class in Java. For example, create a dmcam_frame_info_t structure as follows:
```
finfo = new frame_info_t()
```
Caution

dmcam.init(null) is automatically called when the Java extension is loaded，dmcam.uninit() will be called automatically when released. So it is not necessary to use dmcam.init() and dmcam.uninit() in the program.
Accessing member variables of a structure： obj.field -> obj.getField()/setField. Member variable access needs to be performed by the get / set method corresponding to the member variable name. For example：
```
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 is mapped to null, for example:

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

The following are some differences between calling API in Java and C, need to pay attention.
dmcam.dev_list()
In Java, the device list is obtained as follows. The return value is the number of ready devices. Use example like below:
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()
Setting parameters in Java is a bit more complicated than C, and you need to construct a param_item_t instance. The specific usage example is as follows:
.. code-block:: Java
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 %% failedn”, pwr_percent);}
dmcam.param_batch_get(dev, list)
Setting parameters in Java is a bit more complicated than C, and you need to construct a param_item_t instance. The specific usage example is as follows:
.. code-block:: Java
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 and dmcam.set_callback_on_error
Java extensions do not support callback functions. When capturing, you can refer to the following settings:：
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 extension instructions¶

dmcam Android extension overview¶

Android extension provided by dmcam can facilitate Android developers’ rapid secondary development based on SmartToF camera, This document mainly describes the use of Android extensions and their associations and differences with the C API.

Android extension installation¶

Supported systems：
- Android 4.4.2
Android extended dynamic libraries include (ARM V5 and ARM V7 architecture)
- libdmcam.so: dmcam core lib
- libdmcam_java.so: Java dmcam extension adapter library
- dmcam_android.jar: android extended dynamic library, can be imported into Android projects
- libusb1.0.so: usb device driver library
Installation method
- Add all the above libraries(.so) to libs under Android project
- Add dmcam.jar under Android project

Android API description¶

Android app development is based on the Java language, so the main API description in Android and Java are basically the same, and they all correspond to the APIs defined in ** dmcam.h ** in the C library.

The default namespace expanded in Android is: com.smarttof.dmcam . Can be imported via 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;
}

The calling API in Android is basically the same as the calling API in Java，the mapping relationship is as follows: dmcam_xxxxx(…) -> dmcam.xxxxx(…) . For example dmcam_dev_close be mapped to dmcam.dev_close
Structure mapping： dmcam_xxxxx -> xxxxx() . Structure is mapped to a class in java. For example, create a dmcam_param_item_t structure as follows:
```
wparam = new param_item_t();
```
Caution

The API called when opening the device in Android is dmcam.dev_open_by_fd, not dmcam.dev_open in other environments.
Accessing member variables of a structure： obj.field -> obj.getField()/setField . Member variable access needs to be performed by the get / set method corresponding to the member variable name. For example:
```
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 is mapped to null , for example:
```
cfg.setOn_error(null);
```

The following are some differences between calling API in Android and C, need to pay attention.

dmcam.dev_open_by_fd()

To open the device under Android, you need to call the API dmcam.dev_open_by_fd () designed for Android. The specific usage example is as follows：
UsbDeviceConnection connection = usbManager.openDevice(usbDevice);
fd = connection.getFileDescriptor();
dev = dmcam.dev_open_by_fd(fd);

dmcam.param_batch_set()

Need to construct param_item_t instance, the specific example is as follows:

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()

To obtain parameters, you also need to construct an instance. The specific example is as follows:

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 and dmcam.set_callback_on_error

Callback functions are not supported in Android extensions. When capture data, you can refer to the following settings:

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 extensions instroduction¶

ROS extension design introduction¶

ROS extension Overview¶

The ROS extension function provided in the SDK is a package of the Dmcam API on the basis of ROS. When we call the ROS API, we will interact with the module through the corresponding dmcam api.

ROS extension framework¶

The correspondence between the API in ROS and the API in dmcam is as follows.

ROS extension API description¶

dmcam_ros posted topics¶

/smarttof/image_dist

Command used

rosrun image_view image_view image:=/smarttof/image_dist

Function description

Get depth data from topics posted by image_dist
/smarttof/image_gray

Command used

rosrun image_view image_view image:=/smarttof/image_gray

Function description

Get depth data from topics posted by image_gray
/smarttof/camera_info

Command used

rosrun image_view image_view image:=/smarttof/camera_info

Function description

Print camera information from topics posted by camera_info
/smarttof/pointcloud

Command used

rosrun image_view image_view image:=/smarttof/pointcloud

Function description

Display point cloud data from topics published via pointcloud from rviz

Services posted dmcam_ros¶

/smarttof/change_power

Command used

rosservice call /smarttof/change_power “power_value:<value>”

Function description

Modify the value of PARAM_ILLUM_POWER dynamically

function parameter

value defaults to 0

/smarttof/change_intg

Command used

rosservice call /smarttof/change_intg “intg_value:<value>”

Function description

Dynamically modify the value of PARAM_INTG_TIME, PARAM_INTG_TIME is the exposure time.

Function parameter

The value of the exposure time ranges from 0 to 1500

/smarttof/change_mod_freq

Command used

rosservice call /smarttof/ change_mod_freq “mod_freq_value:<value>”

Function description

Dynamically modify the value of PARAM_MOD_FREQ, PARAM_MOD_FREQ is the modulation frequency.

Function parameter

The value is currently fixed at 12MHz

/smarttof/change_frame_rate

Command used

rosservice call /smarttof/ change_frame_rate “frame_rate_value:<value>”

Function description

Dynamically modify the value of PARAM_FRAME_RATE, PARAM_INTG_TIME is the exposure time.

Function parameter

PARAM_FRAME_RATE is the frame rate ranges from 1 to 30

/smarttof/change_sync_delay

Command used

rosservice call /smarttof/ change_sync_delay “sync_delay_value:<value>”

Function description

Dynamically modify the value of PARAM_SYNC_DELAY, PARAM_SYNC_DELAY is the synchronization delay time.

Function parameter

PARAM_FRAME_RATE is the frame rate ranges from 1 to 30

/smarttof/change_filter

Command used

rosservice call /smarttof/change_filter “filter_id: ‘<id>’filter_value:<value>”

Function description

Turn on the filtering function of the specified id value in filter_id

Function parameter

The id value in filter_id can be set to:

DMCAM_FILTER_ID_LEN_CALIB //Lens calibration

DMCAM_FILTER_ID_PIXEL_CALIB //Pixel calibration

DMCAM_FILTER_ID_RESERVED //Not currently supported

DMCAM_FILTER_ID_AMP //amplitude filter

DMCAM_FILTER_ID_AUTO_INTG //exposure time

DMCAM_FILTER_ID_SYNC_DELAY //Not currently supported

DMCAM_FILTER_ID_TEMP_MONITOR //Not currently supported

DMCAM_FILTER_ID_HDR //HDR mode

DMCAM_FILTER_ID_OFFSET //distance offset

DMCAM_FILTER_ID_SPORT_MODE //sport mode

DMCAM_FILTER_ID_SYS_CALIB //Not currently supported

DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB //Not currently supported

Currently only the value of filter_value needs to be set in, DMCAM_FILTER_ID_AMP, the range is 0-100

The value of other filter_value can be 0 by default

/smarttof/disable_filter

Command used

rosservice call /smarttof/disable_filter “filter_id: ‘<id>’”

Function description

Turn off the filtering function of the specified id value in filter_id

Function parameter

The id value in filter_id can be set to:

DMCAM_FILTER_ID_LEN_CALIB //Lens calibration

DMCAM_FILTER_ID_PIXEL_CALIB //Pixel calibration

DMCAM_FILTER_ID_RESERVED //Not currently supported

DMCAM_FILTER_ID_AMP //amplitude filter

DMCAM_FILTER_ID_AUTO_INTG //exposure time

DMCAM_FILTER_ID_SYNC_DELAY //Not currently supported

DMCAM_FILTER_ID_TEMP_MONITOR //Not currently supported

DMCAM_FILTER_ID_HDR //HDR mode

DMCAM_FILTER_ID_OFFSET //distance offset

DMCAM_FILTER_ID_SPORT_MODE //sport mode

DMCAM_FILTER_ID_SYS_CALIB //Not currently supported

DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB //Not currently supported

OpenNI2 extension¶

OpenNI2 extension introduction¶

n order to support the framework in OpenNI2 to implement the call to the Smart module, the corresponding driver library samrttof.dll is provided in the SDK, This driver follows the definition of OpenNI2 in OniDriverAPI.h, which mainly includes DriverService, DriverBase, DeviceBase, StreamBase In these several categories, the driver source code for smarttof.dll is released in the SDK.

SmartToF module settings¶

All related parameter settings and use of filtering functions in SmartToF are performed through the setProperty function in the smarttofStream class, according to setProperty set the corresponding propertyId.

The following table lists the property ID of the property:

function ID	Description
PROPERTY_ID_PARAM_SET	Module parameter setting IDID
PROPERTY_ID_PARAM_GET	Module parameter acquisition ID
PROPERTY_ID_FILTER_LEN_CALIB_ENABLE	Lens filter enable
PROPERTY_ID_FILTER_LEN_CALIB_DISABLE	Lens filter disable
PROPERTY_ID_FILTER_PIXEL_CALIB_ENABLE	Pixel filtering enabled
PROPERTY_ID_FILTER_PIXEL_CALIB_DISABLE	Pixel filtering disabled
PROPERTY_ID_FILTER_AMP_CALIB_ENABLE	Amplitude filtering enabled
PROPERTY_ID_FILTER_AMP_CALIB_DISABLE	Amplitude filtering disabled
PROPERTY_ID_FILTER_AUTO_INTG_ENABLE	Auto exposure enabled
PROPERTY_ID_FILTER_AUTO_INTG_DISABLE	Auto exposure disabled
PROPERTY_ID_FILTER_TEMP_MONITOR_ENABLE	Temperature monitoring enabled
PROPERTY_ID_FILTER_TEMP_MONITOR_DISABLE	Temperature monitoring disabled
PROPERTY_ID_FILTER_HDR_ENABLE	HDR function enable
PROPERTY_ID_FILTER_HDR_DISABLE	HDR function disable

Sample code for module setup under OpenNI2¶

In OpenNI2, you can set the property ID in the above list to the SmartToF module through setProperty. For specific setting code examples, please refer to the setting of integration time code below.:

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));

The code to get the module settings is as follows:

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);