gsoc_2015: sfm module integration

modules/sfm/CMakeLists.txt

@@ -0,0 +1,128 @@
+set(the_description "SFM algorithms")
+
+
+### LIBMV LIGHT EXTERNAL DEPENDENCIES ###
+
+find_package(Ceres QUIET)
+
+if(NOT DEFINED SFM_DEPS_OK)
+
+  if(NOT DEFINED GLOG_LIBRARIES)
+    set(GLOG_LIBRARIES "glog")
+  endif()
+
+  set(_fname "${CMAKE_CURRENT_BINARY_DIR}/test_sfm_deps.cpp")
+  file(WRITE "${_fname}" "#include <glog/logging.h>\n#include <gflags/gflags.h>\nint main() { (void)(0); return 0; }\n")
+  try_compile(SFM_DEPS_OK "${CMAKE_CURRENT_BINARY_DIR}" "${_fname}"
+      CMAKE_FLAGS "-DINCLUDE_DIRECTORIES:STRING=${GLOG_INCLUDE_DIRS};${GFLAGS_INCLUDE_DIRS}"
+      LINK_LIBRARIES ${GLOG_LIBRARIES} ${GFLAGS_LIBRARIES}
+      OUTPUT_VARIABLE OUTPUT
+  )
+  file(REMOVE "${_fname}")
+  message(STATUS "Checking SFM deps... ${SFM_DEPS_OK}")
+endif()
+
+if(NOT HAVE_EIGEN OR NOT SFM_DEPS_OK)
+  set(DISABLE_MSG "Module opencv_sfm disabled because the following dependencies are not found:")
+  if(NOT HAVE_EIGEN)
+    set(DISABLE_MSG "${DISABLE_MSG} Eigen")
+  endif()
+  if(NOT SFM_DEPS_OK)
+    set(DISABLE_MSG "${DISABLE_MSG} Glog/Gflags")
+  endif()
+  message(STATUS ${DISABLE_MSG})
+  ocv_module_disable(sfm)
+endif()
+
+
+### LIBMV LIGHT DEFINITIONS ###
+
+set(LIBMV_LIGHT_INCLUDES
+  src/libmv_light
+  "${OpenCV_SOURCE_DIR}/include/opencv"
+  "${GLOG_INCLUDE_DIRS}"
+  "${GFLAGS_INCLUDE_DIRS}"
+)
+
+set(LIBMV_LIGHT_LIBS
+  correspondence
+  multiview
+  numeric
+  ${GLOG_LIBRARIES}
+  ${GFLAGS_LIBRARIES}
+)
+
+if(Ceres_FOUND)
+  add_definitions("-DCERES_FOUND=1")
+  list(APPEND LIBMV_LIGHT_LIBS simple_pipeline)
+else()
+  add_definitions("-DCERES_FOUND=0")
+  message(STATUS "CERES support is disabled. Ceres Solver for reconstruction API is required.")
+endif()
+
+### DEFINE OPENCV SFM MODULE DEPENDENCIES ###
+
+### CREATE OPENCV SFM MODULE ###
+
+ocv_add_module(sfm
+  opencv_core
+  opencv_calib3d
+  opencv_features2d
+  opencv_xfeatures2d
+  WRAP python
+)
+
+
+ocv_warnings_disable(CMAKE_CXX_FLAGS
+  -Wundef
+  -Wshadow
+  -Wsign-compare
+  -Wmissing-declarations
+  -Wunused-but-set-variable
+  -Wunused-parameter
+  -Wunused-function
+)
+
+if(UNIX)
+  if(CMAKE_COMPILER_IS_GNUCXX OR CV_ICC)
+      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC")
+  endif()
+endif()
+
+ocv_include_directories( ${LIBMV_LIGHT_INCLUDES} )
+ocv_module_include_directories()
+
+# source files
+FILE(GLOB OPENCV_SFM_SRC src/*.cpp)
+
+# define the header files (make the headers appear in IDEs.)
+FILE(GLOB OPENCV_SFM_HDRS include/opencv2/sfm/*.hpp)
+
+ocv_set_module_sources(HEADERS ${OPENCV_SFM_HDRS}
+                       SOURCES ${OPENCV_SFM_SRC})
+
+ocv_create_module()
+
+# build libmv_light
+if(NOT CMAKE_VERSION VERSION_LESS 2.8.11) # See ocv_target_include_directories() implementation
+  if(TARGET ${the_module})
+    get_target_property(__include_dirs ${the_module} INCLUDE_DIRECTORIES)
+    include_directories(${__include_dirs})
+  endif()
+endif()
+include_directories(${OCV_TARGET_INCLUDE_DIRS_${the_module}})
+add_subdirectory(src/libmv_light)
+
+ocv_target_link_libraries(${the_module} ${LIBMV_LIGHT_LIBS})
+
+
+### CREATE OPENCV SFM TESTS ###
+
+ocv_add_accuracy_tests()
+
+
+### CREATE OPENCV SFM SAMPLES ###
+
+if(Ceres_FOUND)
+  ocv_add_samples(opencv_viz)
+endif ()

modules/sfm/README.md

@@ -0,0 +1,118 @@
+Structure From Motion module
+============================
+
+This module contains algorithms to perform 3d reconstruction from 2d images. The core of the module is a light version of [Libmv](https://developer.blender.org/project/profile/59), which is a Library for Multiview Reconstruction (or LMV) divided into different modules (correspondence/numeric/multiview/simple_pipeline) that allow to resolve part of the SfM process.
+
+
+Dependencies
+------------
+
+Before compiling, take a look at the following details in order to give a proper use of the Struncture from Motion module. **Advice:** The module is only available for Linux/GNU systems.
+
+In addition, it depends on some open source libraries:
+
+- [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page) 3.2.2 or later. **Required**
+- [Google Log](http://code.google.com/p/google-glog) 0.3.1 or later. **Required**
+- [Google Flags](http://code.google.com/p/gflags). **Required**
+- [Ceres Solver](http://ceres-solver.org). Needed by the reconstruction API in order to solve part of the Bundle Adjustment plus the points Intersect. If Ceres Solver is not installed on your system, the reconstruction funcionality will be disabled. **Recommended**
+
+Installation
+------------
+**Required Dependencies**
+
+In case you are on [Ubuntu](http://www.ubuntu.com/) you can simply install the required dependencies by typing the following command.
+
+    sudo apt-get install libeigen3-dev libgflags-dev libgoogle-glog-dev
+
+**Ceres Solver**
+
+Start by installing all the dependencies.
+
+    # CMake
+    sudo apt-get install cmake
+    # google-glog + gflags
+    sudo apt-get install libgoogle-glog-dev
+    # BLAS & LAPACK
+    sudo apt-get install libatlas-base-dev
+    # Eigen3
+    sudo apt-get install libeigen3-dev
+    # SuiteSparse and CXSparse (optional)
+    # - If you want to build Ceres as a *static* library (the default)
+    #   you can use the SuiteSparse package in the main Ubuntu package
+    #   repository:
+    sudo apt-get install libsuitesparse-dev
+    # - However, if you want to build Ceres as a *shared* library, you must
+    #   add the following PPA:
+    sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687
+    sudo apt-get update
+    sudo apt-get install libsuitesparse-dev
+
+We are now ready to build, test, and install Ceres.
+
+    git clone https://ceres-solver.googlesource.com/ceres-solver
+    cd ceres-solver
+    mkdir build && cd build
+    cmake ..
+    make -j4
+    make test
+    sudo make install
+
+Usage
+-----
+
+**trajectory_reconstruction.cpp**
+
+This program shows the camera trajectory reconstruction capabilities in the OpenCV Structure From Motion (SFM) module. It loads a file with the tracked 2d points over all the frames which are embedded into a vector of 2d points array, where each inner array represents a different frame. Every frame is composed by a list of 2d points which e.g. the first point in frame 1 is the same point in frame 2. If there is no point in a frame the assigned value will be (-1,-1).
+
+To run this example you can type the following command in the opencv binaries directory specifying the file path in your system and the camera intrinsics (in this case the tracks file was obtained using Blender Motion module).
+
+    ./example_sfm_trajectory_reconstruction tracks_file.txt 1914 640 360
+
+Finally, the script reconstructs the given set of tracked points and show the result using the OpenCV 3D visualizer (viz). On the image below, it's shown a screenshot with the result you should obtain running the "desktop_tracks.txt" found inside the samples directory.
+
+<p align="center">
+  <img src="doc/pics/desktop_trajectory.png" width="400" height="300">
+</p>
+
+**scene_reconstruction.cpp**
+
+This program shows the multiview scene reconstruction capabilities in the OpenCV Structure From Motion (SFM) module. It calls the recontruction API using the overloaded signature for real images. In this case the script loads a file which provides a list with all the image paths that we want to reconstruct. Internally, this script extract and compute the sparse 2d features using DAISY descriptors which are matched using FlannBasedMatcher to finally build the tracks structure.
+
+To run this example you can type the following command in the opencv binaries directory specifying the file path  and the camera intrinsics.
+
+    ./example_sfm_scene_reconstruction image_paths_file.txt 350 240 360
+
+This sample shows the estimated camera trajectory plus the sparse 3D reconstruction using the the OpenCV 3D visualizer (viz).
+
+On the next pictures, it's shown a screenshot where you can see the used images as input from the "Temple of the Dioskouroi" [1] and the obtained result after running the reconstruction API.
+
+<p align="center">
+  <img src="doc/pics/temple_input.jpg" width="800" height="200">
+</p>
+<p align="center">
+  <img src="doc/pics/temple_reconstruction.jpg" width="400" height="250">
+</p>
+
+On the next pictures, it's shown a screenshot where you can see the used images as input from la Sagrada Familia (BCN) [2] which you can find in the samples directory and the obtained result after running the reconstruction API.
+
+<p align="center">
+  <img src="doc/pics/sagrada_familia_input.jpg" width="700" height="250">
+</p>
+<p align="center">
+  <img src="doc/pics/sagrada_familia_reconstruction.jpg" width="400" height="250">
+</p>
+
+
+[1] [http://vision.middlebury.edu/mview/data](http://vision.middlebury.edu/mview/data)
+
+[2] Penate Sanchez, A. and Moreno-Noguer, F. and Andrade Cetto, J. and Fleuret, F. (2014). LETHA: *Learning from High Quality Inputs for 3D Pose Estimation in Low Quality Images*. Proceedings of the International Conference on 3D vision (3DV). [[URL]](http://www.iri.upc.edu/research/webprojects/pau/datasets/sagfam)
+
+
+Future Work
+-----------
+
+* Update signatures documentation.
+* Add prototype for dense reconstruction once is working (DAISY paper implementation).
+* Decide which functions are kept since most of them are the same in calib3d.
+* Finish to implement computeOrientation().
+* Find a good features matchig algorithm for reconstruction() in case we provide pure images for autocalibration (look into OpenMVG).

modules/sfm/include/opencv2/sfm.hpp

@@ -0,0 +1,102 @@
+/*
+ * Software License Agreement (BSD License)
+ *
+ *  Copyright (c) 2009, Willow Garage, Inc.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions
+ *  are met:
+ *
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above
+ *     copyright notice, this list of conditions and the following
+ *     disclaimer in the documentation and/or other materials provided
+ *     with the distribution.
+ *   * Neither the name of Willow Garage, Inc. nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+#ifndef __OPENCV_SFM_HPP__
+#define __OPENCV_SFM_HPP__
+
+#include <opencv2/sfm/conditioning.hpp>
+#include <opencv2/sfm/fundamental.hpp>
+#include <opencv2/sfm/numeric.hpp>
+#include <opencv2/sfm/projection.hpp>
+#include <opencv2/sfm/triangulation.hpp>
+#if CERES_FOUND
+#include <opencv2/sfm/reconstruct.hpp>
+#include <opencv2/sfm/simple_pipeline.hpp>
+#endif
+
+/** @defgroup sfm Structure From Motion
+
+The opencv_sfm module contains algorithms to perform 3d reconstruction
+from 2d images.\n
+The core of the module is based on a light version of
+[Libmv](https://developer.blender.org/project/profile/59) originally
+developed by Sameer Agarwal and Keir Mierle.
+
+__Whats is libmv?__ \n
+libmv, also known as the Library for Multiview Reconstruction (or LMV),
+is the computer vision backend for Blender's motion tracking abilities.
+Unlike other vision libraries with general ambitions, libmv is focused
+on algorithms for match moving, specifically targeting [Blender](https://developer.blender.org) as the
+primary customer. Dense reconstruction, reconstruction from unorganized
+photo collections, image recognition, and other tasks are not a focus
+of libmv.
+
+__Development__ \n
+libmv is officially under the Blender umbrella, and so is developed
+on developer.blender.org. The [source repository](https://developer.blender.org/diffusion/LMV) can get checked out
+independently from Blender.
+
+This module has been originally developed as a project for Google Summer of Code 2012-2015.
+
+@note
+  - Notice that it is compiled only when Eigen, GLog and GFlags are correctly installed.\n
+    Check installation instructions in the following tutorial: @ref tutorial_sfm_installation
+
+  @{
+    @defgroup conditioning Conditioning
+    @defgroup fundamental Fundamental
+    @defgroup numeric Numeric
+    @defgroup projection Projection
+    @defgroup robust Robust Estimation
+    @defgroup triangulation Triangulation
+
+    @defgroup reconstruction Reconstruction
+      @note
+        - Notice that it is compiled only when Ceres Solver is correctly installed.\n
+          Check installation instructions in the following tutorial: @ref tutorial_sfm_installation
+
+
+    @defgroup simple_pipeline Simple Pipeline
+      @note
+          - Notice that it is compiled only when Ceres Solver is correctly installed.\n
+            Check installation instructions in the following tutorial: @ref tutorial_sfm_installation
+
+  @}
+
+*/
+
+#endif
+
+/* End of file. */