scikit-image · warmspringwinds · Jun 26, 2015 · Jun 26, 2015 · Jun 26, 2015 · Jun 30, 2015
diff --git a/.gitignore b/.gitignore
@@ -7,6 +7,7 @@
 *.pyd
 *.bak
 *.c
+*.cpp
 *.new
 *.md5
 *.old

diff --git a/bento.info b/bento.info
@@ -34,7 +34,7 @@ Library:
     Packages:
         skimage, skimage.color, skimage.data, skimage.draw, skimage.exposure,
         skimage.feature, skimage.filters, skimage.future, skimage.future.graph,
-        skimage.graph, skimage.io,
+        skimage.graph, skimage.io, skimage.future.detect_obj
         skimage.io._plugins, skimage.measure, skimage.morphology,
         skimage.scripts, skimage.restoration, skimage.segmentation,
         skimage.transform, skimage.util
@@ -167,6 +167,9 @@ Library:
     Extension: skimage.transform._seam_carving
         Sources:
             skimage/transform/_seam_carving.pyx
+    Extension: skimage.future.detect.cascade
+        Sources:
+            skimage/future/detect/cascade.pyx
 
 Executable: skivi
     Module: skimage.scripts.skivi

diff --git a/doc/examples/plot_face_detection.py b/doc/examples/plot_face_detection.py
@@ -0,0 +1,99 @@
+"""
+==============
+Face Detection
+==============
+
+This example shows how to detect faces on an image using object detection framework.
+
+First, you will need an xml file, from which the trained data can be read.
+The framework works with files, trained using Multi-block Local Binary Patterns
+Features (See `MB-LBP <plot_multiblock_local_binary_pattern.html>`_) and
+Gentle Adaboost with attentional cascade. So, the detection framework will also
+work with `xml files from OpenCV <https://github.com/Itseez/opencv/tree/master/data/lbpcascades>`_.
+There you can find files that were trained to detect cat faces, profile faces and other things.
+But if you want to detect frontal faces, the respective file is already included in
+scikit-image.
+
+Next you will have to specify the parameters for the `detect_multi_scale` function.
+Here you can find the meaning of each of them.
+
+First one is `scale_ratio`. To find all faces, the algorithm does the search on
+multiple scales. This is done by changing the size of searching window. The smallest
+window size is the size of window that was used in training. This size is specified
+in the xml file with trained parameters. The `scale_ratio` parameter specifies by which
+ratio the search window is increased on each step. If you increase this parameter, the
+search time decreases and the accuracy decreases. So, faces on some scales can be not detected.
+
+`step_ratio` specifies the step of sliding window that is used to search for faces on
+each scale of the image. If this parameter is equal to one, then all the
+possible locations are searched. If the parameter is greater than one, for example, two,
+the window will be moved by two pixels and not all of the possible locations will be searched
+for faces. By increasing this parameter we can reduce the working
+time of the algorithm, but the accuracy will also be decreased.
+
+`min_size` is the minimum size of search window during the scale search. `max_size` specifies
+the maximum size of the window. If you know the size of faces on the images that you
+want to search, you should specify these parameters as precisely as possible, because you
+can avoid doing expensive computations and possibly decrease the amount
+of false detections. You can save a lot of time by increasing the `min_size`
+parameter, because the majority of time is spent on searching on the smallest scales.
+
+`min_neighbour_number` and `intersection_score_threshold` parameters are made to
+cluster the excessive detections of the same face and to filter out false detections.
+True faces usually has a lot of dectections around them and false ones usually have
+single detection. First algorithm searches for clusters: two rectangle detections
+are placed in the same cluster if the intersection score between them
+is larger then `intersection_score_threshold`. The intersection score is computed
+using the equation (intersection area) / (small rectangle ratio). The described intersection
+criteria was chosen over intersection over union to avoid a corner case when
+small rectangle inside of a big one have small intersection score.  Then each cluster
+is thresholded using `min_neighbour_number` parameter which leaves the clusters
+that have a same or bigger number of detections in them.
+
+You should also take into account that false detections are inevitable and if you want
+to have a really precise detector, you will have to train it yourself using
+`OpenCV train cascade utility <http://docs.opencv.org/doc/user_guide/ug_traincascade.html>`_.
+"""
+
+import skimage.data as data
+import skimage.future.detect as detect
+
+from matplotlib import pyplot as plt
+from matplotlib import patches
+
+# Load the trained file from the module root.
+trained_file = data.detect.frontal_face_cascade_xml()
+
+# Initialize the detector cascade.
+detector = detect.Cascade(trained_file)
+
+img = data.astronaut()
+
+detected = detector.detect_multi_scale(img=img,
+                                       scale_factor=1.2,
+                                       step_ratio=1,
+                                       min_size=(60, 60),
+                                       max_size=(123, 123))
+
+plt.imshow(img)
+img_desc = plt.gca()
+plt.set_cmap('gray')
+
+for patch in detected:
+
+    img_desc.add_patch(
+        patches.Rectangle(
+            (patch['c'], patch['r']),
+            patch['width'],
+            patch['height'],
+            fill=False,
+            color='r',
+            linewidth=2
+        )
+    )
+
+plt.show()
+
+"""
+.. image:: PLOT2RST.current_figure
+"""
diff --git a/object_detection.ipynb b/object_detection.ipynb
diff --git a/setup.py b/setup.py
@@ -23,6 +23,57 @@
 
 import setuptools
 from distutils.command.build_py import build_py
+from numpy.distutils.command.build_ext import build_ext
+from distutils.errors import CompileError, LinkError
+import tempfile
+import shutil
+
+compile_flags = ['-fopenmp']
+link_flags = ['-fopenmp']
+
+code = """#include <omp.h>
+int main(int argc, char** argv) { return(0); }"""
+
+class ConditionalOpenMP(build_ext):
+
+    def can_compile_link(self):
+
+        cc = self.compiler
+        fname = 'test.c'
+        cwd = os.getcwd()
+        tmpdir = tempfile.mkdtemp()
+
+        try:
+            os.chdir(tmpdir)
+            with open(fname, 'wt') as fobj:
+                fobj.write(code)
+            try:
+                objects = cc.compile([fname],
+                                     extra_postargs=compile_flags)
+            except CompileError:
+                return False
+            try:
+                # Link shared lib rather then executable to avoid
+                # http://bugs.python.org/issue4431 with MSVC 10+
+                cc.link_shared_lib(objects, "testlib",
+                                   extra_postargs=link_flags)
+            except (LinkError, TypeError):
+                return False
+        finally:
+            os.chdir(cwd)
+            shutil.rmtree(tmpdir)
+        return True
+
+    def build_extensions(self):
+        """ Hook into extension building to check compiler flags """
+
+        if self.can_compile_link():
+
+            for ext in self.extensions:
+                ext.extra_compile_args += compile_flags
+                ext.extra_link_args += link_flags
+
+        build_ext.build_extensions(self)
 
 
 with open('skimage/__init__.py') as fid:
@@ -122,6 +173,7 @@ def configuration(parent_package='', top_path=None):
             'console_scripts': ['skivi = skimage.scripts.skivi:main'],
         },
 
-        cmdclass={'build_py': build_py},
+        cmdclass={'build_py': build_py,
+                  'build_ext': ConditionalOpenMP},
         **extra
     )
diff --git a/skimage/_shared/interpolation.pxd b/skimage/_shared/interpolation.pxd
@@ -8,6 +8,12 @@ from libc.math cimport ceil, floor
 cdef inline Py_ssize_t round(double r) nogil:
     return <Py_ssize_t>((r + 0.5) if (r > 0.0) else (r - 0.5))
 
+cdef inline Py_ssize_t fmax(Py_ssize_t one, Py_ssize_t two) nogil:
+    return one if one > two else two
+
+cdef inline Py_ssize_t fmin(Py_ssize_t one, Py_ssize_t two) nogil:
+    return one if one < two else two
+
 
 cdef inline double nearest_neighbour_interpolation(double* image,
                                                    Py_ssize_t rows,

diff --git a/skimage/data/__init__.py b/skimage/data/__init__.py
@@ -11,6 +11,7 @@
 from .. import data_dir
 from ..io import imread, use_plugin
 from ._binary_blobs import binary_blobs
+from . import detect
 
 __all__ = ['load',
            'camera',
@@ -27,7 +28,8 @@
            'coffee',
            'hubble_deep_field',
            'rocket',
-           'astronaut']
+           'astronaut',
+           'detect']
 
 
 def load(f):
@@ -261,3 +263,4 @@ def rocket():
 
     """
     return load("rocket.jpg")
+
diff --git a/skimage/data/detect.py b/skimage/data/detect.py
@@ -0,0 +1,16 @@
+import os as _os
+from .. import data_dir
+
+
+def frontal_face_cascade_xml():
+    """
+    Returns the file's path to the trained xml file for frontal face detection
+    that was taken from OpenCV repository [1]_.
+
+    References
+    ----------
+    .. [1] OpenCV lbpcascade trained files
+           https://github.com/Itseez/opencv/tree/master/data/lbpcascades
+    """
+
+    return _os.path.join(data_dir, 'lbpcascade_frontalface_opencv.xml')
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,6 +7,7 @@ @@
     *.pyd
     *.bak
     *.c
+    *.cpp
     *.new
     *.md5
     *.old
@@ Expand Down @@