# Geometric (Box, Polygon, Line, Keypoints, Cuboid) Annotations

In this guide, we'll use the Python SDK to construct geometric annotations. Each geometric
annotation object in Nucleus has five components:

* **Label** of the annotation in the class taxonomy, e.g. car or pedestrian
* **Geometry** to define the position, size, etc. of the box / polygon / line / cuboid
* **Reference ID** of the item to which to apply the annotation
* **Annotation ID**, an optional unique (per dataset item) key to refer to the annotation
* **Metadata**, optional key-value pairs pertaining to the annotation, e.g. vehicle\_color = blue

All geometric annotation types (box, polygon, line, cuboid) share the same structure aside from the geometry. Below, we'll explore how to construct the annotation objects, including geometries, for each type:

* [`BoxAnnotations`](https://nucleus.scale.com/docs/geometric-annotations#boxannotation)
* [`PolygonAnnotations`](https://nucleus.scale.com/docs/geometric-annotations#polygonannotation)
* [`LineAnnotations`](https://nucleus.scale.com/docs/geometric-annotations#lineannotation)
* [`KeypointsAnnotations`](https://nucleus.scale.com/docs/geometric-annotations#keypointsannotation)
* [`CuboidAnnotations`](https://nucleus.scale.com/docs/geometric-annotations#cuboidannotation)

## `BoxAnnotation`

A 2D bounding box based on a given XY position, width, and height.

For more info, see our Python SDK Reference for [`BoxAnnotations`](https://docs.nucleus.scale.com/en/latest/api/nucleus/index.html#nucleus.BoxAnnotation).

[block:code]
{
  "codes": [
    {
      "code": "from nucleus import BoxAnnotation\n\nbox_gt = BoxAnnotation(\n    label=\"car\",\n    x=4,        # px between left edge of the box and left border of the image\n    y=6,        # px between top edge of the box and top border of the image\n    width=12,   # width in px\n    height=18,  # height in px\n    reference_id=\"image_1\",\n    annotation_id=\"image_1_car_box_1\",\n    metadata={\"vehicle_color\": \"ruby\"}\n)",
      "language": "python"
    }
  ]
}
[/block]

## `PolygonAnnotation`

A 2D polygon constructed by connecting 3+ vertices.

For more info, see our Python SDK Reference for [`PolygonAnnotations`](https://docs.nucleus.scale.com/en/latest/api/nucleus/index.html#nucleus.PolygonAnnotation).

[block:code]
{
  "codes": [
    {
      "code": "from nucleus import Point, PolygonAnnotation\n\npolygon_gt = PolygonAnnotation(\n    label=\"bus\",\n    vertices=[\t# list of vertices as Point objects\n        Point(x=100, y=100),\n        Point(150, 200),\n        Point(200, 100),\n    ],\n    reference_id=\"image_2\",\n    annotation_id=\"image_2_bus_polygon_1\",\n    metadata={\"vehicle_color\": \"sapphire\"}\n)",
      "language": "python"
    }
  ]
}
[/block]

## `LineAnnotation`

A 2D line constructed by connecting 2+ vertices (an unclosed polygon).

For more info, see our Python SDK Reference for [`LineAnnotations`](https://docs.nucleus.scale.com/en/latest/api/nucleus/index.html#nucleus.LineAnnotation).

[block:code]
{
  "codes": [
    {
      "code": "from nucleus import Point, LineAnnotation\n\nline_gt = LineAnnotation(\n    label=\"lane\",\n    vertices=[\t# list of vertices as Point objects\n        Point(x=100, y=100),\n        Point(200, 300),\n        Point(300, 200),\n    ],\n    reference_id=\"image_1\",\n    annotation_id=\"image_1_lane_line_1\",\n    metadata={\"position\": \"shoulder\"},\n)",
      "language": "python"
    }
  ]
}
[/block]

## `KeypointsAnnotation`

A collection of 2D points that are named and connected via a domain-specific skeleton.

For more info, see our Python SDK Reference for [`KeypointsAnnotations`](https://docs.nucleus.scale.com/en/latest/api/nucleus/index.html#nucleus.KeypointsAnnotation).

[block:code]
{
  "codes": [
    {
      "code": "from nucleus import Keypoint, KeypointsAnnotation\n\nkeypoint_gt = KeypointsAnnotation(\n    label=\"face\",\n    keypoints=[\n        Keypoint(100, 100, visible=True),\n        Keypoint(200, 300, visible=False),\n        Keypoint(visible=False),\n    ],\n    names=[\"left_eye\", \"right_eye\", \"nose\"],\n    skeleton=[[0, 2], [1, 2]],\n    reference_id=\"image_1\",\n    annotation_id=\"image_1_face_1\",\n    metadata={\"visibility\": \"partial\"},\n)",
      "language": "python"
    }
  ]
}
[/block]

## `CuboidAnnotation`

A 3D cuboid based on a given position, dimensions, and yaw. Cannot be applied to 2D images, only 3D pointcloud [`DatasetItems`](https://nucleus.scale.com/docs/uploading-3d-data#pointclouds).

For more info, see our Python SDK Reference for [`CuboidAnnotations`](https://docs.nucleus.scale.com/en/latest/api/nucleus/index.html#nucleus.CuboidAnnotation).

[block:code]
{
  "codes": [
    {
      "code": "from nucleus import Point3D, CuboidAnnotation\n\ncuboid_gt = CuboidAnnotation(\n    label=\"car\",\n    position=Point3D(100, 100, 10),\t\t\t# center of the cuboid\n    dimensions=Point3D(x=5, y=10, z=5),\t# length (x), width (y), height (z)\n    yaw=0,\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t# rotation in rad about the Z axis\n    reference_id=\"pointcloud_1\",\n    annotation_id=\"pointcloud_1_car_cuboid_1\",\n    metadata={\"vehicle_color\": \"emerald\"}\n)",
      "language": "python"
    }
  ]
}
[/block]