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 data and the test data:

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

--holds open_data marks the dataset as open data. If your data is about patients, pass --holds patient_data; if it was generated, pass --holds synthetic_data. Leave --holds out on a terminal and the CLI asks; in a script, the dataset is marked as patient data. The mark decides which use case types you can create on the dataset. --label-column names the class column in labels.csv. Images sorted into one folder per class, with no labels.csv, ingest too: each image’s label is its folder’s name, the CLI writes labels.csv in the copy, and you leave out --label-column. On a terminal, tracebloc data ingest ./cats-dogs-train works the task out from the folder and asks only what the files can’t say; see Guided ingest. --target-size WxH, with the letter x, for example 256x256, is the size every image has to be; without it, the CLI takes the most common size among your images. 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