ifm3d
Library and utilities for working with ifm pmd-based 3D ToF Cameras.
Current Revision
ifm3d version | Supported O3D Firmware Version | Supported O3X Firmware Version | Supported Ubuntu Linux Version | Notes |
---|---|---|---|---|
0.10.0 | 1.6.2114, 1.8.769, 1.20.1138, 1.23.1506, 1.23.1522 | 1.0.111, 1.0.122, 1.0.126 | 16.04,18.04 | Session IDs can be explicitly set and shared across camera instances. Speed improvements to JSON imports. |
A full software compatibility matrix, including older releases, is available here.
Organization of the Software
The ifm3d software is organized into modules, they are:
Module Name | Description |
---|---|
camera | Provides an implementation of the XMLRPC protocol for configuring the camera and pmd imager settings. |
framegrabber | Provides an implementation of the PCIC protocol for streaming pixel data and triggered image acquisition. |
image | Provides a bridge from raw camera bytes to OpenCV and PCL image encodings. |
opencv | This is an officially supported and alternate data container to the default Image module. This module provides a bridge from raw camera bytes to OpenCV image encodings without any dependence upon PCL. |
pcicclient | Direct access to PCIC to, for example, actuate digital IO. |
tools | Provides the ifm3d command line tool for manipulating and introspecting the hardware interactively. It is also suitable for usage within shell scripts to, for example, manage fleets of cameras. |
As of version 0.9.0, we have removed the viewer
sub-command from the ifm3d
command line tool (part of the tools
module). The objective was to lessen the
dependencies for the core library. However, a clone of the pre-0.9.0
viewer is available in its own repository:
ifm3d-pcl-viewer.
Installing the Software
Build Dependencies
Dependency | Dependent ifm3d module | Notes |
---|---|---|
Boost | framegrabber, pcicclient, tools | We use Boost ASIO (header-only) to handle cross-platform network communication with the camera. While ASIO itself is header-only, it does require runtime linking to Boost System. We also use Boost Program Options to handle command line parsing in the tools module. |
CMake | camera, framegrabber, image, opencv, pcicclient, tools | Meta-build framework |
Curl | tools | Used to help enable command-line based firmware flashing. |
Glog | camera, framegrabber, image, opencv, pcicclient, tools | Logging framework |
Gtest | camera, framegrabber, image, opencv, pcicclient, tools | Unit testing framework |
libxmlrpc | camera | XMLRPC client used call into the camera configuration interface |
OpenCV | image, opencv | N-dimensional array container for encoding 2d and 3d image data |
PCL | image | A 3D point cloud encoding. NOTE: the PCL dependency in ifm3d is header-only (we need to construct a point cloud) however there is no runtime linking dependency. |
Additionally, if you plan to build the debian packages and have the
dependencies computed for you dynamically (see the note below on the
repackage
target), you will also need:
- Python 2.7
- readelf (Part of the
binutils
package) - ldd (Part of the
libc-bin
package) - dpkg
We note that, if you are running on a supported Linux, all of these packages
are available through the offical debian repositories and should be a simple
apt-get
away from being installed on your machine.
Use the following steps to install all the library dependencies on Debian based systems
$ sudo apt-get update && apt-get -y upgrade
$ sudo apt-get update && apt-get install -y libboost-all-dev git jq libcurl4-openssl-dev \
libgtest-dev libgoogle-glog-dev \
libxmlrpc-c++8-dev libopencv-dev \
libpcl-dev libproj-dev \
build-essential coreutils cmake
Note: The package name may differ in different flavours of Linux. Above apt-get commands are specific to Debian based systems
Building From Source
The default build
By default, the ifm3d
build enables the camera
, framegrabber
, image
,
and tools
modules. Building the software follows the usual cmake idiom of:
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make
$ make check
$ sudo make install
Alternatively, if you are on a supported Linux platform (see above), the preferred method of building and installing the software is:
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make
$ make check
$ make package
$ make repackage
$ sudo dpkg -i ifm3d_0.9.0_amd64-camera.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-framegrabber.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-image.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-tools.deb
(The version number embedded in the deb file will be dependent upon which
version of the ifm3d
software you are building)
A few important notes when building from source:
-
For the
make check
step, you will need to have your camera plugged in. The camera settings will get mutated by this process, so, you are encouraged to back up your configuration if you'd like to later restore your camera to its pre-testing state. You are also encouraged to test against the camera (or cameras) you plan to use. I.e., O3D, O3X, etc. -
Many
ifm3d
users ultimately plan to use this library along with its associated ROS wrapper. If this is the case, you need to be sure that the version of OpenCV that you link to in bothifm3d
andifm3d-ros
are consistent. To give you some control over that, the build process allows you to explicitly call out which version of OpenCV you wish to use. For example, if you are using OpenCV 2.4, yourcmake
line above should look something like:$ cmake -DCMAKE_INSTALL_PREFIX=/usr -DFORCE_OPENCV2=ON ..
. Similarly, if you using OpenCV 3, yourcmake
line above should look something like:$ cmake -DCMAKE_INSTALL_PREFIX=/usr -DFORCE_OPENCV3=ON ..
-
Experienced users may be puzzled by the
repackage
step. If you are simply building for your local machine, you can skip it (albeit, with minimal risk). This step is used to dynamically compute the debian dependencies for the particular module. Due to how we are partitioning out the software, this approach is necessary vs. the more traditionalCPACK_DEBIAN_PACKAGE_SHLIBDEPS
wrapper arounddpkg-shlibdeps
. We basically created a version of that tool that exploits a-priori information about theifm3d
environment to properly compute the debian dependencies. If you are building debs on a build machine to be distributed out to various runtime computers, you will certainly want to execute therepackage
target so that you are ensured the runtime machines have the proper dependency chain in place.
A build that does not require PCL
Many ifm3d
users seem to be moving away from PCL. To that end, it is possible
to build ifm3d
without any reliance on PCL yet still maintain a bridge to
OpenCV image encodings. (NOTE: As of 0.9.0, it is also quite easy to build your
own image encoding to interoperate within the ifm3d
ecosystem.)
Building ifm3d
without a PCL dependency looks like the following:
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_MODULE_OPENCV=ON -DBUILD_MODULE_IMAGE=OFF ..
$ make
$ make check
$ make package
$ make repackage
$ sudo dpkg -i ifm3d_0.9.0_amd64-camera.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-framegrabber.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-opencv.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-tools.deb
A sumo-build
If you want to build everything:
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_MODULE_OPENCV=ON -DBUILD_MODULE_PCICCLIENT=ON ..
$ make -j 8
$ make check
$ make package
$ make repackage
$ sudo dpkg -i ifm3d_0.9.0_amd64-camera.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-framegrabber.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-image.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-opencv.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-tools.deb
$ sudo dpkg -i ifm3d_0.9.0_amd64-pcicclient.deb
Additional Resources
- Building on Windows
- Basic library usage
- ifm3d command line tool
- Configuring Your Camera
- Viewing the Point Cloud
- Implementing your own image container
- ROS
- Troubleshoot
Known Issues, Bugs, and our TODO list
Please see the Github Issue Tracker.
LICENSE
Please see the file called LICENSE.