pychubby.detect module¶
Collection of detection algorithms.

class
pychubby.detect.
LandmarkFace
(points, img, rectangle=None)¶ Bases:
object
Class representing a combination of a face image and its landmarks.
Parameters:  points (np.ndarray) – Array of shape (68, 2) where rows are different landmark points and the columns are x and y coordinates.
 img (np.ndarray) – Representing an image of a face. Any dtype and any number of channels.
 rectangle (tuple) – Two containing two tuples where the first one represents the top left corner of a rectangle and the second one the bottom right corner of a rectangle.

shape
¶ Tuple representing the height and width of the image.
Type: tuple

angle
(landmark_1, landmark_2, reference_vector=None, use_radians=False)¶ Angle between two landmarks and positive part of the x axis.
The possible values range from (180, 180) in degrees.
Parameters:  landmark_1 (int) – An integer from [0,57] representing a landmark point. The start of the vector.
 landmark_2 (int) – An integer from [0,57] representing a landmark point. The end of the vector.
 reference_vector (None or tuple) – If None, then positive part of the x axis used (1, 0). Otherwise specified by the user.
 use_radians (bool) – If True, then radians used. Otherwise degrees.
Returns: angle – The angle between the two landmarks and positive part of the x axis.
Return type: float

classmethod
estimate
(img, model_path=None, n_upsamples=1, allow_multiple=True)¶ Estimate the 68 landmarks.
Parameters:  img (np.ndarray) – Array representing an image of a face. Any dtype and any number of channels.
 model_path (str or pathlib.Path, default=None) – Path to where the pretrained model is located. If None then using the CACHE_FOLDER model.
 n_upsamples (int) – Upsample factor to apply to the image before detection. Allows to recognize more faces.
 allow_multiple (bool) – If True, multiple faces are allowed. In case more than one face detected then instance
of
LandmarkFaces
is returned. If False, raises error if more faces detected.
Returns: If only one face detected, then returns instance of
LandmarkFace
. If multiple faces detected and allow_multiple=True then instance ofLandmarFaces
is returned.Return type:

euclidean_distance
(landmark_1, landmark_2)¶ Euclidean distance between 2 landmarks.
Parameters:  landmark_1 (int) – An integer from [0,57] representing a landmark point.
 landmark_2 (int) – An integer from [0,57] representing a landmark point.
Returns: dist – Euclidean distance between landmark_1 and landmark_2.
Return type: float

plot
(figsize=(12, 12), show_landmarks=True)¶ Plot face together with landmarks.
Parameters:  figsize (tuple) – Size of the figure  (height, width).
 show_landmarks (bool) – Show all 68 landmark points on the face.

class
pychubby.detect.
LandmarkFaces
(*lf_list)¶ Bases:
object
Class enclosing multiple instances of
LandmarkFace
.Parameters: *lf_list (list) – Sequence of LandmarkFace
instances.
plot
(figsize=(12, 12), show_numbers=True, show_landmarks=False)¶ Plot.
Parameters:  figsize (tuple) – Size of the figure  (height, width).
 show_numbers (bool) – If True, then a number is shown on each face representing its order. This order is
useful when using the metaaction
Multiple
.  show_landmarks (bool) – Show all 68 landmark points on each of the faces.


pychubby.detect.
face_rectangle
(img, n_upsamples=1)¶ Find a face rectangle.
Parameters: img (np.ndarray) – Image of any dtype and number of channels. Returns:  corners (list) – List of tuples where each tuple represents the top left and bottom right coordinates of the face rectangle. Note that these coordinates use the (row, column) convention. The length of the list is equal to the number of detected faces.
 faces (list) – Instance of
dlib.rectagles
that can be used in other algorithm.  n_upsamples (int) – Upsample factor to apply to the image before detection. Allows to recognize more faces.

pychubby.detect.
landmarks_68
(img, rectangle, model_path=None)¶ Predict 68 face landmarks.
Parameters:  img (np.ndarray) – Image of any dtype and number of channels.
 rectangle (dlib.rectangle) – Rectangle that represents the bounding box around a single face.
 model_path (str or pathlib.Path, default=None) – Path to where the pretrained model is located. If None then using the CACHE_FOLDER model.
Returns:  lm_points (np.ndarray) – Array of shape (68, 2) where rows are different landmark points and the columns are x and y coordinates.
 original (dlib.full_object_detection) – Instance of
dlib.full_object_detection
.