Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Eldies
Eldies committed Jul 26, 2024
1 parent 3ae6c6e commit 58c2261
Show file tree
Hide file tree
Showing 2 changed files with 329 additions and 0 deletions.
312 changes: 312 additions & 0 deletions site/content/en/docs/formats/yolo8.md
View file
Original file line number Diff line number Diff line change
@@ -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 <path/to/dataset> # for Detection dataset
datum import --format yolo8_obb <path/to/dataset> # for Oriented Bounding Box dataset
datum import --format yolo8_segmentation <path/to/dataset> # for Segmentation dataset
datum import --format yolo8_pose <path/to/dataset> # 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
<path/to/image1.jpg>
<path/to/image2.jpg>
...
```

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:
# <label_index> <x_center> <y_center> <width> <height>
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:
# <label_index> <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4>
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:
# <label_index> <x_center> <y_center> <width> <height> <x1> <y1> <visibility1> <x2> <y2> <visibility2> ...
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 <path/to/yolov8/>
datum export -f coco_instances -o <output/dir>
```
or
```bash
datum convert -if yolo8 -i <path/to/dataset> -f coco_instances -o <path/to/dataset>
```

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 <path/to/dataset>
datum export -f yolo8 -o <path/to/dataset>
```

Extra options for exporting to YOLO8 format:
- `--save-media` allow to export dataset with saving media files
(default: `False`)
- `--image-ext <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')
```
17 changes: 17 additions & 0 deletions site/content/en/docs/user-manual/supported_formats.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<a id="annotation-types"></a>
### Supported annotation types
Expand Down

0 comments on commit 58c2261

Please sign in to comment.