# 이미지 데이터 로드

Image 데이터셋에는 PIL 객체를 포함하는 [Image](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Image) 타입의 컬럼이 있습니다.

> [!TIP]
> 이미지 데이터셋을 다루려면 `vision` 의존성이 설치되어 있어야 합니다. 설치 방법은 [설치](./installation#vision) 가이드를 참고하세요.

이미지 데이터셋을 로드하고 이미지 컬럼을 호출하면 이미지는 PIL Image로 디코딩됩니다:

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

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

> [!WARNING]
> `dataset[0]["image"]`와 같이 행 인덱스를 먼저 사용하고 `image` 열을 인덱싱하여 이미지 데이터셋에 접근하세요. 이렇게 하면 데이터셋의 모든 이미지 객체를 디코딩하고 리샘플링하는 것을 피할 수 있습니다. 그렇지 않으면 데이터셋이 크면 느리고 시간이 많이 걸리는 과정이 될 수 있습니다.

모든 유형의 데이터를 로드하는 방법에 대한 가이드는 일반적인 로드 가이드를 참고하세요.

## 로컬 파일

이미지 경로에서 데이터셋을 로드할 수 있습니다. [cast_column()](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Dataset.cast_column) 함수를 사용하여 이미지 파일 경로 컬럼을 받아 [Image](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Image) feature로 PIL 이미지로 디코딩합니다:
```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>]
```

이미지 객체를 디코딩하지 않고 이미지 데이터셋의 기본 경로만 로드하려면 [Image](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Image) 기능에서 `decode=False`를 설정하세요:

```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` 데이터셋 빌더를 사용하여 커스텀 dataloader를 작성하지 않고도 데이터셋을 로드할 수 있습니다. 이를 통해 `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/ko/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")
```

로컬 데이터셋의 경우, 이는 [load_dataset()](/docs/datasets/v5.2.0/ko/package_reference/loading_methods#datasets.load_dataset)에서 `imagefolder`를 수동으로 전달하고 `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}
```

메타데이터 파일의 정보를 무시하려면 [load_dataset()](/docs/datasets/v5.2.0/ko/package_reference/loading_methods#datasets.load_dataset)에서 `drop_metadata=True`를 설정하세요:

```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 아카이브 폴더를 기반으로 하며, 대규모 이미지 데이터셋에 적합합니다. 크기가 크기 때문에 WebDataset은 일반적으로 스트리밍 모드( `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)는 오픈 멀티모달 레이크하우스 테이블 형식입니다. 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] `datasets` API는 현재 Lance 테이블로 연산을 push down하지 않으므로, 대규모 데이터셋의 경우 느릴 수 있습니다. 당분간 `lance` Python 패키지를 직접 사용하는 것이 훨씬 나은 성능을 제공합니다. 사용 예제는 [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/ko/package_reference/main_classes#datasets.IterableDataset.decode)는 현재 스트리밍 데이터셋에서만 사용할 수 있습니다.