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

# Annotation Types

> Detailed reference for each annotation type supported by Avala

This reference documents every annotation type supported by Avala, including their properties and JSON representations.

## Overview

Avala supports the following annotation types:

| Type              | Geometry                      | Use Cases                                    |
| ----------------- | ----------------------------- | -------------------------------------------- |
| Bounding Box      | 2D rectangle                  | Object detection, localization               |
| Polygon           | 2D arbitrary shape            | Instance segmentation, precise outlines      |
| 3D Cuboid         | 3D box                        | Autonomous driving, robotics                 |
| Segmentation Mask | Pixel-level mask              | Semantic segmentation, panoptic segmentation |
| Polyline          | Open line segments            | Lane detection, path annotation              |
| Classification    | No geometry                   | Scene classification, image tagging          |
| Keypoints         | Named points with connections | Pose estimation, facial landmarks            |

All annotation types share a set of [common properties](#common-properties) in addition to their type-specific fields.

## Bounding Box

A 2D axis-aligned rectangular box defined by its top-left corner, width, and height.

### Properties

| Property     | Type     | Description                                  |
| ------------ | -------- | -------------------------------------------- |
| `x`          | `float`  | X coordinate of the top-left corner (pixels) |
| `y`          | `float`  | Y coordinate of the top-left corner (pixels) |
| `width`      | `float`  | Width of the box (pixels)                    |
| `height`     | `float`  | Height of the box (pixels)                   |
| `label`      | `string` | Class label                                  |
| `attributes` | `object` | Optional key-value attributes                |

### JSON Example

```json theme={null}
{
  "uid": "ann_01HSN4X9K2M...",
  "type": "bounding_box",
  "label": "car",
  "x": 120.0,
  "y": 85.5,
  "width": 200.0,
  "height": 150.0,
  "attributes": {
    "occlusion": "partial",
    "truncated": false
  },
  "created_by": "user_01H...",
  "created_at": "2025-09-15T10:30:00Z"
}
```

## Polygon

An arbitrary closed polygon defined by an ordered list of vertices.

### Properties

| Property     | Type     | Description                                        |
| ------------ | -------- | -------------------------------------------------- |
| `vertices`   | `array`  | Ordered list of `[x, y]` coordinate pairs (pixels) |
| `label`      | `string` | Class label                                        |
| `attributes` | `object` | Optional key-value attributes                      |

### JSON Example

```json theme={null}
{
  "uid": "ann_01HSN4X9K2N...",
  "type": "polygon",
  "label": "pedestrian",
  "vertices": [
    [305.0, 120.0],
    [320.0, 115.0],
    [340.0, 130.0],
    [345.0, 200.0],
    [330.0, 210.0],
    [310.0, 205.0],
    [300.0, 150.0]
  ],
  "attributes": {
    "pose": "walking"
  },
  "created_by": "user_01H...",
  "created_at": "2025-09-15T10:32:00Z"
}
```

## 3D Cuboid

A 3D bounding box defined by its center position, dimensions (length, width, height), and rotation.

### Properties

| Property     | Type     | Description                                    |
| ------------ | -------- | ---------------------------------------------- |
| `center`     | `object` | Center position with `x`, `y`, `z` (meters)    |
| `dimensions` | `object` | Size with `length`, `width`, `height` (meters) |
| `rotation`   | `object` | Rotation with `yaw`, `pitch`, `roll` (radians) |
| `label`      | `string` | Class label                                    |
| `attributes` | `object` | Optional key-value attributes                  |

### JSON Example

```json theme={null}
{
  "uid": "ann_01HSN4X9K2P...",
  "type": "cuboid_3d",
  "label": "vehicle",
  "center": {
    "x": 12.5,
    "y": -3.2,
    "z": 0.8
  },
  "dimensions": {
    "length": 4.5,
    "width": 1.8,
    "height": 1.6
  },
  "rotation": {
    "yaw": 1.57,
    "pitch": 0.0,
    "roll": 0.0
  },
  "attributes": {
    "num_lidar_points": 342,
    "occlusion": "none",
    "activity": "moving"
  },
  "created_by": "user_01H...",
  "created_at": "2025-09-15T10:35:00Z"
}
```

<Info>
  3D cuboid coordinates use the sensor frame of the point cloud. The `yaw` value represents rotation around the Z-axis (vertical), which corresponds to the object's heading direction.
</Info>

## Segmentation Mask

A pixel-level mask that labels every pixel within a region. Masks are stored in run-length encoding (RLE) for efficiency.

### Properties

| Property      | Type      | Description                                     |
| ------------- | --------- | ----------------------------------------------- |
| `mask`        | `object`  | RLE-encoded mask with `counts` and `size`       |
| `label`       | `string`  | Class label                                     |
| `instance_id` | `integer` | Instance identifier (for instance segmentation) |
| `attributes`  | `object`  | Optional key-value attributes                   |

### JSON Example

```json theme={null}
{
  "uid": "ann_01HSN4X9K2Q...",
  "type": "segmentation",
  "label": "road",
  "mask": {
    "counts": [10, 5, 20, 8, 15, 3, 40],
    "size": [1080, 1920]
  },
  "instance_id": 1,
  "attributes": {
    "surface": "asphalt"
  },
  "created_by": "user_01H...",
  "created_at": "2025-09-15T10:38:00Z"
}
```

### Mask Format

The `mask` field uses COCO-style run-length encoding:

* `counts`: Alternating runs of background and foreground pixel counts
* `size`: `[height, width]` of the image

## Polyline

An open line defined by an ordered sequence of points. Unlike polygons, polylines are not closed.

### Properties

| Property     | Type     | Description                                        |
| ------------ | -------- | -------------------------------------------------- |
| `points`     | `array`  | Ordered list of `[x, y]` coordinate pairs (pixels) |
| `label`      | `string` | Class label                                        |
| `attributes` | `object` | Optional key-value attributes                      |

### JSON Example

```json theme={null}
{
  "uid": "ann_01HSN4X9K2R...",
  "type": "polyline",
  "label": "lane_marking",
  "points": [
    [400.0, 600.0],
    [420.0, 500.0],
    [450.0, 400.0],
    [490.0, 300.0],
    [540.0, 200.0]
  ],
  "attributes": {
    "line_type": "dashed",
    "color": "white"
  },
  "created_by": "user_01H...",
  "created_at": "2025-09-15T10:40:00Z"
}
```

## Classification

An image-level or frame-level label with no spatial geometry. Used for categorizing entire images or frames.

### Properties

| Property     | Type     | Description                                                          |
| ------------ | -------- | -------------------------------------------------------------------- |
| `label`      | `string` | Classification label                                                 |
| `confidence` | `float`  | Confidence score (0.0 to 1.0), typically set by auto-labeling models |
| `attributes` | `object` | Optional key-value attributes                                        |

### JSON Example

```json theme={null}
{
  "uid": "ann_01HSN4X9K2S...",
  "type": "classification",
  "label": "highway",
  "confidence": 0.95,
  "attributes": {
    "weather": "clear",
    "time_of_day": "daytime"
  },
  "created_by": "user_01H...",
  "created_at": "2025-09-15T10:42:00Z"
}
```

## Keypoints

A set of named points with connections between them, typically used for pose estimation and skeleton annotation.

### Properties

| Property      | Type     | Description                                                            |
| ------------- | -------- | ---------------------------------------------------------------------- |
| `keypoints`   | `array`  | List of keypoint objects, each with `name`, `x`, `y`, and `visibility` |
| `connections` | `array`  | List of `[name_a, name_b]` pairs defining skeleton edges               |
| `label`       | `string` | Class label                                                            |
| `attributes`  | `object` | Optional key-value attributes                                          |

### Keypoint Visibility Values

| Value | Meaning                                             |
| ----- | --------------------------------------------------- |
| `0`   | Not present (not in frame or not applicable)        |
| `1`   | Occluded (estimated position, not directly visible) |
| `2`   | Visible                                             |

### JSON Example

```json theme={null}
{
  "uid": "ann_01HSN4X9K2T...",
  "type": "keypoints",
  "label": "person",
  "keypoints": [
    { "name": "nose", "x": 250.0, "y": 100.0, "visibility": 2 },
    { "name": "left_eye", "x": 245.0, "y": 95.0, "visibility": 2 },
    { "name": "right_eye", "x": 255.0, "y": 95.0, "visibility": 2 },
    { "name": "left_shoulder", "x": 230.0, "y": 140.0, "visibility": 2 },
    { "name": "right_shoulder", "x": 270.0, "y": 140.0, "visibility": 2 },
    { "name": "left_elbow", "x": 215.0, "y": 180.0, "visibility": 2 },
    { "name": "right_elbow", "x": 285.0, "y": 180.0, "visibility": 1 },
    { "name": "left_wrist", "x": 200.0, "y": 210.0, "visibility": 2 },
    { "name": "right_wrist", "x": 295.0, "y": 215.0, "visibility": 0 }
  ],
  "connections": [
    ["left_shoulder", "right_shoulder"],
    ["left_shoulder", "left_elbow"],
    ["left_elbow", "left_wrist"],
    ["right_shoulder", "right_elbow"],
    ["right_elbow", "right_wrist"]
  ],
  "attributes": {
    "action": "standing"
  },
  "created_by": "user_01H...",
  "created_at": "2025-09-15T10:45:00Z"
}
```

## Common Properties

Every annotation in Avala includes these shared properties regardless of type.

| Property      | Type      | Description                                                                    |
| ------------- | --------- | ------------------------------------------------------------------------------ |
| `uid`         | `string`  | Unique annotation identifier                                                   |
| `type`        | `string`  | Annotation type (e.g., `bounding_box`, `polygon`, `cuboid_3d`)                 |
| `label`       | `string`  | Class label from the project taxonomy                                          |
| `attributes`  | `object`  | Optional key-value pairs for additional metadata (e.g., occlusion, truncation) |
| `tracking_id` | `string`  | Object tracking identifier for video/sequence annotations (same across frames) |
| `frame_index` | `integer` | Frame number within the sequence (for temporal data)                           |
| `created_by`  | `string`  | User ID of the annotator who created the annotation                            |
| `created_at`  | `string`  | ISO 8601 timestamp of creation                                                 |
| `updated_by`  | `string`  | User ID of the last person to modify the annotation                            |
| `updated_at`  | `string`  | ISO 8601 timestamp of the last modification                                    |

<Info>
  The `tracking_id` field is only present for annotations in video or multi-frame sequence data. It links the same object across frames for consistent tracking.
</Info>

## Next Steps

* Learn how to use these tools in the [Annotation Tools](/docs/annotation/guides/annotation-tools) guide
* See [Supported Formats](/docs/annotation/reference/supported-formats) for input data formats
* Explore [Keyboard Shortcuts](/docs/annotation/reference/keyboard-shortcuts) for efficient annotation