Merge branch 'doc' into 'master'

Fix the documentation to use bob.ip.facedetect instead of opencv

See merge request !12

bob/ip/flandmark/test.py

@@ -24,14 +24,14 @@ def F(f):
 LENA = F('lena.jpg')
 LENA_BBX = [
     [214, 202, 183, 183]
-    ] #from OpenCV's cascade detector
+    ]
 
 MULTI = F('multi.jpg')
 MULTI_BBX = [
     [326, 20, 31, 31],
     [163, 25, 34, 34],
     [253, 42, 28, 28],
-    ] #from OpenCV's cascade detector
+    ]
 
 
 def pnpoly(point, vertices):

doc/extra-intersphinx.txt

+bob.ip.draw
+bob.io.image
+bob.ip.facedetect
+matplotlib

doc/guide.rst

@@ -9,9 +9,9 @@
      from pkg_resources import resource_filename
      return resource_filename('bob.ip.flandmark', join('data', f))
 
-=============
- Users Guide
-=============
+==============================================
+ Face Landmark Detection Using Python and Bob
+==============================================
 
 :py:class:`bob.ip.flandmark` detects 8 coordinates of important keypoints in **frontal** human faces.
 To properly work, the keypoint localizer requires the input of an image (of type ``uint8``, gray-scaled) and of a bounding box describing a rectangle where the face is supposed to be located in the image (see :py:meth:`bob.ip.flandmark.Flandmark.locate`).
@@ -53,43 +53,37 @@ The input bounding box describes the rectangle coordinates using 4 values: ``(y,
 Square bounding boxes, i.e. when ``height == width``, will give best results.
 
 If you don't know the bounding box coordinates of faces on the provided image, you will need to either manually annotate them or use an automatic face detector.
-OpenCV_, if compiled with Python support, provides an easy to use frontal face detector.
-The code below shall detect most frontal faces in a provided (gray-scaled) image:
+:ref:`bob.ip.facedetect` provides an easy to use frontal face detector.
+The code below shall detect most frontal faces in a provided image:
 
 .. doctest::
    :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
 
    >>> import bob.io.base
    >>> import bob.io.image
-   >>> import bob.ip.color
-   >>> lena_gray = bob.ip.color.rgb_to_gray(bob.io.base.load(get_file('lena.jpg')))
-   >>> try:
-   ...   # the following lines depend on opencv API, hence commented out.
-   ...   # from cv2 import CascadeClassifier
-   ...   # cc = CascadeClassifier(get_file('haarcascade_frontalface_alt.xml'))
-   ...   # face_bbxs = cc.detectMultiScale(lena_gray, 1.3, 4, 0, (20, 20))
-   ...   face_bbxs = [[214, 202, 183, 183]] #e.g., manually
-   ... except ImportError: #if you don't have OpenCV, do it otherwise
-   ...   face_bbxs = [[214, 202, 183, 183]] #e.g., manually
-   >>> print(face_bbxs)
-   [[...]]
+   >>> import bob.ip.facedetect
+   >>> lena = bob.io.base.load(get_file('lena.jpg'))
+   >>> bounding_box, quality = bob.ip.facedetect.detect_single_face(lena)
+   >>> # scale the bounding box to cover more of the face
+   >>> bounding_box = bounding_box.scale(1.2, True)
+   >>> y, x = bounding_box.topleft
+   >>> height, width = bounding_box.size
+   >>> width = height  # make it square
+   >>> print((y, x, height, width))
+   (...)
 
 .. note::
    To enable the :py:func:`bob.io.base.load` function to load images, :ref:`bob.io.image <bob.io.image>` must be imported, see :ref:`bob.io.image`.
 
-The function ``detectMultiScale`` returns OpenCV_ rectangles as 2D :py:class:`numpy.ndarray`\s.
-Each row corresponds to a detected face at the input image.
-Notice the format of each bounding box differs from that of Bob_.
-Their format is ``(x, y, width, height)``.
-
 Once in possession of bounding boxes for the provided (gray-scaled) image, you can find the keypoints in the following way:
 
 .. doctest::
    :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
 
-   >>> x, y, width, height = face_bbxs[0]
+   >>> import bob.ip.color
    >>> from bob.ip.flandmark import Flandmark
    >>> localizer = Flandmark()
+   >>> lena_gray = bob.ip.color.rgb_to_gray(lena)
    >>> keypoints = localizer.locate(lena_gray, y, x, height, width)
    >>> keypoints
    array([[...]])

doc/links.rst

@@ -45,7 +45,6 @@
 .. _matplotlib: http://matplotlib.sourceforge.net
 .. _numpy: http://numpy.scipy.org
 .. _nose: http://nose.readthedocs.org
-.. _opencv: http://opencv.org/
 .. _pil: http://www.pythonware.com/products/pil/
 .. _pillow: https://pypi.python.org/pypi/Pillow/
 .. _python: http://www.python.org

doc/plot/show_lena.py

-from matplotlib import pyplot
 from bob.ip.flandmark import Flandmark
 from bob.ip.draw import box, cross
 from bob.ip.color import rgb_to_gray
+from bob.ip.facedetect import detect_single_face
+import bob.io.image
+
 
 def get_data(f):
   from os.path import join
   from pkg_resources import resource_filename
   from bob.io.base import load
-  import bob.io.image
   return load(resource_filename('bob.ip.flandmark', join('data', f)))
 
+
 lena = get_data('lena.jpg')
 lena_gray = rgb_to_gray(lena)
-x, y, width, height = [214, 202, 183, 183] #or from OpenCV
+bounding_box, quality = detect_single_face(lena)
+bounding_box = bounding_box.scale(1.2, True)
+y, x = bounding_box.topleft
+height, width = bounding_box.size
+width = height
+# x, y, width, height = [214, 202, 183, 183] # Manual annotations
 localizer = Flandmark()
 keypoints = localizer.locate(lena_gray, y, x, height, width)
 
 # draw the keypoints and bounding box
-box(lena, (y, x), (height, width), (255, 0, 0)) # red bounding box
+box(lena, (y, x), (height, width), (255, 0, 0))  # red bounding box
 for k in keypoints:
-  cross(lena, k.astype(int), 5, (255, 255, 0)) # yellow key points
+  cross(lena, k.astype(int), 5, (255, 255, 0))  # yellow key points
 
-pyplot.imshow(lena.transpose(1, 2, 0))
+bob.io.image.imshow(lena)

requirements.txt

@@ -6,11 +6,3 @@ bob.io.base
 bob.math
 bob.sp
 bob.ip.base
-
-# For tests
-bob.io.image
-bob.ip.color
-
-# For documentation generation
-bob.ip.draw
-matplotlib

test-requirements.txt

+bob.io.image
+bob.ip.color
+bob.ip.facedetect