diff --git a/site/content/en/docs/formats/yolo8.md b/site/content/en/docs/formats/yolo8.md new file mode 100644 index 0000000000..304e3e71bd --- /dev/null +++ b/site/content/en/docs/formats/yolo8.md @@ -0,0 +1,312 @@ +--- +title: 'YOLO8' +linkTitle: 'YOLO8' +description: '' +--- + +## Format specification + +The YOLO8 format family allows you to define the dataset root directory, the relative paths to training/validation/testing image directories or *.txt files containing image paths, and a dictionary of class names. + +Family consists of four formats: +- [Detection](https://docs.ultralytics.com/datasets/detect/) +- [Oriented bounding Box](https://docs.ultralytics.com/datasets/obb/) +- [Segmentation](https://docs.ultralytics.com/datasets/segment/) +- [Pose](https://docs.ultralytics.com/datasets/pose/) + +Supported annotation types and formats: +- `Bbox` + - Detection (only not rotated) + - Oriented Bounding Box, + - Segmentation (only export)) +- `Polygon` + - Segmentation +- `Skeleton` + - Pose + +The format supports arbitrary subset names, except `classes`, `names`, `backup`, `path`, `kpt_shape`, `flip_idx`. + +> Note, that by default, the YOLO framework does not expect any subset names, + except `train` and `valid`, Datumaro supports this as an extension. + If there is no subset separation in a project, the data + will be saved in the `train` subset. + +## Import YOLO8 dataset +To create a Datumaro project with a YOLO8 source, use the following commands: + +```bash +datum create +datum import --format yolo8 # for Detection dataset +datum import --format yolo8_obb # for Oriented Bounding Box dataset +datum import --format yolo8_segmentation # for Segmentation dataset +datum import --format yolo8_pose # for Pose dataset +``` + +The YOLO8 dataset directory should have the following structure: + +```bash +└─ yolo_dataset/ + │ # a list of non-format labels (optional) # file with list of classes + ├── data.yaml # file with dataset information + ├── train.txt # list of image paths in train subset [Optional] + ├── val.txt # list of image paths in valid subset [Optional] + │ + ├── images/ + │ ├── train/ # directory with images for train subset + │ │ ├── image1.jpg + │ │ ├── image2.jpg + │ │ ├── image3.jpg + │ │ └── ... + │ ├── valid/ # directory with images for validation subset + │ │ ├── image11.jpg + │ │ ├── image12.jpg + │ │ ├── image13.jpg + │ │ └── ... + ├── labels/ + │ ├── train/ # directory with annotations for train subset + │ │ ├── image1.txt + │ │ ├── image2.txt + │ │ ├── image3.txt + │ │ └── ... + │ ├── valid/ # directory with annotations for validation subset + │ │ ├── image11.txt + │ │ ├── image12.txt + │ │ ├── image13.txt + │ │ └── ... +``` + +`data.yaml` should have the following content: + +```yaml +# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..] +path: ./ # dataset root dir +train: train.txt # train images (relative to 'path') 4 images +val: val.txt # val images (relative to 'path') 4 images + +# YOLO8 Pose specific field +# First number is a number of points in skeleton +# Second number defines a format of point info in an annotation txt files +kpt_shape: [17, 3] + +# Classes +names: + 0: person + 1: bicycle + 2: car + # ... + 77: teddy bear + 78: hair drier + 79: toothbrush +``` + +> Note, that though by default YOLO8 expects `data.yaml`, Datumaro allows this file to have arbitrary name. + +Files `train.txt` and `val.txt` should have the following structure: + +```txt + + +... +``` + +Files in directories `labels/train/` and `labels/valid/` should contain information about labels for images in `images/train` and `images/valid` respectively. +If there are no objects in an image, no `.txt` file is required. + +Content of the `.txt` file depends on format. + +For **Detection** it contains bounding boxes: +```txt +# labels/image1.txt: +# +0 0.250000 0.400000 0.300000 0.400000 +3 0.600000 0.400000 0.400000 0.266667 +... +``` + +For **Oriented Bounding Box** and **Segmentation** it contains coordinates of all points of oriented bounding box or polygon respectively: +```txt +# labels/image1.txt: +# +0 0.146731 0.151795 0.319936 0.301795 0.186603 0.648205 0.013397 0.498205 +3 0.557735 0.090192 0.357735 0.609808 0.242265 0.509808 0.442265 -0.009808 +... +``` + +For **Pose** it contains bounding boxes and then description of points in one of two forms. +- If the second number in kpt_shape field is 2, then the line contains two values for every point - `x`, `y`. +- If the second number in kpt_shape field is 3, then the line contains three values for every point - `x`, `y`, `visibility`, where `visibility` can have one of three values: + - 0: The keypoint is not visible. + - 1: The keypoint is partially visible. + - 2: The keypoint is fully visible. + +```txt +# labels/image1.txt: +# ... +0 0.250000 0.400000 0.300000 0.400000 0.250000 0.400000 2 0.350000 0.500000 0 ... +3 0.600000 0.400000 0.400000 0.266667 0.250000 0.400000 1 0.440000 0.550000 2 ... +... +``` + +All coordinates must be normalized and be in range [0, 1]. It can be achieved by dividing x coordinates and widths by image width, and y coordinates and heights by image height. + + +## Export to other formats + +Datumaro can convert a YOLO8 dataset into any other format Datumaro supports. +To get the expected result, convert the dataset to formats that support the same annotations as YOLO8 format you have. + +```bash +datum create +datum add -f yolo8 +datum export -f coco_instances -o +``` +or +```bash +datum convert -if yolo8 -i -f coco_instances -o +``` + +Extra options for importing YOLO8 format: +- `--config-file` allows to specify config file name to use instead of default `data.yaml` + +Alternatively, using the Python API: + +```python +from datumaro.components.dataset import Dataset + +data_path = 'path/to/dataset' +data_format = 'yolo8' + +dataset = Dataset.import_from(data_path, data_format) +dataset.export('save_dir', 'coco_instances') +``` + +## Export to YOLO8 format +Datumaro can convert an existing dataset to YOLO8 format if it supports annotations from source format. + +Example: + +```bash +datum create +datum import -f coco_instances +datum export -f yolo8 -o +``` + +Extra options for exporting to YOLO8 format: +- `--save-media` allow to export dataset with saving media files + (default: `False`) +- `--image-ext ` allow to specify image extension + for exporting dataset (default: use original or `.jpg`, if none) +- `--add-path-prefix` allows to specify, whether to include the + `data/` path prefix in the annotation files or not (default: `True`) +- `--config-file` allows to specify config file name to use instead of default `data.yaml` + +## Examples + +### Example 1. Create a custom dataset in YOLO8 Detection format + +```python +import numpy as np +import datumaro as dm + +dataset = dm.Dataset.from_iterable( + [ + dm.DatasetItem( + id=1, + subset="train", + media=dm.Image(data=np.ones((8, 8, 3))), + annotations=[ + dm.Bbox(0, 2, 4, 2, label=2), + dm.Bbox(0, 1, 2, 3, label=4), + ], + ), + ], + categories=["label_" + str(i) for i in range(10)], +) +dataset.export('../yolov8_dataset', format='yolo8') +``` + +### Example 2. Create a custom dataset in YOLO8 Oriented Bounding Box format + +```python +import numpy as np +import datumaro as dm + +dataset = dm.Dataset.from_iterable( + [ + dm.DatasetItem( + id=1, + subset="train", + media=dm.Image(data=np.ones((8, 8, 3))), + annotations=[ + dm.Bbox(0, 2, 4, 2, label=2), + dm.Bbox(0, 1, 2, 3, label=4, attributes={"rotation": 30}), + ], + ), + ], + categories=["label_" + str(i) for i in range(10)], +) +dataset.export('../yolov8_dataset', format='yolo8_obb') +``` + +### Example 3. Create a custom dataset in YOLO8 Segmentation format + +```python +import numpy as np +import datumaro as dm + +dataset = dm.Dataset.from_iterable( + [ + dm.DatasetItem( + id=1, + subset="train", + media=dm.Image(data=np.ones((8, 8, 3))), + annotations=[ + dm.Bbox(0, 2, 4, 2, label=2), + dm.Bbox(0, 1, 2, 3, label=4, attributes={"rotation": 30}), + dm.Polygon([3.0, 1.5, 6.0, 1.5, 6.0, 7.5, 4.5, 7.5, 3.75, 3.0], label=4), + ], + ), + ], + categories=["label_" + str(i) for i in range(10)], +) +dataset.export('../yolov8_dataset', format='yolo8_segmentation') +``` + +### Example 4. Create a custom dataset in YOLO8 Pose format + +```python +import numpy as np +import datumaro as dm + +dataset = dm.Dataset.from_iterable( + [ + dm.DatasetItem( + id="1", + subset="train", + media=dm.Image(data=np.ones((5, 10, 3))), + annotations=[ + dm.Skeleton( + [ + dm.Points([1.5, 2.0], [2], label=1), + dm.Points([4.5, 4.0], [2], label=2), + dm.Points([7.5, 6.0], [1], label=3), + ], + label=0, + ), + ], + ), + ], + categories={ + dm.AnnotationType.label: dm.LabelCategories.from_iterable([ + "skeleton_label", + ("point_0", "skeleton_label"), + ("point_1", "skeleton_label"), + ("point_2", "skeleton_label"), + ]), + dm.AnnotationType.points: dm.PointsCategories.from_iterable([ + (0, ["point_0", "point_1", "point_2"], set()) + ]), + }, +) +dataset.export('../yolov8_dataset', format='yolo8_pose') +``` \ No newline at end of file diff --git a/site/content/en/docs/user-manual/supported_formats.md b/site/content/en/docs/user-manual/supported_formats.md index cea5d41f96..2eb3b2f592 100644 --- a/site/content/en/docs/user-manual/supported_formats.md +++ b/site/content/en/docs/user-manual/supported_formats.md @@ -161,6 +161,23 @@ List of supported formats: - [Format specification](https://github.com/AlexeyAB/darknet#how-to-train-pascal-voc-data) - [Dataset example](https://github.com/cvat-ai/datumaro/tree/develop/tests/assets/yolo_dataset) - [Format documentation](/docs/formats/yolo) +- YOLO8 (`detection`, `segmentation`, `pose`, `oriented_box`) + - Detection + - [Format specification](https://docs.ultralytics.com/datasets/detect/) + - [Dataset example](https://docs.ultralytics.com/datasets/detect/coco8/) + - [Format documentation](/docs/formats/yolo8) + - Segmentation + - [Format specification](https://docs.ultralytics.com/datasets/segment/) + - [Dataset example](https://docs.ultralytics.com/datasets/segment/coco8-seg/) + - [Format documentation](/docs/formats/yolo8) + - Pose + - [Format specification](https://docs.ultralytics.com/datasets/pose/) + - [Dataset example](https://docs.ultralytics.com/datasets/pose/coco8-pose/) + - [Format documentation](/docs/formats/yolo8) + - Oriented box + - [Format specification](https://docs.ultralytics.com/datasets/obb/) + - [Dataset example](https://docs.ultralytics.com/datasets/obb/dota8/) + - [Format documentation](/docs/formats/yolo8) ### Supported annotation types