Datasets documentation

이미지 데이터 로드

Datasets

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

이미지 데이터 로드

Image 데이터셋에는 PIL 객체를 포함하는 Image 타입의 컬럼이 있습니다.

이미지 데이터셋을 다루려면 vision 의존성이 설치되어 있어야 합니다. 설치 방법은 설치 가이드를 참고하세요.

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

>>> from datasets import load_dataset, Image

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

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

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

로컬 파일

이미지 경로에서 데이터셋을 로드할 수 있습니다. cast_column() 함수를 사용하여 이미지 파일 경로 컬럼을 받아 Image feature로 PIL 이미지로 디코딩합니다:

>>> 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 기능에서 decode=False를 설정하세요:

>>> 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()를 사용하여 직접 로드할 수 있습니다:

>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_name")
>>> # OR locally:
>>> dataset = load_dataset("/path/to/folder")

로컬 데이터셋의 경우, 이는 load_dataset()에서 imagefolder를 수동으로 전달하고 data_dir에 해당 디렉터리를 지정하는 것과 동일합니다:

>>> 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()에서 drop_metadata=True를 설정하세요:

>>> from datasets import load_dataset

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

메타데이터 파일이 없는 경우, ImageFolder는 디렉터리 이름에서 라벨 이름을 자동으로 추론합니다. 자동 생성된 라벨을 제거하려면 drop_labels=True를 설정하세요. 이 경우 데이터셋에는 이미지 컬럼만 포함됩니다:

>>> from datasets import load_dataset

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

마지막으로 filters 인수를 사용하면 라벨 또는 메타데이터에 대한 조건을 기반으로 데이터셋의 부분 집합만 로드할 수 있습니다. 이는 메타데이터가 Parquet 형식으로 저장된 경우 특히 유용하며, 이 형식은 빠른 필터링을 지원하기 때문입니다. 기본적으로 필터링 전에 데이터셋이 완전히 다운로드되므로, 이 인수를 사용할 때 streaming=True를 함께 사용하는 것이 권장됩니다.

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

ImageFolder 데이터셋을 직접 만드는 방법에 대한 자세한 내용은 이미지 데이터셋 만들기 가이드를 참고하세요.

WebDataset

WebDataset 형식은 TAR 아카이브 폴더를 기반으로 하며, 대규모 이미지 데이터셋에 적합합니다. 크기가 크기 때문에 WebDataset은 일반적으로 스트리밍 모드( streaming=True 사용)로 로드됩니다.

WebDataset를 다음과 같이 로드할 수 있습니다:

>>> from datasets import load_dataset

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

Lance

Lance는 오픈 멀티모달 레이크하우스 테이블 형식입니다. Lance 테이블은 텍스트와 스칼라 값뿐만 아니라 이미지, 오디오, 비디오와 같은 대형 바이너리 객체(blobs)도 테이블 데이터와 함께 네이티브로 저장할 수 있습니다.

Lance는 메타데이터와 이미지 블롭을 한 위치에 함께 유지하면서, 이미지 바이트를 로드하지 않고도 관심 있는 메타데이터 컬럼만 효율적으로 스캔할 수 있도록 합니다. 준비가 되면, 이미지 블롭을 포함한 소수의 행을 가져와 로컬 파일 시스템의 파일에 직접 쓸 수 있습니다.

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 파일에 직접 쓸 수 있습니다.

datasets API는 현재 Lance 테이블로 연산을 push down하지 않으므로, 대규모 데이터셋의 경우 느릴 수 있습니다. 현재로서는 lance Python 패키지를 직접 사용하는 것이 훨씬 나은 성능을 제공합니다. 사용 예제는 Hub의 문서를 참고하세요.

이미지 디코딩

기본적으로 데이터셋을 반복할 때 이미지는 PIL.Images로 순차적으로 디코딩됩니다. 하지만 멀티스레드 디코딩을 사용하면 데이터셋의 속도를 크게 높일 수 있습니다:

>>> 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로 디코딩된 이미지에 관심이 없고 대신 경로/바이트에 액세스하려면 디코딩을 비활성화할 수 있습니다:

>>> dataset = dataset.decode(False)

참고: IterableDataset.decode()는 현재 스트리밍 데이터셋에서만 사용할 수 있습니다.

Update on GitHub

←오디오 데이터셋 만들기 이미지 데이터 처리→