Module datatap.template

Templates are used to describe how a given annotation (or set of annotations) is structured.

All Datasets and DatasetVersions will have templates attached to them. If you need to create your own template (for instance, in order to create a new dataset), you can instantiate them as such:

from datatap.template import ImageAnnotationTemplate, ClassAnnotationTemplate, InstanceTemplate

ImageAnnotationTemplate(classes = {
        "person": ClassAnnotationTemplate(
                instances = InstanceTemplate(
                        bounding_box = True,
                        segmentation = False, # this could also be omitted, since False is the default
                        keypoints = { "head", "left shoulder", "right shoulder" },
                        attributes = { "face mask": { "present", "absent" } }
                )
        )
})
Expand source code
"""
Templates are used to describe how a given annotation (or set of annotations) is structured.

All `Dataset`s and `DatasetVersion`s will have templates attached to them. If you need to
create your own template (for instance, in order to create a new dataset), you can
instantiate them as such:

```py
from datatap.template import ImageAnnotationTemplate, ClassAnnotationTemplate, InstanceTemplate

ImageAnnotationTemplate(classes = {
        "person": ClassAnnotationTemplate(
                instances = InstanceTemplate(
                        bounding_box = True,
                        segmentation = False, # this could also be omitted, since False is the default
                        keypoints = { "head", "left shoulder", "right shoulder" },
                        attributes = { "face mask": { "present", "absent" } }
                )
        )
})
```
"""


from .class_annotation_template import ClassAnnotationTemplate
from .frame_annotation_template import FrameAnnotationTemplate
from .image_annotation_template import ImageAnnotationTemplate
from .instance_template import InstanceTemplate
from .multi_instance_template import MultiInstanceTemplate
from .video_annotation_template import VideoAnnotationTemplate

__all__ = [
        "ClassAnnotationTemplate",
        "FrameAnnotationTemplate",
        "ImageAnnotationTemplate",
        "InstanceTemplate",
        "MultiInstanceTemplate",
        "VideoAnnotationTemplate",
]

Sub-modules

datatap.template.class_annotation_template
datatap.template.frame_annotation_template
datatap.template.image_annotation_template
datatap.template.instance_template
datatap.template.multi_instance_template
datatap.template.video_annotation_template

Classes

class ClassAnnotationTemplate (*, instances: Optional[InstanceTemplate] = None, multi_instances: Optional[MultiInstanceTemplate] = None)

A ClassAnnotationTemplate describes what each class should provide.

In practice, most of the specification is delegated to its constituent tepmlates, instances and multi_instances.

Expand source code
class ClassAnnotationTemplate():
        """
        A `ClassAnnotationTemplate` describes what each class should provide.

        In practice, most of the specification is delegated to its constituent tepmlates,
        `instances` and `multi_instances`.
        """

        instances: Optional[InstanceTemplate]
        """
        An `InstanceTemplate` that describes how instances are structured.
        """

        multi_instances: Optional[MultiInstanceTemplate]
        """
        A `MultiInstanceTemplate` that describes how multi instances are structured.
        """

        def __init__(
                self,
                *,
                instances: Optional[InstanceTemplate] = None,
                multi_instances: Optional[MultiInstanceTemplate] = None
        ):
                self.instances = instances
                self.multi_instances = multi_instances

        def to_json(self) -> ClassAnnotationTemplateJson:
                """
                Serializes this object into JSON.
                """
                json = ClassAnnotationTemplateJson()
                if self.instances is not None: json["instances"] = self.instances.to_json()
                if self.multi_instances is not None: json["multiInstances"] = self.multi_instances.to_json()
                return json

        @staticmethod
        def from_json(json: ClassAnnotationTemplateJson) -> ClassAnnotationTemplate:
                """
                Deserializes a JSON object into a `ClassAnnotationTemplate`.
                """
                instances = InstanceTemplate.from_json(json["instances"]) if "instances" in json else None
                multi_instances = MultiInstanceTemplate.from_json(json["multiInstances"]) if "multiInstances" in json else None
                return ClassAnnotationTemplate(instances=instances, multi_instances=multi_instances)

        def __repr__(self) -> str:
                return basic_repr(
                        "ClassAnnotationTemplate",
                        instances = self.instances,
                        multi_instances = self.multi_instances
                )

Class variables

var instances : Optional[InstanceTemplate]

An InstanceTemplate that describes how instances are structured.

var multi_instances : Optional[MultiInstanceTemplate]

A MultiInstanceTemplate that describes how multi instances are structured.

Static methods

def from_json(json: ClassAnnotationTemplateJson) ‑> ClassAnnotationTemplate

Deserializes a JSON object into a ClassAnnotationTemplate.

Expand source code
@staticmethod
def from_json(json: ClassAnnotationTemplateJson) -> ClassAnnotationTemplate:
        """
        Deserializes a JSON object into a `ClassAnnotationTemplate`.
        """
        instances = InstanceTemplate.from_json(json["instances"]) if "instances" in json else None
        multi_instances = MultiInstanceTemplate.from_json(json["multiInstances"]) if "multiInstances" in json else None
        return ClassAnnotationTemplate(instances=instances, multi_instances=multi_instances)

Methods

def to_json(self) ‑> ClassAnnotationTemplateJson

Serializes this object into JSON.

Expand source code
def to_json(self) -> ClassAnnotationTemplateJson:
        """
        Serializes this object into JSON.
        """
        json = ClassAnnotationTemplateJson()
        if self.instances is not None: json["instances"] = self.instances.to_json()
        if self.multi_instances is not None: json["multiInstances"] = self.multi_instances.to_json()
        return json
class FrameAnnotationTemplate (*, classes: Mapping[str, ClassAnnotationTemplate])

Describes how a FrameAnnotation is structured.

For each of its classes, it provides a ClassAnnotationTemplate.

Expand source code
class FrameAnnotationTemplate():
        """
        Describes how a `FrameAnnotation` is structured.

        For each of its classes, it provides a `ClassAnnotationTemplate`.
        """

        classes: Mapping[str, ClassAnnotationTemplate]
        """
        A mapping from class name to `ClassAnnotationTemplate`.
        """

        def __init__(self, *, classes: Mapping[str, ClassAnnotationTemplate]):
                self.classes = classes

        def to_json(self) -> FrameAnnotationTemplateJson:
                """
                Serializes this object to JSON.
                """
                return {
                        "classes": {
                                class_name: class_template.to_json()
                                for class_name, class_template in self.classes.items()
                        }
                }

        @staticmethod
        def from_json(json: FrameAnnotationTemplateJson) -> FrameAnnotationTemplate:
                """
                Deserializes a JSON object into a `FrameAnnotationTemplate`.
                """
                classes = {
                        key: ClassAnnotationTemplate.from_json(value)
                        for key, value in json.get("classes", {}).items()
                }

                return FrameAnnotationTemplate(classes=classes)

        def __repr__(self) -> str:
                return basic_repr(
                        "FrameAnnotationTemplate",
                        classes = self.classes
                )

Class variables

var classes : Mapping[str, ClassAnnotationTemplate]

A mapping from class name to ClassAnnotationTemplate.

Static methods

def from_json(json: FrameAnnotationTemplateJson) ‑> FrameAnnotationTemplate

Deserializes a JSON object into a FrameAnnotationTemplate.

Expand source code
@staticmethod
def from_json(json: FrameAnnotationTemplateJson) -> FrameAnnotationTemplate:
        """
        Deserializes a JSON object into a `FrameAnnotationTemplate`.
        """
        classes = {
                key: ClassAnnotationTemplate.from_json(value)
                for key, value in json.get("classes", {}).items()
        }

        return FrameAnnotationTemplate(classes=classes)

Methods

def to_json(self) ‑> FrameAnnotationTemplateJson

Serializes this object to JSON.

Expand source code
def to_json(self) -> FrameAnnotationTemplateJson:
        """
        Serializes this object to JSON.
        """
        return {
                "classes": {
                        class_name: class_template.to_json()
                        for class_name, class_template in self.classes.items()
                }
        }
class ImageAnnotationTemplate (*, classes: Mapping[str, ClassAnnotationTemplate])

Describes how an ImageAnnotation is structured.

For each of its classes, it provides a ClassAnnotationTemplate.

Expand source code
class ImageAnnotationTemplate():
        """
        Describes how an `ImageAnnotation` is structured.

        For each of its classes, it provides a `ClassAnnotationTemplate`.
        """

        classes: Mapping[str, ClassAnnotationTemplate]
        """
        A mapping from class name to `ClassAnnotationTemplate`.
        """

        def __init__(self, *, classes: Mapping[str, ClassAnnotationTemplate]):
                self.classes = classes

        def to_json(self) -> ImageAnnotationTemplateJson:
                """
                Serializes this object to JSON.
                """
                return {
                        "kind": "ImageAnnotationTemplate",
                        "classes": {
                                class_name: class_template.to_json()
                                for class_name, class_template in self.classes.items()
                        }
                }

        @staticmethod
        def from_json(json: ImageAnnotationTemplateJson) -> ImageAnnotationTemplate:
                """
                Deserializes a JSON object into an `ImageAnnotationTemplate`.
                """
                classes = {
                        key: ClassAnnotationTemplate.from_json(value)
                        for key, value in json.get("classes", {}).items()
                }

                return ImageAnnotationTemplate(classes=classes)

        def __repr__(self) -> str:
                return basic_repr(
                        "ImageAnnotationTemplate",
                        classes = self.classes
                )

Class variables

var classes : Mapping[str, ClassAnnotationTemplate]

A mapping from class name to ClassAnnotationTemplate.

Static methods

def from_json(json: ImageAnnotationTemplateJson) ‑> ImageAnnotationTemplate

Deserializes a JSON object into an ImageAnnotationTemplate.

Expand source code
@staticmethod
def from_json(json: ImageAnnotationTemplateJson) -> ImageAnnotationTemplate:
        """
        Deserializes a JSON object into an `ImageAnnotationTemplate`.
        """
        classes = {
                key: ClassAnnotationTemplate.from_json(value)
                for key, value in json.get("classes", {}).items()
        }

        return ImageAnnotationTemplate(classes=classes)

Methods

def to_json(self) ‑> ImageAnnotationTemplateJson

Serializes this object to JSON.

Expand source code
def to_json(self) -> ImageAnnotationTemplateJson:
        """
        Serializes this object to JSON.
        """
        return {
                "kind": "ImageAnnotationTemplate",
                "classes": {
                        class_name: class_template.to_json()
                        for class_name, class_template in self.classes.items()
                }
        }
class InstanceTemplate (*, id: bool = False, bounding_box: bool = False, segmentation: bool = False, keypoints: AbstractSet[str] = set(), attributes: Mapping[str, AbstractSet[str]] = {})

Describes how an individual instance is structured.

Expand source code
class InstanceTemplate():
        """
        Describes how an individual instance is structured.
        """

        id: bool
        """
        If `id` is `True`, then all corresponding `Instance`s will have an ID
        that uniquely identifies the object represented by the instance in the
        context of the containing annotation.
        """

        bounding_box: bool
        """
        If `bounding_box` is `True`, then all corresponding `Instance`s will have a
        `BoundingBox` representing the bounds of their shape.
        """

        segmentation: bool
        """
        If `segmentation` is `True`, then all corresponding `Instance`s will have a
        `Segmentation` tightly representing their shape.
        """

        keypoints: AbstractSet[str]
        """
        For each keypoint name specified in `keypoints`, all corresponding instances
        will have a corresponding key in their `keypoints` field, the value of which
        will contain he keypoint if it is present or has an inferrable position in
        the image or `None` if it is not in-frame.
        """

        attributes: Mapping[str, AbstractSet[str]]
        """
        For each attribute name specified in `attributes`, all corresponding
        `Instance`s will provide one of the given values.
        """

        def __init__(
                self,
                *,
                id: bool = False,
                bounding_box: bool = False,
                segmentation: bool = False,
                keypoints: AbstractSet[str] = set(),
                attributes: Mapping[str, AbstractSet[str]] = dict(),
        ):
                self.id = id
                self.bounding_box = bounding_box
                self.segmentation = segmentation
                self.keypoints = keypoints
                self.attributes = attributes

        def to_json(self) -> InstanceTemplateJson:
                """
                Serializes this object as JSON.
                """
                json = InstanceTemplateJson()

                if self.id: json["id"] = True
                if self.bounding_box: json["boundingBox"] = True
                if self.segmentation: json["segmentation"] = True
                if len(self.keypoints) > 0: json["keypoints"] = list(self.keypoints)
                if len(self.attributes) > 0: json["attributes"] = { key: list(values) for key, values in self.attributes.items() }

                return json

        @staticmethod
        def from_json(json: InstanceTemplateJson) -> InstanceTemplate:
                """
                Deserializes a JSON object as an `InstanceTemplate`.
                """
                id = json.get("id", False)
                bounding_box = json.get("boundingBox", False)
                segmentation = json.get("segmentation", False)
                keypoints = set(json.get("keypoints", []))
                attributes = {
                        key: set(values)
                        for key, values in json.get("attributes", {}).items()
                }
                return InstanceTemplate(
                        id = id,
                        bounding_box=bounding_box,
                        segmentation=segmentation,
                        keypoints=keypoints,
                        attributes=attributes,
                )

        def __repr__(self) -> str:
                return basic_repr(
                        "InstanceTemplate",
                        id = self.id,
                        bounding_box = self.bounding_box,
                        segmentation = self.segmentation,
                        keypoints = self.keypoints,
                        attributes = self.attributes,
                )

Class variables

var attributes : Mapping[str, AbstractSet[str]]

For each attribute name specified in attributes, all corresponding Instances will provide one of the given values.

var bounding_box : bool

If bounding_box is True, then all corresponding Instances will have a BoundingBox representing the bounds of their shape.

var id : bool

If id is True, then all corresponding Instances will have an ID that uniquely identifies the object represented by the instance in the context of the containing annotation.

var keypoints : AbstractSet[str]

For each keypoint name specified in keypoints, all corresponding instances will have a corresponding key in their keypoints field, the value of which will contain he keypoint if it is present or has an inferrable position in the image or None if it is not in-frame.

var segmentation : bool

If segmentation is True, then all corresponding Instances will have a Segmentation tightly representing their shape.

Static methods

def from_json(json: InstanceTemplateJson) ‑> InstanceTemplate

Deserializes a JSON object as an InstanceTemplate.

Expand source code
@staticmethod
def from_json(json: InstanceTemplateJson) -> InstanceTemplate:
        """
        Deserializes a JSON object as an `InstanceTemplate`.
        """
        id = json.get("id", False)
        bounding_box = json.get("boundingBox", False)
        segmentation = json.get("segmentation", False)
        keypoints = set(json.get("keypoints", []))
        attributes = {
                key: set(values)
                for key, values in json.get("attributes", {}).items()
        }
        return InstanceTemplate(
                id = id,
                bounding_box=bounding_box,
                segmentation=segmentation,
                keypoints=keypoints,
                attributes=attributes,
        )

Methods

def to_json(self) ‑> InstanceTemplateJson

Serializes this object as JSON.

Expand source code
def to_json(self) -> InstanceTemplateJson:
        """
        Serializes this object as JSON.
        """
        json = InstanceTemplateJson()

        if self.id: json["id"] = True
        if self.bounding_box: json["boundingBox"] = True
        if self.segmentation: json["segmentation"] = True
        if len(self.keypoints) > 0: json["keypoints"] = list(self.keypoints)
        if len(self.attributes) > 0: json["attributes"] = { key: list(values) for key, values in self.attributes.items() }

        return json
class MultiInstanceTemplate (*, bounding_box: bool = False, segmentation: bool = False, count: bool = False)

Describes how an individual multi-instance is structured.

Expand source code
class MultiInstanceTemplate():
        """
        Describes how an individual multi-instance is structured.
        """

        bounding_box: bool
        """
        If `bounding_box` is `True`, then all corresponding `MultiInstance`s will
        have a `BoundingBox` representing the bounds of their shape.
        """

        segmentation: bool
        """
        If `segmentation` is `True`, then all corresponding `MultiInstance`s will
        have a `Segmentation` tightly representing their shape.
        """

        count: bool
        """
        If `count` is `True`, then all corresponding `MultiInstance`s will have a
        count of how many true instances are present in the multi-instance.
        """

        def __init__(
                self,
                *,
                bounding_box: bool = False,
                segmentation: bool = False,
                count: bool = False
        ):
                self.bounding_box = bounding_box
                self.segmentation = segmentation
                self.count = count

        def to_json(self) -> MultiInstanceTemplateJson:
                json = MultiInstanceTemplateJson()
                if self.bounding_box: json["boundingBox"] = True
                if self.segmentation: json["segmentation"] = True
                if self.count: json["count"] = True
                return json

        @staticmethod
        def from_json(json: MultiInstanceTemplateJson) -> MultiInstanceTemplate:
                bounding_box = json.get("boundingBox", False)
                segmentation = json.get("segmentation", False)
                count = json.get("count", False)
                return MultiInstanceTemplate(
                        bounding_box = bounding_box,
                        segmentation = segmentation,
                        count = count
                )

        def __repr__(self) -> str:
                return basic_repr(
                        "MultiInstanceTemplate",
                        bounding_box = self.bounding_box,
                        segmentation = self.segmentation
                )

Class variables

var bounding_box : bool

If bounding_box is True, then all corresponding MultiInstances will have a BoundingBox representing the bounds of their shape.

var count : bool

If count is True, then all corresponding MultiInstances will have a count of how many true instances are present in the multi-instance.

var segmentation : bool

If segmentation is True, then all corresponding MultiInstances will have a Segmentation tightly representing their shape.

Static methods

def from_json(json: MultiInstanceTemplateJson) ‑> MultiInstanceTemplate
Expand source code
@staticmethod
def from_json(json: MultiInstanceTemplateJson) -> MultiInstanceTemplate:
        bounding_box = json.get("boundingBox", False)
        segmentation = json.get("segmentation", False)
        count = json.get("count", False)
        return MultiInstanceTemplate(
                bounding_box = bounding_box,
                segmentation = segmentation,
                count = count
        )

Methods

def to_json(self) ‑> MultiInstanceTemplateJson
Expand source code
def to_json(self) -> MultiInstanceTemplateJson:
        json = MultiInstanceTemplateJson()
        if self.bounding_box: json["boundingBox"] = True
        if self.segmentation: json["segmentation"] = True
        if self.count: json["count"] = True
        return json
class VideoAnnotationTemplate (*, frames: FrameAnnotationTemplate)

Describes how a VideoAnnotation is structured.

It consists only of a FrameAnnotationTemplate that describes its frames.

Expand source code
class VideoAnnotationTemplate():
        """
        Describes how a `VideoAnnotation` is structured.

        It consists only of a `FrameAnnotationTemplate` that describes its frames.
        """

        frames: FrameAnnotationTemplate
        """
        A `FrameAnnotationTemplate` that describes how the frames are structured.
        """

        def __init__(self, *, frames: FrameAnnotationTemplate):
                self.frames = frames

        def to_json(self) -> VideoAnnotationTemplateJson:
                """
                Serializes this object to JSON.
                """
                return {
                        "kind": "VideoAnnotationTemplate",
                        "frames": self.frames.to_json()
                }

        @staticmethod
        def from_json(json: VideoAnnotationTemplateJson) -> VideoAnnotationTemplate:
                """
                Deserializes a JSON object into a `VideoAnnotationTemplate`.
                """
                return VideoAnnotationTemplate(
                        frames = FrameAnnotationTemplate.from_json(json["frames"])
                )

        def __repr__(self) -> str:
                return basic_repr(
                        "VideoAnnotationTemplate",
                        frames = self.frames
                )

Class variables

var framesFrameAnnotationTemplate

A FrameAnnotationTemplate that describes how the frames are structured.

Static methods

def from_json(json: VideoAnnotationTemplateJson) ‑> VideoAnnotationTemplate

Deserializes a JSON object into a VideoAnnotationTemplate.

Expand source code
@staticmethod
def from_json(json: VideoAnnotationTemplateJson) -> VideoAnnotationTemplate:
        """
        Deserializes a JSON object into a `VideoAnnotationTemplate`.
        """
        return VideoAnnotationTemplate(
                frames = FrameAnnotationTemplate.from_json(json["frames"])
        )

Methods

def to_json(self) ‑> VideoAnnotationTemplateJson

Serializes this object to JSON.

Expand source code
def to_json(self) -> VideoAnnotationTemplateJson:
        """
        Serializes this object to JSON.
        """
        return {
                "kind": "VideoAnnotationTemplate",
                "frames": self.frames.to_json()
        }