Hugging Face's logo

Datasets documentation

画像データを読み込む

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v4.8.4).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

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"]

行インデックスを先に使用し、次にimage列にインデックスを指定して画像データセットにアクセスします - dataset[0]["image"] - 。これにより、データセット内のすべての画像オブジェクトのデコードとリサンプリングを回避できます。そうしないと、データセットが大きい場合、この処理は低速で時間がかかる可能性があります。

あらゆる種類のデータセットを読み込む方法については、一般的な読み込みガイドを参照してください。

ローカルファイル

画像パスからデータセットを読み込むことができます。cast_column()関数を使用して、画像ファイルのパスの列を受け取り、Image機能で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

カスタムdataloaderの作成を必要としない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()で直接読み込むことができます:

>>> from datasets import load_dataset

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

ローカルデータセットの場合、これはdata_dirにディレクトリを指定してimagefolderを手動で渡すload_dataset()に相当します:

>>> 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テーブルは、テキストやスカラー値だけでなく、画像、音声、動画などの大きなバイナリオブジェクト（blob）も、タブラーデータと並んでネイティブに保存できます。

Lanceはメタデータとイメージのブロブを1つの場所にまとめて保持しつつ、イメージのバイトを読み込まずに、必要なメタデータのカラムのみを効率的にスキャンできるようにします。準備が整ったら、行の小さなサブセット（イメージのブロブを含む）を取得し、ローカルファイルシステム上のファイルに直接書き出すことができます。

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 テーブルへ操作をプッシュダウンしないため、大規模なデータセットでは遅くなる場合があります。 当面は、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

←オーディオデータセットを作成する 画像データを処理する→