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.

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
Shared rules for every template: Dataset templates

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Keypoint detection

Folder layout

Labels CSV

ingest.yaml

What the ingestor checks

Sample dataset

Next steps

​Folder layout

​Labels CSV

​ingest.yaml

​What the ingestor checks

​Sample dataset

​Next steps

Folder layout

Labels CSV

ingest.yaml

What the ingestor checks

Sample dataset

Next steps