Datasets documentation

画像データセットを作成する

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

and get access to the augmented documentation experience

to get started

画像データセットを作成する

画像データセットを作成して共有するには、2つの方法があります。このガイドでは、次の方法について説明します。

  • Create an image dataset from local files in python with Dataset.push_to_hub(). This is an easy way that requires only a few steps in python.

  • ImageFolderと一部のメタデータを使用して画像データセットを作成します。これは、数千枚の画像からなる画像データセットを素早く作成するためのノーコードソリューションです。

ユーザーが連絡先情報を共有することを条件に、データセットへのアクセスを制御できます。この機能をHubで有効にする方法の詳細については、Gated datasetsガイドを参照してください。

ImageFolder

ImageFolderは、コードを書かずに数千枚の画像を含む画像データセットを素早く読み込むために設計されたデータセットビルダーです。

💡 ImageFolderがデータセットリポジトリの構造に基づいてどのようにデータセットの分割を作成するかを詳しく知るには、Split pattern hierarchyをご覧ください。

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()で直接読み込むことができます:

>>> from datasets import load_dataset

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

これは、load_dataset() で imagefolder を手動で渡し、data_dir にディレクトリを指定することと同等です:

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

すべての画像ファイルが単一のディレクトリに格納されている場合、または同じディレクトリ階層にない場合、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形式で圧縮することもできます。この場合、各zipファイルには画像とメタデータの両方が含まれている必要があります。

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

metadata.csvファイルには、画像ファイルとそのメタデータを関連付けるfile_nameまたは*_file_nameフィールドが必要です。

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を使用します:

{"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はメタデータファイルの隣にある画像ファイルの名前である必要があります。より一般的には、メタデータを含むディレクトリからの画像ファイルへの相対パスである必要があります。

データセットの各行で複数の画像を指定できます。例えば、入力と出力の両方が画像である場合などです。

{"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にする必要があります。例を以下に示します。

{"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の例は次のようになります。

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列が作成されます:

>>> 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の例は次のようになります。

{"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列が作成されます:

>>> 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にデータセットをアップロード

データセットを作成した後、push_to_hub() メソッドを使用して Hub に共有できます。huggingface_hub ライブラリがインストールされていること、および Hugging Face アカウントにログインしていることを確認してください(詳細は Python によるアップロードチュートリアル を参照してください)。

push_to_hub()でデータセットをアップロードします:

>>> 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形式はTARアーカイブをベースとしており、大規模な画像データセットに適しています。 実際、画像をTARアーカイブにグループ化(例:1つのTARアーカイブあたり1GBの画像)し、数千個の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を読み込むと、ファイルの拡張子ごとに1列ずつ作成されます(ここではjpgとjson):

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

1つのサンプルに複数の画像を割り当てることも可能です。

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

WebDataset形式とPythonライブラリに関する詳細については、WebDatasetのドキュメントを参照してください。

Lance

Lanceは、オープンなマルチモーダルなレイクハウス用テーブル形式です。Lanceテーブルは、テキストやスカラー値だけでなく、画像、音声、動画などの大きなバイナリオブジェクト(blob)も、タブラーデータと並んでネイティブに保存できます。

ディスク上の画像ファイルと関連するメタデータ(キャプションや寸法など)を起点として、ローカルの*.lanceディレクトリに自己完結型のLanceデータセットを書き込むことができます。生成されるテーブルには、エンコードされた画像バイト列を含むimageカラムのほかに、メタデータのカラムを格納できます。

例えば、次のようなメタデータから始めることができます。

{'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データセットとして書き出すことができます。

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 列にはエンコードされたバイト列が含まれます):

+-----------------------------------------------+--------+-------+-----+------------------------------+
| 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上のデータセットを参照してください。

Lanceデータセットの取り扱いに関する詳細については、Lanceのドキュメントを参照してください。

Update on GitHub