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

# Objects.coordinates

## BoundingBoxCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class BoundingBoxCoordinates()
```

Represents bounding box coordinates, where all values are percentages relative to the total image size.

**Attributes**:

* `height` *float* - The height of the bounding box.
* `width` *float* - The width of the bounding box.
* `top_left_x` *float* - The x-coordinate of the top-left corner.
* `top_left_y` *float* - The y-coordinate of the top-left corner.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: BoundingBoxFrameCoordinatesDict) -> BoundingBoxCoordinates
```

Create a BoundingBoxCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing bounding box information.

**Returns**:

* `BoundingBoxCoordinates` - An instance of BoundingBoxCoordinates.

#### to\_dict

```python theme={"dark"}
def to_dict() -> BoundingBoxDict
```

Convert the BoundingBoxCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the bounding box coordinates.

## RotatableBoundingBoxCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class RotatableBoundingBoxCoordinates()
```

Represents rotatable bounding box coordinates, where all values are percentages relative to the total image size.

**Attributes**:

* `height` *float* - The height of the bounding box.
* `width` *float* - The width of the bounding box.
* `top_left_x` *float* - The x-coordinate of the top-left corner.
* `top_left_y` *float* - The y-coordinate of the top-left corner.
* `theta` *float* - The angle of rotation originating at the center of the box.

#### theta

angle of rotation originating at center of box

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(
    d: RotatableBoundingBoxFrameCoordinatesDict
) -> RotatableBoundingBoxCoordinates
```

Create a RotatableBoundingBoxCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing rotatable bounding box information.

**Returns**:

* `RotatableBoundingBoxCoordinates` - An instance of RotatableBoundingBoxCoordinates.

#### to\_dict

```python theme={"dark"}
def to_dict() -> RotatableBoundingBoxDict
```

Convert the RotatableBoundingBoxCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the rotatable bounding box coordinates.

## CircleCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class CircleCoordinates()
```

Represents circle coordinates, where values are normalized relative to image size.

**Attributes**:

* `center_x` *float* - Normalized x-coordinate of the circle center \[0, 1].
* `center_y` *float* - Normalized y-coordinate of the circle center \[0, 1].
* `radius` *float* - Primary semi-axis radius, normalized to image width.
* `stretch` *float* - Ratio of the secondary semi-axis to the primary (1.0 = true circle, !=1.0 = ellipse).
* `theta` *float* - Rotation angle in degrees, clockwise in screen space (matches RBB convention).
  `theta=0` aligns the primary semi-axis (`radius`) with the +X axis.

## EllipseCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class EllipseCoordinates()
```

Represents ellipse coordinates. Mirrors RotatableBoundingBox's
aspect-decoupled normalization: `rx` is normalized to image width,
`ry` to image height, `theta` is a rotation in degrees applied in
screen-pixel space.

**Attributes**:

* `center_x` *float* - Normalized x-coordinate of the ellipse center \[0, 1].
* `center_y` *float* - Normalized y-coordinate of the ellipse center \[0, 1].
* `rx` *float* - Horizontal semi-axis, normalized to image width.
* `ry` *float* - Vertical semi-axis, normalized to image height.
* `theta` *float* - Rotation in degrees, clockwise in screen space.

## CuboidCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class CuboidCoordinates()
```

Represents a cuboid.

**Attributes**:

* `position` *tuple\[float, float, float]* - The (x, y, z) coordinates of the center of the cuboid in the 3D space.
* `orientation` *tuple\[float, float, float]* - The (alpha, beta, gamma) Euler angles of the cuboid, in radians.
* `size` *tuple\[float, float, float]* - The size of the cuboid along its (x, y, z) axes.

## Cuboid2DPerspectiveCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class Cuboid2DPerspectiveCoordinates()
```

Represents a 2.5D prism with perspective projection.

The back face shrinks and moves towards the vanishing point.

**Attributes**:

* `front` *List\[PointCoordinate]* - The vertices of the front face as a list of PointCoordinate objects.
* `vanishing_point` *PointCoordinate* - The point where parallel lines appear to converge.
* `scale_ratio` *float* - The size of the back face relative to the front face (0.0 to N).
  * 2.0: Back face is twice the size.
  * 1.0: No depth (back matches front).
  * 0.5: Back face is half the size.
  * 0.0: Back face recedes infinitely to the vanishing point.

**Examples**:

```python theme={"dark"}
cuboid = Cuboid2DPerspectiveCoordinates(
    front=[PointCoordinate(x=0, y=0), PointCoordinate(x=0.1, y=0),
           PointCoordinate(x=0.1, y=0.1), PointCoordinate(x=0, y=0.1)],
    vanishing_point=PointCoordinate(x=0.4, y=0.3),
    scale_ratio=0.75
)
```

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict
```

Convert the coordinates to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the cuboid 2D coordinates.

## Cuboid2DIsometricCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class Cuboid2DIsometricCoordinates()
```

Represents a 2.5D prism with parallel (isometric) projection.

The back face remains the same size as the front but is shifted by the offset.

**Attributes**:

* `front` *List\[PointCoordinate]* - The vertices of the front face as a list of PointCoordinate objects.
* `offset` *PointCoordinate* - The translation vector {x, y} to shift the back face.

**Examples**:

```python theme={"dark"}
cuboid = Cuboid2DIsometricCoordinates(
    front=[PointCoordinate(x=0, y=0), PointCoordinate(x=0.1, y=0),
           PointCoordinate(x=0.1, y=0.1), PointCoordinate(x=0, y=0.1)],
    offset=PointCoordinate(x=0.05, y=-0.05)
)
```

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict
```

Convert the coordinates to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the cuboid 2D coordinates.

#### Cuboid2DCoordinates

Union type for 2D cuboid coordinates - either perspective or isometric projection.

#### cuboid\_2d\_coordinates\_from\_dict

```python theme={"dark"}
def cuboid_2d_coordinates_from_dict(
        d: Cuboid2DFrameCoordinatesDict) -> Cuboid2DCoordinates
```

Create a Cuboid2DCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing cuboid\_2d coordinates information.

**Returns**:

* `Cuboid2DCoordinates` - Either Cuboid2DPerspectiveCoordinates or Cuboid2DIsometricCoordinates.

## PointCoordinate Objects

```python theme={"dark"}
@dataclass(frozen=True)
class PointCoordinate()
```

Represents a point coordinate, where all coordinates are a percentage relative to the total image size.

**Attributes**:

* `x` *float* - The x-coordinate of the point.
* `y` *float* - The y-coordinate of the point.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: PointFrameCoordinatesDict) -> PointCoordinate
```

Create a PointCoordinate instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing point coordinate information.

**Returns**:

* `PointCoordinate` - An instance of PointCoordinate.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict[str, PointDict]
```

Convert the PointCoordinate instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the point coordinate.

## PointCoordinate3D Objects

```python theme={"dark"}
@dataclass(frozen=True)
class PointCoordinate3D()
```

Represents a 3D point coordinate, where all coordinates are a percentage relative to the total image size.

**Attributes**:

* `x` *float* - The x-coordinate of the point.
* `y` *float* - The y-coordinate of the point.
* `z` *float* - The z-coordinate of the point.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: Point3DFrameCoordinatesDict) -> PointCoordinate3D
```

Create a PointCoordinate3D instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing point coordinate information.

**Returns**:

* `PointCoordinate3D` - An instance of PointCoordinate3D.

#### to\_dict

```python theme={"dark"}
def to_dict() -> dict[str, PointDict3D]
```

Convert the PointCoordinate instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the point coordinate.

## PolygonCoordinates Objects

```python theme={"dark"}
class PolygonCoordinates()
```

Represents polygon coordinates

#### \_\_init\_\_

```python theme={"dark"}
def __init__(values: Optional[List[PointCoordinate]] = None,
             polygons: Optional[List[List[List[PointCoordinate]]]] = None)
```

**Arguments**:

* `values` *List\[PointCoordinate]* - A list of PointCoordinate objects defining the polygon.
* `polygons` *List\[List\[List\[PointCoordinate]]]* - A list of polygons, where each polygon is a list of contours, where each contour is a list of points.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: PolygonFrameCoordinatesDict) -> "PolygonCoordinates"
```

Create a PolygonCoordinates instance from a dictionary.

Supports both legacy format (single polygon with one contour) and the new complex format (multiple polygons and contours).

**Arguments**:

* `d` *dict* - Dictionary containing polygon coordinates information.

**Returns**:

* `PolygonCoordinates` - A PolygonCoordinates instance.

**Examples**:

Legacy format (mapping of index -> point):

```json theme={"dark"}
{
  "polygon": {
    "0": {"x": 12.3, "y": 45.6},
    "1": {"x": 78.9, "y": 12.3}
  }
}
```

Legacy format (list of points):

```json theme={"dark"}
{
  "polygon": [
    {"x": 12.3, "y": 45.6},
    {"x": 78.9, "y": 12.3}
  ]
}
```

New format (polygons -> contours -> points):

```json theme={"dark"}
{
  "polygons": [
    [
      [
        {"x": 12.3, "y": 45.6},
        {"x": 78.9, "y": 12.3}
      ]
    ]
  ]
}
```

#### to\_dict

```python theme={"dark"}
def to_dict(
    kind: Union[PolygonCoordsToDict, str] = PolygonCoordsToDict.single_polygon
) -> Union[Dict, List[List[List[float]]]]
```

Convert the PolygonCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the polygon coordinates.

## PolylineCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class PolylineCoordinates()
```

Represents polyline coordinates as a list of point coordinates.

**Attributes**:

* `values` *Union\[List\[PointCoordinate], List\[PointCoordinate3D]]* - A list of (3D) PointCoordinate objects defining the polyline.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: PolylineFrameCoordinatesDict) -> PolylineCoordinates
```

Create a PolylineCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing polyline coordinates information.

**Returns**:

* `PolylineCoordinates` - An instance of PolylineCoordinates.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict
```

Convert the PolylineCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the polyline coordinates.

## Visibility Objects

```python theme={"dark"}
class Visibility(CamelStrEnum)
```

An enumeration to represent the visibility state of an item.

**Attributes**:

* `VISIBLE` - The item is visible within the frame.
* `INVISIBLE` - The item is outside the frame and thus invisible.
* `OCCLUDED` - The item is within the frame but occluded by something else.
* `SELF_OCCLUDED` - The item is occluded by itself.

## SkeletonCoordinate Objects

```python theme={"dark"}
class SkeletonCoordinate(BaseDTO)
```

Represents a coordinate for a skeleton structure in an image.

**Attributes**:

* `x` *float* - The x-coordinate of the skeleton point.
* `y` *float* - The y-coordinate of the skeleton point.
* `name` *str* - The name of the skeleton point.
* `color` *Optional\[str]* - The color associated with the skeleton point.
* `feature_hash` *Optional\[str]* - A unique hash for the feature.
* `value` *Optional\[str]* - An optional value associated with the skeleton point.
* `visibility` *Optional\[Visibility]* - The visibility state of the skeleton point.

## SkeletonCoordinates Objects

```python theme={"dark"}
class SkeletonCoordinates(BaseDTO)
```

Represents a collection of skeleton coordinates.

**Attributes**:

* `values` *List\[SkeletonCoordinate]* - A list of SkeletonCoordinate objects.
* `name` *str* - The name of the skeleton structure.

#### to\_dict

```python theme={"dark"}
def to_dict(by_alias=True, exclude_none=True) -> Dict[str, Any]
```

Convert the SkeletonCoordinates instance to a dictionary.

**Arguments**:

* `by_alias` *bool* - Whether to use alias for the field names.
* `exclude_none` *bool* - Whether to exclude fields with None values.

**Returns**:

Dict\[str, Any]: A dictionary representation of the skeleton coordinates.

## AudioCoordinates Objects

```python theme={"dark"}
class AudioCoordinates(BaseDTO)
```

Represents coordinates for an audio file

**Attributes**:

* `range` *Ranges* - Ranges in milliseconds for audio files

## TextCoordinates Objects

```python theme={"dark"}
class TextCoordinates(BaseDTO)
```

Represents coordinates for a text file

**Attributes**:

* `range` *Ranges* - Ranges of chars for simple text files

## HtmlCoordinates Objects

```python theme={"dark"}
class HtmlCoordinates(BaseDTO)
```

Represents coordinates for a html file

**Attributes**:

* `range` *List\[HtmlRange]* - A list of HtmlRange objects

#### add\_coordinates\_to\_frame\_object\_dict

```python theme={"dark"}
def add_coordinates_to_frame_object_dict(coordinates: Coordinates,
                                         base_frame_object: BaseFrameObject,
                                         width: Optional[int],
                                         height: Optional[int]) -> FrameObject
```

Attach geometry to a frame object. The wire field and `shape`
discriminator are inferred from the coordinates class.