> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracebloc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Image classification

> Dataset template for image classification: folder layout, labels CSV, ingest.yaml and the checks the data ingestor runs.

Sort images into classes. Each sample is one image file plus one row in a labels CSV that names the file and its class.

## Folder layout

```text theme={null}
/data/shared/cats-dogs/
├── labels.csv
└── images/
    ├── cat1.jpeg
    ├── cat2.jpeg
    ├── dog1.jpeg
    └── ...
```

* The image folder must be named `images` and sit next to the labels CSV.
* Every image in the dataset must have the **same extension** and the **same width and height**. Mixed extensions or mixed resolutions fail the ingest.
* Supported extensions: `.jpg`, `.jpeg`, `.png`. The default is `.jpeg`; override it with `spec.file_options.extension`.
* The ingestor copies images as they are. It does not resize them — bring them to the target size before you ingest.

## Labels CSV

```csv theme={null}
filename,label
cat1.jpeg,cat
cat2.jpeg,cat
dog1.jpeg,dog
dog2.jpeg,dog
```

| Column     | Required               | Meaning                                                                                                           |
| ---------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `filename` | yes, exactly this name | The image file, with or without extension (`cat1` resolves to `images/cat1.jpeg` under the default extension).    |
| `label`    | yes                    | The class of the image. Any column name works — set it with `label:`. At least two distinct classes are required. |

Extra columns are ignored unless you declare them in `schema`.

## ingest.yaml

```yaml theme={null}
apiVersion: tracebloc.io/v1
kind: IngestConfig
category: image_classification
table: cats_dogs_train
intent: train
csv: /data/shared/cats-dogs/labels.csv
images: /data/shared/cats-dogs/images/
label: label
```

| Field                         | Required | Meaning                                                                                           |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `csv`                         | yes      | Path to the labels CSV inside the ingestor.                                                       |
| `images`                      | yes      | The `images/` folder. Its parent becomes the dataset root.                                        |
| `label`                       | yes      | Name of the class column in the CSV.                                                              |
| `target_size`                 | no       | `[width, height]` every image must have. Default `[256, 256]`.                                    |
| `spec.file_options.extension` | no       | `.jpg`, `.jpeg` or `.png`. Default `.jpeg`.                                                       |
| `spec.file_options.min_size`  | no       | Absolute minimum `[width, height]`; images with a smaller side are rejected. Default `[32, 32]`.  |
| `color_mode`, `bit_depth`     | no       | Declare `RGB` or `grayscale` and `8` or `16` so combined datasets can be checked for consistency. |

To use images of another size, set `target_size` (or `spec.file_options.target_size`) to their exact dimensions:

```yaml theme={null}
target_size: [512, 512]
spec:
  file_options:
    extension: .png
```

## What the ingestor checks

| Check            | Rejects                                                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| File type        | Any file under `images/` whose extension is not the configured one, or a mix of extensions.                                                                                     |
| Image resolution | Any image whose `(width, height)` differs from `target_size`, more than one resolution in the folder, images with a side below `min_size`, and unreadable or empty image files. |
| Label column     | A CSV whose header has no column matching `label:`.                                                                                                                             |
| Label diversity  | Fewer than two distinct label values.                                                                                                                                           |

Plus the [checks every ingest runs](/create-use-case/templates#checks-every-ingest-runs).

## Sample dataset

The template ships six 256×256 RGB JPEG images (three cats, three dogs) and a labels CSV with the two classes `cat` and `dog`. The `ingest.yaml` above ingests it with no overrides.

## Next steps

* Stage the data and run the ingest: [Prepare Data](/create-use-case/prepare-dataset)
* Shared rules for every template: [Dataset templates](/create-use-case/templates)