Keypoint detection

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

/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

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.
Use pixel coordinates or 0–1 fractions of the image size, as in the sample. Training detects fractions and converts them to pixels for every keypoint model. Use one unit for the whole dataset: if any coordinate is above 1, training reads every coordinate as pixels.
At least two keypoints must differ in both x and y, so the keypoints span a real bounding box.

Ingest with the tracebloc CLI

tracebloc data ingest ./pose-train --task keypoint_detection --name pose_train --intent train --number-of-keypoints 9 --label-column image_label

--number-of-keypoints is required and has no default. --label-column names the class column; the CLI asks for it at a terminal, but a run with --no-input or in CI fails without it. The CLI reads target_size from the first image; pass --target-size WxH to override it.

ingest.yaml

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 in `ingest.yaml` for this task. The CLI detects it from the first image.
`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.

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, and scale the keypoint coordinates to match.
Use fewer images.

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

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. Its coordinates are 0–1 fractions. Training converts them to pixels, so you do not need to convert them yourself.

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

Keypoint detection

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