> ## 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.

# Semantic segmentation

> Dataset template for semantic segmentation: images plus PNG masks linked by mask_id, ingest.yaml and the checks the data ingestor runs.

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

```text theme={null}
/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. The template's masks are single-channel (grayscale) PNGs where pixel value `0` is background and `1`, `2`, ... are classes.
* Images share one extension (`.jpg`, `.jpeg` or `.png`; default `.jpg`) and one resolution. Nothing is resized at ingest.

## Labels CSV

```csv theme={null}
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.                                                                        |

An image may appear on several rows, one per class it contains.

## ingest.yaml

```yaml theme={null}
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](/create-use-case/templates#checks-every-ingest-runs). A record is copied only when both its image and its mask copy succeed.

## 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.

## 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)