Charger les données d’image

Les jeux de données d'images possèdent des colonnes de type Image, qui contiennent des objets PIL.

Pour travailler avec des jeux de données d'images, vous devez avoir installé la dépendance vision. Consultez le guide d'installation pour savoir comment l'installer.

Lorsque vous chargez un jeu de données d'images et que vous appelez la colonne d'images, les images sont décodées en images PIL :

>>> from datasets import load_dataset, Image

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

Accédez à un jeu de données d’images en utilisant d’abord l’index de la ligne, puis la colonne image - dataset[0]["image"] - afin d’éviter de décoder et de rééchantillonner tous les objets image du jeu de données. Sinon, cela peut être un processus lent et chronophage si vous disposez d’un jeu de données volumineux.

Pour un guide sur la façon de charger n'importe quel type de jeu de données, consultez le guide de chargement général.

Fichiers locaux

Vous pouvez charger un jeu de données à partir du chemin d'accès à l'image. Utilisez la fonction cast_column() pour accepter une colonne de chemins d'accès aux fichiers d'image, et décodez-la en image PIL avec la fonctionnalité Image :

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

Si vous souhaitez uniquement charger le chemin sous-jacent du jeu de données d’images sans décoder l’objet image, définissez decode=False dans la fonctionnalité Image :

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

Vous pouvez également charger un jeu de données avec le constructeur de jeu de données ImageFolder, qui ne nécessite pas d'écrire un chargeur de données personnalisé. Cela rend ImageFolder idéal pour créer et charger rapidement des jeux de données d'images contenant plusieurs milliers d'images pour différentes tâches de vision. La structure de votre jeu de données d'images doit ressembler à ceci :

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

Sinon, il devrait contenir des métadonnées, par exemple :

folder/train/metadata.csv
folder/train/0001.png
folder/train/0002.png
folder/train/0003.png

Si le jeu de données suit la structure ImageFolder, vous pouvez le charger directement avec load_dataset() :

>>> from datasets import load_dataset

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

Pour les jeux de données locaux, cela équivaut à passer manuellement imagefolder dans load_dataset() et le répertoire dans data_dir :

>>> dataset = load_dataset("imagefolder", data_dir="/path/to/folder")

Vous pouvez ensuite accéder aux vidéos en tant qu'objets 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}

Pour ignorer les informations du fichier de métadonnées, définissez drop_metadata=True dans load_dataset() :

>>> from datasets import load_dataset

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

Si vous n’avez pas de fichier de métadonnées, ImageFolder infère automatiquement le nom de l’étiquette à partir du nom du répertoire. Si vous souhaitez supprimer les étiquettes créées automatiquement, définissez drop_labels=True. Dans ce cas, votre jeu de données ne contiendra qu’une colonne d’images :

>>> from datasets import load_dataset

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

Enfin, l'argument filters permet de charger uniquement un sous-ensemble du jeu de données, en fonction d'une condition sur l'étiquette ou les métadonnées. C'est particulièrement utile si les métadonnées sont au format Parquet, car ce format permet un filtrage rapide. Il est également recommandé d'utiliser cet argument avec streaming=True, car par défaut le jeu de données est entièrement téléchargé avant le filtrage.

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

Pour plus d'informations sur la création de votre propre jeu de données ImageFolder, consultez le guide Créer un jeu de données d'images.

WebDataset

Le format WebDataset est basé sur un dossier d’archives TAR et convient aux grands jeux de données d’images. En raison de leur taille, les WebDatasets sont généralement chargés en mode streaming (en utilisant streaming=True).

Vous pouvez charger un WebDataset de cette manière :

>>> from datasets import load_dataset

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

Lance

Lance est un format de table de lakehouse multimodal ouvert. Les tables Lance peuvent stocker nativement non seulement du texte et des valeurs scalaires, mais aussi de grands objets binaires (blobs) tels que des images, de l’audio et de la vidéo, aux côtés de vos données tabulaires.

Lance conserve vos métadonnées et vos blobs d’images ensemble dans un même endroit, tout en vous permettant de scanner efficacement uniquement les colonnes de métadonnées qui vous intéressent sans charger les octets des images. Lorsque vous êtes prêt, vous pouvez récupérer un petit sous-ensemble de lignes (y compris les blobs d’images) et les écrire directement dans des fichiers sur votre système de fichiers local.

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

Dans cet exemple, la colonne image contient les octets de l'image encodés, vous pouvez donc les écrire directement dans des fichiers .jpg.

L’API datasets ne pousse actuellement pas les opérations vers la table Lance, ce qui peut être lent pour les grands jeux de données. Pour l’instant, vous obtiendrez de bien meilleures performances en utilisant directement le package Python lance. Consultez la documentation sur the Hub pour des exemples d’utilisation.

Décodage d'image

Par défaut, les images sont décodées séquentiellement en PIL.Images lors de l'itération sur un jeu de données. Il est toutefois possible d'accélérer considérablement le jeu de données en utilisant un décodage multithreadé :

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

Vous pouvez activer le multithreading à l'aide de num_threads. Cela est particulièrement utile pour accélérer le streaming de données distantes. Cependant, cela peut être plus lent que num_threads=0 pour des données locales sur des disques rapides.

Si vous n’êtes pas intéressé par les images décodées en PIL.Images et souhaitez accéder au chemin/aux octets à la place, vous pouvez désactiver le décodage :

>>> dataset = dataset.decode(False)

Remarque : IterableDataset.decode() n'est actuellement disponible que pour les jeux de données en flux.