# Создание набора данных изображений

Существует два способа создания и публикации набора данных изображений. В этом руководстве показано, как:

* Create an image dataset from local files in python with [Dataset.push_to_hub()](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.Dataset.push_to_hub). This is an easy way that requires only a few steps in python.

* Создайте набор данных изображений с помощью `ImageFolder` и некоторыми метаданными. Это решение без написания кода для быстрого создания набора данных изображений, содержащего несколько тысяч файлов.

> [!TIP]
> Вы можете управлять доступом к вашему набору данных, требуя, чтобы пользователи сначала предоставили свои контактные данные. Подробнее о том, как включить эту функцию на Hub, читайте в руководстве [Gated datasets](https://huggingface.co/docs/hub/datasets-gated).

## ImageFolder

`ImageFolder` — это конструктор набора данных, предназначенный для быстрого загрузки набора изображений, содержащего несколько тысяч файлов, без необходимости писать какой-либо код.

> [!TIP]
> 💡 Ознакомьтесь с [Иерархией паттернов разбиения](repository_structure#split-pattern-hierarchy), чтобы узнать, как `ImageFolder` создаёт разбиения датасета на основе структуры вашего репозитория с данными.

`ImageFolder` автоматически определяет метки классов вашего набора данных на основе имен директорий. Разместите ваш набор данных в структуре директорий, похожей на следующую:

```
folder/train/dog/golden_retriever.png
folder/train/dog/german_shepherd.png
folder/train/dog/chihuahua.png

folder/train/cat/maine_coon.png
folder/train/cat/bengal.png
folder/train/cat/birman.png
```

Если набор данных следует структуре `ImageFolder`, то его можно загрузить напрямую с помощью [load_dataset()](/docs/datasets/v5.2.0/ru/package_reference/loading_methods#datasets.load_dataset):

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("path/to/folder")
```

Это эквивалентно ручной передаче `imagefolder` в [load_dataset()](/docs/datasets/v5.2.0/ru/package_reference/loading_methods#datasets.load_dataset) и указанию каталога в `data_dir`:

```py
>>> dataset = load_dataset("imagefolder", data_dir="/path/to/folder")
```

Вы также можете использовать `imagefolder` для загрузки наборов данных, содержащих несколько разбиений. Для этого каталог вашего набора данных должен иметь следующую структуру:

```
folder/train/dog/golden_retriever.png
folder/train/cat/maine_coon.png
folder/test/dog/german_shepherd.png
folder/test/cat/bengal.png
```

> [!WARNING]
> Если все файлы изображений находятся в одной директории или на разных уровнях иерархии каталогов, столбец `label` не будет добавлен автоматически. Если он вам нужен, явно установите `drop_labels=False`.

Если вы хотите добавить дополнительную информацию о вашем наборе данных, например текстовые подписи или ограничивающие прямоугольники, добавьте её в виде файла `metadata.csv` в вашей папке. Это позволяет быстро создавать наборы данных для различных задач компьютерного зрения, таких как генерация текстовых подписей или обнаружение объектов. Вы также можете использовать файл JSONL `metadata.jsonl` или файл Parquet `metadata.parquet`.

```
folder/train/metadata.csv
folder/train/0001.png
folder/train/0002.png
folder/train/0003.png
```

Вы также можете упаковать изображения в архивы zip, при этом каждый архив должен содержать как сами изображения, так и метаданные

```
folder/train.zip
folder/test.zip
folder/validation.zip
```

Файл `metadata.csv` должен содержать поле `file_name` или `*_file_name`, которое связывает файлы изображений с их метаданными:

```csv
file_name,additional_feature
0001.png,This is a first value of a text feature you added to your images
0002.png,This is a second value of a text feature you added to your images
0003.png,This is a third value of a text feature you added to your images
```

или с использованием `metadata.jsonl`:

```jsonl
{"file_name": "0001.png", "additional_feature": "This is a first value of a text feature you added to your images"}
{"file_name": "0002.png", "additional_feature": "This is a second value of a text feature you added to your images"}
{"file_name": "0003.png", "additional_feature": "This is a third value of a text feature you added to your images"}
```

Здесь `file_name` должно содержать имя файла изображения, расположенного рядом с файлом метаданных. Более общо, это должен быть относительный путь от каталога, содержащего метаданные, до файла изображения.

В каждой строке набора данных можно указать несколько изображений, например, если и входные, и выходные данные являются изображениями:

```jsonl
{"input_file_name": "0001.png", "output_file_name": "0001_output.png"}
{"input_file_name": "0002.png", "output_file_name": "0002_output.png"}
{"input_file_name": "0003.png", "output_file_name": "0003_output.png"}
```

Вы также можете определять списки изображений. В этом случае нужно назвать поле `file_names` или `*_file_names`. Вот пример:

```jsonl
{"frames_file_names": ["0001_t0.png", "0001_t1.png"], label: "moving_up"}
{"frames_file_names": ["0002_t0.png", "0002_t1.png"], label: "moving_down"}
{"frames_file_names": ["0003_t0.png", "0003_t1.png"], label: "moving_right"}
```

### Подпись изображений

Наборы данных для описания изображений содержат текст, описывающий изображение. Пример `metadata.csv` может выглядеть так:

```csv
file_name,text
0001.png,This is a golden retriever playing with a ball
0002.png,A german shepherd
0003.png,One chihuahua
```

Загрузите набор данных с помощью `ImageFolder`, и он создаст столбец `text` для подписей к изображениям:

```py
>>> dataset = load_dataset("imagefolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["text"]
"This is a golden retriever playing with a ball"
```

### Обнаружение объектов

Наборы данных для обнаружения объектов содержат ограничивающие прямоугольники и категории, идентифицирующие объекты на изображении. Пример `metadata.jsonl` может выглядеть так:

```jsonl
{"file_name": "0001.png", "objects": {"bbox": [[302.0, 109.0, 73.0, 52.0]], "categories": [0]}}
{"file_name": "0002.png", "objects": {"bbox": [[810.0, 100.0, 57.0, 28.0]], "categories": [1]}}
{"file_name": "0003.png", "objects": {"bbox": [[160.0, 31.0, 248.0, 616.0], [741.0, 68.0, 202.0, 401.0]], "categories": [2, 2]}}
```

Загрузите набор данных с помощью `ImageFolder`, и он создаст столбец `objects` с ограничивающими рамками и категориями:

```py
>>> dataset = load_dataset("imagefolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["objects"]
{"bbox": [[302.0, 109.0, 73.0, 52.0]], "categories": [0]}
```

### Загрузка набора данных в Hub

После создания набора данных вы можете поделиться им на Hub с помощью метода [push_to_hub()](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.DatasetDict.push_to_hub). Убедитесь, что библиотека [huggingface_hub](https://huggingface.co/docs/huggingface_hub/index) установлена, и вы вошли в свой аккаунт Hugging Face (подробнее см. в [руководстве по загрузке с помощью Python](upload_dataset#upload-with-python)).

Загрузите ваш набор данных с помощью [push_to_hub()](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.DatasetDict.push_to_hub):

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("imagefolder", data_dir="/path/to/folder", split="train")
>>> dataset.push_to_hub("stevhliu/my-image-captioning-dataset")
```

## WebDataset

Формат [WebDataset](https://github.com/webdataset/webdataset) основан на архивах TAR и подходит для больших наборов изображений. Вы можете группировать изображения в архивы TAR (например, 1 ГБ изображений на один архив TAR) и иметь тысячи таких архивов:

```
folder/train/00000.tar
folder/train/00001.tar
folder/train/00002.tar
...
```

В архивах каждый пример состоит из файлов, имеющих общий префикс:

```
e39871fd9fd74f55.jpg
e39871fd9fd74f55.json
f18b91585c4d3f3e.jpg
f18b91585c4d3f3e.json
ede6e66b2fb59aab.jpg
ede6e66b2fb59aab.json
ed600d57fcee4f94.jpg
ed600d57fcee4f94.json
...
```

Вы можете хранить метки/подписи/ограничивающие рамки для изображений, например, в файлах JSON или текстовых файлах.

Загрузите ваш WebDataset, и он создаст по одному столбцу для каждого суффикса файла (здесь «jpg» и «json»):

```python
>>> from datasets import load_dataset

>>> dataset = load_dataset("webdataset", data_dir="/path/to/folder", split="train")
>>> dataset[0]["json"]
{"bbox": [[302.0, 109.0, 73.0, 52.0]], "categories": [0]}
```

Также можно использовать несколько изображений на один пример, как показано ниже:

```
e39871fd9fd74f55.input.jpg
e39871fd9fd74f55.output.jpg
e39871fd9fd74f55.json
f18b91585c4d3f3e.input.jpg
f18b91585c4d3f3e.output.jpg
f18b91585c4d3f3e.json
...
```

Для получения подробной информации о формате WebDataset и библиотеке python обратитесь к [документации WebDataset](https://webdataset.github.io/webdataset).

## Lance

[Lance](https://lance.org) — это открытый формат таблиц для мультимодальных lakehouse-хранилищ. Таблицы Lance могут нативно хранить не только текст и скалярные значения, но и крупные двоичные объекты (blobs), такие как изображения, аудио и видео, наряду с табличными данными.

Исходя из файлов изображений на диске и связанных с ними метаданных (например, подписей и размеров), вы можете записать автономный набор данных Lance в локальный каталог `*.lance`. Полученная таблица может хранить ваши столбцы метаданных вместе со столбцом `image`, содержащим закодированные байты изображения.

Например, вы можете начать с метаданных, таких как:

```text
{'caption': 'Cordelia and Dudley on their wedding  day last year', 'height': 315, 'width': 233}
{'caption': 'Statistics on challenges for automation in 2021', 'height': 299, 'width': 701}
```

Вы можете определить схему `pyarrow` для метаданных и байтов изображений, построить таблицу и записать её как датасет Lance:

```python
import lance
import pyarrow as pa

schema = pa.schema(
    [
        pa.field("caption", pa.utf8()),
        pa.field("height", pa.int32()),
        pa.field("width", pa.int32()),
        # ... add any additional metadata columns you want here ...
        pa.field("image", pa.binary()),
    ]
)

# Provide image files alongside metadata
rows = [
    {
        "image_path": "/path/to/images/0001.jpg",
        "caption": "Cordelia and Dudley on their wedding  day last year",
        "height": 315,
        "width": 233,
    },
    {
        "image_path": "/path/to/images/0002.jpg",
        "caption": "Statistics on challenges for automation in 2021",
        "height": 299,
        "width": 701,
    },
]

image_bytes = []
for r in rows:
    with open(r["image_path"], "rb") as f:
        image_bytes.append(f.read())

table = pa.table(
    {
        "caption": [r["caption"] for r in rows],
        "height": [r["height"] for r in rows],
        "width": [r["width"] for r in rows],
        "image": image_bytes,
    },
    schema=schema,
)

ds = lance.write_dataset(
    table,
    "./images.lance",
    schema=schema,
    mode="create",
)
```

Ниже приведён пример того, как может выглядеть таблица Lance, хранящая изображения (колонка `image` содержит закодированные байты):

```text
+-----------------------------------------------+--------+-------+-----+------------------------------+
| caption                                       | height | width | ... | image                        |
+-----------------------------------------------+--------+-------+-----+------------------------------+
| "Cordelia and Dudley on their wedding ..."    | 315    | 233   | ... | b"\\xff\\xd8\\xff...\\xd9"   |
| "Statistics on challenges for automation ..." | 299    | 701   | ... | b"\\xff\\xd8\\xff...\\xd9"   |
+-----------------------------------------------+--------+-------+-----+------------------------------+
```

С помощью этого подхода можно хранить в Lance изображения произвольного размера. Полученный каталог `images.lance/` с файлами `*.lance` можно загрузить на Hugging Face Hub так же, как в других примерах выше. Пример набора изображений в формате Lance — датасет `lance-format/laion-1m` [на Hub](https://huggingface.co/datasets/lance-format/laion-1m).

Для получения подробной информации о работе с наборами данных Lance см. [документацию Lance](https://lance.org).

