Annotation

class Annotation(StaticCollection):
    """
    A class used to annotate `GroundTruths` and `Predictions`.

    Attributes
    ----------
    metadata: Dictionary
        A dictionary of metadata that describes the `Annotation`.
    labels: List[Label], optional
        A list of labels to use for the `Annotation`.
    bounding_box: Box
        A bounding box to assign to the `Annotation`.
    polygon: BoundingPolygon
        A polygon to assign to the `Annotation`.
    raster: Raster
        A raster to assign to the `Annotation`.
    embedding: List[float]
        An embedding, described by a list of values with type float and a maximum length of 16,000.
    text: str, optional
        A piece of text to assign to the `Annotation`.
    context_list: List[str], optional
        A list of contexts associated with an `Annotation`.
    is_instance: bool, optional
        A boolean describing whether we should treat the Raster attached to an annotation as an instance segmentation or not. If set to true, then the Annotation will be validated for use in object detection tasks. If set to false, then the Annotation will be validated for use in semantic segmentation tasks.
    implied_task_types: list[str], optional
        The validated task types that are applicable to each Annotation. Doesn't need to bet set by the user.

    Examples
    --------

    Classification
    >>> Annotation.create(
    ...     labels=[
    ...         Label(key="class", value="dog"),
    ...         Label(key="category", value="animal"),
    ...     ]
    ... )

    Object-Detection Box
    >>> annotation = Annotation(
    ...     labels=[Label(key="k1", value="v1")],
    ...     bounding_box=box2,
    ... )

    Object-Detection Polygon
    >>> annotation = Annotation(
    ...     labels=[Label(key="k1", value="v1")],
    ...     polygon=BoundingPolygon(...),
    ... )

     Raster
    >>> annotation = Annotation(
    ...     labels=[Label(key="k1", value="v1")],
    ...     raster=Raster(...),
    ...     is_instance=True
    ... )

    Object-Detection with all supported Geometries defined.
    >>> Annotation(
    ...     labels=[Label(key="k1", value="v1")],
    ...     bounding_box=Box(...),
    ...     polygon=BoundingPolygon(...),
    ...     raster=Raster(...),
    ...     is_instance=True,
    ... )

    Semantic-Segmentation Raster
    >>> annotation = Annotation(
    ...     labels=[Label(key="k1", value="v1")],
    ...     raster=Raster(...),
    ...     is_instance=False # or None
    ... )

    Text Generation
    >>> annotation = Annotation(
    ...     text="Yes, Lincoln won the election of 1860. He received the highest number of votes...",
    ...     context_list=["Republican speakers focused first on...", "Lincoln received 1,866,452 votes...", ...],
    ... )
    """

    metadata: Dictionary = Dictionary.symbolic(
        owner="annotation", name="metadata"
    )
    labels: SymbolicList[Label] = SymbolicList[Label].symbolic(
        owner="annotation", name="labels"
    )
    bounding_box: Box = Box.symbolic(owner="annotation", name="bounding_box")
    polygon: Polygon = Polygon.symbolic(owner="annotation", name="polygon")
    raster: Raster = Raster.symbolic(owner="annotation", name="raster")
    embedding: Embedding = Embedding.symbolic(
        owner="annotation", name="embedding"
    )
    text: String = String.symbolic(owner="annotation", name="text")
    context_list: ContextList = ContextList.symbolic(
        owner="annotation", name="context_list"
    )
    is_instance: Boolean = Boolean.symbolic(
        owner="annotation", name="is_instance"
    )
    implied_task_types: SymbolicList[String] = SymbolicList[String].symbolic(
        owner="annotation", name="implied_task_types"
    )

    def __init__(
        self,
        *,
        metadata: Optional[dict] = None,
        labels: Optional[List[Label]] = None,
        bounding_box: Optional[Box] = None,
        polygon: Optional[Polygon] = None,
        raster: Optional[Raster] = None,
        embedding: Optional[Embedding] = None,
        text: Optional[str] = None,
        context_list: Optional[List[str]] = None,
        is_instance: Optional[bool] = None,
        implied_task_types: Optional[List[String]] = None,
    ):
        """
        Constructs an annotation.

        Parameters
        ----------
        metadata: Dict[str, Union[int, float, str, bool, datetime.datetime, datetime.date, datetime.time]]
            A dictionary of metadata that describes the `Annotation`.
        labels: List[Label]
            A list of labels to use for the `Annotation`.
        bounding_box: Box, optional
            A bounding box annotation.
        polygon: Polygon, optional
            A polygon annotation.
        raster: Raster, optional
            A raster annotation.
        embedding: List[float], optional
            An embedding, described by a list of values with type float and a maximum length of 16,000.
        text: str, optional
            A text annotation.
        context_list: List[str], optional
            A list of contexts associated to the annotation text. Not all text annotations will have context_list.
        is_instance: bool, optional
            A boolean describing whether we should treat the Raster attached to an annotation as an instance segmentation or not. If set to true, then the Annotation will be validated for use in object detection tasks. If set to false, then the Annotation will be validated for use in semantic segmentation tasks.
        implied_task_types: list[str], optional
            The validated task types that are applicable to each Annotation. Doesn't need to bet set by the user.
        """
        super().__init__(
            metadata=metadata if metadata else dict(),
            labels=labels if labels else list(),
            bounding_box=bounding_box,
            polygon=polygon,
            raster=raster,
            embedding=embedding,
            text=text,
            context_list=context_list,
            is_instance=is_instance,
            implied_task_types=implied_task_types,
        )

    @staticmethod
    def formatting() -> Dict[str, Any]:
        """Attribute format mapping."""
        return {
            "bounding_box": Box.nullable,
            "polygon": Polygon.nullable,
            "raster": Raster.nullable,
            "embedding": Embedding.nullable,
            "text": String.nullable,
            "context_list": ContextList.nullable,
            "is_instance": Boolean.nullable,
            "implied_task_types": SymbolicList,
        }