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.
At least two keypoints must differ in both x and y, so the keypoints span a real bounding box.

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

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.

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

What the ingestor checks

Size limit

Sample dataset

Next steps

​Folder layout

​Labels CSV

​ingest.yaml

​What the ingestor checks

​Size limit

​Sample dataset

​Next steps

Folder layout

Labels CSV

ingest.yaml

What the ingestor checks

Size limit

Sample dataset

Next steps