libo3d3xx

Library and utilities for working with IFM Efector O3D3xx PMD-based ToF Cameras.

Software Compatibility Matrix

libo3d3xx version	IFM Firmware Version	Supported Cameras	Notes
0.1.7	0.06.13	O3D303	Initial Release
0.1.8	0.06.39	O3D303	DEPRECATED, USE 0.1.9
0.1.9	0.06.39	O3D303	Initial support for 100k pixel images
0.1.10	0.06.39	O3D303	DEPRECATED, USE 0.1.11
0.1.11	0.06.39	O3D303	Adds the XYZ OpenCV image
0.2.0	1.1.288	O3D303	Cross-compilation support and exposing raw amplitude image
0.3.0	1.3.1001	O3D303	100k pixel support, pluggable pcic schemas, exposing extrinsics and unit vectors, installing to /usr, and more.
0.4.0	1.3.1001	O3D303	Split up of the library into 3 modules: camera, framegrabber, image.
0.4.1	1.4.1639	O3D303	Updates for Firmware version-1.4.x XML-RPC protocol changes.
0.4.2	1.4.1639	O3D303	Fixed unit test validating Extrinsics (image module)
0.4.3	1.4.1639	O3D303	Updated build scripts for Ubuntu 16.04 LTS (Xenial) and parallel installs of OpenCV 3 and 2.4 (e.g., systems w/ ROS Kinetic installed)
0.4.4	1.4.1639	O3D303	SW triggering in framegrabber.
0.4.5	1.4.1639	O3D303	SW triggering supports multiple concurrent PCIC connections
0.4.6	1.6.2038	O3D303	Updates to XML-RPC protocol for 1.6 firmware
0.4.8	1.6.2038	O3D303	Framegrabber is more robust to H/W volatility
0.4.9	1.8.XXX (testing was: 1.5.698, 1.5.759)	O3D303	Support for v2 image chunk headers, ability to modulate exposure times on the fly.

Features

High-level features of this library include:

• The code is written in modern C++11 (and will continue to evolve with the standard C++14, C++17, and beyond as compiler support matures).
• The library is modular, allowing developers to use only the parts they need without incurring the overhead of unnecessary dependencies.
• The image module of the library employs PCL and OpenCV native image formats for users who wish to immediately take advantage of the time-tested algorithms from these widely popular open-source packages.
• Easily scriptable command line utilities are provided for performing common tasks associated with configuring, backing up, restoring, and introspecting, the camera settings. This scriptability lends itself to managing fleets of cameras for large-scale installations.
• A simple viewer application is provided (as part of the image module) for concurrently inspecting the point cloud, depth, amplitude, and confidence images.
• A business-friendly (Apache 2.0) License is employed.
• The code is being actively developed and maintained at Love Park Robotics. Pull requests are welcome from those who wish to contribute code!

ROS bindings are available here

Prerequisites

Camera Module

Implements the XML-RPC protocol employed by the O3D3xx cameras and provides a set of command-line utilities for configuring and managing the camera or fleet of cameras.

• Boost (>= 1.54)
• Gtest (unit testing)
• Glog (logging infrastructure)
• libxmlrpc
• CMake (>= 2.8.12)

Framegrabber Module

Implements a framegrabber for acquiring image data from the O3D3xx. Additionally, this module defines a ByteBuffer interface allowing developers to bridge the image data from the camera to their favorite image and point cloud data structures.

• libo3d3xx_camera (part of this project)

Image Module

Bridges the O3D3xx to OpenCV and PCL utilizing the framegrabber module's ByteBuffer interface.

• libo3d3xx_camera (part of this project)
• libo3d3xx_framegrabber (part of this project)
• OpenCV (>= 2.4)
• PCL (>= 1.7.1)

Additionally, your compiler must support a modern C++ implementation, i.e., C++11. You should note that we will not hesitate to employ features in C++14/17 and beyond as necessary. Bottom-line: keep your compiler current. We have validated:

• g++ 4.8.x on Ubuntu Linux 14.04 LTS
• g++ 5.3.x on Ubuntu Linux 16.04 LTS

Installation (from source)

(Assumes Ubuntu Linux)

Quick Start

If you want to build, test, and install all three modules (camera, framegrabber, and image) and you want to accept the default build options, these are the directions you want to follow.

Assuming you are starting from the top-level directory of this source distribution:

$ mkdir build
$ cd build
$ cmake ..
$ make

That is it, you are done! Please don't walk away from your computer while the code is building. To install the packages, we need root access, so, a sudo is issued and will prompt you for your password.

NOTE: This automated build runs make check to run the unit tests. It assumes that the hardware is available and running with factory default settings. If your camera is using an IP address different from the factory default of 192.168.0.69, you can set the O3D3XX_IP environment variable to point to the proper IP. Please note, the unit tests will wipe out your current camera settings and applications. You should back up your camera prior to running the unit tests.

Full Instructions

If you need finer-grained control over the build of the individual modules, you are not on Ubuntu, you want to selectively build a module, or you are cross-compiling, etc., these are the instructions for you.

NOTE: The dpkg commands issued in support of the installation(s) are here as an example. The particular version and architecture may differ on your computer.

Building the camera module

Assuming you are starting from the top-level directory of this source distribution:

$ cd modules/camera
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make
$ make check
$ make package
$ sudo dpkg -i libo3d3xx-camera_0.4.0_amd64.deb

If you are not on Debian or Ubuntu, you can substitute the make package and dpkg ... commands with make install.

Building the framegrabber module

(You must ensure that you have already installed the camera module prior to building and installing the framegrabber module.)

Assuming you are starting from the top-level directory of this source distribution:

$ cd modules/framegrabber
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make
$ make check
$ make package
$ sudo dpkg -i libo3d3xx-framegrabber_0.4.0_amd64.deb

If you are not on Debian or Ubuntu, you can substitute the make package and dpkg ... commands with make install.

Building the image module

(You must ensure that you have already installed the camera and framegrabber modules prior to building and installing the image module.)

Assuming you are starting from the top-level directory of this source distribution:

$ cd modules/image
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make
$ make check
$ make package
$ sudo dpkg -i libo3d3xx-image_0.4.0_amd64.deb

If you are not on Debian or Ubuntu, you can substitute the make package and dpkg ... commands with make install.

Also note that due to some library changes (and a VTK bug) from Ubuntu 14.04 to 16.04, linking the o3d3xx-viewer and building the deb file dependencies now has some conditional code in the build scripts to accomodate for this. If you are on Ubuntu (and you don't mess with your /etc/issue file), the build scripts auto-detect your Ubuntu version and try to do the right thing. However, if you are not on Ubuntu, you have to give the build some extra hints. Specifically, in the cmake line above, you can lie to us and tell us you are on a particular Ubuntu version, for example:

$ cmake -DUBUNTU_VERSION:STRING=16.04 ..

So, the above line will have the build scripts act as if you are on the 16.04 variant of Ubuntu.

Customizing the builds

If you are building the modules individually, you can further customize the build by supplying -D... options on the cmake command line. To see what is available to you, please look at the individual module's top-level CMakeLists.txt file. For example, this snippet is from the camera module:

# These can be set with -D... on the command line
option(BUILD_TESTS "Build unit tests" ON)
option(BUILD_SHARED_LIBS "Build shared libraries" ON)
option(BUILD_STATIC_LIBS "Build static libraries" ON)
option(BUILD_EXE_VERSION "Build o3d3xx-version" ON)
option(BUILD_EXE_RESET "Build o3d3xx-reset" ON)
option(BUILD_EXE_LS "Build o3d3xx-ls" ON)
option(BUILD_EXE_DUMP "Build o3d3xx-dump" ON)
option(BUILD_EXE_CONFIG "Build o3d3xx-config" ON)
option(BUILD_EXE_RM "Build o3d3xx-rm" ON)
option(BUILD_EXE_REBOOT "Build o3d3xx-reboot" ON)
option(BUILD_EXE_IMAGER_TYPES "Build o3d3xx-imager-types" ON)
option(BUILD_EXE_IFM_IMPORT "Build o3d3xx-ifm-import" ON)
option(BUILD_EXE_IFM_EXPORT "Build o3d3xx-ifm-export" ON)

So, for example, if you did not want to build and run the unit tests (bad idea, BTW), you could:

$ mkdir build
$ cd build
$ cmake -DBUILD_TESTS=OFF ..
$ ... etc ...

Cross-compiling

Please see the cross compiling article.

Running

• Command-line utilities
• Examples

Known Issues, Bugs, and our TODO list

Please see the Github Issues.

LICENSE

Please see the file called LICENSE.

AUTHORS

Tom Panzarella [email protected]