# Загрузка данных изображений

Наборы данных изображений имеют столбцы типа [Image](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.Image), содержащие объекты PIL.

> [!TIP]
> Для работы с наборами данных изображений необходимо установить зависимость `vision`. Ознакомьтесь с руководством по [установке](./installation#vision), чтобы узнать, как это сделать.

При загрузке набора данных изображений и обращении к столбцу с изображениями они декодируются как PIL Images:

```py
>>> from datasets import load_dataset, Image

>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train")
>>> dataset[0]["image"]
```

> [!WARNING]
> Обращайтесь к набору данных изображений сначала по индексу строки, а затем по столбцу `image` — `dataset[0]["image"]` — чтобы избежать декодирования и ресемплинга всех объектов изображений в наборе данных. В противном случае, если набор данных большой, этот процесс может быть медленным и требовать много времени.

Справочник по загрузке любого типа набора данных см. в общем руководстве по загрузке.

## Локальные файлы

Вы можете загрузить набор данных из пути к изображению. Используйте функцию [cast_column()](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.Dataset.cast_column), чтобы принять столбец с путями к файлам изображений и декодировать его в изображение PIL с помощью фичи [Image](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.Image):
```py
>>> from datasets import Dataset, Image

>>> dataset = Dataset.from_dict({"image": ["path/to/image_1", "path/to/image_2", ..., "path/to/image_n"]}).cast_column("image", Image())
>>> dataset[0]["image"]
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=1200x215 at 0x15E6D7160>]
```

Если вам нужно загрузить только базовый путь к набору данных изображений без декодирования объекта изображения, установите `decode=False` в признаке [Image](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.Image):

```py
>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train").cast_column("image", Image(decode=False))
>>> dataset[0]["image"]
{'bytes': None,
 'path': '/root/.cache/huggingface/datasets/downloads/extracted/b0a21163f78769a2cf11f58dfc767fb458fc7cea5c05dccc0144a2c0f0bc1292/train/bean_rust/bean_rust_train.29.jpg'}
```

## ImageFolder

Также можно загрузить набор данных с помощью конструктора `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
```

В качестве альтернативы у него должны быть метаданные, например:

```
folder/train/metadata.csv
folder/train/0001.png
folder/train/0002.png
folder/train/0003.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("username/dataset_name")
>>> # OR locally:
>>> 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")
```

Затем вы можете обращаться к видео как к объектам `PIL.Image`:

```
>>> dataset["train"][0]
{"image": <PIL.PngImagePlugin.PngImageFile image mode=RGBA size=1200x215 at 0x15E6D7160>, "label": 0}

>>> dataset["train"][-1]
{"image": <PIL.PngImagePlugin.PngImageFile image mode=RGBA size=1200x215 at 0x15E8DAD30>, "label": 1}
```

Чтобы игнорировать информацию в файле метаданных, установите `drop_metadata=True` в [load_dataset()](/docs/datasets/v5.2.0/ru/package_reference/loading_methods#datasets.load_dataset):

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_with_metadata", drop_metadata=True)
```

Если у вас нет файла метаданных, `ImageFolder` автоматически определяет имя метки по имени каталога. Если вы хотите отбросить автоматически созданные метки, установите `drop_labels=True`. В этом случае ваш набор данных будет содержать только столбец с изображениями:

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_without_metadata", drop_labels=True)
```

Наконец, аргумент `filters` позволяет загрузить только часть набора данных на основе условия, наложенного на метку или метаданные. Это особенно полезно, если метаданные хранятся в формате Parquet, поскольку этот формат обеспечивает быструю фильтрацию. Также рекомендуется использовать этот аргумент вместе с `streaming=True`, так как по умолчанию набор данных полностью загружается до применения фильтрации.

```python
>>> filters = [("label", "=", 0)]
>>> dataset = load_dataset("username/dataset_name", streaming=True, filters=filters)
```

> [!TIP]
> Для получения дополнительной информации о создании собственного набора данных `ImageFolder` ознакомьтесь с руководством [Создание набора данных изображений](./image_dataset).

## WebDataset

Формат [WebDataset](https://github.com/webdataset/webdataset) основан на папке с TAR-архивами и подходит для больших наборов изображений. Из-за их размера WebDatasets, как правило, загружаются в режиме потоковой обработки (с использованием `streaming=True`).

Вы можете загрузить WebDataset следующим образом:

```python
>>> from datasets import load_dataset

>>> dataset = load_dataset("webdataset", data_dir="/path/to/folder", streaming=True)
```

## Lance

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

Lance хранит метаданные и блоки изображений вместе в одном месте, при этом позволяя эффективно просматривать только нужные вам столбцы метаданных без загрузки байтов изображений. Когда вы будете готовы, вы сможете получить небольшой подмножество строк (включая блоки изображений) и записать их напрямую в файлы на локальной файловой системе.

```python
from datasets import load_dataset

# Return as a Hugging Face dataset
ds = load_dataset(
    "lance-format/laion-1m",
    split="train",
    streaming=True
)

dir_name = "laion_samples"
Path(dir_name).mkdir(exist_ok=True)

for idx, row in enumerate(ds.take(3)):
    with open(f"{dir_name}/{idx}.jpg", "wb") as f:
        f.write(row["image"])
```

В этом примере столбец `image` содержит закодированные байты изображения, поэтому их можно записать напрямую в файлы `.jpg`.

> [!NOTE] API `datasets` в настоящее время не переносит операции на таблицу Lance, поэтому для больших наборов данных это может быть медленно. Пока что вы получите гораздо лучшую производительность, используя пакет Python `lance` напрямую. Примеры использования см. в документации на [Hub](https://huggingface.co/docs/datasets-lance).

## Декодирование изображений

По умолчанию при итерации по набору данных изображения декодируются последовательно в `PIL.Images`. Однако с помощью многопоточного декодирования можно значительно ускорить работу с набором данных:

```python
>>> import os
>>> num_threads = num_threads = min(32, (os.cpu_count() or 1) + 4)
>>> dataset = dataset.decode(num_threads=num_threads)
>>> for example in dataset:  # up to 20 times faster !
...     ...
```

Вы можете включить многопоточность с помощью `num_threads`. Это особенно полезно для ускорения потоковой передачи удалённых данных. Однако для локальных данных на быстрых дисках это может работать медленнее, чем при `num_threads=0`.

Если вам не нужны изображения, декодированные в `PIL.Images`, и вы хотите получить доступ к пути/байтам, вы можете отключить декодирование:

```python
>>> dataset = dataset.decode(False)
```

Примечание: [IterableDataset.decode()](/docs/datasets/v5.2.0/ru/package_reference/main_classes#datasets.IterableDataset.decode) в настоящее время доступен только для потоковых наборов данных.

