# Muat data gambar

Dataset gambar memiliki kolom bertipe [Image](/docs/datasets/main/id/package_reference/main_classes#datasets.Image), yang berisi objek PIL.

> [!TIP]
> Untuk bekerja dengan dataset gambar, Anda perlu menginstal dependensi `vision`. Lihat panduan [instalasi](./installation#vision) untuk mempelajari cara menginstalnya.

Saat Anda memuat dataset gambar dan memanggil kolom gambar, gambar-gambar tersebut didekode sebagai Gambar PIL:

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

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

> [!WARNING]
> Gunakan indeks baris terlebih dahulu, lalu kolom `image` - `dataset[0]["image"]` - untuk mengakses dataset gambar, guna menghindari dekoding dan resampling semua objek gambar dalam dataset. Jika tidak, proses ini dapat menjadi lambat dan memakan waktu jika Anda memiliki dataset yang besar.

Untuk panduan tentang cara memuat jenis dataset apa pun, lihat panduan pemuatan umum.

## File lokal

Anda dapat memuat dataset dari jalur gambar. Gunakan fungsi [cast_column()](/docs/datasets/main/id/package_reference/main_classes#datasets.Dataset.cast_column) untuk menerima kolom jalur file gambar, dan mendekodekannya menjadi gambar PIL dengan fitur [Image](/docs/datasets/main/id/package_reference/main_classes#datasets.Image):
```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>]
```

Jika Anda hanya ingin memuat jalur dasar ke dataset gambar tanpa mendekode objek gambar, atur `decode=False` pada fitur [Image](/docs/datasets/main/id/package_reference/main_classes#datasets.Image):

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

Anda juga dapat memuat dataset dengan builder dataset `ImageFolder` yang tidak memerlukan penulisan dataloader kustom. Hal ini menjadikan `ImageFolder` ideal untuk dengan cepat membuat dan memuat dataset gambar dengan beberapa ribu gambar untuk berbagai tugas visi. Struktur dataset gambar Anda harus seperti ini:

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

Sebagai alternatif, seharusnya memiliki metadata, misalnya:

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

Jika dataset mengikuti struktur `ImageFolder`, maka Anda dapat memuatnya langsung dengan [load_dataset()](/docs/datasets/main/id/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")
```

Untuk dataset lokal, ini setara dengan meneruskan `imagefolder` secara manual di [load_dataset()](/docs/datasets/main/id/package_reference/loading_methods#datasets.load_dataset) dan direktori di `data_dir`:

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

Lalu Anda dapat mengakses video sebagai objek `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}
```

Untuk mengabaikan informasi dalam file metadata, atur `drop_metadata=True` di [load_dataset()](/docs/datasets/main/id/package_reference/loading_methods#datasets.load_dataset):

```py
>>> from datasets import load_dataset

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

Jika Anda tidak memiliki file metadata, `ImageFolder` secara otomatis menyimpulkan nama label dari nama direktori. Jika Anda ingin menghapus label yang dibuat secara otomatis, atur `drop_labels=True`. Dalam kasus ini, dataset Anda hanya akan berisi kolom gambar:

```py
>>> from datasets import load_dataset

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

Terakhir, argumen `filters` memungkinkan Anda memuat hanya sebagian dari dataset, berdasarkan kondisi pada label atau metadata. Ini sangat berguna jika metadata dalam format Parquet, karena format ini memungkinkan filtering yang cepat. Disarankan juga untuk menggunakan argumen ini dengan `streaming=True`, karena secara default dataset diunduh sepenuhnya sebelum filtering dilakukan.

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

> [!TIP]
> Untuk informasi lebih lanjut tentang cara membuat dataset `ImageFolder` Anda sendiri, lihat panduan [Membuat dataset gambar](./image_dataset).

## WebDataset

Format [WebDataset](https://github.com/webdataset/webdataset) didasarkan pada folder arsip TAR dan cocok untuk dataset gambar besar. Karena ukurannya, WebDataset umumnya dimuat dalam mode streaming (menggunakan `streaming=True`).

Anda dapat memuat WebDataset seperti ini:

```python
>>> from datasets import load_dataset

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

## Lance

[Lance](https://lance.org) adalah format tabel lakehouse multimodal terbuka. Tabel Lance dapat menyimpan secara native tidak hanya teks dan nilai skalar, tetapi juga objek biner besar (blobs) seperti gambar, audio, dan video berdampingan dengan data tabular Anda.

Lance menyimpan metadata dan blob gambar Anda bersama di satu tempat, sambil tetap memungkinkan Anda memindai secara efisien hanya kolom metadata yang Anda butuhkan tanpa memuat byte gambar. Ketika Anda siap, Anda dapat mengambil subset kecil baris (termasuk blob gambar) dan menuliskannya langsung ke file pada sistem file lokal Anda.

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

Pada contoh ini, kolom `image` berisi byte gambar yang telah dikodekan, sehingga Anda dapat menuliskannya langsung ke file `.jpg`.

> [!NOTE] API `datasets` saat ini tidak mendorong operasi ke tabel Lance, sehingga untuk dataset yang lebih besar, prosesnya mungkin lambat. Untuk saat ini, Anda akan mendapatkan performa yang jauh lebih baik dengan menggunakan paket Python `lance` secara langsung. Lihat dokumentasi di [the Hub](https://huggingface.co/docs/datasets-lance) untuk contoh penggunaan.

## Dekoding gambar

Secara default, gambar didekode secara berurutan sebagai `PIL.Images` saat Anda mengiterasi dataset. Namun, dataset dapat dipercepat secara signifikan menggunakan dekoding multithreaded:

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

Anda dapat mengaktifkan multithreading menggunakan `num_threads`. Hal ini sangat berguna untuk mempercepat streaming data jarak jauh. Namun, hal ini bisa lebih lambat daripada `num_threads=0` untuk data lokal pada disk yang cepat.

Jika Anda tidak tertarik pada gambar yang didekode sebagai `PIL.Images` dan ingin mengakses path/bytes-nya, Anda dapat menonaktifkan dekoding:

```python
>>> dataset = dataset.decode(False)
```

Catatan: [IterableDataset.decode()](/docs/datasets/main/id/package_reference/main_classes#datasets.IterableDataset.decode) saat ini hanya tersedia untuk dataset streaming.

