# Conjunto de Dados de Imagens

Este guia mostrará como configurar seu repositório de dataset com arquivos de imagem. Você pode encontrar exemplos de repositórios acompanhantes nesta [coleção de exemplos de datasets de imagem](https://huggingface.co/collections/datasets-examples/image-dataset-6568e7cf28639db76eb92d65).

Um conjunto de dados com uma estrutura e [formatos de arquivo](./datasets-adding#file-formats) suportados possui automaticamente um Visualizador de Conjunto de Dados em sua página no Hub.

Informações adicionais sobre suas imagens - como legendas ou bounding boxes para detecção de objetos - são carregadas automaticamente, desde que você inclua essas informações em um arquivo de metadados (`metadata.csv`/`metadata.jsonl`/`metadata.parquet`).

Alternativamente, as imagens podem estar em arquivos Parquet ou em arquivos TAR seguindo o formato [WebDataset](https://github.com/webdataset/webdataset).

## Somente imagens

Se o seu conjunto de dados consiste apenas de uma coluna com imagens, você pode simplesmente armazenar seus arquivos de imagens na raiz:

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

ou em um subdiretório:

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

Vários [formatos](./datasets-adding#file-formats) são suportados simultaneamente, incluindo PNG, JPEG, TIFF e WebP.

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

Se você tiver vários splits, pode colocar suas imagens em diretórios nomeados de acordo:

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

Veja [Nomes de arquivos e splits](./datasets-file-names-and-splits) para mais informações e outras formas de organizar dados por splits.

## Colunas adicionais

Se houver informações adicionais que você deseja incluir sobre seu conjunto de dados, como legendas de texto ou caixas delimitadoras, adicione-as como um arquivo `metadata.csv` no seu repositório. Isso permite criar rapidamente conjuntos de dados para diferentes tarefas de visão computacional, como [legendas de texto](https://huggingface.co/tasks/image-to-text) ou [detecção de objetos](https://huggingface.co/tasks/object-detection).

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

O seu arquivo `metadata.csv` deve ter uma coluna `file_name` que vincula os arquivos de imagem aos seus metadados:

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

Você também pode usar um arquivo [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"}
```

E para conjuntos de dados maiores ou se você estiver interessado em recursos avançados de recuperação de dados, pode usar um arquivo [Parquet](https://parquet.apache.org/) `metadata.parquet`.

## Caminhos relativos

O arquivo de metadados deve estar localizado no mesmo diretório das imagens às quais está vinculado ou em qualquer diretório pai, como neste exemplo:

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

Neste caso, a coluna `file_name` deve ser um caminho relativo completo para as imagens, não apenas o nome do arquivo:

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

Arquivos de metadados não podem ser colocados em subdiretórios de um diretório com as imagens.

De forma mais geral, qualquer coluna nomeada `file_name` ou `*_file_name` deve conter o caminho relativo completo para as imagens.

## Classificação de imagens

Para conjuntos de dados de classificação de imagens, você também pode usar uma configuração simples: use diretórios para nomear as classes de imagem. Armazene seus arquivos de imagem em uma estrutura de diretórios como:

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

O dataset criado com essa estrutura contém duas colunas: `image` e `label` (com os valores `green` e `red`).

Você também pode fornecer múltiplos splits. Para isso, o diretório do seu dataset deve ter a seguinte estrutura (veja [Nomes de arquivos e splits](./datasets-file-names-and-splits) para mais informações):

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

Você pode desabilitar essa adição automática da coluna `label` na [configuração YAML](./datasets-manual-configuration). Se os nomes dos seus diretórios não tiverem significado especial, defina `drop_labels: true` no cabeçalho do README:

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

## Conjuntos de dados em larga escala

### Formato WebDataset

O formato [WebDataset](./datasets-webdataset) é adequado para conjuntos de dados de imagens em larga escala (veja, por exemplo, [timm/imagenet-12k-wds](https://huggingface.co/datasets/timm/imagenet-12k-wds)). Ele consiste em arquivos TAR contendo imagens e seus metadados e é otimizado para streaming. É útil quando você possui um grande número de imagens e deseja obter carregadores de dados em streaming para treinamento em larga escala.

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

Para criar um arquivo TAR do WebDataset, crie um diretório contendo as imagens e os arquivos de metadados a serem arquivados e crie o arquivo TAR usando, por exemplo, o comando `tar`. O tamanho usual por arquivo é geralmente em torno de 1GB. Certifique-se de que cada par de imagem e metadados compartilhe o mesmo prefixo de arquivo, por exemplo:

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

Observe que, para a conveniência do usuário e para habilitar o [Dataset Viewer](./data-studio), todo dataset hospedado no Hub é automaticamente convertido para o formato Parquet, até 5GB. Leia mais sobre isso na documentação do [Parquet format](./data-studio#access-the-parquet-files).

### Formato Parquet

Em vez de enviar as imagens e os metadados como arquivos individuais, você pode incorporar tudo dentro de um arquivo [Parquet](https://parquet.apache.org/). Isso é útil se você tiver um grande número de imagens, se quiser incorporar várias colunas de imagens ou se quiser armazenar informações adicionais sobre as imagens no mesmo arquivo. O Parquet também é útil para armazenar dados como bytes brutos, que não são suportados por JSON/CSV.

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

Arquivos Parquet com dados de imagem podem ser criados usando `pandas` ou a biblioteca `datasets`. Para criar arquivos Parquet com dados de imagem no `pandas`, você pode usar [pandas-image-methods](https://github.com/lhoestq/pandas-image-methods) e `df.to_parquet()`. No `datasets`, você pode definir o tipo da coluna como `Image()` e usar o método `ds.to_parquet(...)` ou `ds.push_to_hub(...)`. Você pode encontrar um guia sobre o carregamento de conjuntos de dados de imagem no `datasets` [aqui](/docs/datasets/image_load).

Como alternativa, você pode definir manualmente o tipo de imagem do Parquet criado usando outras ferramentas. Primeiro, verifique se suas colunas de imagem são do tipo _struct_, com um campo binário `"bytes"` para os dados da imagem e um campo de string `"path"` para o nome ou caminho do arquivo de imagem. Em seguida, você deve especificar os tipos de recurso das colunas diretamente no YAML no cabeçalho do README, por exemplo:

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

Observe que o Parquet é recomendado para imagens pequenas (<1MB por imagem) e grupos de linhas pequenos (100 linhas por grupo de linhas, o que é o que o `datasets` usa para imagens). Para imagens maiores, é recomendado usar o formato WebDataset ou compartilhar os arquivos de imagem originais (opcionalmente com arquivos de metadados e seguindo as [recomendações e limites dos repositórios](https://huggingface.co/docs/hub/en/storage-limits) para armazenamento e número de arquivos).