Datasets

Warning

Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the supervision version in your requirements.txt or setup.py.

DetectionDataset

supervision.dataset.core.DetectionDataset

Bases: BaseDataset

Contains information about a detection dataset. Handles lazy image loading and annotation retrieval, dataset splitting, conversions into multiple formats.

Attributes:

Name	Type	Description
classes		List containing dataset class names.
images		Accepts a list of image paths. Passing a dict (Dict[str, np.ndarray]) is deprecated in 0.30.0 and will be removed in 0.33.0; use a list of paths instead. When a list of paths is provided, images are loaded lazily on demand, which is more memory-efficient.
annotations		Dictionary mapping image path to annotations. The dictionary keys match match the keys in images or entries in the list of image paths.

Source code in src/supervision/dataset/core.py

class DetectionDataset(BaseDataset):
    """
    Contains information about a detection dataset. Handles lazy image loading
    and annotation retrieval, dataset splitting, conversions into multiple
    formats.

    Attributes:
        classes: List containing dataset class names.
        images:
            Accepts a list of image paths. Passing a dict
            (``Dict[str, np.ndarray]``) is deprecated in ``0.30.0`` and will
            be removed in ``0.33.0``; use a list of paths instead.
            When a list of paths is provided, images are loaded lazily on
            demand, which is more memory-efficient.
        annotations: Dictionary mapping
            image path to annotations. The dictionary keys match
            match the keys in `images` or entries in the list of
            image paths.
    """

    def __init__(
        self,
        classes: list[str],
        images: list[str] | dict[str, npt.NDArray[np.uint8]],
        annotations: dict[str, Detections],
    ) -> None:
        self.classes = classes

        if set(images) != set(annotations):
            raise ValueError(
                "The keys of the images and annotations dictionaries must match."
            )
        self.annotations = {
            image_path: deepcopy(annotation)
            for image_path, annotation in annotations.items()
        }

        np_classes = np.array(self.classes)
        for image_path, annotation in self.annotations.items():
            class_ids = annotation.class_id
            if class_ids is None:
                continue
            if not np.issubdtype(class_ids.dtype, np.integer):
                raise ValueError(
                    f"Detection annotation for image {image_path!r} contains "
                    f"non-integer class_id values with dtype {class_ids.dtype}."
                )

            invalid_class_ids = class_ids[
                (class_ids < 0) | (class_ids >= len(self.classes))
            ]
            if len(invalid_class_ids) > 0:
                valid_range = (
                    "empty"
                    if len(self.classes) == 0
                    else f"[0, {len(self.classes) - 1}]"
                )
                raise ValueError(
                    f"Detection annotation for image {image_path!r} contains "
                    f"class_id {int(invalid_class_ids[0])}, outside the valid "
                    f"range {valid_range} for {len(self.classes)} classes."
                )

            annotation.data[CLASS_NAME_DATA_FIELD] = np_classes[class_ids]

        # Eliminate duplicates while preserving order
        self.image_paths = list(dict.fromkeys(images))

        self._images_in_memory: dict[str, npt.NDArray[np.uint8]] = {}
        if isinstance(images, dict):
            self._images_in_memory = images
            warn_deprecated(
                "Passing a `Dict[str, np.ndarray]` into `DetectionDataset` is "
                "deprecated in `0.30.0` and will be removed in `0.33.0`. Use "
                "a list of paths `List[str]` instead."
            )

    def _get_image(self, image_path: str) -> npt.NDArray[np.uint8]:
        """Assumes that image is in dataset."""
        if self._images_in_memory:
            return self._images_in_memory[image_path]
        image = cv2.imread(image_path)
        if image is None:
            raise ValueError(f"Could not read image from path: {image_path}")
        return cast(npt.NDArray[np.uint8], image)

    def __len__(self) -> int:
        return len(self._images_in_memory) or len(self.image_paths)

    def __getitem__(self, i: int) -> tuple[str, npt.NDArray[np.uint8], Detections]:
        """
        Returns:
            The image path, image data,
                and its corresponding annotation at index i.
        """
        image_path = self.image_paths[i]
        image = self._get_image(image_path)
        annotation = self.annotations[image_path]
        return image_path, image, annotation

    def __iter__(self) -> Iterator[tuple[str, npt.NDArray[np.uint8], Detections]]:
        """
        Iterate over the images and annotations in the dataset.

        Yields:
            Tuples containing the image path, image data, and its annotation.
        """
        for i in range(len(self)):
            image_path, image, annotation = self[i]
            yield image_path, image, annotation

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, DetectionDataset):
            return False

        if self.classes != other.classes:
            return False

        if self.image_paths != other.image_paths:
            return False

        if self._images_in_memory or other._images_in_memory:
            if not np.array_equal(
                list(self._images_in_memory.values()),
                list(other._images_in_memory.values()),
            ):
                return False

        if self.annotations != other.annotations:
            return False

        return True

    def split(
        self,
        split_ratio: float = 0.8,
        random_state: int | None = None,
        shuffle: bool = True,
    ) -> tuple[DetectionDataset, DetectionDataset]:
        """
        Splits the dataset into two parts (training and testing)
            using the provided split_ratio. The input dataset is not mutated.

        Args:
            split_ratio: The ratio of the training
                set to the entire dataset.
            random_state: The seed for the random number generator.
                This is used for reproducibility.
            shuffle: Whether to shuffle the data before splitting.

        Returns:
            A tuple containing
                the training and testing datasets.

        Examples:
            ```pycon
            >>> import numpy as np
            >>> import supervision as sv
            >>> ds = sv.DetectionDataset(
            ...     classes=['dog', 'person'],
            ...     images={
            ...         'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
            ...         'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
            ...     },
            ...     annotations={
            ...         'img1.jpg': sv.Detections(xyxy=np.array([[10, 10, 20, 20]])),
            ...         'img2.jpg': sv.Detections(xyxy=np.array([[30, 30, 40, 40]])),
            ...     }
            ... )
            >>> train_ds, test_ds = ds.split(split_ratio=0.5, random_state=42)
            >>> len(train_ds), len(test_ds)
            (1, 1)

            ```
        """

        train_paths, test_paths = train_test_split(
            data=self.image_paths,
            train_ratio=split_ratio,
            random_state=random_state,
            shuffle=shuffle,
        )

        train_annotations = {path: self.annotations[path] for path in train_paths}
        test_annotations = {path: self.annotations[path] for path in test_paths}

        train_dataset = DetectionDataset(
            classes=self.classes,
            images=train_paths,
            annotations=train_annotations,
        )
        test_dataset = DetectionDataset(
            classes=self.classes,
            images=test_paths,
            annotations=test_annotations,
        )
        if self._images_in_memory:
            train_dataset._images_in_memory = {
                path: self._images_in_memory[path] for path in train_paths
            }
            test_dataset._images_in_memory = {
                path: self._images_in_memory[path] for path in test_paths
            }
        return train_dataset, test_dataset

    @classmethod
    def merge(cls, dataset_list: list[DetectionDataset]) -> DetectionDataset:
        """
        Merge a list of `DetectionDataset` objects into a single
            `DetectionDataset` object.

        This method takes a list of `DetectionDataset` objects and combines
        their respective fields (`classes`, `images`,
        `annotations`) into a single `DetectionDataset` object.

        Args:
            dataset_list: A list of `DetectionDataset`
                objects to merge.

        Returns:
            A single `DetectionDataset` object containing
            the merged data from the input list.

        Examples:
            ```pycon
            >>> import numpy as np
            >>> import supervision as sv
            >>> ds_1 = sv.DetectionDataset(
            ...     classes=['dog', 'person'],
            ...     images={'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8)},
            ...     annotations={'img1.jpg': sv.Detections.empty()}
            ... )
            >>> len(ds_1)
            1
            >>> ds_1.classes
            ['dog', 'person']
            >>> ds_2 = sv.DetectionDataset(
            ...     classes=['cat'],
            ...     images={'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8)},
            ...     annotations={'img2.jpg': sv.Detections.empty()}
            ... )
            >>> len(ds_2)
            1
            >>> ds_2.classes
            ['cat']
            >>> ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
            >>> len(ds_merged)
            2
            >>> ds_merged.classes
            ['cat', 'dog', 'person']

            ```
        """

        def is_in_memory(dataset: DetectionDataset) -> bool:
            return len(dataset._images_in_memory) > 0 or len(dataset.image_paths) == 0

        def is_lazy(dataset: DetectionDataset) -> bool:
            return len(dataset._images_in_memory) == 0

        all_in_memory = all([is_in_memory(dataset) for dataset in dataset_list])
        all_lazy = all([is_lazy(dataset) for dataset in dataset_list])
        if not all_in_memory and not all_lazy:
            raise ValueError(
                "Merging lazy and in-memory DetectionDatasets is not supported."
            )

        images_in_memory = {}
        for dataset in dataset_list:
            images_in_memory.update(dataset._images_in_memory)

        image_paths = list(
            chain.from_iterable(dataset.image_paths for dataset in dataset_list)
        )
        image_paths_unique = list(dict.fromkeys(image_paths))
        if len(image_paths) != len(image_paths_unique):
            duplicates = find_duplicates(image_paths)
            raise ValueError(
                f"Image paths {duplicates} are not unique across datasets."
            )
        image_paths = image_paths_unique

        classes = merge_class_lists(
            class_lists=[dataset.classes for dataset in dataset_list]
        )

        annotations = {}
        for dataset in dataset_list:
            annotations.update(dataset.annotations)
        for dataset in dataset_list:
            class_index_mapping = build_class_index_mapping(
                source_classes=dataset.classes, target_classes=classes
            )
            for image_path in dataset.image_paths:
                annotations[image_path] = map_detections_class_id(
                    source_to_target_mapping=class_index_mapping,
                    detections=annotations[image_path],
                )

        merged_dataset = cls(
            classes=classes,
            images=image_paths,
            annotations=annotations,
        )
        if all_in_memory:
            merged_dataset._images_in_memory = images_in_memory
        return merged_dataset

    def as_pascal_voc(
        self,
        images_directory_path: str | None = None,
        annotations_directory_path: str | None = None,
        min_image_area_percentage: float = 0.0,
        max_image_area_percentage: float = 1.0,
        approximation_percentage: float = 0.0,
        show_progress: bool = False,
    ) -> None:
        """
        Exports the dataset to PASCAL VOC format. This method saves the images
        and their corresponding annotations in PASCAL VOC format. Both output
        layouts are preflighted before any files are written so a collision in
        either target fails without partial output.

        Args:
            images_directory_path: The path to the directory
                where the images should be saved.
                If not provided, images will not be saved.
            annotations_directory_path: The path to
                the directory where the annotations in PASCAL VOC format should be
                saved. If not provided, annotations will not be saved.
            min_image_area_percentage: The minimum percentage of
                detection area relative to
                the image area for a detection to be included.
                Argument is used only for segmentation datasets.
            max_image_area_percentage: The maximum percentage
                of detection area relative to
                the image area for a detection to be included.
                Argument is used only for segmentation datasets.
            approximation_percentage: The percentage of
                polygon points to be removed from the input polygon,
                in the range [0, 1). Argument is used only for segmentation datasets.
            show_progress: If True, display a progress bar during saving.

        Raises:
            ValueError: If two image paths share the same basename (when
                images_directory_path is set) or the same stem (when
                annotations_directory_path is set), which would cause one
                output file to overwrite another. Rename images to ensure
                unique basenames before exporting a merged dataset.
        """
        if images_directory_path:
            check_no_basename_collisions(
                image_paths=self.image_paths,
                key=lambda image_path: Path(image_path).name,
                output_kind="image",
            )
        if annotations_directory_path:
            check_no_basename_collisions(
                image_paths=self.image_paths,
                key=lambda image_path: f"{Path(image_path).stem}.xml",
                output_kind="Pascal VOC annotation",
            )

        if images_directory_path:
            save_dataset_images(
                dataset=self,
                images_directory_path=images_directory_path,
                show_progress=show_progress,
            )
        if annotations_directory_path:
            save_pascal_voc_annotations(
                dataset=self,
                annotations_directory_path=annotations_directory_path,
                min_image_area_percentage=min_image_area_percentage,
                max_image_area_percentage=max_image_area_percentage,
                approximation_percentage=approximation_percentage,
                show_progress=show_progress,
            )

    @classmethod
    def from_pascal_voc(
        cls,
        images_directory_path: str,
        annotations_directory_path: str,
        force_masks: bool = False,
        show_progress: bool = False,
    ) -> DetectionDataset:
        """
        Creates a Dataset instance from PASCAL VOC formatted data.

        Args:
            images_directory_path: Path to the directory containing the images.
            annotations_directory_path: Path to the directory
                containing the PASCAL VOC XML annotations.
            force_masks: If True, forces masks to
                be loaded for all annotations, regardless of whether they are present.
            show_progress: If True, display a progress bar during loading.

        Returns:
            A DetectionDataset instance containing
                the loaded images and annotations.

        Examples:
            ```python
            import roboflow
            from roboflow import Roboflow
            import supervision as sv

            roboflow.login()

            rf = Roboflow()

            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
            dataset = project.version(PROJECT_VERSION).download("voc")

            ds = sv.DetectionDataset.from_pascal_voc(
                images_directory_path=f"{dataset.location}/train/images",
                annotations_directory_path=f"{dataset.location}/train/labels",
                # pass show_progress=True to enable a tqdm progress bar
            )

            ds.classes
            # ['dog', 'person']
            ```
        """

        classes, image_paths, annotations = load_pascal_voc_annotations(
            images_directory_path=images_directory_path,
            annotations_directory_path=annotations_directory_path,
            force_masks=force_masks,
            show_progress=show_progress,
        )

        return DetectionDataset(
            classes=classes, images=image_paths, annotations=annotations
        )

    @classmethod
    def from_yolo(
        cls,
        images_directory_path: str,
        annotations_directory_path: str,
        data_yaml_path: str,
        force_masks: bool = False,
        is_obb: bool = False,
        show_progress: bool = False,
    ) -> DetectionDataset:
        """
        Creates a Dataset instance from YOLO formatted data.

        Args:
            images_directory_path: The path to the
                directory containing the images.
            annotations_directory_path: The path to the directory
                containing the YOLO annotation files.
            data_yaml_path: The path to the data
                YAML file containing class information.
            force_masks: If True, forces
                masks to be loaded for all annotations,
                regardless of whether they are present.
            is_obb: If True, loads the annotations in OBB format.
                OBB annotations are defined as `[class_id, x, y, x, y, x, y, x, y]`,
                where pairs of [x, y] are box corners.
            show_progress: If True, display a progress bar during loading.

        Returns:
            A DetectionDataset instance
                containing the loaded images and annotations.

        Examples:
            ```python
            import roboflow
            from roboflow import Roboflow
            import supervision as sv

            roboflow.login()
            rf = Roboflow()

            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
            dataset = project.version(PROJECT_VERSION).download("yolov5")

            ds = sv.DetectionDataset.from_yolo(
                images_directory_path=f"{dataset.location}/train/images",
                annotations_directory_path=f"{dataset.location}/train/labels",
                data_yaml_path=f"{dataset.location}/data.yaml",
                # pass show_progress=True to enable a tqdm progress bar
            )

            ds.classes
            # ['dog', 'person']
            ```
        """
        classes, image_paths, annotations = load_yolo_annotations(
            images_directory_path=images_directory_path,
            annotations_directory_path=annotations_directory_path,
            data_yaml_path=data_yaml_path,
            force_masks=force_masks,
            is_obb=is_obb,
            show_progress=show_progress,
        )
        return DetectionDataset(
            classes=classes, images=image_paths, annotations=annotations
        )

    def as_yolo(
        self,
        images_directory_path: str | None = None,
        annotations_directory_path: str | None = None,
        data_yaml_path: str | None = None,
        min_image_area_percentage: float = 0.0,
        max_image_area_percentage: float = 1.0,
        approximation_percentage: float = 0.0,
        is_obb: bool = False,
        show_progress: bool = False,
    ) -> None:
        """
        Exports the dataset to YOLO format. This method saves the
        images and their corresponding annotations in YOLO format.

        Args:
            images_directory_path: The path to the
                directory where the images should be saved.
                If not provided, images will not be saved.
            annotations_directory_path: The path to the
                directory where the annotations in
                YOLO format should be saved. If not provided,
                annotations will not be saved.
            data_yaml_path: The path where the data.yaml
                file should be saved.
                If not provided, the file will not be saved.
            min_image_area_percentage: The minimum percentage of
                detection area relative to
                the image area for a detection to be included.
                Argument is used only for segmentation datasets.
            max_image_area_percentage: The maximum percentage
                of detection area relative to
                the image area for a detection to be included.
                Argument is used only for segmentation datasets.
            approximation_percentage: The percentage of polygon points to
                be removed from the input polygon, in the range [0, 1).
                This is useful for simplifying the annotations.
                Argument is used only for segmentation datasets.
            is_obb: If True, exports annotations in OBB format
                (`class_id x1 y1 x2 y2 x3 y3 x4 y4`) using the oriented
                corners stored in `detections.data["xyxyxyxy"]`. Mirrors
                `from_yolo(..., is_obb=True)`. Masks are ignored when
                `is_obb=True`.
            show_progress: If True, display a progress bar during saving.

        Raises:
            ValueError: If two image paths share the same basename (when
                images_directory_path is set) or the same annotation
                file name (when annotations_directory_path is set),
                which would cause one output file to overwrite another.
        """
        if is_obb and (
            min_image_area_percentage != 0.0
            or max_image_area_percentage != 1.0
            or approximation_percentage != 0.0
        ):
            import warnings

            warnings.warn(
                "`min_image_area_percentage`, `max_image_area_percentage`, and "
                "`approximation_percentage` have no effect when `is_obb=True`; "
                "OBB annotations use corner coordinates directly.",
                UserWarning,
                stacklevel=2,
            )
        # Pre-flight: validate output uniqueness before writing any file
        if images_directory_path:
            check_no_basename_collisions(
                image_paths=self.image_paths,
                key=lambda image_path: Path(image_path).name,
                output_kind="image",
            )
        if annotations_directory_path:
            check_no_basename_collisions(
                image_paths=self.image_paths,
                key=lambda image_path: Path(image_path).stem + ".txt",
                output_kind="YOLO annotation",
            )

        if images_directory_path is not None:
            save_dataset_images(
                dataset=self,
                images_directory_path=images_directory_path,
                show_progress=show_progress,
            )
        if annotations_directory_path is not None:
            save_yolo_annotations(
                dataset=self,
                annotations_directory_path=annotations_directory_path,
                min_image_area_percentage=min_image_area_percentage,
                max_image_area_percentage=max_image_area_percentage,
                approximation_percentage=approximation_percentage,
                show_progress=show_progress,
                is_obb=is_obb,
            )
        if data_yaml_path is not None:
            save_data_yaml(data_yaml_path=data_yaml_path, classes=self.classes)

    @classmethod
    def from_labelme(
        cls,
        images_directory_path: str,
        annotations_directory_path: str,
        force_masks: bool = False,
    ) -> DetectionDataset:
        """
        Creates a Dataset instance from LabelMe formatted data.

        LabelMe stores one JSON file per image, each containing a list of
        ``shapes``. ``rectangle`` shapes are loaded as bounding boxes and
        ``polygon`` shapes as masks (with their bounding boxes); other shape
        types are skipped. Class names are inferred from the labels present in
        the files. When an image file contains a ``polygon`` shape, or when
        ``force_masks=True`` is set, both ``rectangle`` and ``polygon`` shapes
        produce masks: rectangles via a four-corner polygon fill.

        Args:
            images_directory_path: The path to the
                directory containing the images.
            annotations_directory_path: The path to the directory
                containing the LabelMe ``.json`` annotation files.
            force_masks: If True, forces masks to be loaded for all
                annotations, regardless of whether polygon shapes are present.
                Requires ``imageWidth`` and ``imageHeight`` in every JSON file.

        Returns:
            A DetectionDataset instance containing
                the loaded images and annotations.

        Raises:
            ValueError: If an annotation is malformed - for example
                ``imagePath`` is empty or resolves to ``..``, a shape is
                missing its ``label`` or ``points``, or a mask is required but
                ``imageWidth`` / ``imageHeight`` are missing or zero.

        Examples:
            ```python
            import supervision as sv

            ds = sv.DetectionDataset.from_labelme(
                images_directory_path="<IMAGES_DIRECTORY_PATH>",
                annotations_directory_path="<ANNOTATIONS_DIRECTORY_PATH>",
            )

            ds.classes
            # ['dog', 'person']
            ```
        """
        classes, image_paths, annotations = load_labelme_annotations(
            images_directory_path=images_directory_path,
            annotations_directory_path=annotations_directory_path,
            force_masks=force_masks,
        )
        return DetectionDataset(
            classes=classes, images=image_paths, annotations=annotations
        )

    def as_labelme(
        self,
        images_directory_path: str | None = None,
        annotations_directory_path: str | None = None,
    ) -> None:
        """
        Exports the dataset to LabelMe format. This method saves the images and
        their corresponding annotations as per-image LabelMe ``.json`` files.
        Masked detections are written as ``polygon`` shapes whose vertices
        approximate the mask contour, so masks are not bit-exact on round-trip.
        Because the bounding box is recomputed from the quantized polygon contour
        on re-import, bounding boxes for masked detections may also shift by
        approximately one pixel after a save-load cycle.

        Args:
            images_directory_path: The path to the directory
                where the images should be saved.
                If not provided, images will not be saved.
            annotations_directory_path: The path to the directory where the
                LabelMe ``.json`` files should be saved.
                If not provided, annotations will not be saved.

        Examples:
            ```python
            import supervision as sv

            ds = sv.DetectionDataset(...)

            ds.as_labelme(
                images_directory_path="<IMAGES_DIRECTORY_PATH>",
                annotations_directory_path="<ANNOTATIONS_DIRECTORY_PATH>",
            )
            ```
        """
        if images_directory_path is not None:
            save_dataset_images(
                dataset=self, images_directory_path=images_directory_path
            )
        if annotations_directory_path is not None:
            save_labelme_annotations(
                dataset=self,
                annotations_directory_path=annotations_directory_path,
            )

    @classmethod
    def from_createml(
        cls,
        images_directory_path: str,
        annotations_path: str,
        show_progress: bool = False,
    ) -> DetectionDataset:
        """
        Creates a Dataset instance from CreateML formatted data.

        CreateML stores object-detection annotations in a single JSON file as a
        list of per-image entries, with each box expressed as a pixel-space
        centre point plus width and height. Class names are inferred from the
        labels present in the file.

        Args:
            images_directory_path: The path to the directory containing the
                images.
            annotations_path: The path to the CreateML json annotation file.
            show_progress: If True, display a progress bar during loading.

        Returns:
            A DetectionDataset instance containing the loaded images and
            annotations.

        Examples:
            ```python
            import roboflow
            from roboflow import Roboflow
            import supervision as sv

            roboflow.login()
            rf = Roboflow()

            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
            dataset = project.version(PROJECT_VERSION).download("createml")

            ds = sv.DetectionDataset.from_createml(
                images_directory_path=f"{dataset.location}/train",
                annotations_path=f"{dataset.location}/train/_annotations.createml.json",
            )

            ds.classes
            # ['dog', 'person']
            ```
        """
        classes, image_paths, annotations = load_createml_annotations(
            images_directory_path=images_directory_path,
            annotations_path=annotations_path,
            show_progress=show_progress,
        )
        return DetectionDataset(
            classes=classes, images=image_paths, annotations=annotations
        )

    def as_createml(
        self,
        images_directory_path: str | None = None,
        annotations_path: str | None = None,
        show_progress: bool = False,
    ) -> None:
        """
        Exports the dataset to CreateML format. This method saves the
        images and their corresponding annotations in CreateML format.

        Args:
            images_directory_path: The path to the directory where the images
                should be saved. If not provided, images will not be saved.
            annotations_path: The path to the CreateML json annotation file.
                If not provided, the annotations will not be saved.
            show_progress: If True, display a progress bar while saving images.

        Returns:
            None. Side-effects only: writes images and/or annotation file.

        Examples:
            ```python
            import supervision as sv

            ds = sv.DetectionDataset(classes=["dog"], images=[], annotations={})
            ds.as_createml(
                images_directory_path="/tmp/images",
                annotations_path="/tmp/annotations.json",
            )
            ```
        """
        if images_directory_path is not None:
            save_dataset_images(
                dataset=self,
                images_directory_path=images_directory_path,
                show_progress=show_progress,
            )
        if annotations_path is not None:
            save_createml_annotations(
                dataset=self,
                annotations_path=annotations_path,
            )

    @classmethod
    def from_coco(
        cls,
        images_directory_path: str,
        annotations_path: str,
        force_masks: bool = False,
        show_progress: bool = False,
        *,
        use_iscrowd: bool = True,
    ) -> DetectionDataset:
        """
        Creates a Dataset instance from COCO formatted data.

        Args:
            images_directory_path: The path to the
                directory containing the images.
            annotations_path: The path to the json annotation files.
            force_masks: If True,
                forces masks to be loaded for all annotations,
                regardless of whether they are present.
            show_progress: If True, display a progress bar during loading.
            use_iscrowd: If True, includes COCO ``iscrowd`` and ``area``
                annotation fields in ``Detections.data``.
        Returns:
            A DetectionDataset instance containing
                the loaded images and annotations.

        Examples:
            ```python
            import roboflow
            from roboflow import Roboflow
            import supervision as sv

            roboflow.login()
            rf = Roboflow()

            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
            dataset = project.version(PROJECT_VERSION).download("coco")

            ds = sv.DetectionDataset.from_coco(
                images_directory_path=f"{dataset.location}/train",
                annotations_path=f"{dataset.location}/train/_annotations.coco.json",
                # pass show_progress=True to enable a tqdm progress bar
            )

            ds.classes
            # ['dog', 'person']
            ```
        """
        classes, images, annotations = load_coco_annotations(
            images_directory_path=images_directory_path,
            annotations_path=annotations_path,
            force_masks=force_masks,
            use_iscrowd=use_iscrowd,
            show_progress=show_progress,
        )
        return DetectionDataset(classes=classes, images=images, annotations=annotations)

    def as_coco(
        self,
        images_directory_path: str | None = None,
        annotations_path: str | None = None,
        min_image_area_percentage: float = 0.0,
        max_image_area_percentage: float = 1.0,
        approximation_percentage: float = 0.0,
        starting_image_id: int = 1,
        starting_annotation_id: int = 1,
        show_progress: bool = False,
    ) -> tuple[int, int]:
        """
        Exports the dataset to COCO format. This method saves the
        images and their corresponding annotations in COCO format.

        !!! tip

            The format of the mask is determined automatically based on its structure:

            - If a mask contains multiple disconnected components or holes, it will be
            saved using the Run-Length Encoding (RLE) format for efficient storage and
            processing.
            - If a mask consists of a single, contiguous region without any holes, it
            will be encoded as a polygon, preserving the outline of the object.

            This automatic selection ensures that the masks are stored in the most
            appropriate and space-efficient format, complying with COCO dataset
            standards.

        Args:
            images_directory_path: The path to the directory
                where the images should be saved.
                If not provided, images will not be saved.
            annotations_path: The path to COCO annotation file.
            min_image_area_percentage: The minimum percentage of
                detection area relative to
                the image area for a detection to be included.
                Argument is used only for segmentation datasets.
            max_image_area_percentage: The maximum percentage of
                detection area relative to
                the image area for a detection to be included.
                Argument is used only for segmentation datasets.
            approximation_percentage: The percentage of polygon points
                to be removed from the input polygon,
                in the range [0, 1). This is useful for simplifying the annotations.
                Argument is used only for segmentation datasets.
            starting_image_id: First image id to assign in the exported file.
                Defaults to ``1``. Override when exporting multiple splits into
                a coordinated COCO collection so ids remain unique across the
                set (see example below).
            starting_annotation_id: First annotation id to assign in the
                exported file. Defaults to ``1``. Override for the same
                multi-split reason as ``starting_image_id``.
            show_progress: If True, display a progress bar during saving.

        Returns:
            A ``(next_image_id, next_annotation_id)`` tuple containing the
            first unused ids after this export. Feed them straight back into
            ``starting_image_id`` and ``starting_annotation_id`` on the next
            split so ids stay globally unique. When ``annotations_path`` is
            ``None`` (images-only export) the starting ids are returned
            unchanged so chaining still composes.

        Example:
            ```python
            # Exporting train, valid, and test splits with non-colliding ids
            # so the three annotation files can later be merged into one COCO.
            next_image_id, next_annotation_id = train_ds.as_coco(
                images_directory_path="out/train/images",
                annotations_path="out/train/annotations.json",
            )
            next_image_id, next_annotation_id = valid_ds.as_coco(
                images_directory_path="out/valid/images",
                annotations_path="out/valid/annotations.json",
                starting_image_id=next_image_id,
                starting_annotation_id=next_annotation_id,
            )
            _, _ = test_ds.as_coco(
                images_directory_path="out/test/images",
                annotations_path="out/test/annotations.json",
                starting_image_id=next_image_id,
                starting_annotation_id=next_annotation_id,
            )  # return value not needed — no further split
            ```
        """
        if images_directory_path is not None:
            save_dataset_images(
                dataset=self,
                images_directory_path=images_directory_path,
                show_progress=show_progress,
            )
        if annotations_path is not None:
            return save_coco_annotations(
                dataset=self,
                annotation_path=annotations_path,
                min_image_area_percentage=min_image_area_percentage,
                max_image_area_percentage=max_image_area_percentage,
                approximation_percentage=approximation_percentage,
                starting_image_id=starting_image_id,
                starting_annotation_id=starting_annotation_id,
                show_progress=show_progress,
            )
        return starting_image_id, starting_annotation_id

Methods:

__getitem__(i: int) -> tuple[str, npt.NDArray[np.uint8], Detections]

Returns:

Type	Description
tuple[str, NDArray[uint8], Detections]	The image path, image data, and its corresponding annotation at index i.

Source code in src/supervision/dataset/core.py

def __getitem__(self, i: int) -> tuple[str, npt.NDArray[np.uint8], Detections]:
    """
    Returns:
        The image path, image data,
            and its corresponding annotation at index i.
    """
    image_path = self.image_paths[i]
    image = self._get_image(image_path)
    annotation = self.annotations[image_path]
    return image_path, image, annotation

__iter__() -> Iterator[tuple[str, npt.NDArray[np.uint8], Detections]]

Iterate over the images and annotations in the dataset.

Yields:

Type	Description
tuple[str, NDArray[uint8], Detections]	Tuples containing the image path, image data, and its annotation.

Source code in src/supervision/dataset/core.py

def __iter__(self) -> Iterator[tuple[str, npt.NDArray[np.uint8], Detections]]:
    """
    Iterate over the images and annotations in the dataset.

    Yields:
        Tuples containing the image path, image data, and its annotation.
    """
    for i in range(len(self)):
        image_path, image, annotation = self[i]
        yield image_path, image, annotation

as_coco(images_directory_path: str | None = None, annotations_path: str | None = None, min_image_area_percentage: float = 0.0, max_image_area_percentage: float = 1.0, approximation_percentage: float = 0.0, starting_image_id: int = 1, starting_annotation_id: int = 1, show_progress: bool = False) -> tuple[int, int]

Exports the dataset to COCO format. This method saves the images and their corresponding annotations in COCO format.

Tip

The format of the mask is determined automatically based on its structure:

• If a mask contains multiple disconnected components or holes, it will be saved using the Run-Length Encoding (RLE) format for efficient storage and processing.
• If a mask consists of a single, contiguous region without any holes, it will be encoded as a polygon, preserving the outline of the object.

This automatic selection ensures that the masks are stored in the most appropriate and space-efficient format, complying with COCO dataset standards.

Parameters:

Name	Type	Description	Default
images_directory_path	str | None	The path to the directory where the images should be saved. If not provided, images will not be saved.	None
annotations_path	str | None	The path to COCO annotation file.	None
min_image_area_percentage	float	The minimum percentage of detection area relative to the image area for a detection to be included. Argument is used only for segmentation datasets.	0.0
max_image_area_percentage	float	The maximum percentage of detection area relative to the image area for a detection to be included. Argument is used only for segmentation datasets.	1.0
approximation_percentage	float	The percentage of polygon points to be removed from the input polygon, in the range [0, 1). This is useful for simplifying the annotations. Argument is used only for segmentation datasets.	0.0
starting_image_id	int	First image id to assign in the exported file. Defaults to 1. Override when exporting multiple splits into a coordinated COCO collection so ids remain unique across the set (see example below).	1
starting_annotation_id	int	First annotation id to assign in the exported file. Defaults to 1. Override for the same multi-split reason as starting_image_id.	1
show_progress	bool	If True, display a progress bar during saving.	False

Returns:

Type	Description
int	A (next_image_id, next_annotation_id) tuple containing the
int	first unused ids after this export. Feed them straight back into
tuple[int, int]	starting_image_id and starting_annotation_id on the next
tuple[int, int]	split so ids stay globally unique. When annotations_path is
tuple[int, int]	None (images-only export) the starting ids are returned
tuple[int, int]	unchanged so chaining still composes.

Example

# Exporting train, valid, and test splits with non-colliding ids
# so the three annotation files can later be merged into one COCO.
next_image_id, next_annotation_id = train_ds.as_coco(
    images_directory_path="out/train/images",
    annotations_path="out/train/annotations.json",
)
next_image_id, next_annotation_id = valid_ds.as_coco(
    images_directory_path="out/valid/images",
    annotations_path="out/valid/annotations.json",
    starting_image_id=next_image_id,
    starting_annotation_id=next_annotation_id,
)
_, _ = test_ds.as_coco(
    images_directory_path="out/test/images",
    annotations_path="out/test/annotations.json",
    starting_image_id=next_image_id,
    starting_annotation_id=next_annotation_id,
)  # return value not needed — no further split

Source code in src/supervision/dataset/core.py

def as_coco(
    self,
    images_directory_path: str | None = None,
    annotations_path: str | None = None,
    min_image_area_percentage: float = 0.0,
    max_image_area_percentage: float = 1.0,
    approximation_percentage: float = 0.0,
    starting_image_id: int = 1,
    starting_annotation_id: int = 1,
    show_progress: bool = False,
) -> tuple[int, int]:
    """
    Exports the dataset to COCO format. This method saves the
    images and their corresponding annotations in COCO format.

    !!! tip

        The format of the mask is determined automatically based on its structure:

        - If a mask contains multiple disconnected components or holes, it will be
        saved using the Run-Length Encoding (RLE) format for efficient storage and
        processing.
        - If a mask consists of a single, contiguous region without any holes, it
        will be encoded as a polygon, preserving the outline of the object.

        This automatic selection ensures that the masks are stored in the most
        appropriate and space-efficient format, complying with COCO dataset
        standards.

    Args:
        images_directory_path: The path to the directory
            where the images should be saved.
            If not provided, images will not be saved.
        annotations_path: The path to COCO annotation file.
        min_image_area_percentage: The minimum percentage of
            detection area relative to
            the image area for a detection to be included.
            Argument is used only for segmentation datasets.
        max_image_area_percentage: The maximum percentage of
            detection area relative to
            the image area for a detection to be included.
            Argument is used only for segmentation datasets.
        approximation_percentage: The percentage of polygon points
            to be removed from the input polygon,
            in the range [0, 1). This is useful for simplifying the annotations.
            Argument is used only for segmentation datasets.
        starting_image_id: First image id to assign in the exported file.
            Defaults to ``1``. Override when exporting multiple splits into
            a coordinated COCO collection so ids remain unique across the
            set (see example below).
        starting_annotation_id: First annotation id to assign in the
            exported file. Defaults to ``1``. Override for the same
            multi-split reason as ``starting_image_id``.
        show_progress: If True, display a progress bar during saving.

    Returns:
        A ``(next_image_id, next_annotation_id)`` tuple containing the
        first unused ids after this export. Feed them straight back into
        ``starting_image_id`` and ``starting_annotation_id`` on the next
        split so ids stay globally unique. When ``annotations_path`` is
        ``None`` (images-only export) the starting ids are returned
        unchanged so chaining still composes.

    Example:
        ```python
        # Exporting train, valid, and test splits with non-colliding ids
        # so the three annotation files can later be merged into one COCO.
        next_image_id, next_annotation_id = train_ds.as_coco(
            images_directory_path="out/train/images",
            annotations_path="out/train/annotations.json",
        )
        next_image_id, next_annotation_id = valid_ds.as_coco(
            images_directory_path="out/valid/images",
            annotations_path="out/valid/annotations.json",
            starting_image_id=next_image_id,
            starting_annotation_id=next_annotation_id,
        )
        _, _ = test_ds.as_coco(
            images_directory_path="out/test/images",
            annotations_path="out/test/annotations.json",
            starting_image_id=next_image_id,
            starting_annotation_id=next_annotation_id,
        )  # return value not needed — no further split
        ```
    """
    if images_directory_path is not None:
        save_dataset_images(
            dataset=self,
            images_directory_path=images_directory_path,
            show_progress=show_progress,
        )
    if annotations_path is not None:
        return save_coco_annotations(
            dataset=self,
            annotation_path=annotations_path,
            min_image_area_percentage=min_image_area_percentage,
            max_image_area_percentage=max_image_area_percentage,
            approximation_percentage=approximation_percentage,
            starting_image_id=starting_image_id,
            starting_annotation_id=starting_annotation_id,
            show_progress=show_progress,
        )
    return starting_image_id, starting_annotation_id

as_createml(images_directory_path: str | None = None, annotations_path: str | None = None, show_progress: bool = False) -> None

Exports the dataset to CreateML format. This method saves the images and their corresponding annotations in CreateML format.

Parameters:

Name	Type	Description	Default
images_directory_path	str | None	The path to the directory where the images should be saved. If not provided, images will not be saved.	None
annotations_path	str | None	The path to the CreateML json annotation file. If not provided, the annotations will not be saved.	None
show_progress	bool	If True, display a progress bar while saving images.	False

Returns:

Type	Description
None	None. Side-effects only: writes images and/or annotation file.

Examples:

import supervision as sv

ds = sv.DetectionDataset(classes=["dog"], images=[], annotations={})
ds.as_createml(
    images_directory_path="/tmp/images",
    annotations_path="/tmp/annotations.json",
)

Source code in src/supervision/dataset/core.py

def as_createml(
    self,
    images_directory_path: str | None = None,
    annotations_path: str | None = None,
    show_progress: bool = False,
) -> None:
    """
    Exports the dataset to CreateML format. This method saves the
    images and their corresponding annotations in CreateML format.

    Args:
        images_directory_path: The path to the directory where the images
            should be saved. If not provided, images will not be saved.
        annotations_path: The path to the CreateML json annotation file.
            If not provided, the annotations will not be saved.
        show_progress: If True, display a progress bar while saving images.

    Returns:
        None. Side-effects only: writes images and/or annotation file.

    Examples:
        ```python
        import supervision as sv

        ds = sv.DetectionDataset(classes=["dog"], images=[], annotations={})
        ds.as_createml(
            images_directory_path="/tmp/images",
            annotations_path="/tmp/annotations.json",
        )
        ```
    """
    if images_directory_path is not None:
        save_dataset_images(
            dataset=self,
            images_directory_path=images_directory_path,
            show_progress=show_progress,
        )
    if annotations_path is not None:
        save_createml_annotations(
            dataset=self,
            annotations_path=annotations_path,
        )

as_labelme(images_directory_path: str | None = None, annotations_directory_path: str | None = None) -> None

Exports the dataset to LabelMe format. This method saves the images and their corresponding annotations as per-image LabelMe .json files. Masked detections are written as polygon shapes whose vertices approximate the mask contour, so masks are not bit-exact on round-trip. Because the bounding box is recomputed from the quantized polygon contour on re-import, bounding boxes for masked detections may also shift by approximately one pixel after a save-load cycle.

Parameters:

Name	Type	Description	Default
images_directory_path	str | None	The path to the directory where the images should be saved. If not provided, images will not be saved.	None
annotations_directory_path	str | None	The path to the directory where the LabelMe .json files should be saved. If not provided, annotations will not be saved.	None

Examples:

import supervision as sv

ds = sv.DetectionDataset(...)

ds.as_labelme(
    images_directory_path="<IMAGES_DIRECTORY_PATH>",
    annotations_directory_path="<ANNOTATIONS_DIRECTORY_PATH>",
)

Source code in src/supervision/dataset/core.py

def as_labelme(
    self,
    images_directory_path: str | None = None,
    annotations_directory_path: str | None = None,
) -> None:
    """
    Exports the dataset to LabelMe format. This method saves the images and
    their corresponding annotations as per-image LabelMe ``.json`` files.
    Masked detections are written as ``polygon`` shapes whose vertices
    approximate the mask contour, so masks are not bit-exact on round-trip.
    Because the bounding box is recomputed from the quantized polygon contour
    on re-import, bounding boxes for masked detections may also shift by
    approximately one pixel after a save-load cycle.

    Args:
        images_directory_path: The path to the directory
            where the images should be saved.
            If not provided, images will not be saved.
        annotations_directory_path: The path to the directory where the
            LabelMe ``.json`` files should be saved.
            If not provided, annotations will not be saved.

    Examples:
        ```python
        import supervision as sv

        ds = sv.DetectionDataset(...)

        ds.as_labelme(
            images_directory_path="<IMAGES_DIRECTORY_PATH>",
            annotations_directory_path="<ANNOTATIONS_DIRECTORY_PATH>",
        )
        ```
    """
    if images_directory_path is not None:
        save_dataset_images(
            dataset=self, images_directory_path=images_directory_path
        )
    if annotations_directory_path is not None:
        save_labelme_annotations(
            dataset=self,
            annotations_directory_path=annotations_directory_path,
        )

as_pascal_voc(images_directory_path: str | None = None, annotations_directory_path: str | None = None, min_image_area_percentage: float = 0.0, max_image_area_percentage: float = 1.0, approximation_percentage: float = 0.0, show_progress: bool = False) -> None

Exports the dataset to PASCAL VOC format. This method saves the images and their corresponding annotations in PASCAL VOC format. Both output layouts are preflighted before any files are written so a collision in either target fails without partial output.

Parameters:

Name	Type	Description	Default
images_directory_path	str | None	The path to the directory where the images should be saved. If not provided, images will not be saved.	None
annotations_directory_path	str | None	The path to the directory where the annotations in PASCAL VOC format should be saved. If not provided, annotations will not be saved.	None
min_image_area_percentage	float	The minimum percentage of detection area relative to the image area for a detection to be included. Argument is used only for segmentation datasets.	0.0
max_image_area_percentage	float	The maximum percentage of detection area relative to the image area for a detection to be included. Argument is used only for segmentation datasets.	1.0
approximation_percentage	float	The percentage of polygon points to be removed from the input polygon, in the range [0, 1). Argument is used only for segmentation datasets.	0.0
show_progress	bool	If True, display a progress bar during saving.	False

Raises:

Type	Description
ValueError	If two image paths share the same basename (when images_directory_path is set) or the same stem (when annotations_directory_path is set), which would cause one output file to overwrite another. Rename images to ensure unique basenames before exporting a merged dataset.

Source code in src/supervision/dataset/core.py

def as_pascal_voc(
    self,
    images_directory_path: str | None = None,
    annotations_directory_path: str | None = None,
    min_image_area_percentage: float = 0.0,
    max_image_area_percentage: float = 1.0,
    approximation_percentage: float = 0.0,
    show_progress: bool = False,
) -> None:
    """
    Exports the dataset to PASCAL VOC format. This method saves the images
    and their corresponding annotations in PASCAL VOC format. Both output
    layouts are preflighted before any files are written so a collision in
    either target fails without partial output.

    Args:
        images_directory_path: The path to the directory
            where the images should be saved.
            If not provided, images will not be saved.
        annotations_directory_path: The path to
            the directory where the annotations in PASCAL VOC format should be
            saved. If not provided, annotations will not be saved.
        min_image_area_percentage: The minimum percentage of
            detection area relative to
            the image area for a detection to be included.
            Argument is used only for segmentation datasets.
        max_image_area_percentage: The maximum percentage
            of detection area relative to
            the image area for a detection to be included.
            Argument is used only for segmentation datasets.
        approximation_percentage: The percentage of
            polygon points to be removed from the input polygon,
            in the range [0, 1). Argument is used only for segmentation datasets.
        show_progress: If True, display a progress bar during saving.

    Raises:
        ValueError: If two image paths share the same basename (when
            images_directory_path is set) or the same stem (when
            annotations_directory_path is set), which would cause one
            output file to overwrite another. Rename images to ensure
            unique basenames before exporting a merged dataset.
    """
    if images_directory_path:
        check_no_basename_collisions(
            image_paths=self.image_paths,
            key=lambda image_path: Path(image_path).name,
            output_kind="image",
        )
    if annotations_directory_path:
        check_no_basename_collisions(
            image_paths=self.image_paths,
            key=lambda image_path: f"{Path(image_path).stem}.xml",
            output_kind="Pascal VOC annotation",
        )

    if images_directory_path:
        save_dataset_images(
            dataset=self,
            images_directory_path=images_directory_path,
            show_progress=show_progress,
        )
    if annotations_directory_path:
        save_pascal_voc_annotations(
            dataset=self,
            annotations_directory_path=annotations_directory_path,
            min_image_area_percentage=min_image_area_percentage,
            max_image_area_percentage=max_image_area_percentage,
            approximation_percentage=approximation_percentage,
            show_progress=show_progress,
        )

as_yolo(images_directory_path: str | None = None, annotations_directory_path: str | None = None, data_yaml_path: str | None = None, min_image_area_percentage: float = 0.0, max_image_area_percentage: float = 1.0, approximation_percentage: float = 0.0, is_obb: bool = False, show_progress: bool = False) -> None

Exports the dataset to YOLO format. This method saves the images and their corresponding annotations in YOLO format.

Parameters:

Name	Type	Description	Default
images_directory_path	str | None	The path to the directory where the images should be saved. If not provided, images will not be saved.	None
annotations_directory_path	str | None	The path to the directory where the annotations in YOLO format should be saved. If not provided, annotations will not be saved.	None
data_yaml_path	str | None	The path where the data.yaml file should be saved. If not provided, the file will not be saved.	None
min_image_area_percentage	float	The minimum percentage of detection area relative to the image area for a detection to be included. Argument is used only for segmentation datasets.	0.0
max_image_area_percentage	float	The maximum percentage of detection area relative to the image area for a detection to be included. Argument is used only for segmentation datasets.	1.0
approximation_percentage	float	The percentage of polygon points to be removed from the input polygon, in the range [0, 1). This is useful for simplifying the annotations. Argument is used only for segmentation datasets.	0.0
is_obb	bool	If True, exports annotations in OBB format (class_id x1 y1 x2 y2 x3 y3 x4 y4) using the oriented corners stored in detections.data["xyxyxyxy"]. Mirrors from_yolo(..., is_obb=True). Masks are ignored when is_obb=True.	False
show_progress	bool	If True, display a progress bar during saving.	False

Raises:

Type	Description
ValueError	If two image paths share the same basename (when images_directory_path is set) or the same annotation file name (when annotations_directory_path is set), which would cause one output file to overwrite another.

Source code in src/supervision/dataset/core.py

def as_yolo(
    self,
    images_directory_path: str | None = None,
    annotations_directory_path: str | None = None,
    data_yaml_path: str | None = None,
    min_image_area_percentage: float = 0.0,
    max_image_area_percentage: float = 1.0,
    approximation_percentage: float = 0.0,
    is_obb: bool = False,
    show_progress: bool = False,
) -> None:
    """
    Exports the dataset to YOLO format. This method saves the
    images and their corresponding annotations in YOLO format.

    Args:
        images_directory_path: The path to the
            directory where the images should be saved.
            If not provided, images will not be saved.
        annotations_directory_path: The path to the
            directory where the annotations in
            YOLO format should be saved. If not provided,
            annotations will not be saved.
        data_yaml_path: The path where the data.yaml
            file should be saved.
            If not provided, the file will not be saved.
        min_image_area_percentage: The minimum percentage of
            detection area relative to
            the image area for a detection to be included.
            Argument is used only for segmentation datasets.
        max_image_area_percentage: The maximum percentage
            of detection area relative to
            the image area for a detection to be included.
            Argument is used only for segmentation datasets.
        approximation_percentage: The percentage of polygon points to
            be removed from the input polygon, in the range [0, 1).
            This is useful for simplifying the annotations.
            Argument is used only for segmentation datasets.
        is_obb: If True, exports annotations in OBB format
            (`class_id x1 y1 x2 y2 x3 y3 x4 y4`) using the oriented
            corners stored in `detections.data["xyxyxyxy"]`. Mirrors
            `from_yolo(..., is_obb=True)`. Masks are ignored when
            `is_obb=True`.
        show_progress: If True, display a progress bar during saving.

    Raises:
        ValueError: If two image paths share the same basename (when
            images_directory_path is set) or the same annotation
            file name (when annotations_directory_path is set),
            which would cause one output file to overwrite another.
    """
    if is_obb and (
        min_image_area_percentage != 0.0
        or max_image_area_percentage != 1.0
        or approximation_percentage != 0.0
    ):
        import warnings

        warnings.warn(
            "`min_image_area_percentage`, `max_image_area_percentage`, and "
            "`approximation_percentage` have no effect when `is_obb=True`; "
            "OBB annotations use corner coordinates directly.",
            UserWarning,
            stacklevel=2,
        )
    # Pre-flight: validate output uniqueness before writing any file
    if images_directory_path:
        check_no_basename_collisions(
            image_paths=self.image_paths,
            key=lambda image_path: Path(image_path).name,
            output_kind="image",
        )
    if annotations_directory_path:
        check_no_basename_collisions(
            image_paths=self.image_paths,
            key=lambda image_path: Path(image_path).stem + ".txt",
            output_kind="YOLO annotation",
        )

    if images_directory_path is not None:
        save_dataset_images(
            dataset=self,
            images_directory_path=images_directory_path,
            show_progress=show_progress,
        )
    if annotations_directory_path is not None:
        save_yolo_annotations(
            dataset=self,
            annotations_directory_path=annotations_directory_path,
            min_image_area_percentage=min_image_area_percentage,
            max_image_area_percentage=max_image_area_percentage,
            approximation_percentage=approximation_percentage,
            show_progress=show_progress,
            is_obb=is_obb,
        )
    if data_yaml_path is not None:
        save_data_yaml(data_yaml_path=data_yaml_path, classes=self.classes)

from_coco(images_directory_path: str, annotations_path: str, force_masks: bool = False, show_progress: bool = False, *, use_iscrowd: bool = True) -> DetectionDataset classmethod

Creates a Dataset instance from COCO formatted data.

Parameters:

Name	Type	Description	Default
images_directory_path	str	The path to the directory containing the images.	required
annotations_path	str	The path to the json annotation files.	required
force_masks	bool	If True, forces masks to be loaded for all annotations, regardless of whether they are present.	False
show_progress	bool	If True, display a progress bar during loading.	False
use_iscrowd	bool	If True, includes COCO iscrowd and area annotation fields in Detections.data.	True

Returns: A DetectionDataset instance containing the loaded images and annotations.

Examples:

import roboflow
from roboflow import Roboflow
import supervision as sv

roboflow.login()
rf = Roboflow()

project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
dataset = project.version(PROJECT_VERSION).download("coco")

ds = sv.DetectionDataset.from_coco(
    images_directory_path=f"{dataset.location}/train",
    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
    # pass show_progress=True to enable a tqdm progress bar
)

ds.classes
# ['dog', 'person']

Source code in src/supervision/dataset/core.py

@classmethod
def from_coco(
    cls,
    images_directory_path: str,
    annotations_path: str,
    force_masks: bool = False,
    show_progress: bool = False,
    *,
    use_iscrowd: bool = True,
) -> DetectionDataset:
    """
    Creates a Dataset instance from COCO formatted data.

    Args:
        images_directory_path: The path to the
            directory containing the images.
        annotations_path: The path to the json annotation files.
        force_masks: If True,
            forces masks to be loaded for all annotations,
            regardless of whether they are present.
        show_progress: If True, display a progress bar during loading.
        use_iscrowd: If True, includes COCO ``iscrowd`` and ``area``
            annotation fields in ``Detections.data``.
    Returns:
        A DetectionDataset instance containing
            the loaded images and annotations.

    Examples:
        ```python
        import roboflow
        from roboflow import Roboflow
        import supervision as sv

        roboflow.login()
        rf = Roboflow()

        project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
        dataset = project.version(PROJECT_VERSION).download("coco")

        ds = sv.DetectionDataset.from_coco(
            images_directory_path=f"{dataset.location}/train",
            annotations_path=f"{dataset.location}/train/_annotations.coco.json",
            # pass show_progress=True to enable a tqdm progress bar
        )

        ds.classes
        # ['dog', 'person']
        ```
    """
    classes, images, annotations = load_coco_annotations(
        images_directory_path=images_directory_path,
        annotations_path=annotations_path,
        force_masks=force_masks,
        use_iscrowd=use_iscrowd,
        show_progress=show_progress,
    )
    return DetectionDataset(classes=classes, images=images, annotations=annotations)

from_createml(images_directory_path: str, annotations_path: str, show_progress: bool = False) -> DetectionDataset classmethod

Creates a Dataset instance from CreateML formatted data.

CreateML stores object-detection annotations in a single JSON file as a list of per-image entries, with each box expressed as a pixel-space centre point plus width and height. Class names are inferred from the labels present in the file.

Parameters:

Name	Type	Description	Default
images_directory_path	str	The path to the directory containing the images.	required
annotations_path	str	The path to the CreateML json annotation file.	required
show_progress	bool	If True, display a progress bar during loading.	False

Returns:

Type	Description
DetectionDataset	A DetectionDataset instance containing the loaded images and
DetectionDataset	annotations.

Examples:

import roboflow
from roboflow import Roboflow
import supervision as sv

roboflow.login()
rf = Roboflow()

project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
dataset = project.version(PROJECT_VERSION).download("createml")

ds = sv.DetectionDataset.from_createml(
    images_directory_path=f"{dataset.location}/train",
    annotations_path=f"{dataset.location}/train/_annotations.createml.json",
)

ds.classes
# ['dog', 'person']

Source code in src/supervision/dataset/core.py

@classmethod
def from_createml(
    cls,
    images_directory_path: str,
    annotations_path: str,
    show_progress: bool = False,
) -> DetectionDataset:
    """
    Creates a Dataset instance from CreateML formatted data.

    CreateML stores object-detection annotations in a single JSON file as a
    list of per-image entries, with each box expressed as a pixel-space
    centre point plus width and height. Class names are inferred from the
    labels present in the file.

    Args:
        images_directory_path: The path to the directory containing the
            images.
        annotations_path: The path to the CreateML json annotation file.
        show_progress: If True, display a progress bar during loading.

    Returns:
        A DetectionDataset instance containing the loaded images and
        annotations.

    Examples:
        ```python
        import roboflow
        from roboflow import Roboflow
        import supervision as sv

        roboflow.login()
        rf = Roboflow()

        project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
        dataset = project.version(PROJECT_VERSION).download("createml")

        ds = sv.DetectionDataset.from_createml(
            images_directory_path=f"{dataset.location}/train",
            annotations_path=f"{dataset.location}/train/_annotations.createml.json",
        )

        ds.classes
        # ['dog', 'person']
        ```
    """
    classes, image_paths, annotations = load_createml_annotations(
        images_directory_path=images_directory_path,
        annotations_path=annotations_path,
        show_progress=show_progress,
    )
    return DetectionDataset(
        classes=classes, images=image_paths, annotations=annotations
    )

from_labelme(images_directory_path: str, annotations_directory_path: str, force_masks: bool = False) -> DetectionDataset classmethod

Creates a Dataset instance from LabelMe formatted data.

LabelMe stores one JSON file per image, each containing a list of shapes. rectangle shapes are loaded as bounding boxes and polygon shapes as masks (with their bounding boxes); other shape types are skipped. Class names are inferred from the labels present in the files. When an image file contains a polygon shape, or when force_masks=True is set, both rectangle and polygon shapes produce masks: rectangles via a four-corner polygon fill.

Parameters:

Name	Type	Description	Default
images_directory_path	str	The path to the directory containing the images.	required
annotations_directory_path	str	The path to the directory containing the LabelMe .json annotation files.	required
force_masks	bool	If True, forces masks to be loaded for all annotations, regardless of whether polygon shapes are present. Requires imageWidth and imageHeight in every JSON file.	False

Returns:

Type	Description
DetectionDataset	A DetectionDataset instance containing the loaded images and annotations.

Raises:

Type	Description
ValueError	If an annotation is malformed - for example imagePath is empty or resolves to .., a shape is missing its label or points, or a mask is required but imageWidth / imageHeight are missing or zero.

Examples:

import supervision as sv

ds = sv.DetectionDataset.from_labelme(
    images_directory_path="<IMAGES_DIRECTORY_PATH>",
    annotations_directory_path="<ANNOTATIONS_DIRECTORY_PATH>",
)

ds.classes
# ['dog', 'person']

Source code in src/supervision/dataset/core.py

@classmethod
def from_labelme(
    cls,
    images_directory_path: str,
    annotations_directory_path: str,
    force_masks: bool = False,
) -> DetectionDataset:
    """
    Creates a Dataset instance from LabelMe formatted data.

    LabelMe stores one JSON file per image, each containing a list of
    ``shapes``. ``rectangle`` shapes are loaded as bounding boxes and
    ``polygon`` shapes as masks (with their bounding boxes); other shape
    types are skipped. Class names are inferred from the labels present in
    the files. When an image file contains a ``polygon`` shape, or when
    ``force_masks=True`` is set, both ``rectangle`` and ``polygon`` shapes
    produce masks: rectangles via a four-corner polygon fill.

    Args:
        images_directory_path: The path to the
            directory containing the images.
        annotations_directory_path: The path to the directory
            containing the LabelMe ``.json`` annotation files.
        force_masks: If True, forces masks to be loaded for all
            annotations, regardless of whether polygon shapes are present.
            Requires ``imageWidth`` and ``imageHeight`` in every JSON file.

    Returns:
        A DetectionDataset instance containing
            the loaded images and annotations.

    Raises:
        ValueError: If an annotation is malformed - for example
            ``imagePath`` is empty or resolves to ``..``, a shape is
            missing its ``label`` or ``points``, or a mask is required but
            ``imageWidth`` / ``imageHeight`` are missing or zero.

    Examples:
        ```python
        import supervision as sv

        ds = sv.DetectionDataset.from_labelme(
            images_directory_path="<IMAGES_DIRECTORY_PATH>",
            annotations_directory_path="<ANNOTATIONS_DIRECTORY_PATH>",
        )

        ds.classes
        # ['dog', 'person']
        ```
    """
    classes, image_paths, annotations = load_labelme_annotations(
        images_directory_path=images_directory_path,
        annotations_directory_path=annotations_directory_path,
        force_masks=force_masks,
    )
    return DetectionDataset(
        classes=classes, images=image_paths, annotations=annotations
    )

from_pascal_voc(images_directory_path: str, annotations_directory_path: str, force_masks: bool = False, show_progress: bool = False) -> DetectionDataset classmethod

Creates a Dataset instance from PASCAL VOC formatted data.

Parameters:

Name	Type	Description	Default
images_directory_path	str	Path to the directory containing the images.	required
annotations_directory_path	str	Path to the directory containing the PASCAL VOC XML annotations.	required
force_masks	bool	If True, forces masks to be loaded for all annotations, regardless of whether they are present.	False
show_progress	bool	If True, display a progress bar during loading.	False

Returns:

Type	Description
DetectionDataset	A DetectionDataset instance containing the loaded images and annotations.

Examples:

import roboflow
from roboflow import Roboflow
import supervision as sv

roboflow.login()

rf = Roboflow()

project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
dataset = project.version(PROJECT_VERSION).download("voc")

ds = sv.DetectionDataset.from_pascal_voc(
    images_directory_path=f"{dataset.location}/train/images",
    annotations_directory_path=f"{dataset.location}/train/labels",
    # pass show_progress=True to enable a tqdm progress bar
)

ds.classes
# ['dog', 'person']

Source code in src/supervision/dataset/core.py

@classmethod
def from_pascal_voc(
    cls,
    images_directory_path: str,
    annotations_directory_path: str,
    force_masks: bool = False,
    show_progress: bool = False,
) -> DetectionDataset:
    """
    Creates a Dataset instance from PASCAL VOC formatted data.

    Args:
        images_directory_path: Path to the directory containing the images.
        annotations_directory_path: Path to the directory
            containing the PASCAL VOC XML annotations.
        force_masks: If True, forces masks to
            be loaded for all annotations, regardless of whether they are present.
        show_progress: If True, display a progress bar during loading.

    Returns:
        A DetectionDataset instance containing
            the loaded images and annotations.

    Examples:
        ```python
        import roboflow
        from roboflow import Roboflow
        import supervision as sv

        roboflow.login()

        rf = Roboflow()

        project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
        dataset = project.version(PROJECT_VERSION).download("voc")

        ds = sv.DetectionDataset.from_pascal_voc(
            images_directory_path=f"{dataset.location}/train/images",
            annotations_directory_path=f"{dataset.location}/train/labels",
            # pass show_progress=True to enable a tqdm progress bar
        )

        ds.classes
        # ['dog', 'person']
        ```
    """

    classes, image_paths, annotations = load_pascal_voc_annotations(
        images_directory_path=images_directory_path,
        annotations_directory_path=annotations_directory_path,
        force_masks=force_masks,
        show_progress=show_progress,
    )

    return DetectionDataset(
        classes=classes, images=image_paths, annotations=annotations
    )

from_yolo(images_directory_path: str, annotations_directory_path: str, data_yaml_path: str, force_masks: bool = False, is_obb: bool = False, show_progress: bool = False) -> DetectionDataset classmethod

Creates a Dataset instance from YOLO formatted data.

Parameters:

Name	Type	Description	Default
images_directory_path	str	The path to the directory containing the images.	required
annotations_directory_path	str	The path to the directory containing the YOLO annotation files.	required
data_yaml_path	str	The path to the data YAML file containing class information.	required
force_masks	bool	If True, forces masks to be loaded for all annotations, regardless of whether they are present.	False
is_obb	bool	If True, loads the annotations in OBB format. OBB annotations are defined as [class_id, x, y, x, y, x, y, x, y], where pairs of [x, y] are box corners.	False
show_progress	bool	If True, display a progress bar during loading.	False

Returns:

Type	Description
DetectionDataset	A DetectionDataset instance containing the loaded images and annotations.

Examples:

import roboflow
from roboflow import Roboflow
import supervision as sv

roboflow.login()
rf = Roboflow()

project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
dataset = project.version(PROJECT_VERSION).download("yolov5")

ds = sv.DetectionDataset.from_yolo(
    images_directory_path=f"{dataset.location}/train/images",
    annotations_directory_path=f"{dataset.location}/train/labels",
    data_yaml_path=f"{dataset.location}/data.yaml",
    # pass show_progress=True to enable a tqdm progress bar
)

ds.classes
# ['dog', 'person']

Source code in src/supervision/dataset/core.py

@classmethod
def from_yolo(
    cls,
    images_directory_path: str,
    annotations_directory_path: str,
    data_yaml_path: str,
    force_masks: bool = False,
    is_obb: bool = False,
    show_progress: bool = False,
) -> DetectionDataset:
    """
    Creates a Dataset instance from YOLO formatted data.

    Args:
        images_directory_path: The path to the
            directory containing the images.
        annotations_directory_path: The path to the directory
            containing the YOLO annotation files.
        data_yaml_path: The path to the data
            YAML file containing class information.
        force_masks: If True, forces
            masks to be loaded for all annotations,
            regardless of whether they are present.
        is_obb: If True, loads the annotations in OBB format.
            OBB annotations are defined as `[class_id, x, y, x, y, x, y, x, y]`,
            where pairs of [x, y] are box corners.
        show_progress: If True, display a progress bar during loading.

    Returns:
        A DetectionDataset instance
            containing the loaded images and annotations.

    Examples:
        ```python
        import roboflow
        from roboflow import Roboflow
        import supervision as sv

        roboflow.login()
        rf = Roboflow()

        project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
        dataset = project.version(PROJECT_VERSION).download("yolov5")

        ds = sv.DetectionDataset.from_yolo(
            images_directory_path=f"{dataset.location}/train/images",
            annotations_directory_path=f"{dataset.location}/train/labels",
            data_yaml_path=f"{dataset.location}/data.yaml",
            # pass show_progress=True to enable a tqdm progress bar
        )

        ds.classes
        # ['dog', 'person']
        ```
    """
    classes, image_paths, annotations = load_yolo_annotations(
        images_directory_path=images_directory_path,
        annotations_directory_path=annotations_directory_path,
        data_yaml_path=data_yaml_path,
        force_masks=force_masks,
        is_obb=is_obb,
        show_progress=show_progress,
    )
    return DetectionDataset(
        classes=classes, images=image_paths, annotations=annotations
    )

merge(dataset_list: list[DetectionDataset]) -> DetectionDataset classmethod

Merge a list of DetectionDataset objects into a single DetectionDataset object.

This method takes a list of DetectionDataset objects and combines their respective fields (classes, images, annotations) into a single DetectionDataset object.

Parameters:

Name	Type	Description	Default
dataset_list	list[DetectionDataset]	A list of DetectionDataset objects to merge.	required

Returns:

Type	Description
DetectionDataset	A single DetectionDataset object containing
DetectionDataset	the merged data from the input list.

Examples:

>>> import numpy as np
>>> import supervision as sv
>>> ds_1 = sv.DetectionDataset(
...     classes=['dog', 'person'],
...     images={'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8)},
...     annotations={'img1.jpg': sv.Detections.empty()}
... )
>>> len(ds_1)
1
>>> ds_1.classes
['dog', 'person']
>>> ds_2 = sv.DetectionDataset(
...     classes=['cat'],
...     images={'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8)},
...     annotations={'img2.jpg': sv.Detections.empty()}
... )
>>> len(ds_2)
1
>>> ds_2.classes
['cat']
>>> ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
>>> len(ds_merged)
2
>>> ds_merged.classes
['cat', 'dog', 'person']

Source code in src/supervision/dataset/core.py

@classmethod
def merge(cls, dataset_list: list[DetectionDataset]) -> DetectionDataset:
    """
    Merge a list of `DetectionDataset` objects into a single
        `DetectionDataset` object.

    This method takes a list of `DetectionDataset` objects and combines
    their respective fields (`classes`, `images`,
    `annotations`) into a single `DetectionDataset` object.

    Args:
        dataset_list: A list of `DetectionDataset`
            objects to merge.

    Returns:
        A single `DetectionDataset` object containing
        the merged data from the input list.

    Examples:
        ```pycon
        >>> import numpy as np
        >>> import supervision as sv
        >>> ds_1 = sv.DetectionDataset(
        ...     classes=['dog', 'person'],
        ...     images={'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8)},
        ...     annotations={'img1.jpg': sv.Detections.empty()}
        ... )
        >>> len(ds_1)
        1
        >>> ds_1.classes
        ['dog', 'person']
        >>> ds_2 = sv.DetectionDataset(
        ...     classes=['cat'],
        ...     images={'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8)},
        ...     annotations={'img2.jpg': sv.Detections.empty()}
        ... )
        >>> len(ds_2)
        1
        >>> ds_2.classes
        ['cat']
        >>> ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
        >>> len(ds_merged)
        2
        >>> ds_merged.classes
        ['cat', 'dog', 'person']

        ```
    """

    def is_in_memory(dataset: DetectionDataset) -> bool:
        return len(dataset._images_in_memory) > 0 or len(dataset.image_paths) == 0

    def is_lazy(dataset: DetectionDataset) -> bool:
        return len(dataset._images_in_memory) == 0

    all_in_memory = all([is_in_memory(dataset) for dataset in dataset_list])
    all_lazy = all([is_lazy(dataset) for dataset in dataset_list])
    if not all_in_memory and not all_lazy:
        raise ValueError(
            "Merging lazy and in-memory DetectionDatasets is not supported."
        )

    images_in_memory = {}
    for dataset in dataset_list:
        images_in_memory.update(dataset._images_in_memory)

    image_paths = list(
        chain.from_iterable(dataset.image_paths for dataset in dataset_list)
    )
    image_paths_unique = list(dict.fromkeys(image_paths))
    if len(image_paths) != len(image_paths_unique):
        duplicates = find_duplicates(image_paths)
        raise ValueError(
            f"Image paths {duplicates} are not unique across datasets."
        )
    image_paths = image_paths_unique

    classes = merge_class_lists(
        class_lists=[dataset.classes for dataset in dataset_list]
    )

    annotations = {}
    for dataset in dataset_list:
        annotations.update(dataset.annotations)
    for dataset in dataset_list:
        class_index_mapping = build_class_index_mapping(
            source_classes=dataset.classes, target_classes=classes
        )
        for image_path in dataset.image_paths:
            annotations[image_path] = map_detections_class_id(
                source_to_target_mapping=class_index_mapping,
                detections=annotations[image_path],
            )

    merged_dataset = cls(
        classes=classes,
        images=image_paths,
        annotations=annotations,
    )
    if all_in_memory:
        merged_dataset._images_in_memory = images_in_memory
    return merged_dataset

split(split_ratio: float = 0.8, random_state: int | None = None, shuffle: bool = True) -> tuple[DetectionDataset, DetectionDataset]

Splits the dataset into two parts (training and testing) using the provided split_ratio. The input dataset is not mutated.

Parameters:

Name	Type	Description	Default
split_ratio	float	The ratio of the training set to the entire dataset.	0.8
random_state	int | None	The seed for the random number generator. This is used for reproducibility.	None
shuffle	bool	Whether to shuffle the data before splitting.	True

Returns:

Type	Description
tuple[DetectionDataset, DetectionDataset]	A tuple containing the training and testing datasets.

Examples:

>>> import numpy as np
>>> import supervision as sv
>>> ds = sv.DetectionDataset(
...     classes=['dog', 'person'],
...     images={
...         'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
...         'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
...     },
...     annotations={
...         'img1.jpg': sv.Detections(xyxy=np.array([[10, 10, 20, 20]])),
...         'img2.jpg': sv.Detections(xyxy=np.array([[30, 30, 40, 40]])),
...     }
... )
>>> train_ds, test_ds = ds.split(split_ratio=0.5, random_state=42)
>>> len(train_ds), len(test_ds)
(1, 1)

Source code in src/supervision/dataset/core.py

def split(
    self,
    split_ratio: float = 0.8,
    random_state: int | None = None,
    shuffle: bool = True,
) -> tuple[DetectionDataset, DetectionDataset]:
    """
    Splits the dataset into two parts (training and testing)
        using the provided split_ratio. The input dataset is not mutated.

    Args:
        split_ratio: The ratio of the training
            set to the entire dataset.
        random_state: The seed for the random number generator.
            This is used for reproducibility.
        shuffle: Whether to shuffle the data before splitting.

    Returns:
        A tuple containing
            the training and testing datasets.

    Examples:
        ```pycon
        >>> import numpy as np
        >>> import supervision as sv
        >>> ds = sv.DetectionDataset(
        ...     classes=['dog', 'person'],
        ...     images={
        ...         'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
        ...         'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
        ...     },
        ...     annotations={
        ...         'img1.jpg': sv.Detections(xyxy=np.array([[10, 10, 20, 20]])),
        ...         'img2.jpg': sv.Detections(xyxy=np.array([[30, 30, 40, 40]])),
        ...     }
        ... )
        >>> train_ds, test_ds = ds.split(split_ratio=0.5, random_state=42)
        >>> len(train_ds), len(test_ds)
        (1, 1)

        ```
    """

    train_paths, test_paths = train_test_split(
        data=self.image_paths,
        train_ratio=split_ratio,
        random_state=random_state,
        shuffle=shuffle,
    )

    train_annotations = {path: self.annotations[path] for path in train_paths}
    test_annotations = {path: self.annotations[path] for path in test_paths}

    train_dataset = DetectionDataset(
        classes=self.classes,
        images=train_paths,
        annotations=train_annotations,
    )
    test_dataset = DetectionDataset(
        classes=self.classes,
        images=test_paths,
        annotations=test_annotations,
    )
    if self._images_in_memory:
        train_dataset._images_in_memory = {
            path: self._images_in_memory[path] for path in train_paths
        }
        test_dataset._images_in_memory = {
            path: self._images_in_memory[path] for path in test_paths
        }
    return train_dataset, test_dataset

ClassificationDataset

supervision.dataset.core.ClassificationDataset dataclass

Bases: BaseDataset

Contains information about a classification dataset, handles lazy image loading, dataset splitting.

Attributes:

Name	Type	Description
classes		List containing dataset class names.
images		List of image paths or dictionary mapping image name to image data.
annotations		Dictionary mapping image name to annotations.

Source code in src/supervision/dataset/core.py

@dataclass
class ClassificationDataset(BaseDataset):
    """
    Contains information about a classification dataset, handles lazy image
    loading, dataset splitting.

    Attributes:
        classes: List containing dataset class names.
        images:
            List of image paths or dictionary mapping image name to image data.
        annotations: Dictionary mapping
            image name to annotations.
    """

    def __init__(
        self,
        classes: list[str],
        images: list[str] | dict[str, npt.NDArray[np.uint8]],
        annotations: dict[str, Classifications],
    ) -> None:
        self.classes = classes

        if set(images) != set(annotations):
            raise ValueError(
                "The keys of the images and annotations dictionaries must match."
            )
        self.annotations = annotations

        # Eliminate duplicates while preserving order
        self.image_paths = list(dict.fromkeys(images))

        self._images_in_memory: dict[str, npt.NDArray[np.uint8]] = {}
        if isinstance(images, dict):
            self._images_in_memory = images
            warn_deprecated(
                "Passing a `Dict[str, np.ndarray]` into `ClassificationDataset` is "
                "deprecated and will be removed in a future release. Use "
                "a list of paths `List[str]` instead."
            )

    def _get_image(self, image_path: str) -> npt.NDArray[np.uint8]:
        """Assumes that image is in dataset."""
        if self._images_in_memory:
            return self._images_in_memory[image_path]
        image = cv2.imread(image_path)
        if image is None:
            raise ValueError(f"Could not read image from path: {image_path}")
        return cast(npt.NDArray[np.uint8], image)

    def __len__(self) -> int:
        return len(self._images_in_memory) or len(self.image_paths)

    def __getitem__(self, i: int) -> tuple[str, npt.NDArray[np.uint8], Classifications]:
        """
        Returns:
            The image path, image data,
                and its corresponding annotation at index i.
        """
        image_path = self.image_paths[i]
        image = self._get_image(image_path)
        annotation = self.annotations[image_path]
        return image_path, image, annotation

    def __iter__(
        self,
    ) -> Iterator[tuple[str, npt.NDArray[np.uint8], Classifications]]:
        """
        Iterate over the images and annotations in the dataset.

        Yields:
            Tuples containing the image path, image data, and its annotation.
        """
        for i in range(len(self)):
            image_path, image, annotation = self[i]
            yield image_path, image, annotation

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, ClassificationDataset):
            return False

        if self.classes != other.classes:
            return False

        if self.image_paths != other.image_paths:
            return False

        if self._images_in_memory or other._images_in_memory:
            if not np.array_equal(
                list(self._images_in_memory.values()),
                list(other._images_in_memory.values()),
            ):
                return False

        if self.annotations != other.annotations:
            return False

        return True

    def split(
        self,
        split_ratio: float = 0.8,
        random_state: int | None = None,
        shuffle: bool = True,
    ) -> tuple[ClassificationDataset, ClassificationDataset]:
        """
        Splits the dataset into two parts (training and testing)
            using the provided split_ratio.

        Args:
            split_ratio: The ratio of the training
                set to the entire dataset.
            random_state: The seed for the
                random number generator. This is used for reproducibility.
            shuffle: Whether to shuffle the data before splitting.

        Returns:
            A tuple containing
            the training and testing datasets.

        Examples:
            ```pycon
            >>> import numpy as np
            >>> import supervision as sv
            >>> cd = sv.ClassificationDataset(
            ...     classes=['cat', 'dog'],
            ...     images={
            ...         'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
            ...         'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
            ...     },
            ...     annotations={
            ...         'img1.jpg': sv.Classifications(class_id=np.array([0])),
            ...         'img2.jpg': sv.Classifications(class_id=np.array([1])),
            ...     }
            ... )
            >>> train_cd, test_cd = cd.split(split_ratio=0.5, random_state=42)
            >>> len(train_cd), len(test_cd)
            (1, 1)

            ```
        """
        train_paths, test_paths = train_test_split(
            data=self.image_paths,
            train_ratio=split_ratio,
            random_state=random_state,
            shuffle=shuffle,
        )

        train_input: list[str] | dict[str, npt.NDArray[np.uint8]]
        test_input: list[str] | dict[str, npt.NDArray[np.uint8]]
        if self._images_in_memory:
            train_input = {path: self._images_in_memory[path] for path in train_paths}
            test_input = {path: self._images_in_memory[path] for path in test_paths}
        else:
            train_input = train_paths
            test_input = test_paths
        train_annotations = {path: self.annotations[path] for path in train_paths}
        test_annotations = {path: self.annotations[path] for path in test_paths}

        train_dataset = ClassificationDataset(
            classes=self.classes,
            images=train_input,
            annotations=train_annotations,
        )
        test_dataset = ClassificationDataset(
            classes=self.classes,
            images=test_input,
            annotations=test_annotations,
        )

        return train_dataset, test_dataset

    def as_folder_structure(
        self, root_directory_path: str, show_progress: bool = False
    ) -> None:
        """
        Saves the dataset as a multi-class folder structure.

        Args:
            root_directory_path: The path to the directory
                where the dataset will be saved.
            show_progress: If True, display a progress bar during saving.
        """
        os.makedirs(root_directory_path, exist_ok=True)

        for class_name in self.classes:
            os.makedirs(os.path.join(root_directory_path, class_name), exist_ok=True)

        for image_save_path, image, annotation in tqdm(
            self,
            total=len(self),
            desc="Saving classification images",
            disable=not show_progress,
        ):
            image_name = Path(image_save_path).name
            class_id = (
                annotation.class_id[0]
                if annotation.confidence is None
                else annotation.get_top_k(1)[0][0]
            )
            class_name = self.classes[class_id]
            image_save_path = os.path.join(root_directory_path, class_name, image_name)
            cv2.imwrite(image_save_path, image)

    @classmethod
    def from_folder_structure(
        cls, root_directory_path: str, show_progress: bool = False
    ) -> ClassificationDataset:
        """
        Load data from a multiclass folder structure into a ClassificationDataset.

        Args:
            root_directory_path: The path to the dataset directory. Hidden
                entries, root-level files, nested directories, and files whose
                suffix is not a supported image extension are ignored.
            show_progress: If True, display a progress bar during loading.

        Returns:
            The dataset.

        Examples:
            ```python
            import roboflow
            from roboflow import Roboflow
            import supervision as sv

            roboflow.login()
            rf = Roboflow()

            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
            dataset = project.version(PROJECT_VERSION).download("folder")

            cd = sv.ClassificationDataset.from_folder_structure(
                root_directory_path=f"{dataset.location}/train"
                # pass show_progress=True to enable a tqdm progress bar
            )
            ```
        """
        root_directory = Path(root_directory_path)
        classes = sorted(
            {
                entry.name
                for entry in root_directory.iterdir()
                if entry.is_dir() and not entry.name.startswith(".")
            }
        )

        image_paths = []
        annotations = {}

        for class_id, class_name in enumerate(
            tqdm(
                classes,
                total=len(classes),
                desc="Loading classification dataset",
                disable=not show_progress,
            )
        ):
            class_directory = root_directory / class_name

            for image_path in sorted(
                class_directory.iterdir(), key=lambda path: path.name
            ):
                if image_path.name.startswith(".") or not image_path.is_file():
                    continue
                if image_path.suffix.lower() not in _IMAGE_FILE_EXTENSIONS:
                    continue
                image_paths.append(str(image_path))
                annotations[str(image_path)] = Classifications(
                    class_id=np.array([class_id]),
                )

        return cls(
            classes=classes,
            images=image_paths,
            annotations=annotations,
        )

Methods:

__getitem__(i: int) -> tuple[str, npt.NDArray[np.uint8], Classifications]

Returns:

Type	Description
tuple[str, NDArray[uint8], Classifications]	The image path, image data, and its corresponding annotation at index i.

Source code in src/supervision/dataset/core.py

def __getitem__(self, i: int) -> tuple[str, npt.NDArray[np.uint8], Classifications]:
    """
    Returns:
        The image path, image data,
            and its corresponding annotation at index i.
    """
    image_path = self.image_paths[i]
    image = self._get_image(image_path)
    annotation = self.annotations[image_path]
    return image_path, image, annotation

__iter__() -> Iterator[tuple[str, npt.NDArray[np.uint8], Classifications]]

Iterate over the images and annotations in the dataset.

Yields:

Type	Description
tuple[str, NDArray[uint8], Classifications]	Tuples containing the image path, image data, and its annotation.

Source code in src/supervision/dataset/core.py

def __iter__(
    self,
) -> Iterator[tuple[str, npt.NDArray[np.uint8], Classifications]]:
    """
    Iterate over the images and annotations in the dataset.

    Yields:
        Tuples containing the image path, image data, and its annotation.
    """
    for i in range(len(self)):
        image_path, image, annotation = self[i]
        yield image_path, image, annotation

as_folder_structure(root_directory_path: str, show_progress: bool = False) -> None

Saves the dataset as a multi-class folder structure.

Parameters:

Name	Type	Description	Default
root_directory_path	str	The path to the directory where the dataset will be saved.	required
show_progress	bool	If True, display a progress bar during saving.	False

Source code in src/supervision/dataset/core.py

def as_folder_structure(
    self, root_directory_path: str, show_progress: bool = False
) -> None:
    """
    Saves the dataset as a multi-class folder structure.

    Args:
        root_directory_path: The path to the directory
            where the dataset will be saved.
        show_progress: If True, display a progress bar during saving.
    """
    os.makedirs(root_directory_path, exist_ok=True)

    for class_name in self.classes:
        os.makedirs(os.path.join(root_directory_path, class_name), exist_ok=True)

    for image_save_path, image, annotation in tqdm(
        self,
        total=len(self),
        desc="Saving classification images",
        disable=not show_progress,
    ):
        image_name = Path(image_save_path).name
        class_id = (
            annotation.class_id[0]
            if annotation.confidence is None
            else annotation.get_top_k(1)[0][0]
        )
        class_name = self.classes[class_id]
        image_save_path = os.path.join(root_directory_path, class_name, image_name)
        cv2.imwrite(image_save_path, image)

from_folder_structure(root_directory_path: str, show_progress: bool = False) -> ClassificationDataset classmethod

Load data from a multiclass folder structure into a ClassificationDataset.

Parameters:

Name	Type	Description	Default
root_directory_path	str	The path to the dataset directory. Hidden entries, root-level files, nested directories, and files whose suffix is not a supported image extension are ignored.	required
show_progress	bool	If True, display a progress bar during loading.	False

Returns:

Type	Description
ClassificationDataset	The dataset.

Examples:

import roboflow
from roboflow import Roboflow
import supervision as sv

roboflow.login()
rf = Roboflow()

project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
dataset = project.version(PROJECT_VERSION).download("folder")

cd = sv.ClassificationDataset.from_folder_structure(
    root_directory_path=f"{dataset.location}/train"
    # pass show_progress=True to enable a tqdm progress bar
)

Source code in src/supervision/dataset/core.py

@classmethod
def from_folder_structure(
    cls, root_directory_path: str, show_progress: bool = False
) -> ClassificationDataset:
    """
    Load data from a multiclass folder structure into a ClassificationDataset.

    Args:
        root_directory_path: The path to the dataset directory. Hidden
            entries, root-level files, nested directories, and files whose
            suffix is not a supported image extension are ignored.
        show_progress: If True, display a progress bar during loading.

    Returns:
        The dataset.

    Examples:
        ```python
        import roboflow
        from roboflow import Roboflow
        import supervision as sv

        roboflow.login()
        rf = Roboflow()

        project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
        dataset = project.version(PROJECT_VERSION).download("folder")

        cd = sv.ClassificationDataset.from_folder_structure(
            root_directory_path=f"{dataset.location}/train"
            # pass show_progress=True to enable a tqdm progress bar
        )
        ```
    """
    root_directory = Path(root_directory_path)
    classes = sorted(
        {
            entry.name
            for entry in root_directory.iterdir()
            if entry.is_dir() and not entry.name.startswith(".")
        }
    )

    image_paths = []
    annotations = {}

    for class_id, class_name in enumerate(
        tqdm(
            classes,
            total=len(classes),
            desc="Loading classification dataset",
            disable=not show_progress,
        )
    ):
        class_directory = root_directory / class_name

        for image_path in sorted(
            class_directory.iterdir(), key=lambda path: path.name
        ):
            if image_path.name.startswith(".") or not image_path.is_file():
                continue
            if image_path.suffix.lower() not in _IMAGE_FILE_EXTENSIONS:
                continue
            image_paths.append(str(image_path))
            annotations[str(image_path)] = Classifications(
                class_id=np.array([class_id]),
            )

    return cls(
        classes=classes,
        images=image_paths,
        annotations=annotations,
    )

split(split_ratio: float = 0.8, random_state: int | None = None, shuffle: bool = True) -> tuple[ClassificationDataset, ClassificationDataset]

Splits the dataset into two parts (training and testing) using the provided split_ratio.

Parameters:

Name	Type	Description	Default
split_ratio	float	The ratio of the training set to the entire dataset.	0.8
random_state	int | None	The seed for the random number generator. This is used for reproducibility.	None
shuffle	bool	Whether to shuffle the data before splitting.	True

Returns:

Type	Description
ClassificationDataset	A tuple containing
ClassificationDataset	the training and testing datasets.

Examples:

>>> import numpy as np
>>> import supervision as sv
>>> cd = sv.ClassificationDataset(
...     classes=['cat', 'dog'],
...     images={
...         'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
...         'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
...     },
...     annotations={
...         'img1.jpg': sv.Classifications(class_id=np.array([0])),
...         'img2.jpg': sv.Classifications(class_id=np.array([1])),
...     }
... )
>>> train_cd, test_cd = cd.split(split_ratio=0.5, random_state=42)
>>> len(train_cd), len(test_cd)
(1, 1)

Source code in src/supervision/dataset/core.py

def split(
    self,
    split_ratio: float = 0.8,
    random_state: int | None = None,
    shuffle: bool = True,
) -> tuple[ClassificationDataset, ClassificationDataset]:
    """
    Splits the dataset into two parts (training and testing)
        using the provided split_ratio.

    Args:
        split_ratio: The ratio of the training
            set to the entire dataset.
        random_state: The seed for the
            random number generator. This is used for reproducibility.
        shuffle: Whether to shuffle the data before splitting.

    Returns:
        A tuple containing
        the training and testing datasets.

    Examples:
        ```pycon
        >>> import numpy as np
        >>> import supervision as sv
        >>> cd = sv.ClassificationDataset(
        ...     classes=['cat', 'dog'],
        ...     images={
        ...         'img1.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
        ...         'img2.jpg': np.zeros((100, 100, 3), dtype=np.uint8),
        ...     },
        ...     annotations={
        ...         'img1.jpg': sv.Classifications(class_id=np.array([0])),
        ...         'img2.jpg': sv.Classifications(class_id=np.array([1])),
        ...     }
        ... )
        >>> train_cd, test_cd = cd.split(split_ratio=0.5, random_state=42)
        >>> len(train_cd), len(test_cd)
        (1, 1)

        ```
    """
    train_paths, test_paths = train_test_split(
        data=self.image_paths,
        train_ratio=split_ratio,
        random_state=random_state,
        shuffle=shuffle,
    )

    train_input: list[str] | dict[str, npt.NDArray[np.uint8]]
    test_input: list[str] | dict[str, npt.NDArray[np.uint8]]
    if self._images_in_memory:
        train_input = {path: self._images_in_memory[path] for path in train_paths}
        test_input = {path: self._images_in_memory[path] for path in test_paths}
    else:
        train_input = train_paths
        test_input = test_paths
    train_annotations = {path: self.annotations[path] for path in train_paths}
    test_annotations = {path: self.annotations[path] for path in test_paths}

    train_dataset = ClassificationDataset(
        classes=self.classes,
        images=train_input,
        annotations=train_annotations,
    )
    test_dataset = ClassificationDataset(
        classes=self.classes,
        images=test_input,
        annotations=test_annotations,
    )

    return train_dataset, test_dataset

Comments