Semantic segmentation

Label every pixel. Each sample is one image, one mask image of the same size whose pixel values are class indices, and one CSV row that links the two and names a class present in the image.

Folder layout

/data/shared/tumors/
├── labels.csv
├── images/
│   ├── image_001.jpg
│   ├── image_002.jpg
│   └── ...
└── masks/
    ├── image_001_mask.png
    ├── image_002_mask.png
    └── ...

The folders must be named images and masks and sit side by side, next to the labels CSV.
Masks are PNG files named <image stem>_mask.png. Every image needs a mask and every mask needs an image.
Masks must be readable images with exactly the same width and height as the images. Use single-channel (grayscale) PNGs whose pixel values are class indices 0 to N-1, where N is the number of classes (see image_label below).
Images share one extension (.jpg, .jpeg or .png; default .jpg) and one resolution. Nothing is resized at ingest.

Labels CSV

filename,mask_id,image_label
image_001,image_001_mask,road
image_002,image_002_mask,building
image_003,image_003_mask,person

Column	Required	Meaning
`filename`	yes, exactly this name	The image file, with or without extension.
`mask_id`	yes, exactly this name, lowercase	The mask file name, with or without extension (`image_001_mask` resolves to `masks/image_001_mask.png`). Must be populated on every row and declared in `schema` — training reads this column to find each mask.
`image_label`	yes	A class present in the image. Any column name works — set it with `label:`. At least two distinct values are required across the dataset.

The number of classes, N, is the number of distinct image_label values in the dataset. A model links to the dataset only if its output classes equal N, and training reads mask pixel values 0 to N-1 as those classes. If 0 is background, background is one of the N classes, so background must appear as an image_label value too. Training reads each CSV row as one sample. An image listed on several rows is trained on once per row and can end up in both the training and validation split, so list each image once where you can.

Ingest with the tracebloc CLI

tracebloc data ingest ./tumors-train --task semantic_segmentation --name tumors_train --intent train --label-column image_label

--label-column is required. The CLI stages masks/ and declares mask_id for you. It reads the image size from the first image; pass --target-size WxH to override it.

ingest.yaml

apiVersion: tracebloc.io/v1
kind: IngestConfig
category: semantic_segmentation
table: tumors_train
intent: train
csv: /data/shared/tumors/labels.csv
images: /data/shared/tumors/images/
masks: /data/shared/tumors/masks/
label: image_label
schema:
  mask_id: VARCHAR(255)   # required — the training side reads this column to locate each mask

Field	Required	Meaning
`csv`	yes	Path to the labels CSV.
`images`	yes	The `images/` folder.
`masks`	yes	The `masks/` folder.
`label`	yes	Name of the class column.
`schema`	yes	Must declare `mask_id` (exactly that spelling). Without it the column is not stored and training cannot find the masks.
`target_size`	no	`[width, height]` of every image and every mask. Default `[512, 512]`.
`spec.file_options.extension`	no	Image extension: `.jpg`, `.jpeg` or `.png`. Default `.jpg`. Masks are always checked as `.png`.
`spec.file_options.min_size`	no	Minimum `[width, height]`. Default `[32, 32]`.
`color_mode`, `bit_depth`	no	`RGB` or `grayscale`; `8` or `16`.

What the ingestor checks

Check	Rejects
File type (images)	Files under `images/` with an extension other than the configured one, or mixed extensions.
File type (masks)	Files under `masks/` that are not `.png`.
File pairing	Images without a `<stem>_mask.png`, and masks without a matching image (or not following the `_mask` naming).
Mask id column	A `schema` without `mask_id`; a manifest without a `mask_id` header; any row whose `mask_id` is empty or a null token. A wrong-case variant (`Mask_ID`) is reported with a rename hint.
Image resolution	Images whose size differs from `target_size`, mixed resolutions, images below `min_size`, unreadable files.
Mask resolution	The same rule applied to `masks/`.
Label diversity	Fewer than two distinct label values.

Plus the checks every ingest runs. A record is copied only when both its image and its mask copy succeed.

Size limit

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

Save the images as JPEG instead of PNG (masks stay PNG).
Lower the resolution: resize every image and its mask to one smaller size. Resize masks with nearest-neighbour resampling so their pixel values stay valid class indices.
Use fewer images.

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

Sample dataset

The template ships three 512×512 RGB JPEG images, three matching single-channel PNG masks and a three-row labels CSV (road, building, person). The ingest.yaml above ingests it with no overrides. Use it to try ingestion only: its masks use pixel values 0 to 8, while the CSV names three classes, so it is not a valid training set.

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

Semantic segmentation

Folder layout

Labels CSV

Ingest with the tracebloc CLI

ingest.yaml

What the ingestor checks

Size limit

Sample dataset

Next steps

​Folder layout

​Labels CSV

​Ingest with the tracebloc CLI

​ingest.yaml

​What the ingestor checks

​Size limit

​Sample dataset

​Next steps

Folder layout

Labels CSV

Ingest with the tracebloc CLI

ingest.yaml

What the ingestor checks

Size limit

Sample dataset

Next steps