Multithreaded detection/tracking

CMakeLists.txt

@@ -36,12 +36,13 @@ message(STATUS "OpenCV version: ${OpenCV_VERSION}")
 ##           Options                   ###
 ##########################################
 
-option(WITH_SAMPLES                     "compile misc demos" OFF)
-option(WITH_TESTS                       "build tests" OFF)
-option(WITH_JNI_BINDINGS                "JNI bindings compatible with ordinary Java and Android" OFF)
-option(ANDROID_INSTALL_LIBRARIES        "Whether to install the chilitag libraries inside project at ANDROID_PROJECT_ROOT" OFF)
+option(WITH_SAMPLES                     "Build demos" OFF)
+option(WITH_TESTS                       "Build tests" OFF)
+option(WITH_JNI_BINDINGS                "Build JNI bindings compatible with ordinary Java and Android" OFF)
+option(ANDROID_INSTALL_LIBRARIES        "Install the chilitag libraries inside project at ANDROID_PROJECT_ROOT" OFF)
 
 if(DEFINED ANDROID) #OPENCV has a nice macro for this: OCV_OPTION, consider using it.
+    option(WITH_PTHREADS                "Multithreading support with pthreads" ON)
     option(WITH_TOOLS                   "provides the marker generation tool" OFF)
 
     #Set Android install path
@@ -60,33 +61,40 @@ if(DEFINED ANDROID) #OPENCV has a nice macro for this: OCV_OPTION, consider usin
     if(NOT DEFINED ENV{ANDROID_TOOLCHAIN_NAME})
         message(FATAL_ERROR "Please define the ANDROID_TOOLCHAIN_NAME environment variable first, e.g arm-linux-androideabi-4.8")
     endif()
+elseif(UNIX)
+    option(WITH_PTHREADS                "Multithreading support with pthreads" ON)
+    option(WITH_TOOLS                   "provides the marker generation tool" ON)
 else()
+    option(WITH_PTHREADS                "Multithreading support with pthreads" OFF)
     option(WITH_TOOLS                   "provides the marker generation tool" ON)
 endif()
 
+##########################################
+##           Chilitags lib             ###
+##########################################
+
+if(WITH_PTHREADS)
+    add_definitions(-DHAS_MULTITHREADING)
+endif()
+
 if(${OpenCV_VERSION} VERSION_GREATER 2.9.0)
     add_definitions(-DOPENCV3)
 endif()
 
 include_directories(include)
 add_subdirectory(src)
 
-# documentation generation
+##########################################
+##           Modules                   ###
+##########################################
+
 include("${CMAKE_SOURCE_DIR}/cmake/TargetDoc.cmake" OPTIONAL)
 
 if (WITH_TOOLS)
-    if(NOT OPENCV_HIGHGUI_FOUND)
-        message(FATAL_ERROR "OpenCV compiled without support for highgui! Can not compile detector.")
-    endif()
-
     add_subdirectory(tools)
 endif()
 
 if (WITH_SAMPLES)
-    if(NOT OPENCV_HIGHGUI_FOUND)
-        message(FATAL_ERROR "OpenCV compiled without support for highgui! Can not compile creator.")
-    endif()
-
     add_subdirectory(samples)
 endif()
 
@@ -103,3 +111,4 @@ if(ANDROID_INSTALL_LIBRARIES)
         message(FATAL_ERROR "ANDROID_PROJECT_ROOT undefined, can't install libraries inside Android project.")
     endif()
 endif()
+

README.md

@@ -176,7 +176,7 @@ for a research project. Let us make that easy for you:
 ```
 	@misc{chilitags,
 		title = {Chilitags 2: Robust Fiducial Markers for Augmented Reality and Robotics.},
-		author={Bonnard, Quentin and Lemaignan, S\'{e}verin and Zufferey, Guillaume and Mazzei, Andrea and Cuendet, S\'{e}bastien and Li, Nan and Dillenbourg, Pierre},
+		author={Bonnard, Quentin and Lemaignan, S\'{e}verin and Zufferey, Guillaume and Mazzei, Andrea and Cuendet, S\'{e}bastien and Li, Nan and \"{O}zg\"{u}r, Ayberk and Dillenbourg, Pierre},
 		publisher={CHILI, EPFL, Switzerland},
 		url={http://chili.epfl.ch/software},
 		year={2013}

include/chilitags.hpp

@@ -148,6 +148,34 @@ enum DetectionTrigger {
     previous results.
 */
     DETECT_PERIODICALLY,
+
+#ifdef HAS_MULTITHREADING
+    /**
+     * @brief Runs the detection in the background, with a period
+     *
+     * Runs the detection in a background thread, only tracking in the call to
+     * `find()`.
+     *
+     * `setDetectionPeriod()` allows to specify the number of calls between two
+     * detections. It defaults to 15, i.e. out of 15 consecutive calls to
+     * `find()`, the background thread will be informed to run detection. After
+     * this, a new detection will be done as soon as a new image frame is
+     * presented in the call to `find()`. If the background thread takes more
+     * time than 15 calls to `find()`, it will be running as frequently as
+     * possible, i.e the same as `BACKGROUND_DETECT_ALWAYS`.
+     */
+    ASYNC_DETECT_PERIODICALLY,
+
+    /**
+     * @brief Runs the detection in the background, as frequently as possible
+     *
+     * Runs the detection in a background thread, only tracking in the call to
+     * `find()`. The detection is run as frequently as possible, i.e a new
+     * detection is started as soon as the new image frame is presented in the
+     * call to `find()` after the previous detection is finished.
+     */
+    ASYNC_DETECT_ALWAYS
+#endif
 };
 
 /**

samples/CMakeLists.txt

@@ -18,6 +18,10 @@
 #   along with Chilitags.  If not, see <http://www.gnu.org/licenses/>.         #
 ################################################################################
 
+if(NOT OPENCV_HIGHGUI_FOUND)
+    message(FATAL_ERROR "OpenCV compiled without support for highgui, cannot compile samples!")
+endif()
+
 add_executable( estimate3d 3destimation/estimate3d.cpp)
 target_link_libraries( estimate3d chilitags_static )
 target_link_libraries( estimate3d ${OpenCV_LIBS} )
@@ -42,3 +46,11 @@ add_executable( tracking tracking/tracking.cpp)
 target_link_libraries( tracking chilitags )
 target_link_libraries( tracking ${OpenCV_LIBS} )
 install (TARGETS tracking RUNTIME DESTINATION bin)
+
+if(WITH_PTHREADS)
+    add_executable( async-detection multithreaded/async-detection.cpp)
+    target_link_libraries( async-detection chilitags )
+    target_link_libraries( async-detection ${OpenCV_LIBS} )
+    install (TARGETS async-detection RUNTIME DESTINATION bin)
+endif()
+

samples/multithreaded/async-detection.cpp

@@ -0,0 +1,147 @@
+/*******************************************************************************
+ *   Copyright 2013-2014 EPFL                                                   *
+ *   Copyright 2013-2014 Quentin Bonnard                                        *
+ *                                                                              *
+ *   This file is part of chilitags.                                            *
+ *                                                                              *
+ *   Chilitags is free software: you can redistribute it and/or modify          *
+ *   it under the terms of the Lesser GNU General Public License as             *
+ *   published by the Free Software Foundation, either version 3 of the         *
+ *   License, or (at your option) any later version.                            *
+ *                                                                              *
+ *   Chilitags is distributed in the hope that it will be useful,               *
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of             *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the              *
+ *   GNU Lesser General Public License for more details.                        *
+ *                                                                              *
+ *   You should have received a copy of the GNU Lesser General Public License   *
+ *   along with Chilitags.  If not, see <http://www.gnu.org/licenses/>.         *
+ *******************************************************************************/
+
+#include <chilitags.hpp>
+
+#ifdef OPENCV3
+#include <opencv2/core/utility.hpp> // getTickCount...
+#include <opencv2/imgproc/imgproc.hpp>
+#endif
+
+#include <opencv2/core/core_c.h> // CV_AA
+
+#include <opencv2/highgui/highgui.hpp>
+
+#include <iostream>
+
+cv::Scalar COLOR = cv::Scalar(0, 0, 255);
+
+void drawTags(cv::Mat outputImage, std::map<int, chilitags::Quad> const& tags);
+
+int main(int argc, char* argv[])
+{
+    // Initialising input video
+    int xRes = 640;
+    int yRes = 480;
+    int cameraIndex = 0;
+    if (argc > 2) {
+        xRes = std::atoi(argv[1]);
+        yRes = std::atoi(argv[2]);
+    }
+    if (argc > 3) {
+        cameraIndex = std::atoi(argv[3]);
+    }
+
+    // The source of input images
+    cv::VideoCapture capture(cameraIndex);
+    if (!capture.isOpened())
+    {
+        std::cerr << "Unable to initialise video capture." << std::endl;
+        return 1;
+    }
+#ifdef OPENCV3
+    capture.set(cv::CAP_PROP_FRAME_WIDTH, xRes);
+    capture.set(cv::CAP_PROP_FRAME_HEIGHT, yRes);
+#else
+    capture.set(CV_CAP_PROP_FRAME_WIDTH, xRes);
+    capture.set(CV_CAP_PROP_FRAME_HEIGHT, yRes);
+#endif
+    cv::Mat inputImage;
+
+    chilitags::Chilitags chilitags;
+    chilitags.setFilter(0, 0.);
+
+    cv::namedWindow("DisplayChilitags");
+
+    char keyPressed;
+    const char* trigName = "DETECT_PERIODICALLY";
+    chilitags::Chilitags::DetectionTrigger trig = chilitags::Chilitags::DETECT_PERIODICALLY;
+    while ('q' != (keyPressed = (char) cv::waitKey(1))) {
+
+        // toggle the processing mode, according to user input
+        if(keyPressed == 't'){
+            if(trig == chilitags::Chilitags::DETECT_PERIODICALLY){
+                trig = chilitags::Chilitags::ASYNC_DETECT_PERIODICALLY;
+                trigName = "ASYNC_DETECT_PERIODICALLY";
+            }
+            else if(trig == chilitags::Chilitags::ASYNC_DETECT_PERIODICALLY){
+                trig = chilitags::Chilitags::ASYNC_DETECT_ALWAYS;
+                trigName = "ASYNC_DETECT_ALWAYS";
+            }
+            else{
+                trig = chilitags::Chilitags::DETECT_PERIODICALLY;
+                trigName = "DETECT_PERIODICALLY";
+            }
+        }
+
+        capture.read(inputImage);
+
+        cv::Mat outputImage = inputImage.clone();
+
+        auto tags = chilitags.find(inputImage, trig);
+        drawTags(outputImage, tags);
+
+        //Print detection trigger
+        cv::putText(outputImage,
+                cv::format("Detection trigger: %s (press 't' to toggle)", trigName),
+                cv::Point(8,yRes - 24),
+                cv::FONT_HERSHEY_SIMPLEX, 0.5, COLOR);
+
+        cv::putText(outputImage,
+                cv::format("Run 'top -H -p `pgrep async-detection`' to see running threads", trigName),
+                cv::Point(8,yRes - 8),
+                cv::FONT_HERSHEY_SIMPLEX, 0.5, COLOR);
+
+        cv::imshow("DisplayChilitags", outputImage);
+    }
+
+    cv::destroyWindow("DisplayChilitags");
+    capture.release();
+
+    return 0;
+}
+
+void drawTags(
+        cv::Mat outputImage,
+        const std::map<int, chilitags::Quad> &tags)
+{
+    for(const auto& tag : tags){
+
+        const cv::Mat_<cv::Point2f> corners(tag.second);
+
+        for(size_t i = 0; i < 4; ++i){
+            const int SHIFT = 16;
+            const float PRECISION = 1 << SHIFT;
+            cv::line(
+                    outputImage,
+                    PRECISION*corners(i),
+                    PRECISION*corners((i+1)%4),
+#ifdef OPENCV3
+                    COLOR, 3, cv::LINE_AA, SHIFT);
+#else
+            COLOR, 3, CV_AA, SHIFT);
+#endif
+        }
+
+        cv::Point2f center = 0.5*(corners(0) + corners(2));
+        cv::putText(outputImage, cv::format("%d", tag.first), center,
+                cv::FONT_HERSHEY_SIMPLEX, 0.5, COLOR);
+    }
+}

src/CMakeLists.txt

@@ -31,15 +31,17 @@ add_library(
         ${chilitags_source}
 )
 
-
 target_link_libraries(chilitags ${OpenCV_LIBS})
 target_link_libraries(chilitags_static ${OpenCV_LIBS})
 
+if(WITH_PTHREADS AND NOT DEFINED ANDROID) #Android pthreads don't require -lpthread
+    target_link_libraries(chilitags pthread)
+    target_link_libraries(chilitags_static pthread)
+endif()
 
 install (TARGETS chilitags chilitags_static
-	LIBRARY DESTINATION lib
-	ARCHIVE DESTINATION lib
-#	PUBLIC_HEADER DESTINATION include/chilitags
+    LIBRARY DESTINATION lib
+    ARCHIVE DESTINATION lib
 )
 
 if(ANDROID_INSTALL_LIBRARIES)
@@ -52,8 +54,8 @@ endif()
 file(GLOB_RECURSE chilitags_headers ../include/*)
 
 install(FILES
-	${chilitags_headers}
-	DESTINATION include/chilitags
+    ${chilitags_headers}
+    DESTINATION include/chilitags
 )
 
 ##########################################