Skip to content

Commit

Permalink
Add Roboflow document (#1127)
Browse files Browse the repository at this point in the history 
<!-- Contributing guide:
https://github.com/openvinotoolkit/datumaro/blob/develop/CONTRIBUTING.md
-->

### Summary

<!--
Resolves #111 and #222.
Depends on #1000 (for series of dependent commits).

This PR introduces this capability to make the project better in this
and that.

- Added this feature
- Removed that feature
- Fixed the problem #1234
-->

### How to test
<!-- Describe the testing procedure for reviewers, if changes are
not fully covered by unit tests or manual testing can be complicated.
-->

### Checklist
<!-- Put an 'x' in all the boxes that apply -->
- [ ] I have added unit tests to cover my changes.​
- [ ] I have added integration tests to cover my changes.​
- [ ] I have added the description of my changes into
[CHANGELOG](https://github.com/openvinotoolkit/datumaro/blob/develop/CHANGELOG.md).​
- [x] I have updated the
[documentation](https://github.com/openvinotoolkit/datumaro/tree/develop/docs)
accordingly

### License

- [ ] I submit _my code changes_ under the same [MIT
License](https://github.com/openvinotoolkit/datumaro/blob/develop/LICENSE)
that covers the project.
  Feel free to contact the maintainers if that's a concern.
- [ ] I have updated the license header for each file (see an example
below).

```python
# Copyright (C) 2023 Intel Corporation
#
# SPDX-License-Identifier: MIT
```
  • Loading branch information
@wonjuleee
wonjuleee authored Aug 22, 2023
1 parent 4f848c9 commit cf244a2
Show file tree
Hide file tree
Showing 3 changed files with 352 additions and 4 deletions.
11 changes: 7 additions & 4 deletions docs/source/docs/data-formats/formats/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Supported Data Formats
kinetics
kitti
kitti_raw
labelme
lfw
mapillary_vistas
market1501
Expand All @@ -40,6 +41,7 @@ Supported Data Formats
nyu_depth_v2
open_images
pascal_voc
roboflow
segment_anything
sly_pointcloud
synthia
Expand Down Expand Up @@ -122,6 +124,7 @@ Supported Data Formats
* LabelMe (``labels``, ``boxes``, ``masks``)
* `Format specification <http://labelme.csail.mit.edu/Release3.0>`_
* `Dataset example <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/labelme_dataset>`_
* `Format documentation <labelme.md>`_
* LFW (``classification``, ``person re-identification``, ``landmarks``)
* `Format specification <http://vis-www.cs.umass.edu/lfw/>`_
* `Dataset example <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/lfw_dataset>`_
Expand Down Expand Up @@ -166,10 +169,10 @@ Supported Data Formats
* `Dataset example <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/coco_dataset>`_
* ``labels`` are our extension - like `instances` with only `category_id`
* `Format documentation <coco.md>`_
* Roboflow COCO (import-only)
* `Format specification <https://roboflow.com/formats/coco-json>`_
* `Dataset example <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/coco_dataset/coco_roboflow>`_
* `Format documentation <coco#coco-from-roboflow.md>`_
* Roboflow (import-only)
* `Format specification <https://roboflow.com/formats/>`_
* `Dataset example <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/roboflow_dataset>`_
* `Format documentation <roboflow.md>`_
* NYU Depth Dataset V2 (``depth estimation``) (import-only)
* `Format specification <https://cs.nyu.edu/~silberman/datasets/nyu_depth_v2.html>`_
* `Dataset example <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/nyu_depth_v2_dataset>`_
Expand Down
110 changes: 110 additions & 0 deletions docs/source/docs/data-formats/formats/labelme.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# LabelMe
## Format specification
[LabelMe](http://labelme.csail.mit.edu/Release3.0/) is an open-source annotation tool provided by MIT, which is commonly used for annotating images and creating ground truth for various computer vision tasks such as object detection and segmentation.
It allows users to draw bounding boxes, polygons, and scribbles on images to label objects and regions of interest.
You can install LabelMe on your local as following [Github instructions](https://github.com/wkentaro/labelme).

Supported annotation types:
- `Bbox`
- `Polygon`
- `Mask`

## Import a LabelMe dataset
A Datumaro project with a LabelMe source can be created in the following way:

``` bash
datum project create
datum project import --format label_me <path/to/dataset>
```

## Export a dataset with LabelMe format
Datumaro helps to export a dataset with LabelMe format through below:

```bash
datum project create
datum project add -f <any-other-dataset-format> <path/to/dataset/>
datum project export -f label_me -o <output/dir> -- --save-media
```
or
```bash
datum convert -if <any-other-dataset-format> -i <path/to/dataset> \
-f label_me -o <output/dir> -- --save-media
```

Or, using Python API:

```python
import datumaro as dm

dataset = dm.Dataset.import_from('<path/to/dataset>', '<any-other-dataset-format>')
dataset.export('save_dir', 'label_me', save_media=True)
```

> This can help you to import any data into LabelMe annotation tool for modifying or adding more annotations to the dataset.
## Directory structure
<!--lint disable fenced-code-flag-->
```
└─ labelme/
├── Images # Image directory
│ ├── subset1 # Subset directory
│ │ ├── img1.jpg # Image file
│ │ ├── img2.jpg # Image file
│ │ └── ...
│ ├── subset2 # Subset directory
│ │ ├── img1.jpg # Image file
│ │ └── ...
│ └── ...
├── Annotations # Label directory
│ ├── subset1 # Subset directory
│ │ ├── img1.xml # Annotation file
│ │ ├── img2.xml # Annotation file
│ │ └── ...
│ ├── subset2 # Subset directory
│ │ ├── img1.xml # Annotation file
│ │ └── ...
│ └── ...
├── Masks # Mask directory
│ ├── subset1 # Subset directory
│ │ ├── img1_mask_0.png # Mask file
│ │ ├── img1_mask_1.png # Mask file
│ │ ├── img2_mask_0.png # Mask file
│ │ └── ...
│ ├── subset2 # Subset directory
│ │ ├── img1_mask_0.png # Mask file
│ │ └── ...
│ └── ...
└──Scribbles # Scribble directory
├── subset1 # Subset directory
│ ├── img1_scribble_0.png # Scribble file
│ ├── img1_scribble_1.png # Scribble file
│ ├── img2_scribble_0.png # Scribble file
│ └── ...
├── subset2 # Subset directory
│ ├── img1_scribble_0.png # Scribble file
│ └── ...
└── ...
```

## Annotation XML example
<!--lint disable fenced-code-flag-->
```
<annotation>
<filename>example_image.jpg</filename>
<size>
<width>640</width>
<height>480</height>
</size>
<object>
<name>cat</name>
<polygon>
<pt>
<x>100</x>
<y>150</y>
</pt>
<!-- Additional points defining the polygon -->
</polygon>
</object>
<!-- Additional objects and annotations -->
</annotation>
```
235 changes: 235 additions & 0 deletions docs/source/docs/data-formats/formats/roboflow.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,235 @@
# Roboflow
## Format specification
[Roboflow](https://universe.roboflow.com/) provides a range of services and tools to assist with various aspects of computer vision and machine learning projects.
These services are aimed at simplifying the process of data importing, annotating, and training models for tasks like image classification, object detection, segmentation, and more.
Datumaro supports various [Roboflow formats](https://roboflow.com/formats) so that can make it easier for users to import and work with datasets that have been prepared and annotated using Roboflow tools.
You can enjoy some examples [here](https://universe.roboflow.com/joseph-nelson/bccd/dataset/4).

Supported annotation formats:
- `COCO JSON`
- `VOC XML`
- `YOLOv5, YOLOv6, YOLOv7, YOLOv8 TXT`
- `TFRecord`
- `CreateML JSON`
- `YOLOv5 Oriented Bounding Boxes TXT`
- `Multiclass Classification CSV`

## Import Roboflow dataset
A Datumaro project with a Roboflow source can be created in the following way:

```bash
datum project create
datum project import --format roboflow_coco <path/to/dataset>
```

Or, using Python API:

```python
import datumaro as dm

dataset = dm.Dataset.import_from('<path/to/dataset>', 'roboflow_coco')
```

### Roboflow COCO JSON
#### Directory structure
<!--lint disable fenced-code-flag-->
```
coco/
├── train # Subset directory
│ ├── _annotations.coco.json # Annotation file
│ ├── train_img1.jpg # Image file
│ ├── train_img2.jpg # Image file
│ └── ...
├── valid # Subset directory
│ ├── _annotations.coco.json # Annotation file
│ ├── valid_img1.jpg # Image file
│ └── ...
└── test # Subset directory
│ ├── _annotations.coco.json # Annotation file
│ ├── test_img1.jpg # Image file
│ └── ...
```
#### Annotation JSON file
The example of `_annotations.coco.json` is given by EXAMPLE tap of [Roboflow COCO JSON](https://roboflow.com/formats/coco-json).

### Roboflow VOC XML
#### Directory structure
<!--lint disable fenced-code-flag-->
```
voc/
├── train # Subset directory
│ ├── train_img1.jpg # Image file
│ ├── train_img1.xml # Annotation file
│ ├── train_img2.jpg # Image file
│ ├── train_img2.xml # Annotation file
│ └── ...
├── valid # Subset directory
│ ├── valid_img1.jpg # Image file
│ ├── valid_img1.xml # Annotation file
│ └── ...
└── test # Subset directory
│ ├── test_img1.jpg # Image file
│ ├── test_img1.xml # Annotation file
│ └── ...
```
#### Annotation XML file
The example of `{*}.xml` is given by EXAMPLE tap of [Roboflow VOC XML](https://roboflow.com/formats/pascal-voc-xml).

### Roboflow YOLOv5, YOLOv7, YOLOv8 TXT
#### Directory structure
<!--lint disable fenced-code-flag-->
```
yolo/
├── data.yaml # YAML meta file (required)
├── train # Subset directory
│ ├── images # Image directory
│ │ ├── train_img1.jpg # Image file
│ │ ├── train_img2.jpg # Image file
│ │ └── ...
│ └── labels # Label directory
│ ├── train_img1.txt # Annotation file
│ ├── train_img2.txt # Annotation file
│ └── ...
├── valid # Subset directory
│ ├── images # Image directory
│ │ ├── valid_img1.jpg # Image file
│ │ └── ...
│ └── labels # Label directory
│ ├── valid_img1.txt # Annotation file
│ └── ...
└── test # Subset directory
├── images # Image directory
│ ├── test_img1.jpg # Image file
│ └── ...
└── labels # Label directory
├── test_img1.txt # Annotation file
└── ...
```
#### Annotation TXT file
The example of `{*}.txt` is given by EXAMPLE tap of [Roboflow YOLO TXT](https://roboflow.com/formats/yolov8-pytorch-txt).

### Roboflow MT-YOLOv6 TXT
#### Directory structure
<!--lint disable fenced-code-flag-->
```
mt-yolov6/
├── data.yaml # YAML meta file (required)
├── images # Image directory
│ ├── train # Subset directory
│ │ ├── train_img1.jpg # Image file
│ │ ├── train_img2.jpg # Image file
│ │ └── ...
│ ├── valid # Subset directory
│ │ ├── valid_img1.jpg # Image file
│ │ └── ...
│ └── test # Subset directory
│ ├── test_img1.jpg # Image file
│ └── ...
└── labels # Label directory
├── train # Subset directory
│ ├── train_img1.txt # Annotation file
│ ├── train_img2.txt # Annotation file
│ └── ...
├── valid # Subset directory
│ ├── test_img1.txt # Annotation file
│ └── ...
└── test # Subset directory
├── test_img1.txt # Annotation file
└── ...
```
#### Annotation TXT file
The example of `{*}.txt` is given by EXAMPLE tap of [Roboflow MT-YOLOv6 TXT](https://roboflow.com/formats/mt-yolov6).

### Roboflow Tensorflow TFRecord
#### Directory structure
<!--lint disable fenced-code-flag-->
```
tfrecord/
├── train # Subset directory
│ ├── label_map.pbtxt # Label map file (label names and ids)
│ └── sample.tfrecord # Tfrecord file
├── valid # Subset directory
│ ├── label_map.pbtxt # Label map file (label names and ids)
│ └── sample.tfrecord # Tfrecord file
└── test # Subset directory
├── label_map.pbtxt # Label map file (label names and ids)
└── sample.tfrecord # Tfrecord file
```

### Roboflow CreateML JSON
#### Directory structure
<!--lint disable fenced-code-flag-->
```
createml/
├── train # Subset directory
│ ├── _annotations.createml.json # Annotation file
│ ├── train_img1.jpg # Image file
│ ├── train_img2.jpg # Image file
│ └── ...
├── valid # Subset directory
│ ├── _annotations.createml.json # Annotation file
│ ├── valid_img1.jpg # Image file
│ └── ...
└── test # Subset directory
│ ├── _annotations.createml.json # Annotation file
│ ├── test_img1.jpg # Image file
│ └── ...
```
#### Annotation JSON file
The example of `_annotations.createml.json` is given by EXAMPLE tap of [Roboflow CreateML JSON](https://roboflow.com/formats/createml-json).

### Roboflow YOLOv5 Oriented Bounding Boxes
#### Directory structure
<!--lint disable fenced-code-flag-->
```
yolov5-obb/
├── data.yaml # YAML meta file (required)
├── train # Subset directory
│ ├── images # Image directory
│ │ ├── train_img1.jpg # Image file
│ │ ├── train_img2.jpg # Image file
│ │ └── ...
│ └── labelTxt # Label directory
│ ├── train_img1.txt # Annotation file
│ ├── train_img2.txt # Annotation file
│ └── ...
├── valid # Subset directory
│ ├── images # Image directory
│ │ ├── valid_img1.jpg # Image file
│ │ └── ...
│ └── labelTxt # Label directory
│ ├── valid_img1.txt # Annotation file
│ └── ...
└── test # Subset directory
├── images # Image directory
│ ├── test_img1.jpg # Image file
│ └── ...
└── labelTxt # Label directory
├── test_img1.txt # Annotation file
└── ...
```
#### Annotation TXT file
The example of `{*}.txt` is given by EXAMPLE tap of [Roboflow YOLOv5-OBB TXT](https://roboflow.com/formats/yolov5-obb).

### Roboflow Multiclass Classification CSV
#### Directory structure
<!--lint disable fenced-code-flag-->
```
multiclass/
├── data.yaml # YAML meta file (required)
├── train # Subset directory
│ ├── _classes.csv # Annotation file
│ ├── train_img1.jpg # Image file
│ ├── train_img2.jpg # Image file
│ └── ...
├── valid # Subset directory
│ ├── _classes.csv # Annotation file
│ ├── valid_img1.jpg # Image file
│ └── ...
└── test # Subset directory
├── _classes.csv # Annotation file
├── test_img1.jpg # Image file
└── ...
```
#### Annotation CSV file
The example of `_classes.csv` is given by EXAMPLE tap of [Roboflow Multiclass CSV](https://roboflow.com/formats/multiclass-classification-csv).

0 comments on commit cf244a2

Please sign in to comment.