detect_all_faces(image, [cascade], [sampler], [threshold], [overlaps], [minimum_overlap], [relative_prediction_threshold]) -> bounding_boxes, qualities

  Detects all faces in the given image, whose prediction values are higher than the given threshold.

  If the given ``minimum_overlap`` is lower than 1, overlapping bounding boxes are grouped, with the ``minimum_overlap`` being the minimum Jaccard similarity between two boxes to be considered to be overlapping.
  Afterwards, all groups which have less than ``overlaps`` elements are discarded (this measure is similar to the Viola-Jones face detector).
  Finally, :py:func:`average_detections` is used to compute the average bounding box for each of the groups, including averaging the detection value (which will, hence, usually decrease in value).

  **Parameters:**

  ``image`` : array_like (2D aka gray or 3D aka RGB)
    The image to detect a face in.

  ``cascade`` : str or :py:class:`Cascade` or ``None``
    If given, the cascade file name or the loaded cascade to be used to classify image patches.
    If not given, the :py:func:`default_cascade` is used.

  ``sampler`` : :py:class:`Sampler` or ``None``
    The sampler that defines the sampling of bounding boxes to search for the face.
    If not specified, a default Sampler is instantiated.

  ``threshold`` : float
    The threshold of the quality of detected faces.
    Detections with a quality lower than this value will not be considered.
    Higher thresholds will not detect all faces, while lower thresholds will generate false detections.

  ``overlaps`` : int
    The number of overlapping boxes that must exist for a bounding box to be considered.
    Higher values will remove a lot of false-positives, but might increase the chance of a face to be missed.
    The default value ``1`` will not limit the boxes.

  ``minimum_overlap`` : float between 0 and 1
    Groups detections based on the given minimum bounding box overlap, see :py:func:`group_detections`.

  ``relative_prediction_threshold`` : float between 0 and 1
    Limits the bounding boxes to those that have a prediction value higher then ``relative_prediction_threshold * max(predictions)``

  **Returns:**

  ``bounding_boxes`` : [:py:class:`BoundingBox`]
    The bounding box containing the detected face.

  ``qualities`` : [float]
    The qualities of the ``bounding_boxes``, values greater than ``threshold``.

def detect_all_faces(image, cascade = None, sampler = None, threshold = 0, overlaps = 1, minimum_overlap = 0.2, relative_prediction_threshold = 0.25):
  """detect_all_faces(image, [cascade], [sampler], [threshold], [overlaps], [minimum_overlap], [relative_prediction_threshold]) -> bounding_boxes, qualities

  Detects all faces in the given image, whose prediction values are higher than the given threshold.

  If the given ``minimum_overlap`` is lower than 1, overlapping bounding boxes are grouped, with the ``minimum_overlap`` being the minimum Jaccard similarity between two boxes to be considered to be overlapping.
  Afterwards, all groups which have less than ``overlaps`` elements are discarded (this measure is similar to the Viola-Jones face detector).
  Finally, :py:func:`average_detections` is used to compute the average bounding box for each of the groups, including averaging the detection value (which will, hence, usually decrease in value).

  **Parameters:**

  ``image`` : array_like (2D aka gray or 3D aka RGB)
    The image to detect a face in.

  ``cascade`` : str or :py:class:`Cascade` or ``None``
    If given, the cascade file name or the loaded cascade to be used to classify image patches.
    If not given, the :py:func:`default_cascade` is used.

  ``sampler`` : :py:class:`Sampler` or ``None``
    The sampler that defines the sampling of bounding boxes to search for the face.
    If not specified, a default Sampler is instantiated.

  ``threshold`` : float
    The threshold of the quality of detected faces.
    Detections with a quality lower than this value will not be considered.
    Higher thresholds will not detect all faces, while lower thresholds will generate false detections.

  ``overlaps`` : int
    The number of overlapping boxes that must exist for a bounding box to be considered.
    Higher values will remove a lot of false-positives, but might increase the chance of a face to be missed.
    The default value ``1`` will not limit the boxes.

  ``minimum_overlap`` : float between 0 and 1
    Groups detections based on the given minimum bounding box overlap, see :py:func:`group_detections`.

  ``relative_prediction_threshold`` : float between 0 and 1
    Limits the bounding boxes to those that have a prediction value higher then ``relative_prediction_threshold * max(predictions)``

  **Returns:**

  ``bounding_boxes`` : [:py:class:`BoundingBox`]
    The bounding box containing the detected face.

  ``qualities`` : [float]
    The qualities of the ``bounding_boxes``, values greater than ``threshold``.
  """
  if cascade is None:
    cascade = default_cascade()
  elif isinstance(cascade, str):
    cascade = Cascade(bob.io.base.HDF5File(cascade))

  if sampler is None:
    sampler = Sampler(patch_size = cascade.extractor.patch_size, distance=2, scale_factor=math.pow(2.,-1./16.), lowest_scale=0.125)

  if image.ndim == 3:
    image = bob.ip.color.rgb_to_gray(image)

  detections = []
  predictions = []
  # get the detection scores for the image
  for prediction, bounding_box in sampler.iterate_cascade(cascade, image, threshold):
    detections.append(bounding_box)
    predictions.append(prediction)

  if not detections:
    # No face detected
    return None

  # group overlapping detections
  if minimum_overlap < 1.:
    detections, predictions = group_detections(detections, predictions, minimum_overlap, threshold, overlaps)

    if not detections:
      return None

    # average them
    detections, predictions = zip(*[average_detections(b, q, relative_prediction_threshold) for b,q in zip(detections, predictions)])

  return detections, predictions