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 of LandmarFaces is returned.

Return type:

LandmarkFace or LandmarkFaces

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.