SPPAS 4.20

def invalidate(self):
    """Invalidate current list of detected object coordinates."""
    self._coords = list()

def get_extension(self):
    """Return the expected extension of the model filename."""
    return self._extension

def get_min_ratio(self):
    """Return the minimum ratio of an object compared to the image."""
    return self.__min_ratio

def set_min_ratio(self, value):
    """Set the minimum ratio of an object compared to the image.

        It means that width and height of a detected object must be at
        least 'value' percent of the image width and height respectively

        :param value: (float) Value ranging [0., 1.]
        :raise: ValueError

        """
    value = BaseObjectsDetector.to_dtype(value, dtype=float)
    if value < 0.0 or value > 1.0:
        raise IntervalRangeException(value, 0.0, 1.0)
    self.__min_ratio = value

def get_min_score(self):
    """Return the minimum score of a detected object to consider it."""
    return self.__min_score

def set_min_score(self, value):
    """Set the minimum score of a detected object to consider it.

        It means that any detected object with a score lesser than the given
        one will be ignored. The score of detected objects are supposed to
        range between 0. and 1.

        :param value: (float) Value ranging [0., 1.]
        :raise: ValueError

        """
    value = BaseObjectsDetector.to_dtype(value, dtype=float)
    if value < 0.0 or value > 1.0:
        raise IntervalRangeException(value, 0.0, 1.0)
    self.__min_score = value

def get_best(self, nb=1):
    """Return a copy of the coordinates with the n-best scores.

        Add "None" if more objects are requested than those detected.

        :param nb: (int) number of coordinates to return
        :return: (list of sppasCoords or sppasCoords or None)

        """
    if len(self._coords) == 0:
        return None
    nb = BaseObjectsDetector.to_dtype(nb)
    if nb == 1:
        return self._coords[0]
    nbest = [c.copy() for c in self._coords[:nb]]
    if nb > len(nbest):
        nbest.extend([None] * (nb - len(nbest)))
    return nbest

def get_confidence(self, confidence=0.2):
    """Return a copy of the coordinate objects with the better scores.

        :param confidence: (float) Minimum confidence score ranging [0., 1.]
        :return: (list of sppasCoords or sppasCoords or None)

        """
    if len(self._coords) == 0:
        return None
    score = BaseObjectsDetector.to_dtype(confidence, dtype=float)
    return [c.copy() for c in self._coords if c.get_confidence() > score]

def load_model(self, model, *args):
    """Load at least a model to instantiate a detector.

        :param model: Filename of a model (DNN, HaarCascade, ...)
        :raise: IOError if model is not loaded.

        """
    if model.endswith(self._extension) is False:
        raise IOExtensionError(model)
    if os.path.exists(model) is False:
        raise sppasIOError(model)
    self._set_detector(model)

def detect(self, image):
    """Determine the coordinates of all the detected objects.

        :param image: (sppasImage or numpy.ndarray)
        :raises: sppasTypeError: Given parameter is not an image.
        :raises: sppasError: No model was instantiated.

        """
    self.invalidate()
    if isinstance(image, numpy.ndarray) is True:
        image = sppasImage(input_array=image)
    if isinstance(image, sppasImage) is False:
        logging.debug('Object detection requires a sppasImage. Got {} instead.'.format(str(type(image))))
        raise sppasTypeError(str(type(image)), expected='sppasImage')
    if self._detector is None:
        raise sppasError(ERR_MODEL_MISS)
    self._detection(image)
    self.filter_confidence(self.get_min_score())
    self.sort_by_score()
    try:
        self.filter_overlapped()
        self.sort_by_score()
    except NotImplementedError:
        pass

def sort_by_score(self):
    """Sort the detected objects by their confidence score.

        The highest the better.

        """
    detected = list()
    for coord in self._coords:
        c = coord.copy()
        score = c.get_confidence()
        detected.append((c, score))
    self._coords = list()
    for coord, score in reversed(sorted(detected, key=lambda x: x[1])):
        self._coords.append(coord)

def filter_best(self, nb=1):
    """Filter the coordinates to select only the n-best scores.

        If there are less coordinates than those requested, nothing is
        changed.

        :param nb: (int) number of coordinates to keep

        """
    best = self.get_best(nb)
    if nb == 1:
        best = [best]
    if nb < len(self._coords):
        self._coords = best

def filter_confidence(self, confidence=0.2):
    """Filter the coordinates to select only the highest scores.

        :param confidence: (float) Minimum confidence score

        """
    if len(self._coords) == 0:
        return None
    best = self.get_confidence(confidence)
    if len(best) < len(self._coords):
        self._coords = best

@staticmethod
def to_dtype(value, dtype=int):
    """Convert a value to dtype or raise the appropriate exception.

        :param value: (any type)
        :param dtype: (type) Expected type of the value
        :returns: Value of the given type
        :raises: TypeError

        """
    try:
        value = dtype(value)
        if isinstance(value, dtype) is False:
            raise sppasTypeError(value, str(dtype))
    except ValueError:
        raise sppasTypeError(value, str(dtype))
    return value

def filter_overlapped(self, overlap=50.0):
    """Remove overlapping detected objects.

        To be overridden.

        """
    pass

def _set_detector(self, model):
    """Really load the model and instantiate the detector.

        To be overridden.

        """
    raise NotImplementedError

def _detection(self, image):
    """Determine the coordinates of the detected objects.

        To be overridden.

        """
    raise NotImplementedError

def __len__(self):
    return len(self._coords)

def __iter__(self):
    for coordinates in self._coords:
        yield coordinates

def __getitem__(self, i):
    return self._coords[i]

def __contains__(self, value):
    """Return true if value in self.__coordinates."""
    for c in self._coords:
        if c == value:
            return True
    return False

def __str__(self):
    return '\n'.join([str(c) for c in self._coords])

def __repr__(self):
    return self.__class__.__name__

def __format__(self, fmt):
    return str(self).__format__(fmt)