# coding: utf-8
"""Tag can be attached to whole image and/or to individual :class:`~supervisely.annotation.label.Label`"""
# docs
from __future__ import annotations
from typing import Dict, List, Optional, Union
from supervisely._utils import take_with_default
from supervisely.annotation.tag_meta import TagMeta, TagValueType
from supervisely.annotation.tag_meta_collection import TagMetaCollection
from supervisely.collection.key_indexed_collection import KeyObject
[docs]
class TagJsonFields:
"""Json fields for :class:`~supervisely.annotation.tag.Tag`"""
TAG_NAME = "name"
""""""
VALUE = "value"
""""""
LABELER_LOGIN = "labelerLogin"
""""""
UPDATED_AT = "updatedAt"
""""""
CREATED_AT = "createdAt"
""""""
ID = "id"
""""""
# TAG_META_ID = 'tagId'
# """"""
[docs]
class Tag(KeyObject):
"""Tag attached to image or label; meta + value. Immutable."""
_SUPPORT_UNFINISHED_TAGS = False
def __init__(
self,
meta: TagMeta,
value: Optional[Union[str, int, float]] = None,
sly_id: Optional[int] = None,
labeler_login: Optional[str] = None,
updated_at: Optional[str] = None,
created_at: Optional[str] = None,
):
"""
:param meta: :class:`~supervisely.annotation.tag_meta.TagMeta` object with tag metadata (name, value type).
:type meta: :class:`~supervisely.annotation.tag_meta.TagMeta`
:param value: Tag value; type must match :class:`~supervisely.annotation.tag_meta.TagMeta`.value_type.
Date tag values must be ISO datetime strings.
:type value: str or int or float, optional
:param sly_id: Server-side tag ID.
:type sly_id: int, optional
:param labeler_login: Login of user who created the tag.
:type labeler_login: str, optional
:param updated_at: Last modification timestamp (ISO format).
:type updated_at: str, optional
:param created_at: Creation timestamp (ISO format).
:type created_at: str, optional
:raises ValueError: If meta is None or value is incompatible with :class:`~supervisely.annotation.tag_meta.TagMeta`.value_type.
:Usage Example:
.. code-block:: python
import supervisely as sly
meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
tag_dog = sly.Tag(meta_dog)
meta_cat = sly.TagMeta('cat', sly.TagValueType.ANY_STRING)
tag_cat = sly.Tag(meta_cat, value="Fluffy")
colors = ["brown", "white", "black"]
meta_coat = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING, possible_values=colors)
tag_coat = sly.Tag(meta_coat, value="white")
meta_date = sly.TagMeta('reviewed_at', sly.TagValueType.DATE)
tag_date = sly.Tag(meta_date, value="2026-04-23T15:15:48")
"""
if meta is None:
raise ValueError("TagMeta is None")
self._meta = meta
self._value = value
if not self._meta.is_valid_value(value):
if not (self._SUPPORT_UNFINISHED_TAGS and value is None):
raise ValueError(f"Tag {self.meta.name} can not have value {value}")
self.labeler_login = labeler_login
self.updated_at = updated_at
self.created_at = created_at
self.sly_id = sly_id
@property
def meta(self) -> TagMeta:
"""
General information about Tag. When creating a new Tag, it's value is automatically cross-checked against :class:`~supervisely.annotation.tag_meta.TagValueType` to make sure that value is valid.
:returns: TagMeta object
:rtype: :class:`~supervisely.annotation.tag_meta.TagMeta`
:Usage Example:
.. code-block:: python
meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
tag_dog = sly.Tag(meta_dog)
# Our TagMeta has value type 'NONE', if we try to add value to our Tag, "ValueError" error will be raised
tag_dog = sly.Tag(meta_dog, value="Husky")
# Output: ValueError: Tag dog can not have value Husky
"""
return self._meta
@property
def value(self) -> str or int or float:
"""
Tag value. Return type depends on :class:`~supervisely.annotation.tag_meta.TagValueType`.
Date tag values are returned as ISO datetime strings.
:returns: Tag value
:rtype: str, int or float or None
:Usage Example:
.. code-block:: python
meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, value="Husky")
meta_age = sly.TagMeta('age', sly.TagValueType.ANY_NUMBER)
tag_age = sly.Tag(meta_age, value=9)
colors = ["Black", "White", "Golden", "Brown"]
meta_color = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING, possible_values=colors)
tag_color = sly.Tag(meta_color, value="White")
meta_date = sly.TagMeta('reviewed_at', sly.TagValueType.DATE)
tag_date = sly.Tag(meta_date, value="2026-04-23T15:15:48")
type(tag_dog.value) # 'str'
type(tag_age.value) # 'int'
type(tag_color.value) # 'str'
type(tag_date.value) # 'str'
"""
return self._value
@property
def name(self) -> str:
"""
Name property.
:returns: Name
:rtype: str
:Usage Example:
.. code-block:: python
meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, value="Husky")
print(tag_dog.name)
# Output: "dog"
"""
return self._meta.name
[docs]
def key(self):
"""
Get TagMeta key value.
:returns: TagMeta key value
:rtype: str
:Usage Example:
.. code-block:: python
import supervisely as sly
weather_conditions = ["Sunny", "Cloudy", "Snowy", "Foggy", "Rainy"]
meta_weather = sly.TagMeta("weather", sly.TagValueType.ONEOF_STRING, possible_values=weather_conditions)
tag_weather = sly.Tag(meta_weather, value="Sunny")
key = tag_weather.key()
print(key)
# Output: weather
"""
return self._meta.key()
[docs]
def to_json(self) -> Dict:
"""
Convert the Tag to a json dict. Read more about `Supervisely format <https://docs.supervisely.com/data-organization/00_ann_format_navi>`_.
:returns: Json format as a dict
:rtype: dict
:Usage Example:
.. code-block:: python
import supervisely as sly
# Tag with all fields filled in
meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(
meta=meta_dog,
value="Husky",
sly_id=38456,
labeler_login="admin",
updated_at="2021-01-22T19:37:50.158Z",
created_at="2021-01-22T18:00:00.000Z"
)
tag_dog_json = tag_dog.to_json()
print(tag_dog_json)
# Notice that sly_id won't print
# Output: {
# "name": "dog",
# "value": "Husky",
# "labelerLogin": "admin",
# "updatedAt": "2021-01-22T19:37:50.158Z",
# "createdAt": "2021-01-22T18:00:00.000Z"
# }
"""
res = {TagJsonFields.TAG_NAME: self.meta.name}
if self.meta.value_type != TagValueType.NONE:
res[TagJsonFields.VALUE] = self.value
if self.labeler_login is not None:
res[TagJsonFields.LABELER_LOGIN] = self.labeler_login
if self.updated_at is not None:
res[TagJsonFields.UPDATED_AT] = self.updated_at
if self.created_at is not None:
res[TagJsonFields.CREATED_AT] = self.created_at
return res
[docs]
@classmethod
def from_json(cls, data: Dict, tag_meta_collection: TagMetaCollection) -> Tag:
"""
Convert a json dict to Tag. Read more about `Supervisely format <https://docs.supervisely.com/data-organization/00_ann_format_navi>`_.
:param data: Tag in json format as a dict.
:type data: dict
:param tag_meta_collection: TagMetaCollection object.
:type tag_meta_collection: :class:`~supervisely.annotation.tag_meta_collection.TagMetaCollection`
:returns: Tag object
:rtype: :class:`~supervisely.annotation.tag.Tag`
:Usage Example:
.. code-block:: python
import supervisely as sly
meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_metas = sly.TagMetaCollection([meta_dog])
data = {
"name": "dog",
"value": "Husky",
"labelerLogin": "admin",
"updatedAt": "2021-01-22T19:37:50.158Z",
"createdAt": "2021-01-22T18:00:00.000Z"
}
tag_dog = sly.Tag.from_json(data, tag_metas)
"""
if type(data) is str:
tag_name = data
value = None
labeler_login = None
updated_at = None
created_at = None
sly_id = None
else:
tag_name = data[TagJsonFields.TAG_NAME]
value = data.get(TagJsonFields.VALUE, None)
labeler_login = data.get(TagJsonFields.LABELER_LOGIN, None)
updated_at = data.get(TagJsonFields.UPDATED_AT, None)
created_at = data.get(TagJsonFields.CREATED_AT, None)
sly_id = data.get(TagJsonFields.ID, None)
meta = tag_meta_collection.get(tag_name)
return cls(
meta=meta,
value=value,
sly_id=sly_id,
labeler_login=labeler_login,
updated_at=updated_at,
created_at=created_at,
)
[docs]
def get_compact_str(self) -> str:
"""
Displays information about Tag's name and value in string format.
:returns: Name and value of the given :class:`~supervisely.annotation.tag.Tag`
:rtype: str
:Usage Example:
.. code-block:: python
import supervisely as sly
meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, value="Husky")
print(tag_dog.get_compact_str())
# Output: 'dog:Husky'
"""
if (self.meta.value_type != TagValueType.NONE) and (len(str(self.value)) > 0):
return "{}:{}".format(self.name, self.value)
return self.name
def __eq__(self, other: Tag) -> bool:
"""
Checks that 2 Tags are equal by comparing their meta and value.
:param other: Tag object.
:type other: :class:`~supervisely.annotation.tag.Tag`
:returns: True if comparable objects are equal, otherwise False
:rtype: bool
:Usage Example:
.. code-block:: python
import supervisely as sly
# Let's create 2 identical Tags
meta_lemon_1 = sly.TagMeta('Lemon', sly.TagValueType.NONE)
tag_lemon_1 = sly.Tag(meta_lemon_1)
meta_lemon_2 = sly.TagMeta('Lemon', sly.TagValueType.NONE)
tag_lemon_2 = sly.Tag(meta_lemon_2)
# and 1 different Tag to compare them
meta_cucumber = sly.TagMeta('Cucumber', sly.TagValueType.ANY_STRING)
tag_cucumber = sly.Tag(meta_cucumber, value="Fresh")
# Compare identical Tags
tag_lemon_1 == tag_lemon_2 # True
# Compare unidentical Tags
tag_lemon_1 == tag_cucumber # False
"""
return isinstance(other, Tag) and self.meta == other.meta and self.value == other.value
def __ne__(self, other: Tag) -> bool:
"""
Checks that 2 Tags are opposite.
:param other: Tag object.
:type other: :class:`~supervisely.annotation.tag.Tag`
:returns: True if comparable objects are not equal, otherwise False
:rtype: bool
:Usage Example:
.. code-block:: python
import supervisely as sly
# Let's create 2 identical Tags
meta_lemon_1 = sly.TagMeta('Lemon', sly.TagValueType.NONE)
tag_lemon_1 = sly.Tag(meta_lemon_1)
meta_lemon_2 = sly.TagMeta('Lemon', sly.TagValueType.NONE)
tag_lemon_2 = sly.Tag(meta_lemon_2)
# and 1 different Tag to compare them
meta_cucumber = sly.TagMeta('Cucumber', sly.TagValueType.ANY_STRING)
tag_cucumber = sly.Tag(meta_cucumber, value="Fresh")
# Compare identical Tags
tag_lemon_1 != tag_lemon_2 # False
# Compare unidentical Tags
tag_lemon_1 != tag_cucumber # True
"""
return not self == other
[docs]
def clone(
self,
meta: Optional[TagMeta] = None,
value: Optional[Union[str, int, float]] = None,
sly_id: Optional[int] = None,
labeler_login: Optional[str] = None,
updated_at: Optional[str] = None,
created_at: Optional[str] = None,
) -> Tag:
"""
Clone makes a copy of Tag with new fields, if fields are given, otherwise it will use original Tag fields.
:param meta: General information about Tag.
:type meta: :class:`~supervisely.annotation.tag_meta.TagMeta`
:type value: str or int or float or None
:param sly_id: Tag ID in Supervisely server.
:type sly_id: int, optional
:param labeler_login: Login of user who created :class:`~supervisely.annotation.tag.Tag`.
:type labeler_login: str, optional
:param updated_at: Date and Time when Tag was modified last. Date Format: Year:Month:Day:Hour:Minute:Seconds. Example: '2021-01-22T19:37:50.158Z'.
:type updated_at: str, optional
:param created_at: Date and Time when Tag was created. Date Format is the same as in "updated_at" parameter.
:type created_at: str, optional
:returns: New instance of Tag object
:rtype: :class:`~supervisely.annotation.tag.Tag`
:Usage Example:
.. code-block:: python
import supervisely as sly
#Original Tag
weather_conditions = ["Sunny", "Cloudy", "Snowy", "Foggy", "Rainy"]
meta_weather = sly.TagMeta("weather", sly.TagValueType.ONEOF_STRING, possible_values=weather_conditions)
tag_weather = sly.Tag(meta_weather, value="Sunny")
# Let's create some more tags by cloning our original Tag
# Remember that Tag class object is immutable, and we need to assign new instance of Tag to a new variable
clone_weather_1 = tag_weather.clone(value="Snowy")
clone_weather_2 = tag_weather.clone(value="Cloudy")
clone_weather_3 = tag_weather.clone(value="Rainy")
"""
return Tag(
meta=take_with_default(meta, self.meta),
value=take_with_default(value, self.value),
sly_id=take_with_default(sly_id, self.sly_id),
labeler_login=take_with_default(labeler_login, self.labeler_login),
updated_at=take_with_default(updated_at, self.updated_at),
created_at=take_with_default(created_at, self.created_at),
)
def __str__(self):
return "{:<7s}{:<10}{:<7s} {:<13}{:<7s} {:<10}".format(
"Name:",
self._meta.name,
"Value type:",
self._meta.value_type,
"Value:",
str(self.value),
)
[docs]
def get_row_ptable(self):
"""
Get row with tag properties.
:returns: List of tag properties.
:rtype: List[str]
:Usage Example:
.. code-block:: python
import supervisely as sly
weather_conditions = ["Sunny", "Cloudy", "Snowy", "Foggy", "Rainy"]
meta_weather = sly.TagMeta("weather", sly.TagValueType.ONEOF_STRING, possible_values=weather_conditions)
tag_weather = sly.Tag(meta_weather, value="Sunny")
row = tag_weather.get_row_ptable()
print(row)
# Output: ['weather', 'oneof_string', 'Sunny']
"""
return [self._meta.name, self._meta.value_type, self.value]
def _set_id(self, id: int):
self.sly_id = id
def _set_updated_at(self, updated_at: str):
self.updated_at = updated_at
def _set_created_at(self, created_at: str):
self.created_at = created_at
def _set_labeler_login(self, labeler_login: str):
self.labeler_login = labeler_login