Merge pull request #888 from VictorLamoine/ensenso

Add Ensenso support
PointCloudLibrary · Oct 16, 2014 · 75d97aa · 75d97aa · aecins · Oct 18, 2014
2 parents 9ec37a5 + f513f15
commit 75d97aa
Show file tree

Hide file tree

Showing 16 changed files with 1,145 additions and 4 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -288,6 +288,17 @@ if(WITH_FZAPI)
   endif(FZAPI_FOUND)
 endif(WITH_FZAPI)
 
+# IDS-Imaging - Ensenso
+option(WITH_ENSENSO "Build IDS-Imaging Ensenso's camera support" TRUE)
+if(WITH_ENSENSO)
+  set(ENSENSO_ABI_DIR "$ENV{PROGRAMW6432}/Ensenso/development/c" CACHE PATH "directory of Ensenso ABI")
+  find_package(Ensenso) # FindEnsenso.cmake
+  if (ENSENSO_FOUND)
+    set(HAVE_ENSENSO ON)
+    include_directories(SYSTEM "${ENSENSO_INCLUDE_DIRS}")
+  endif(ENSENSO_FOUND)
+endif(WITH_ENSENSO)
+
 # Intel Perceptional Computing Interface (PXCAPI)
 option(WITH_PXCAPI "Build PXC Device support" TRUE)
 if(WITH_PXCAPI)
@@ -441,3 +452,4 @@ MAKE_DEP_GRAPH()
 ### ---[ Finish up
 PCL_WRITE_STATUS_REPORT()
 PCL_RESET_MAPS()
+
diff --git a/PCLConfig.cmake.in b/PCLConfig.cmake.in
@@ -247,6 +247,38 @@ macro(find_openni2)
   endif(OPENNI2_FOUND)
 endmacro(find_openni2)
 
+#remove this as soon as the Ensenso SDK is shipped with FindEnsenso.cmake
+macro(find_ensenso)
+  if(NOT ENSENSO_ROOT AND ("ON" STREQUAL "ON"))
+    get_filename_component(ENSENSO_ABI_HINT @ENSENSO_INCLUDE_DIR@ PATH)
+  endif(NOT ENSENSO_ROOT AND ("ON" STREQUAL "ON"))
+
+  find_path(ENSENSO_INCLUDE_DIR nxLib.h
+            HINTS ${ENSENSO_ABI_HINT}
+            /opt/ensenso/development/c
+            "$ENV{PROGRAMFILES}/Ensenso/development/c" "$ENV{PROGRAMW6432}/Ensenso/development/c"
+            PATH_SUFFIXES include/)
+
+  find_library(ENSENSO_LIBRARY QUIET NAMES NxLib64 NxLib32 nxLib64 nxLib32
+               HINTS ${ENSENSO_ABI_HINT}
+               "$ENV{PROGRAMFILES}/Ensenso/development/c" "$ENV{PROGRAMW6432}/Ensenso/development/c"
+               PATH_SUFFIXES lib/)
+
+  set(ENSENSO_LIBRARIES ${ENSENSO_LIBRARY})
+  set(ENSENSO_INCLUDE_DIRS ${ENSENSO_INCLUDE_DIR})
+
+  include(FindPackageHandleStandardArgs)
+  find_package_handle_standard_args(ensenso DEFAULT_MSG
+                                    ENSENSO_LIBRARY ENSENSO_INCLUDE_DIR)
+
+  if(ENSENSO_FOUND)
+    get_filename_component(ENSENSO_LIBRARY_PATH ${ENSENSO_LIBRARY} PATH)
+    set(ENSENSO_LIBRARY_DIRS ${ENSENSO_LIBRARY_PATH}) 
+    set(ENSENSO_LIBRARIES "${ENSENSO_LIBRARY}")
+    set(ENSENSO_REDIST_DIR $ENV{ENSENSO_REDIST${ENSENSO_SUFFIX}})
+  endif(ENSENSO_FOUND)
+endmacro(find_ensenso)
+
 #remove this as soon as flann is shipped with FindFlann.cmake
 macro(find_flann)
   if(PCL_ALL_IN_ONE_INSTALLER)
@@ -442,6 +474,8 @@ macro(find_external_library _component _lib _is_optional)
     find_openni()
   elseif("${_lib}" STREQUAL "openni2")
     find_openni2()
+  elseif("${_lib}" STREQUAL "ensenso")
+    find_ensenso()
   elseif("${_lib}" STREQUAL "vtk")
     find_VTK()
   elseif("${_lib}" STREQUAL "libusb-1.0")
@@ -718,7 +752,8 @@ endif(NOT "${PCL_DEFINITIONS}" STREQUAL "")
 pcl_remove_duplicate_libraries(PCL_LIBRARIES PCL_DEDUP_LIBRARIES)
 set(PCL_LIBRARIES ${PCL_DEDUP_LIBRARIES})
 # Add 3rd party libraries, as user code might include our .HPP implementations
-list(APPEND PCL_LIBRARIES ${BOOST_LIBRARIES} ${QHULL_LIBRARIES} ${OPENNI_LIBRARIES} ${OPENNI2_LIBRARIES} ${FLANN_LIBRARIES} ${VTK_LIBRARIES})
+list(APPEND PCL_LIBRARIES ${BOOST_LIBRARIES} ${QHULL_LIBRARIES} ${OPENNI_LIBRARIES} ${OPENNI2_LIBRARIES} ${ENSENSO_LIBRARIES} ${FLANN_LIBRARIES} ${VTK_LIBRARIES})
 
 find_package_handle_standard_args(PCL DEFAULT_MSG PCL_LIBRARIES PCL_INCLUDE_DIRS)
 mark_as_advanced(PCL_LIBRARIES PCL_INCLUDE_DIRS PCL_LIBRARY_DIRS)
+
diff --git a/cmake/Modules/FindEnsenso.cmake b/cmake/Modules/FindEnsenso.cmake
@@ -0,0 +1,35 @@
+###############################################################################
+# - Try to find Ensenso SDK (IDS-Imaging)
+# Once done this will define
+#  ENSENSO_FOUND - System has Ensenso SDK
+#  ENSENSO_INCLUDE_DIRS - The Ensenso SDK include directories
+#  ENSENSO_LIBRARIES - The libraries needed to use Ensenso SDK
+#  ENSENSO_DEFINITIONS - Compiler switches required for using Ensenso SDK
+# -----------------------
+
+find_path(ENSENSO_INCLUDE_DIR nxLib.h
+          HINTS ${ENSENSO_ABI_HINT}
+          /opt/ensenso/development/c
+          "$ENV{PROGRAMFILES}/Ensenso/development/c" "$ENV{PROGRAMW6432}/Ensenso/development/c"
+          PATH_SUFFIXES include/)
+
+find_library(ENSENSO_LIBRARY QUIET NAMES NxLib64 NxLib32 nxLib64 nxLib32
+             HINTS ${ENSENSO_ABI_HINT}
+             "$ENV{PROGRAMFILES}/Ensenso/development/c" "$ENV{PROGRAMW6432}/Ensenso/development/c"
+             PATH_SUFFIXES lib/)
+
+set(ENSENSO_LIBRARIES ${ENSENSO_LIBRARY})
+set(ENSENSO_INCLUDE_DIRS ${ENSENSO_INCLUDE_DIR})
+
+include(FindPackageHandleStandardArgs)
+# handle the QUIETLY and REQUIRED arguments and set ENSENSO_FOUND to TRUE
+# if all listed variables are TRUE
+find_package_handle_standard_args(ensenso DEFAULT_MSG
+                                  ENSENSO_LIBRARY ENSENSO_INCLUDE_DIR)
+
+mark_as_advanced(ENSENSO_INCLUDE_DIR ENSENSO_LIBRARY)
+
+if(ENSENSO_FOUND)
+  message(STATUS "Ensenso SDK found")
+endif(ENSENSO_FOUND)
+
diff --git a/doc/doxygen/doxyfile.in b/doc/doxygen/doxyfile.in
@@ -278,6 +278,7 @@ INCLUDE_FILE_PATTERNS  = *.h
 #PREDEFINED            = protected=private \
 PREDEFINED =           = "HAVE_QHULL=1" \
                          "HAVE_OPENNI=1" \
+                         "HAVE_ENSENSO=1" \
                          "PCL_DEPRECATED(x)="
 EXPAND_AS_DEFINED      = 
 SKIP_FUNCTION_MACROS   = YES

diff --git a/doc/tutorials/content/ensenso_cameras.rst b/doc/tutorials/content/ensenso_cameras.rst
@@ -0,0 +1,80 @@
+.. _ensenso_cameras:
+
+==========================================
+Grabbing point clouds from Ensenso cameras
+==========================================
+
+In this tutorial we will learn how to use the `IDS-Imaging <http://en.ids-imaging.com/>`_ Ensenso cameras within PCL. This tutorial will show you how to configure PCL
+and how to use the examples to fetch point clouds from the `Ensenso <http://www.ensenso.de/>`_.
+
+.. contents::
+
+Install Ensenso drivers
+=======================
+
+The Ensenso drivers are free (as in beer) and available for download, for each of them follow the instructions provided:
+
+  * `uEye <http://en.ids-imaging.com/download-ueye.html>`_
+  * `Ensenso SDK <http://www.ensenso.de/download>`_
+
+Plug-in the camera and test if the Ensenso is working, launch ``nxView`` in your terminal to check if you can actually use the camera.
+
+Configuring PCL
+===============
+
+You need at least PCL 1.8.0 to be able to use the Ensenso cameras. You need to make sure ``WITH_ENSENSO`` is set to ``true`` in the CMake 
+configuration (it should be set to true by default if you have followed the instructions before).
+
+The default following values can be tweaked into cmake if you don't have a standard installation, for example:
+
+.. code-block::
+
+  ENSENSO_ABI_DIR     /opt/ensenso_test/development/c
+
+You can deactivate building the Ensenso support by setting ``BUILD_ENSENSO`` to false.
+Compile and install PCL.
+
+Using the example
+==================
+
+The `pcl_ensenso_viewer <https://github.com/PointCloudLibrary/pcl/blob/master/visualization/tools/ensenso_viewer.cpp>`_ example shows how to
+display a point cloud grabbed from an Ensenso device using the `EnsensoGrabber <http://docs.pointclouds.org/trunk/classpcl_1_1_ensenso_grabber.html>`_ class.
+
+Note that this program opens the TCP port of the nxLib tree, this allows you to open the nxLib tree with the nxTreeEdit program (port 24000).
+The capture parameters (exposure, gain etc..) are set to default values.
+If you have performed and stored an extrinsic calibration it will be temporary reset.
+
+.. code-block:: cpp
+
+  ensenso_grabber->enumDevices ();
+  ensenso_grabber->openTcpPort ();
+  ensenso_grabber->openDevice ();
+  ensenso_grabber->configureCapture ();
+  ensenso_grabber->setExtrinsicCalibration ();
+
+The code is very similar to the ``pcl_openni_viewer``.
+All the Ensenso devices connected are listed and then the point cloud are fetched as fast as possible.
+
+Here is an example of the terminal output ::
+   
+   $ pcl_ensenso_viewer 
+   Initialising nxLib
+   Number of connected cameras: 1
+   Serial No    Model   Status
+   140242   N10-1210-18   Available
+   
+   Opening Ensenso stereo camera id = 0
+   
+   FPS: 4.46927
+   FPS: 5.01253
+   FPS: 5.16351
+   FPS: 5.27506
+   FPS: 5.32569
+   FPS: 5.51645
+   FPS: 5.53013
+   FPS: 5.56729
+   Closing Ensenso stereo camera
+
+.. image:: images/ensenso/ensenso_viewer.jpg
+  :height: 550
+
diff --git a/doc/tutorials/content/images/ensenso/ensenso_viewer.jpg b/doc/tutorials/content/images/ensenso/ensenso_viewer.jpg
diff --git a/doc/tutorials/content/images/ensenso/ids.png b/doc/tutorials/content/images/ensenso/ids.png
diff --git a/doc/tutorials/content/index.rst b/doc/tutorials/content/index.rst
@@ -601,6 +601,21 @@ I/O
      .. |i_o6| image:: images/dinast_cyclopes.png
                :height: 100px
 
+  * :ref:`ensenso_cameras`
+
+     ======  ======
+     |i_o7|  Title: **Grabbing point clouds from Ensenso cameras**
+
+             Author: *Victor Lamoine*
+
+             Compatibility: >= PCL 1.8.0
+
+             In this tutorial, we will learn how to acquire point cloud data from an IDS-Imaging Ensenso camera.
+     ======  ======
+
+     .. |i_o7| image:: images/ensenso/ids.png
+               :height: 165px
+
 
 .. _keypoints_tutorial:
 

diff --git a/io/CMakeLists.txt b/io/CMakeLists.txt
@@ -5,9 +5,9 @@ set(SUBSYS_DEPS common octree)
 set(build TRUE)
 PCL_SUBSYS_OPTION(build "${SUBSYS_NAME}" "${SUBSYS_DESC}" ON)
 if(WIN32)
-    PCL_SUBSYS_DEPEND(build "${SUBSYS_NAME}" DEPS ${SUBSYS_DEPS} OPT_DEPS openni openni2 pcap png vtk)
+    PCL_SUBSYS_DEPEND(build "${SUBSYS_NAME}" DEPS ${SUBSYS_DEPS} OPT_DEPS openni openni2 ensenso pcap png vtk)
 else(WIN32)
-    PCL_SUBSYS_DEPEND(build "${SUBSYS_NAME}" DEPS ${SUBSYS_DEPS} OPT_DEPS openni openni2 pcap png vtk libusb-1.0)
+    PCL_SUBSYS_DEPEND(build "${SUBSYS_NAME}" DEPS ${SUBSYS_DEPS} OPT_DEPS openni openni2 ensenso pcap png vtk libusb-1.0)
 endif(WIN32)
 
 PCL_ADD_DOC("${SUBSYS_NAME}")
@@ -137,6 +137,23 @@ if(build)
             )
     endif(FZAPI_FOUND)
 
+    ## Ensenso
+    OPTION(BUILD_ENSENSO "Build the Ensenso Grabber." ON)
+    MARK_AS_ADVANCED(BUILD_ENSENSO)
+    if(NOT BUILD_ENSENSO)
+      # Set ENSENSO_FOUND to false locally to avoid building anything Ensenso related
+      # Remember that other modules (libraries) need to check explicitly for BUILD_ENSENSO
+      set(ENSENSO_FOUND FALSE)
+    endif()
+    if(ENSENSO_FOUND)
+        set(ENSENSO_GRABBER_INCLUDES
+            include/pcl/io/ensenso_grabber.h
+            )
+        set(ENSENSO_GRABBER_SOURCES
+            src/ensenso_grabber.cpp
+            )
+    endif(ENSENSO_FOUND)
+
 	if(PXCAPI_FOUND)
 		set(PXC_GRABBER_INCLUDES
 			include/pcl/io/pxc_grabber.h
@@ -207,6 +224,7 @@ if(build)
         ${IMAGE_SOURCES}
         ${DINAST_GRABBER_SOURCES}
         ${FZAPI_GRABBER_SOURCES}
+        ${ENSENSO_GRABBER_SOURCES}
         ${PXC_GRABBER_SOURCES}
         )
     if(PNG_FOUND)
@@ -250,6 +268,7 @@ if(build)
         ${IMAGE_INCLUDES}
         ${DINAST_GRABBER_INCLUDES}
         ${FZAPI_GRABBER_INCLUDES}
+        ${ENSENSO_GRABBER_INCLUDES}
         ${PXC_GRABBER_INCLUDES}
         )
 
@@ -317,6 +336,10 @@ if(build)
   	  endif(WIN32)
     endif(FZAPI_FOUND)
 
+    if(ENSENSO_FOUND)
+      target_link_libraries(${LIB_NAME} ${ENSENSO_LIBRARIES})
+    endif(ENSENSO_FOUND)
+
 	if(PXCAPI_FOUND)
 	  link_directories(${PXCAPI_LIB_DIRS})
 	  target_link_libraries("${LIB_NAME}" ${PXCAPI_LIBS})
@@ -334,6 +357,9 @@ if(build)
     if(OPENNI2_FOUND)
       list(APPEND EXT_DEPS libopenni2)
     endif(OPENNI2_FOUND)
+    if(ENSENSO_FOUND)
+      list(APPEND EXT_DEPS ensenso)
+    endif(ENSENSO_FOUND)
 
     PCL_MAKE_PKGCONFIG("${LIB_NAME}" "${SUBSYS_NAME}" "${SUBSYS_DESC}"
       "${SUBSYS_DEPS}" "${EXT_DEPS}" "" "" "")