Guide

Keypoint annotation for a team: one custom skeleton, several labelers, and review

How to keep keypoints consistent when more than one person labels them: define your own skeleton once on the label, have every labeler click the points in the same order, review file by file, and export COCO keypoints.

Contents

  1. Where keypoint labels go wrong
  2. One skeleton, written once
  3. Every labeler clicks the same points in the same order
  4. Agree on hidden points
  5. Review file by file
  6. Export COCO keypoints
  7. What it costs for a team
  8. Try it on a real skeleton first
Contents

Where keypoint labels go wrong

One careful person labeling keypoints is consistent with themselves. The trouble starts with the second person. They click the wrists in the other order. They read "left" as the left of the picture, not the subject's left. They leave out the elbow behind the body, where the first person guessed it. Each choice is reasonable, and a model trained on the mix learns the disagreement.

A written style guide helps, and people still drift from it on the three-hundredth image. What holds is a tool that leaves the labeler fewer choices to make. This page walks through that setup in DataTorch for a skeleton of your own: defined once, followed by everyone, checked by a second person.

A skier labeled with a 17-point person skeleton and a box in the DataTorch annotator, points joined by bones
The annotator with one skeleton placed: named points in a fixed order, joined by the label's edges. This is the COCO person skeleton, on a file of the hosted COCO person keypoints project

One skeleton, written once

In DataTorch the skeleton belongs to the label. It is a small piece of JSON in the label's Metadata with two keys: keypoints, the point names in the order they will be clicked, and skeleton, the pairs of points to join, counted from 1.

Here is a skeleton for a dog with 11 points:

{
  "keypoints": [
    "nose", "left_eye", "right_eye",
    "left_ear", "right_ear",
    "withers", "tail_base",
    "front_left_paw", "front_right_paw",
    "back_left_paw", "back_right_paw"
  ],
  "skeleton": [
    [1,2], [1,3], [2,4], [3,5], [1,6],
    [6,7], [6,8], [6,9], [7,10], [7,11]
  ]
}

The Update Label dialog for a label named dog, with the keypoints and skeleton JSON in its Metadata field
A custom skeleton on a label: 11 point names and the 10 pairs that join them

To set it up, open Labels in the sidebar, create the label, then edit it and paste the JSON into Metadata. The keypoint tutorial has every click.

Two things to settle as a team before anyone labels:

  • The order. Saved annotations store their points in the label's order. Adding a name in the middle later shifts every point after it, in every file already labeled. Add the points you might want now.
  • Whose left. left_eye is the subject's left, which is on your right when the subject faces the camera. Put it in the names and say it once out loud.

The skeleton is one definition for the whole project. Every labeler gets it, and when it changes, it changes for everyone at once.

Every labeler clicks the same points in the same order

With the label chosen and the Keypoints tool selected, the annotator shows the name of the next point above the cursor. Click the landmark and the name moves on. The bones draw themselves as soon as both ends exist. Nobody has to remember the order, and nobody can choose a different one.

Every point has to be placed, there is no skip. That takes away the quietest disagreement, the labeler who leaves a point out. For a point outside the picture, Shift and click at the border.

Agree on hidden points

A plain click stores a visible point (COCO visibility 2). Shift and click stores a point that is hidden but can be estimated (visibility 1), drawn as a hollow circle. The tool keeps the difference all the way to the export.

It cannot decide for you when a point counts as hidden. Write that one rule down for the team: behind another object, behind the subject's own body, cut off by the frame. It is the one judgment the tool leaves to people, so it is the one to check in review.

Review file by file

A second person checks the work one file at a time. Within a task each file carries its own status: pending, skipped, completed or reviewed. For keypoints the fastest check is the Move tool: hover a point and it grows and shows its name, which makes a swapped left and right easy to see. Drag a point to fix one joint.

Two limits worth knowing before you plan the review. Visibility is set when a point is placed, so fixing a wrong hidden flag means deleting that skeleton and placing it again. And deleting works on the whole skeleton, not on one point.

When the files are checked, someone with the sign-off permission signs off the dataset as a version. That locks the whole dataset as it stands, with no label edits or uploads until it is unlocked, and the unlock is recorded too. The version you train on is then a named thing, not "the export from Tuesday".

Export COCO keypoints

Go to Exports, create a schema with the COCO format, run it and download the JSON. The label's point names and skeleton are written on the category, and each annotation carries its points as x, y and visibility.

Before training, know two things about the file. It does not write num_keypoints. And an annotation that is only keypoints has an empty bbox. If your trainer needs a box, draw the box first, keep it selected, then place the keypoints.

If part of the data is already labeled elsewhere, upload the images, then use Import annotations on the dataset with a COCO keypoint file. Images are matched by file name.

What it costs for a team

The Team plan is priced per builder: the people who create projects and edit label schemas. It is $15 a builder a month billed annually, or $19 month to month. Reviewers and annotators are free, and private projects can have any number of collaborators. The pricing page puts it this way: people who only complete assigned work do not need a paid seat.

The Free plan has unlimited public projects and one private project with one dataset, which is enough to try the skeleton on your own images.

Try it on a real skeleton first

The hosted COCO person set has 17-point skeletons you can open in the browser and inspect before you write your own.

Dataset: datatorch/coco-person-keypoints-val2017, 607 files

COCO Person Keypoints (val2017, open licenses)

Person keypoint subset of COCO 2017 val with openly licensed images only: 605 images whose Flickr license is CC BY 2.0 (413), CC BY-SA 2.0 (189) or No known copyright restrictions (3), with 1,609 people annotated with the 17 COCO keypoints (nose, eyes, ears, shoulders, elbows, wrists, hips, knees, ankles), COCO visibility flags and bounding boxes. Every image is credited with its Flickr URL and license in its file metadata and in annotations/credits.csv. License: annotations CC BY 4.0 (COCO Consortium); each image keeps its Flickr owner's license. Source: https://cocodataset.org Please cite: Lin, T.-Y. et al., Microsoft COCO: Common Objects in Context. ECCV 2014.

Open →

Label keypoints with your team

Write your skeleton once on the label, add your images, and have everyone click the same points in the same order.

Frequently asked questions

Can I define my own keypoint skeleton, not the COCO 17?

Yes. A skeleton is a list of point names and a list of pairs that connect them, written on the label. Any object works, an animal, a hand, a machine part. There is no ready-made COCO 17 preset, so the person skeleton is pasted in the same way.

How do several annotators keep the same keypoint order?

The order is part of the label, not of each person's habit. The annotator shows the name of the next point above the cursor and moves to the next name after each click, and every point has to be placed.

How are occluded keypoints labeled?

A plain click stores a visible point, COCO visibility 2. Shift and click stores a point that is hidden but whose position can be estimated, visibility 1. Agree as a team when to use it, because the tool records the choice and cannot make it.

What does it cost for a team?

On the Team plan a builder, the person who sets up projects and label schemas, is $15 a month billed annually or $19 month to month. Reviewers and annotators are free. The Free plan has unlimited public projects and one private project with one dataset.

Get the data

Open the hosted copy on DataTorch.

Browse the files in your browser, then download the dataset with a free account.

Open the datasetStart free

Related

Tools and community for image annotation: label, review, and share datasets, from everyday photos to the imagery only specialists can read.

Platform

PlatformImaging labsExplore datasetsEnterprisePricing

© 2026 DataTorch. All rights reserved.