Core

Classifications

Source code in supervision/classification/core.py

@dataclass
class Classifications:
    class_id: np.ndarray
    confidence: Optional[np.ndarray] = None

    def __post_init__(self) -> None:
        """
        Validate the classification inputs.
        """
        n = len(self.class_id)

        _validate_class_ids(self.class_id, n)
        _validate_confidence(self.confidence, n)

    @classmethod
    def from_ultralytics(cls, ultralytics_results) -> Classifications:
        """
        Creates a Classifications instance from a
        (https://github.com/ultralytics/ultralytics) inference result.

        Args:
            ultralytics_results (ultralytics.engine.results.Results):
                The output Results instance from ultralytics model

        Returns:
            Classifications: A new Classifications object.

        Example:
            ```python
            >>> import cv2
            >>> from ultralytics import YOLO
            >>> import supervision as sv

            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
            >>> model = YOLO('yolov8n-cls.pt')
            >>> model = YOLO('yolov8s-cls.pt')

            >>> result = model(image)[0]
            >>> classifications = sv.Classifications.from_ultralytics(result)
            ```
        """
        confidence = ultralytics_results.probs.data.cpu().numpy()
        return cls(class_id=np.arange(confidence.shape[0]), confidence=confidence)

    def get_top_k(self, k: int) -> Tuple[np.ndarray, np.ndarray]:
        """
        Retrieve the top k class IDs and confidences,
            ordered in descending order by confidence.

        Args:
            k (int): The number of top class IDs and confidences to retrieve.

        Returns:
            Tuple[np.ndarray, np.ndarray]: A tuple containing
                the top k class IDs and confidences.

        Example:
            ```python
            >>> import supervision as sv

            >>> classifications = sv.Classifications(...)

            >>> classifications.get_top_k(1)

            (array([1]), array([0.9]))
            ```
        """
        if self.confidence is None:
            raise ValueError("top_k could not be calculated, confidence is None")

        order = np.argsort(self.confidence)[::-1]
        top_k_order = order[:k]
        top_k_class_id = self.class_id[top_k_order]
        top_k_confidence = self.confidence[top_k_order]

        return top_k_class_id, top_k_confidence

__post_init__()

Validate the classification inputs.

Source code in supervision/classification/core.py

def __post_init__(self) -> None:
    """
    Validate the classification inputs.
    """
    n = len(self.class_id)

    _validate_class_ids(self.class_id, n)
    _validate_confidence(self.confidence, n)

from_ultralytics(ultralytics_results) classmethod

Creates a Classifications instance from a (https://github.com/ultralytics/ultralytics) inference result.

Parameters:

Name	Type	Description	Default
ultralytics_results	Results	The output Results instance from ultralytics model	required

Returns:

Name	Type	Description
Classifications	Classifications	A new Classifications object.

Example

>>> import cv2
>>> from ultralytics import YOLO
>>> import supervision as sv

>>> image = cv2.imread(SOURCE_IMAGE_PATH)
>>> model = YOLO('yolov8n-cls.pt')
>>> model = YOLO('yolov8s-cls.pt')

>>> result = model(image)[0]
>>> classifications = sv.Classifications.from_ultralytics(result)

Source code in supervision/classification/core.py

@classmethod
def from_ultralytics(cls, ultralytics_results) -> Classifications:
    """
    Creates a Classifications instance from a
    (https://github.com/ultralytics/ultralytics) inference result.

    Args:
        ultralytics_results (ultralytics.engine.results.Results):
            The output Results instance from ultralytics model

    Returns:
        Classifications: A new Classifications object.

    Example:
        ```python
        >>> import cv2
        >>> from ultralytics import YOLO
        >>> import supervision as sv

        >>> image = cv2.imread(SOURCE_IMAGE_PATH)
        >>> model = YOLO('yolov8n-cls.pt')
        >>> model = YOLO('yolov8s-cls.pt')

        >>> result = model(image)[0]
        >>> classifications = sv.Classifications.from_ultralytics(result)
        ```
    """
    confidence = ultralytics_results.probs.data.cpu().numpy()
    return cls(class_id=np.arange(confidence.shape[0]), confidence=confidence)

get_top_k(k)

Retrieve the top k class IDs and confidences, ordered in descending order by confidence.

Parameters:

Name	Type	Description	Default
k	int	The number of top class IDs and confidences to retrieve.	required

Returns:

Type	Description
Tuple[ndarray, ndarray]	Tuple[np.ndarray, np.ndarray]: A tuple containing the top k class IDs and confidences.

Example

>>> import supervision as sv

>>> classifications = sv.Classifications(...)

>>> classifications.get_top_k(1)

(array([1]), array([0.9]))

Source code in supervision/classification/core.py

def get_top_k(self, k: int) -> Tuple[np.ndarray, np.ndarray]:
    """
    Retrieve the top k class IDs and confidences,
        ordered in descending order by confidence.

    Args:
        k (int): The number of top class IDs and confidences to retrieve.

    Returns:
        Tuple[np.ndarray, np.ndarray]: A tuple containing
            the top k class IDs and confidences.

    Example:
        ```python
        >>> import supervision as sv

        >>> classifications = sv.Classifications(...)

        >>> classifications.get_top_k(1)

        (array([1]), array([0.9]))
        ```
    """
    if self.confidence is None:
        raise ValueError("top_k could not be calculated, confidence is None")

    order = np.argsort(self.confidence)[::-1]
    top_k_order = order[:k]
    top_k_class_id = self.class_id[top_k_order]
    top_k_confidence = self.confidence[top_k_order]

    return top_k_class_id, top_k_confidence