# Conjunto de datos de imágenes

Esta guía te mostrará cómo configurar tu repositorio de datos con archivos de imagen. Puedes encontrar ejemplos de repositorios en esta [colección de ejemplos de conjuntos de datos de imágenes](https://huggingface.co/collections/datasets-examples/image-dataset-6568e7cf28639db76eb92d65).

Un conjunto de datos con una estructura y [formatos de archivo](./datasets-adding#file-formats) admitidos tiene automáticamente un visor de conjuntos de datos en su página en el Hub.

La información adicional sobre tus imágenes, como descripciones o recuadros delimitadores para la detección de objetos, se carga automáticamente siempre que incluyas esta información en un archivo de metadatos (`metadata.csv`/`metadata.jsonl`/`metadata.parquet`).

Alternativamente, las imágenes pueden estar en archivos Parquet o en archivos TAR que sigan el formato [WebDataset](https://github.com/webdataset/webdataset).

## Solo imágenes

Si su conjunto de datos consta únicamente de una columna con imágenes, puede simplemente almacenar sus archivos de imagen en la raíz:

```
my_dataset_repository/
├── 1.jpg
├── 2.jpg
├── 3.jpg
└── 4.jpg
```

o en un subdirectorio:

```
my_dataset_repository/
└── images
    ├── 1.jpg
    ├── 2.jpg
    ├── 3.jpg
    └── 4.jpg
```

Se admiten varios [formatos](./datasets-adding#file-formats) a la vez, incluidos PNG, JPEG, TIFF y WebP.

```
my_dataset_repository/
└── images
    ├── 1.jpg
    ├── 2.png
    ├── 3.tiff
    └── 4.webp
```

Si tienes varias divisiones, puedes colocar tus imágenes en directorios con los nombres correspondientes:

```
my_dataset_repository/
├── train
│   ├── 1.jpg
│   └── 2.jpg
└── test
    ├── 3.jpg
    └── 4.jpg
```

Consulte [Nombres de archivo y divisiones](./datasets-file-names-and-splits) para obtener más información y otras formas de organizar los datos por divisiones.

## Columnas adicionales

Si hay información adicional que desees incluir sobre tu conjunto de datos, como descripciones de texto o cajas delimitadoras, añádela como un archivo `metadata.csv` en tu repositorio. Esto te permite crear rápidamente conjuntos de datos para diferentes tareas de visión por computadora, como [descripción de texto](https://huggingface.co/tasks/image-to-text) o [detección de objetos](https://huggingface.co/tasks/object-detection).

```
my_dataset_repository/
└── train
    ├── 1.jpg
    ├── 2.jpg
    ├── 3.jpg
    ├── 4.jpg
    └── metadata.csv
```

El archivo `metadata.csv` debe tener una columna `file_name` que vincule los archivos de imagen con sus metadatos:

```csv
file_name,text
1.jpg,a drawing of a green pokemon with red eyes
2.jpg,a green and yellow toy with a red nose
3.jpg,a red and white ball with an angry look on its face
4.jpg,a cartoon ball with a smile on its face
```

También puedes usar un archivo [JSONL](https://jsonlines.org/) `metadata.jsonl`:

```jsonl
{"file_name": "1.jpg","text": "a drawing of a green pokemon with red eyes"}
{"file_name": "2.jpg","text": "a green and yellow toy with a red nose"}
{"file_name": "3.jpg","text": "a red and white ball with an angry look on its face"}
{"file_name": "4.jpg","text": "a cartoon ball with a smile on its face"}
```

Y para conjuntos de datos más grandes o si te interesan las funciones avanzadas de recuperación de datos, puedes usar un archivo [Parquet](https://parquet.apache.org/) `metadata.parquet`.

## Rutas relativas

El archivo de metadatos debe estar ubicado en el mismo directorio que las imágenes a las que está vinculado, o en cualquier directorio padre, como en este ejemplo:

```
my_dataset_repository/
└── train
    ├── images
    │   ├── 1.jpg
    │   ├── 2.jpg
    │   ├── 3.jpg
    │   └── 4.jpg
    └── metadata.csv
```

En este caso, la columna `file_name` debe ser una ruta relativa completa a las imágenes, no solo el nombre del archivo:

```csv
file_name,text
images/1.jpg,a drawing of a green pokemon with red eyes
images/2.jpg,a green and yellow toy with a red nose
images/3.jpg,a red and white ball with an angry look on its face
images/4.jpg,a cartoon ball with a smile on it's face
```

Los archivos de metadatos no se pueden colocar en subdirectorios de un directorio con las imágenes.

Más en general, cualquier columna llamada `file_name` o `*_file_name` debe contener la ruta relativa completa a las imágenes.

## Clasificación de imágenes

Para conjuntos de datos de clasificación de imágenes, también puedes usar una configuración sencilla: usa directorios para nombrar las clases de imágenes. Guarda tus archivos de imágenes en una estructura de directorios como:

```
my_dataset_repository/
├── green
│   ├── 1.jpg
│   └── 2.jpg
└── red
    ├── 3.jpg
    └── 4.jpg
```

El conjunto de datos creado con esta estructura contiene dos columnas: `image` y `label` (con los valores `green` y `red`).

También puedes proporcionar varias divisiones. Para ello, el directorio de tu conjunto de datos debe tener la siguiente estructura (consulta [Nombres de archivo y divisiones](./datasets-file-names-and-splits) para obtener más información):

```
my_dataset_repository/
├── test
│   ├── green
│   │   └── 2.jpg
│   └── red
│       └── 4.jpg
└── train
    ├── green
    │   └── 1.jpg
    └── red
        └── 3.jpg
```

Puede desactivar esta adición automática de la columna `label` en la [configuración YAML](./datasets-manual-configuration). Si los nombres de sus directorios no tienen un significado especial, establezca `drop_labels: true` en la cabecera del README:

```yaml
configs:
  - config_name: default  # Name of the dataset subset, if applicable.
    drop_labels: true
```

## Conjuntos de datos a gran escala

### Formato WebDataset

El formato [WebDataset](./datasets-webdataset) es adecuado para conjuntos de datos de imágenes a gran escala (por ejemplo, [timm/imagenet-12k-wds](https://huggingface.co/datasets/timm/imagenet-12k-wds)). Está compuesto por archivos TAR que contienen imágenes y sus metadatos, y está optimizado para el procesamiento en streaming. Es útil si se dispone de un gran número de imágenes y se desean cargadores de datos en streaming para el entrenamiento a gran escala.

```
my_dataset_repository/
├── train-0000.tar
├── train-0001.tar
├── ...
└── train-1023.tar
```

Para crear un archivo TAR de WebDataset, cree un directorio que contenga las imágenes y los archivos de metadatos que se van a archivar y cree el archivo TAR usando, por ejemplo, el comando `tar`. El tamaño habitual por archivo suele ser de aproximadamente 1 GB. Asegúrese de que cada par de imagen y metadatos comparta el mismo prefijo de archivo, por ejemplo:

```
train-0000/
├── 000.jpg
├── 000.json
├── 001.jpg
├── 001.json
├── ...
├── 999.jpg
└── 999.json
```

Tenga en cuenta que, por comodidad del usuario y para habilitar el [Dataset Viewer](./data-studio), cada conjunto de datos alojado en el Hub se convierte automáticamente al formato Parquet hasta 5GB. Lea más al respecto en la documentación del [Parquet format](./data-studio#access-the-parquet-files).

### Formato Parquet

En lugar de subir las imágenes y los metadatos como archivos individuales, puede incrustar todo dentro de un archivo [Parquet](https://parquet.apache.org/). Esto es útil si tiene un gran número de imágenes, si desea incrustar varias columnas de imágenes o si quiere almacenar información adicional sobre las imágenes en el mismo archivo. Parquet también es útil para almacenar datos como bytes crudos, que no son compatibles con JSON/CSV.

```
my_dataset_repository/
└── train.parquet
```

Los archivos Parquet con datos de imagen se pueden crear con `pandas` o la biblioteca `datasets`. Para crear archivos Parquet con datos de imagen en `pandas`, puede usar [pandas-image-methods](https://github.com/lhoestq/pandas-image-methods) y `df.to_parquet()`. En `datasets`, puede establecer el tipo de columna como `Image()` y usar el método `ds.to_parquet(...)` o `ds.push_to_hub(...)`. Puede encontrar una guía para cargar conjuntos de datos de imagen en `datasets` [aquí](/docs/datasets/image_load).

Alternativamente, puede establecer manualmente el tipo de imagen de Parquet creado con otras herramientas. Primero, asegúrese de que sus columnas de imagen sean de tipo _struct_, con un campo binario `"bytes"` para los datos de la imagen y un campo de cadena `"path"` para el nombre o la ruta del archivo de imagen. Luego, debe especificar los tipos de características de las columnas directamente en YAML en la cabecera del README, por ejemplo:

```yaml
dataset_info:
  features:
  - name: image
    dtype: image
  - name: caption
    dtype: string
```

Tenga en cuenta que Parquet se recomienda para imágenes pequeñas (<1MB por imagen) y grupos de filas pequeños (100 filas por grupo de filas, que es lo que usa `datasets` para imágenes). Para imágenes más grandes, se recomienda usar el formato WebDataset o compartir los archivos de imagen originales (opcionalmente con archivos de metadatos y siguiendo las [recomendaciones y límites de los repositorios](https://huggingface.co/docs/hub/en/storage-limits) para el almacenamiento y el número de archivos).

