> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Keypoint Tool

> Annotate object pose with keypoints and skeleton connections for pose estimation

The Keypoint tool annotates object pose with keypoints and skeleton connections. It is used for pose estimation tasks such as human body pose, hand pose, and face landmarks.

## When to Use

Use keypoints when:

* The task requires pose estimation (human, animal, or custom skeletons)
* You need to annotate body landmarks (joints, facial features, hand points)
* The downstream model expects keypoint annotations (e.g., OpenPose, HRNet, MediaPipe)
* You need to track articulated objects across video frames

Consider a different tool when:

* You need object localization without pose -- use the [Bounding Box](/docs/annotation/guides/tools/bounding-box) tool
* You need pixel-level masks -- use the [Segmentation](/docs/annotation/guides/tools/segmentation) tool
* You need to outline an object shape -- use the [Polygon](/docs/annotation/guides/tools/polygon) tool

## Usage

1. Press `J` or select the **Keypoint tool** from the toolbar
2. A skeleton template appears based on your project's keypoint definition
3. Click to place the first keypoint
4. Place subsequent keypoints following the skeleton structure
5. The viewer draws connections between keypoints automatically based on the skeleton definition
6. Assign a label

## Skeleton Definitions

Skeleton definitions are configured at the project level. A skeleton specifies:

* **Keypoint names**: e.g., nose, left\_eye, right\_eye, left\_shoulder
* **Connections**: which keypoints are connected by edges
* **Visibility**: each keypoint can be marked as visible, occluded, or not present

Example skeleton for human pose:

```json theme={null}
{
  "keypoints": [
    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
    "left_wrist", "right_wrist", "left_hip", "right_hip",
    "left_knee", "right_knee", "left_ankle", "right_ankle"
  ],
  "connections": [
    ["left_shoulder", "right_shoulder"],
    ["left_shoulder", "left_elbow"],
    ["left_elbow", "left_wrist"],
    ["right_shoulder", "right_elbow"],
    ["right_elbow", "right_wrist"],
    ["left_hip", "right_hip"],
    ["left_hip", "left_knee"],
    ["left_knee", "left_ankle"],
    ["right_hip", "right_knee"],
    ["right_knee", "right_ankle"],
    ["left_shoulder", "left_hip"],
    ["right_shoulder", "right_hip"]
  ]
}
```

## Editing Keypoints

* **Move a keypoint**: Click and drag it
* **Set visibility**: Right-click a keypoint to toggle between visible, occluded, and not present
* **Move entire skeleton**: Select all keypoints and drag

## Shortcuts

| Shortcut               | Action                     |
| ---------------------- | -------------------------- |
| `J`                    | Activate the Keypoint tool |
| `Delete` / `Backspace` | Delete selected skeleton   |
| `Ctrl+Z` / `⌘Z`        | Undo                       |
| `Ctrl+Shift+Z` / `⌘⇧Z` | Redo                       |

## Visibility States

Each keypoint has one of three visibility states:

| State           | Meaning                                                 | When to use                                          |
| --------------- | ------------------------------------------------------- | ---------------------------------------------------- |
| **Visible**     | The keypoint is clearly visible in the image            | Default for most keypoints                           |
| **Occluded**    | The keypoint exists but is hidden behind another object | You can estimate its location from context           |
| **Not present** | The keypoint is not in the image at all                 | The body part is outside the frame or does not exist |

## Common Mistakes

* **Guessing occluded locations**: Mark keypoints as "not present" rather than guessing their location if they are fully hidden with no contextual clues
* **Wrong skeleton assignment**: Make sure the keypoint you are placing matches the correct body part in the skeleton definition
* **Inconsistent occluded vs. not present**: Use occluded when you can reasonably estimate the location (e.g., hand behind back), not present when you cannot
* **Placing on clothing instead of body**: Keypoints should be placed on the anatomical joint location, not on the surface of clothing

## Advanced Tips

* Place the most visible keypoints first, then fill in occluded ones
* Use zoom for precise placement on small or distant subjects
* Keypoints can be tracked across video frames for pose tracking workflows
* For crowd scenes, place each person's skeleton separately, even when they overlap
* Use the camera projection in multi-camera setups to verify 3D keypoint positions

## Related Tools

* [Bounding Box](/docs/annotation/guides/tools/bounding-box) -- For object detection without pose
* [Polygon](/docs/annotation/guides/tools/polygon) -- For precise object outlines
* [Segmentation](/docs/annotation/guides/tools/segmentation) -- For pixel-level masks
* [Classification](/docs/annotation/guides/tools/classification) -- For image-level labels