Image classification

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

Ingest with the CLI

Lay out each split as shown in Folder layout, then ingest the training set and the test set:

tracebloc data ingest ./cats-dogs-train --task image_classification --name cats_dogs_train --intent train --label-column label
tracebloc data ingest ./cats-dogs-test  --task image_classification --name cats_dogs_test  --intent test  --label-column label

--label-column names the class column in labels.csv; on a terminal, the CLI asks for it if you leave it out. In a guided run, the CLI also asks for the image resolution: press Enter to read it from your images, or type it as WxH with the letter x, for example 256x256. Every image is checked against it. Pass --target-size WxH to set it without the question. To read an image’s size on macOS, run sips -g pixelWidth -g pixelHeight <file> or use the file’s Get Info; see Image resolution. The [256, 256] default in the ingest.yaml table below applies only to Helm ingests.

Folder layout

/data/shared/cats-dogs/
├── labels.csv
└── images/
    ├── cat1.jpeg
    ├── cat2.jpeg
    ├── dog1.jpeg
    └── ...

With the CLI, the dataset folder is on your machine (./cats-dogs-train). With Helm, it sits on the shared volume (/data/shared/...).
The image folder must be named images and sit next to the labels CSV, which the CLI expects to be named 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 CLI reads the extension from your files; with Helm, 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

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

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:

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.

Size limit

One tracebloc data ingest takes at most 1 GiB in total and 500 MiB per file. If your dataset is larger:

Save the images as JPEG instead of PNG.
Lower the resolution: resize every image to one smaller size.
Use fewer images.

For datasets that stay above the limit, see Size limit.

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

Ingest the data: Prepare Data
Shared rules for every template: Dataset templates

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Image classification

Ingest with the CLI

Folder layout

Labels CSV

ingest.yaml

What the ingestor checks

Size limit

Sample dataset

Next steps

​Ingest with the CLI

​Folder layout

​Labels CSV

​ingest.yaml

​What the ingestor checks

​Size limit

​Sample dataset

​Next steps

Ingest with the CLI

Folder layout

Labels CSV

ingest.yaml

What the ingestor checks

Size limit

Sample dataset

Next steps