diff --git a/bob/ip/facelandmarks/script/detect_landmarks.py b/bob/ip/facelandmarks/script/detect_landmarks.py
index 5e771961181c4a77277e6eacca5ba5ebab61c803..e10167ff842db451a1c2be3fb8900d6f3286e332 100644
--- a/bob/ip/facelandmarks/script/detect_landmarks.py
+++ b/bob/ip/facelandmarks/script/detect_landmarks.py
@@ -1,7 +1,5 @@
#!/usr/bin/env python
# encoding: utf-8
-# Andre Anjos <andre.anjos@idiap.ch>
-# Tue 16 Feb 2016 15:52:30 CET
'''Face landmark detector using menpo (%(version)s)
diff --git a/bob/ip/facelandmarks/test.py b/bob/ip/facelandmarks/test.py
index 734625b02224702e14f048ba1966eb6d390fcb33..470fe0f96817a67695df8e518ec1414c5d4a82df 100644
--- a/bob/ip/facelandmarks/test.py
+++ b/bob/ip/facelandmarks/test.py
@@ -1,7 +1,5 @@
#!/usr/bin/env python
# encoding: utf-8
-# Andre Anjos <andre.anjos@idiap.ch>
-# Wed 17 Feb 14:32:58 CET 2016
'''Test units for bob.ip.facelandmarks'''
diff --git a/bob/ip/facelandmarks/utils.py b/bob/ip/facelandmarks/utils.py
index 0a230e73c7cc6249343fe24d970d88e46c4135e0..e1a5f99fa41b6717ba9a81afb6c7d34a02be9e62 100644
--- a/bob/ip/facelandmarks/utils.py
+++ b/bob/ip/facelandmarks/utils.py
@@ -1,7 +1,5 @@
#!/usr/bin/env python
# encoding: utf-8
-# Andre Anjos <andre.dos.anjos@gmail.com>
-# Wed 17 Feb 2016 10:53:06 CET
'''A set of helper utitilities to deal with menpo images and point clouds'''
@@ -165,18 +163,22 @@ def _detect_multiple_landmarks_on_gray_image(data, top=0, min_quality=0.):
'''Detects landmarks on a gray-scale image, returns point-clouds from menpo
This helper will detect faces and landmarks, possibly many, on the input
- gray-scale image.
+ gray-scale image. It first detects faces in the input image, using
+ :py:mod:`bob.ip.facedetect`, and then uses the result of the
+ face-detection-step for detecting facial-landmarks.
+
Parameters:
data (:py:class:`numpy.ndarray`): An ``uint8`` array with 2 dimensions,
corresponding to a gray-scale image loaded with Bob (y, x) ordering.
- top (:py:class:`int`): An integer which indicates if we should only consider the first
- N detections or all of them. A value of zero means the selector ignores
- this field.
+ top (:py:class:`int`): An integer which indicates if we should only
+ consider the first N detections or all of them. A value of zero means the
+ selector ignores this field. A value of 1 returns only the best detection
+ (with the highest quality).
- min_quality (:py:class:`float`): also trims the face detector output list
+ min_quality (:py:class:`float`): Also trims the face detector output list
by considering a minimum quality for the detection. A value of zero (0.0)
means "any quality will do". Good detections have a typical value which
is greater than 30. Use this parameter with care. If this and ``top`` are
@@ -293,15 +295,16 @@ def detect_landmarks(data, top=0, min_quality=0.):
This helper will detect faces and landmarks, possibly many, on the input
image.
+
Parameters:
data (:py:class:`numpy.ndarray`): An ``uint8`` array with either 2 or 3
dimensions, corresponding to a either a gray-scale or color image loaded
with Bob.
- top (:py:class:`int`): An integer which indicates if we should only consider the first
- N detections or all of them. A value of zero means the selector ignores
- this field.
+ top (:py:class:`int`): An integer which indicates if we should only
+ consider the first N detections or all of them. A value of zero means the
+ selector ignores this field.
min_quality (:py:class:`float`): trims the face detector output list
by considering a minimum quality for the detection. A value of zero (0.0)
diff --git a/develop.cfg b/develop.cfg
index 58164cdc6501ddf000a90cfce65db499abfecbe3..701bced202f4ac7137bae6c25f265cee8477a7b3 100644
--- a/develop.cfg
+++ b/develop.cfg
@@ -2,26 +2,46 @@
; Sat 3 Dec 20:21:13 2016 CET
[buildout]
-parts = environment scripts
+parts = scripts
eggs = bob.ip.facelandmarks
extensions = bob.buildout
mr.developer
auto-checkout = *
+develop = src/bob.extension
+ src/bob.blitz
+ src/bob.core
+ src/bob.io.base
+ src/bob.io.image
+ src/bob.io.video
+ src/bob.math
+ src/bob.sp
+ src/bob.learn.boosting
+ src/bob.ip.base
+ src/bob.ip.color
+ src/bob.ip.draw
+ src/bob.ip.facedetect
+ .
-develop = .
-
+; options for bob.buildout extension
+debug = true
+verbose = true
newest = false
-[versions]
-pillow = >=2.9,<2.10
-
-[environment]
-;required for MacPorts (OSX) builds
-;make sure to install port vlfeat before
-recipe = collective.recipe.environment
-CFLAGS = -I/opt/local/include
-LDFLAGS = -L/opt/local/lib -lvl
+[sources]
+bob.extension = git https://gitlab.idiap.ch/bob/bob.extension
+bob.blitz = git https://gitlab.idiap.ch/bob/bob.blitz
+bob.core = git https://gitlab.idiap.ch/bob/bob.core
+bob.io.base = git https://gitlab.idiap.ch/bob/bob.io.base
+bob.io.image = git https://gitlab.idiap.ch/bob/bob.io.image
+bob.io.video = git https://gitlab.idiap.ch/bob/bob.io.video
+bob.math = git https://gitlab.idiap.ch/bob/bob.math
+bob.sp = git https://gitlab.idiap.ch/bob/bob.sp
+bob.learn.boosting = git https://gitlab.idiap.ch/bob/bob.learn.boosting
+bob.ip.base = git https://gitlab.idiap.ch/bob/bob.ip.base
+bob.ip.color = git https://gitlab.idiap.ch/bob/bob.ip.color
+bob.ip.draw = git https://gitlab.idiap.ch/bob/bob.ip.draw
+bob.ip.facedetect = git https://gitlab.idiap.ch/bob/bob.ip.facedetect
[scripts]
recipe = bob.buildout:scripts
-
+dependent-scripts = true
diff --git a/doc/guide.rst b/doc/guide.rst
index c2e2fb90a34bc6767476af8ec6774decb1af8f1c..cf06261588fb7b23769091675a46c1633ae6b135 100644
--- a/doc/guide.rst
+++ b/doc/guide.rst
@@ -20,22 +20,25 @@
face_image = bob.io.base.load(lena_file)
multi_image = bob.io.base.load(multi_file)
+
=============
User Guide
=============
-This Bob package allows you to use the [Menpofit_] package to detect facial landmarks.
-Given a gray-level image depicting a human face, this package can be used to extract a specific set of 68 landmarks,
-as defined in Menpofit. Please refer to the original Menpofit [documentation_] for implementation details.
-Here, we show some examples of how to use the ``bob.ip.facelandmarks`` package.
+This Bob package allows you to use the Menpofit_ package to detect facial
+landmarks. Given a gray-level image depicting a human face, this package can
+be used to extract a specific set of 68 landmarks, as defined in Menpofit.
+Please refer to the original Menpofit documentation_ for implementation
+details. Here, we show some examples of how to use this package.
Landmark Detection on a Single Face
-----------------------------------
The most simple face detection task is to detect a single face in an image.
-This task can be accomplished using the ``detect_landmarks()`` function in this package.
-The following code-example shows how to extract facial keypoints for a single face in a gray-level input image:
+This task can be accomplished using the :py:func:`detect_landmarks` function in
+this package. The following code-example shows how to extract facial keypoints
+for a single face in a gray-level input image:
.. doctest::
@@ -51,47 +54,34 @@ The following code-example shows how to extract facial keypoints for a single fa
>>> print(key_points[0].bounding_box.bottomright)
(394, 376)
-This package also provides a handy function, ``draw_landmarks()``, for plotting the extracted facial-landmarks on an image.
+This package also provides a handy function, :py:func:`draw_landmarks`, for
+plotting the extracted facial-landmarks on an image.
.. doctest::
>>> bob.ip.facelandmarks.draw_landmarks(gray_image, key_points)
-The result is shown in the image below.
+The result is shown in the image below:
.. plot:: plot/single_face_lmks.py
:include-source: False
+The return value of :py:func:`detect_landmarks` is a list. When only one face
+is expected in the input, this list will contain only one element. Each
+element in the list is an object of type :py:class:`Result`.
-The ``detect_landmarks()`` function has the following signature: `detect_landmarks(gray_image, top=0, min_quality=0.0)`.
-
- * ``gray_image``: a numpy-array containing the gray-level input image, and,
- * ``top``: positive integer (default=0), specifying the number of faces to be detected in this image.
- * ``min_quality``: positive floating-point number (default=0), specifying the minimum acceptable quality for the result of face-detection.
-
-The first parameter is obligatory, and should be a valid 2D numpy-array representing a gray-level image.
-The remaining two parameters are optional.
-In the example above, ``top`` is specified as 1, hence, landmarks for only one face are extracted.
-
-The function ``detect_landmarks()`` first detects faces in the input image, using ``bob.ip.facedetect``, and then uses the result of the face-detection-step for detecting facial-landmarks.
-
+The first two members, ``bounding_box`` and ``quality``, come from
+:py:mod:`bob.ip.facedetect`. The detected bounding-boxes are sorted in order of
+decreasing quality, and the top-N (where N is the value specified for the
+parameter ``top``) bounding-boxes are used, one by one, in the
+landmark-detection step.
-If the ``min_quality`` parameter is specified, then bounding-boxes having a quality-value lower than the specified value are ignored.
-
-The return value of ``detect_landmarks()`` is a list.
-When only one face is expected in the input, this list will contain only one element.
-Each element in the list is an object with three members, named as follows:
-
- * ``bounding_box``: an object with two elements (topright, and bottomleft), each of which is a tuple (row,col) giving the coordinates of the top-left and bottom-right corners of the detected face-bounding-box.
- * ``quality``: a floating-point number between 0 and 100.0, giving a quality-estimate for the result of the face-detection step.
- * ``landmarks``: a numpy-array of shape (68, 2).
-
-The first two members, ``bounding_box`` and ``quality``, come from ``bob.ip.facedetect``.
-The detected bounding-boxes are sorted in order of decreasing quality, and the top-N (where N is the value specified for the parameter ``top``) bounding-boxes are used, one by one, in the landmark-detection step.
-
-For each detected face, each row in ``landmarks`` represents one of the 68 facial-landmarks, and gives the coordinates (row,col) of that landmark.
-As described in the Menpofit documentation, The facial-landmarks are listed in a specific order in the array:
+For each detected face, each row in third member of :py:class:`Result` called
+``landmarks`` represents one of the 68 facial-landmarks, and gives the
+coordinates (row, column) of that landmark. As described in the Menpofit_
+documentation, The facial-landmarks are listed in a specific order in the
+array:
.. code-block:: python
@@ -106,8 +96,13 @@ As described in the Menpofit documentation, The facial-landmarks are listed in a
inner_mouth_indices = [60, 67]
-If the bounding-box of the desired face is already available (via a preceding call to the function ``face.ip.facedetect.detect_single_face()``), the function ``detect_landmarks_on_boundingbox(gray_image, bounding_box)`` may be used to determine the facial-landmarks within this bounding-box.
-Note that the return-value of ``detect_landmarks_on_boundingbox()`` is a 2D numpy-array representing the coordinates of the 68 landmarks (and not an object as in the case of ``detect_landmarks()``).
+If the bounding-box of the desired face is already available (via a preceding
+call to the function :py:func:`bob.ip.facedetect.detect_single_face`), the
+function :py:func:`detect_landmarks_on_boundingbox` may be used to determine
+the facial-landmarks within this bounding-box. Note that the return-value of
+:py:func:`detect_landmarks_on_boundingbox` is a 2D numpy-array representing the
+coordinates of the 68 landmarks (and not an object as in the case of
+:py:func:`detect_landmarks`).
.. doctest::
@@ -122,8 +117,10 @@ Note that the return-value of ``detect_landmarks_on_boundingbox()`` is a 2D nump
Landmark Detection on Multiple Faces
------------------------------------
-To extract landmarks for multiple faces in the same image, use the ``top`` parameter when calling ``detect_landmarks()``.
-In the following example, the input image contains several faces, out of which, landmarks are extracted for the 5 faces with the best face-detection-quality.
+To extract landmarks for multiple faces in the same image, use the ``top``
+parameter when calling :py:func:`detect_landmarks`. In the following example,
+the input image contains several faces, out of which, landmarks are extracted
+for the 5 faces with the best face-detection-quality.
.. doctest::
@@ -140,5 +137,4 @@ In the following example, the input image contains several faces, out of which,
.. _Menpofit: http://www.menpo.org/menpofit/
-
.. _documentation: https://menpofit.readthedocs.io/en/stable/
diff --git a/doc/nitpick-exceptions.txt b/doc/nitpick-exceptions.txt
index 21e54e64debbe1d792aed74efab96f1540d78c14..d46d4e0246ffdcb963cc4551554f3fae4f7cc6b2 100644
--- a/doc/nitpick-exceptions.txt
+++ b/doc/nitpick-exceptions.txt
@@ -1,3 +1,4 @@
-# Solve some Python 2.7 misses on its documentation
+# This is not documented as py:exc in Python 2.7 - works in Python 3.x
+py:obj list
py:class list
py:class collections.namedtuple