Skip to content

Commit

Permalink
Add notebook for Kaggle importers (#1254)
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 authored Feb 1, 2024
1 parent acc491d commit 76769b5
Show file tree
Hide file tree
Showing 3 changed files with 46,166 additions and 0 deletions.
4 changes: 4 additions & 0 deletions docs/source/docs/data-formats/formats/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Supported Data Formats
icdar
image_zip
imagenet
kaggle
kinetics
kitti
kitti_raw
Expand Down Expand Up @@ -111,6 +112,9 @@ Supported Data Formats
* `Dataset example (txt for classification) <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/imagenet_txt_dataset>`_
* Detection format is the same as in PASCAL VOC
* `Format documentation <imagenet.md>`_
* Kaggle (``classification``, ``detection``, ``segmentation``) (import-only)
* `Dataset examples <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/kaggle_datasets>`_
* `Format documentation <kaggle.md>`_
* KITTI (``segmentation``, ``detection``)
* `Format specification <http://www.cvlibs.net/datasets/kitti/index.php>`_
* `Dataset example <https://github.com/openvinotoolkit/datumaro/tree/develop/tests/assets/kitti_dataset>`_
Expand Down
77 changes: 77 additions & 0 deletions docs/source/docs/data-formats/formats/kaggle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Kaggle

## Format specification

[Kaggle](https://www.kaggle.com/) provides more than 2800 computer vision datasets for the public good and fair competition.
All datasets are available for downloading at [here](https://www.kaggle.com/datasets?tags=13207-Computer+Vision).
However, since Kaggle doesn't enforce community to follow specific rule for dataset uploads, it is more natural to explore a dataset directoy structure by manual.
So it eventually requires to take some time for importing those datasets into their machine learning codes.
Therefore, Datumaro is providing an ability to import them through Datumaro Python APIs.

Supported type of annotations:
- `Label` (classification)
- `Bbox` (object detection)
- `Mask` (segmentation)

## Import Kaggle Image CSV dataset

Indeed, Kaggle doesn't have any specific directory structure, and Datumaro hence requires more user-aided arguments for importing.
For `kaggle_image_csv` format, we want to have one `csv` file and `image_directory` as shown below.

```
├── <annotation_file>.csv
└── <image_directory>
├── <name_of_image_1>.jpg # extension of video could be other
├── <name_of_image_2>.jpg
└── ...
```

Here `<annotation_file>.csv` contains media name and annotation information such as label or box coordinates as

```
media_name_in_image_directory,label,...
<name_of_image_1>,<category_1>,...
<name_of_image_2>,<category_2>,...
...
```

A Datumaro dataset with a Kaggle dataset can be created in the following way in Python API:

```python
import datumaro as dm

dataset = dm.Dataset.import_from('<path_to_image_directory>', format='kaggle_image_csv', ann_file='<path_to_csv_file>', columns={"media": "column_name_of_media", "label": "column_name_of_label"})
```
At this time, it's essential to specify the column names for media and label such as `dm.Dataset.import_from(..., columns={"media": "column_name_of_media", "label": "column_name_of_label"})`

## Import Kaggle Image Txt dataset

Another `kaggle_image_txt` format replaces only `columns` with an order of informations in `.txt`.
For instance, dataset can be created by

```python
dataset = dm.Dataset.import_from('<path_to_image_directory>', format='kaggle_image_txt', ann_file='<path_to_txt_file>', columns={"media": 0, "label": 1})
```

## Import Kaggle Image Mask dataset

For segmentation tasks, `kaggle_image_mask` requires to have a directory for mask images as following Python API.
```python
dataset = dm.Dataset.import_from('<path_to_image_directory>', format='kaggle_image_mask', mask_path='<path_to_mask_directory>')
```

## Import Kaggle VOC and Kaggle YOLO datasets

Sometimes, communities upload their annotation files for each images with VOC (`xml`) and YOLO (`txt`) formats thanks to its popularity.
But, they violate the directory sturcture of the original Pascal-VOC and YOLO described in [VOC](./pascal_voc.md) and [YOLO](./yolo.md), respectively.
For these cases, we provide `kaggle_voc` and `kaggle_yolo` formats by specifying the path to annotation files as below.

```python
dataset = dm.Dataset.import_from('<path_to_image_directory>', format='kaggle_voc', ann_path='<path_to_annotation_directory>')
```
or
```python
dataset = dm.Dataset.import_from('<path_to_image_directory>', format='kaggle_yolo', ann_path='<path_to_annotation_directory>')
```

Please refer to [here](https://github.com/openvinotoolkit/datumaro/blob/develop/notebooks/20_kaggle_data_import.ipynb) for various practices.
Loading

0 comments on commit 76769b5

Please sign in to comment.