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

# Keypoint detection

> Dataset template for keypoint detection: images plus per-image keypoint JSON in the labels CSV, ingest.yaml and the checks the data ingestor runs.

Locate landmark points, for example body joints. Each sample is one image plus one CSV row that carries the keypoint coordinates, their visibility flags and a class label.

## Folder layout

```text theme={null}
/data/shared/pose/
├── labels.csv
└── images/
    ├── person_001.jpg
    ├── person_002.jpg
    └── ...
```

* The image folder must be named `images` and sit next to the labels CSV.
* All images share one extension (`.jpg`, `.jpeg` or `.png`; default `.jpg`) and one resolution, which you declare in `target_size`. The ingestor copies them unchanged.

## Labels CSV

```csv theme={null}
filename,Annotation,Visibility,image_label
person_001,"{""nose"": [0.50, 0.20], ""left_eye"": [0.46, 0.16], ""right_eye"": [0.54, 0.16], ""left_shoulder"": [0.37, 0.39], ""right_shoulder"": [0.63, 0.39], ""left_elbow"": [0.31, 0.59], ""right_elbow"": [0.68, 0.59], ""left_wrist"": [0.27, 0.76], ""right_wrist"": [0.72, 0.76]}","{""nose"": 1, ""left_eye"": 1, ""right_eye"": 1, ""left_shoulder"": 1, ""right_shoulder"": 1, ""left_elbow"": 1, ""right_elbow"": 1, ""left_wrist"": 1, ""right_wrist"": 1}",person
```

| Column        | Required               | Meaning                                                                                                                                                              |
| ------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename`    | yes, exactly this name | The image file, with or without extension.                                                                                                                           |
| `Annotation`  | yes, exactly this name | A JSON object mapping each keypoint name to `[x, y]` (a `{"x": .., "y": ..}` object is also accepted). Quote the JSON and double the inner quotes, as in the sample. |
| `Visibility`  | yes, exactly this name | A JSON object with the **same keys** as `Annotation`, each `1` (visible) or `0` (occluded or out of frame).                                                          |
| `image_label` | yes                    | The class of the image. Any column name works — set it with `label:`. At least two distinct classes are required.                                                    |

Rules for `Annotation`:

* Every row must name exactly `number_of_keypoints` keypoints, and every row must use the same keypoint names as the first row.
* Coordinates must be numeric and non-negative, with `x < width` and `y < height` of `target_size`.
* At least two keypoints must differ in both x and y, so the keypoints span a real bounding box.

## ingest.yaml

```yaml theme={null}
apiVersion: tracebloc.io/v1
kind: IngestConfig
category: keypoint_detection
table: pose_train
intent: train
csv: /data/shared/pose/labels.csv
images: /data/shared/pose/images/
label: image_label
target_size: [448, 448]     # width, height — must match your images
number_of_keypoints: 9      # 17 for COCO pose; 9 for the shipped sample
```

| Field                         | Required | Meaning                                                                                        |
| ----------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `csv`                         | yes      | Path to the labels CSV.                                                                        |
| `images`                      | yes      | The `images/` folder.                                                                          |
| `label`                       | yes      | Name of the class column.                                                                      |
| `target_size`                 | **yes**  | `[width, height]` of every image. There is no default for this task — your pose model decides. |
| `number_of_keypoints`         | **yes**  | Keypoints per sample. Every row's `Annotation` must have exactly this many entries.            |
| `spec.file_options.extension` | no       | `.jpg`, `.jpeg` or `.png`. Default `.jpg`.                                                     |
| `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           | Files under `images/` with a different extension than configured, or mixed extensions.                                                                                                                                            |
| Image resolution    | Images whose size differs from `target_size`, mixed resolutions, images below `min_size`, unreadable files.                                                                                                                       |
| Keypoint annotation | A missing `Annotation` column; invalid JSON; a row with a keypoint count other than `number_of_keypoints`; keypoint names that differ between rows; non-numeric, negative or out-of-image coordinates; a degenerate bounding box. |
| Keypoint visibility | A missing `Visibility` column; invalid JSON; values other than `0`/`1`; keys that do not match the row's `Annotation` keys.                                                                                                       |
| 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 three 448×448 RGB JPEG images with nine upper-body keypoints each (`nose`, `left_eye`, `right_eye`, `left_shoulder`, `right_shoulder`, `left_elbow`, `right_elbow`, `left_wrist`, `right_wrist`) and three classes. The `ingest.yaml` above ingests it as is.

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