TagMeta¶

class TagMeta(name, value_type, possible_values=None, color=None, sly_id=None, hotkey=None, applicable_to=None, applicable_classes=None, target_type=None, frame_range_min_length=None, frame_range_max_length=None)[source]¶

Bases: KeyObject, JsonSerializable

Tag metadata: name, value type (NONE, ANY_STRING, DATE, etc.), optional possible values. Immutable.

Parameters:

name : str¶: Tag name.
value_type : str¶: TagValueType: NONE, ANY_STRING, ANY_NUMBER, ONEOF_STRING, DATE.
possible_values : List[str], optional¶: Required for ONEOF_STRING; list of allowed values.
color : List[int, int, int], optional¶: RGB color [R, G, B]. Random if not provided.
sly_id : int, optional¶: Server-side tag meta ID.
hotkey : str, optional¶: Hotkey in annotation UI.
applicable_to : str, optional¶: TagApplicableTo: ALL, IMAGES_ONLY, OBJECTS_ONLY.
applicable_classes : List[str], optional¶: Restrict to specific class names.
target_type : str, optional¶: TagTargetType: ALL, FRAME_BASED, GLOBAL.
frame_range_min_length : int, optional¶: Minimum length (in frames, inclusive) of a finished frame range tag. 0 or None means no limit.
frame_range_max_length : int, optional¶: Maximum length (in frames, inclusive) of a finished frame range tag. 0 or None means no limit.

Raises:

ValueError – If value_type or color is invalid; ONEOF_STRING requires possible_values; frame range limits are negative or min is greater than max.

Usage Example:

import supervisely as sly

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
meta_cat = sly.TagMeta('cat', sly.TagValueType.ANY_STRING, applicable_to=sly.TagApplicableTo.OBJECTS_ONLY)
colors = ["brown", "white", "black"]
meta_coat = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING, possible_values=colors, color=[255, 120, 0])

# frame range tag that must cover between 5 and 30 frames
meta_running = sly.TagMeta(
    'running',
    sly.TagValueType.NONE,
    target_type=sly.TagTargetType.FRAME_BASED,
    frame_range_min_length=5,
    frame_range_max_length=30,
)

Methods

`add_possible_value`	Adds a new value to the list of possible values.
`clone`	Clone makes a copy of TagMeta with new fields, if fields are given, otherwise it will use original TagMeta fields.
`from_json`	Convert a json dict to TagMeta.
`get_header_ptable`	get_header_ptable
`get_row_ptable`	get_row_ptable
`is_compatible`	Check if the current TagMeta instance is compatible with another TagMeta instance.
`is_valid_frame_range`	Check a frame range against this TagMeta's length limits.
`is_valid_frame_range_length`	Check a frame range length against this TagMeta's limits.
`is_valid_value`	Checks value against object value type to make sure that value is valid.
`key`
`to_json`	Convert the TagMeta to a json dict.
`with_frame_range_length_limits`	Return a copy of this TagMeta with the given frame range length limits.

Attributes

`applicable_classes`	Applicable classes.
`applicable_to`	Tag applicability to objects, images, or both.
`color`	`[R,G,B]` color.
`frame_range_length_limits`	Both frame range length limits as a `(min_length, max_length)` pair.
`frame_range_max_length`	Maximum length (in frames, inclusive) of a finished frame range tag.
`frame_range_min_length`	Minimum length (in frames, inclusive) of a finished frame range tag.
`has_frame_range_length_limits`	Whether at least one frame range length limit is active.
`hotkey`	Hotkey for Tag in annotation tool UI.
`name`	Name.
`possible_values`	Possible values of object.
`sly_id`	Tag ID in Supervisely server.
`target_type`	Tag target type (scope) - entities, frames or both.
`value_type`	Value type.

classmethod from_json(data)[source]¶

Convert a json dict to TagMeta. Read more about Supervisely format.

Parameters:

data : dict¶: TagMeta in json format as a dict.

Returns:

TagMeta object

Return type:

TagMeta

Usage Example:

import supervisely as sly

data = {
    "name":"Color",
    "value_type":"oneof_string",
    "color":"#FF7800",
    "values":[
        "brown",
        "white",
        "black",
        "red",
        "blue",
        "yellow",
        "grey"
    ],
    "hotkey":"M",
    "applicable_type":"all",
    "classes":[
        "car",
        "bicycle"
    ]
}

meta_colors = sly.TagMeta.from_json(data)

classmethod get_header_ptable()[source]¶

add_possible_value(value)[source]¶

Adds a new value to the list of possible values.

Parameters:

value : str¶: New value that will be added to a list.

Raises:

ValueError – if object’s value type is not “oneof_string” or already exists in a list

Returns:

New instance of TagMeta object

Return type:

TagMeta

Usage Example:

import supervisely as sly

#In order to add possible values, you must first initialize a variable where all possible values will be stored if it doesnt exist already
colors = ["brown", "white", "black", "red", "chocolate", "gold", "grey"]
meta_coat_color = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING, possible_values=colors, applicable_classes=["dog", "cat"])

print(meta_coat_color.possible_values)
# Output: ['brown', 'white', 'black', 'red', 'chocolate', 'gold', 'grey']

#Now we can add new possible value to our TagMeta
# Remember that TagMeta object is immutable, and we need to assign new instance of TagMeta to a new variable
meta_coat_color = meta_coat_color.add_possible_value("bald (no coat)")

print(meta_coat_color.possible_values)
# Output: ['brown', 'white', 'black', 'red', 'chocolate', 'gold', 'grey', 'bald (no coat)']

clone(name=None, value_type=None, possible_values=None, color=None, sly_id=None, hotkey=None, applicable_to=None, applicable_classes=None, target_type=None, frame_range_min_length=None, frame_range_max_length=None)[source]¶

Clone makes a copy of TagMeta with new fields, if fields are given, otherwise it will use original TagMeta fields.

Parameters:

name : str¶: Tag name.
value_type : str¶: Tag value type.
possible_values : List[str], optional¶: List of possible values.
color : List[int, int, int], optional¶: [R, G, B] color, generates random color by default.
sly_id : int, optional¶: Tag ID in Supervisely server.
hotkey : str, optional¶: Hotkey for Tag in annotation tool UI.
applicable_to : str, optional¶: Defines applicability of Tag only to images, objects or both.
applicable_classes : List[str], optional¶: Defines applicability of Tag only to certain classes.
target_type : str, optional¶: Defines Tag target type (scope) - entities, frames or both.
frame_range_min_length : int, optional¶: Minimum length (in frames, inclusive) of a finished frame range tag. Pass 0 to disable the limit; None keeps the current value. with_frame_range_length_limits() sets both limits at once.
frame_range_max_length : int, optional¶: Maximum length (in frames, inclusive) of a finished frame range tag. Pass 0 to disable the limit; None keeps the current value.

Returns:

New instance of TagMeta object

Return type:

TagMeta

Usage Example:

import supervisely as sly

#Original TagMeta
meta_dog_breed = sly.TagMeta('breed', sly.TagValueType.NONE)

# TagMetas made of original TagMeta
# Remember that TagMeta class object is immutable, and we need to assign new instance of TagMeta to a new variable
A_breeds = ["Affenpinscher", "Afghan Hound", "Aidi", "Airedale Terrier", "Akbash Dog", "Akita"]
meta_A_breed = meta_dog_breed.clone(value_type=sly.TagValueType.ONEOF_STRING, possible_values=A_breeds, hotkey='A')

B_breeds = ["Basset Fauve de Bretagne", "Basset Hound", "Bavarian Mountain Hound", "Beagle", "Beagle-Harrier", "Bearded Collie"]
meta_B_breed = meta_A_breed.clone(possible_values=B_breeds, hotkey='B')

C_breeds = ["Cairn Terrier", "Canaan Dog", "Canadian Eskimo Dog", "Cane Corso", "Cardigan Welsh Corgi", "Carolina Dog"]
meta_C_breed = meta_B_breed.clone(possible_values=C_breeds, hotkey='C')

get_row_ptable()[source]¶

is_compatible(other)[source]¶: Check if the current TagMeta instance is compatible with another TagMeta instance.

is_valid_frame_range(start_frame, end_frame)[source]¶

Check a frame range against this TagMeta’s length limits.

The range is inclusive on both ends, matching the server: frames 10 to 12 have length 3. Reversed ranges are accepted as-is.

Parameters:

start_frame : int¶: First frame of the range.
end_frame : int¶: Last frame of the range.

Returns:

True if the range length satisfies both active limits, otherwise False

Return type:

bool

Usage Example:

meta_running = sly.TagMeta(
    'running', sly.TagValueType.NONE, frame_range_min_length=5, frame_range_max_length=30
)

meta_running.is_valid_frame_range(10, 12)  # False, length is 3
meta_running.is_valid_frame_range(10, 19)  # True, length is 10

is_valid_frame_range_length(length)[source]¶

Check a frame range length against this TagMeta’s limits.

Parameters:

length : int¶: Frame range length in frames.

Returns:

True if the length satisfies both active limits, otherwise False

Return type:

bool

Usage Example:

meta_running = sly.TagMeta(
    'running', sly.TagValueType.NONE, frame_range_min_length=5, frame_range_max_length=30
)

meta_running.is_valid_frame_range_length(3)   # False
meta_running.is_valid_frame_range_length(10)  # True

is_valid_value(value)[source]¶

Checks value against object value type to make sure that value is valid.

Parameters:

value : str¶: Value to check.

Returns:

True if value is supported, otherwise False

Return type:

bool

Usage Example:

import supervisely as sly

# Initialize TagMeta
meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)

# Check what value type is in our Tagmeta
print(meta_dog.value_type)
# Output: 'any_string'

# Our TagMeta has 'any_string' value type, it means only 'string' values will work with it
# Let's check if value is valid for our TagMeta
meta_dog.is_valid_value('Woof!')            # True
meta_dog.is_valid_value(555)                # False

# TagMetas with 'any_number' value type are compatible with 'int' and 'float' values
meta_quantity = sly.TagMeta('quantity', sly.TagValueType.ANY_NUMBER)

meta_quantity.is_valid_value('new string value') # False
meta_quantity.is_valid_value(555)                # True
meta_quantity.is_valid_value(3.14159265359)      # True

to_json()[source]¶

Convert the TagMeta to a json dict. Read more about Supervisely format.

Returns:

Json format as a dict

Return type:

dict

Usage Example:

import supervisely as sly

colors = ["brown", "white", "black", "red", "blue", "yellow", "grey"]
meta_color = sly.TagMeta(
    'Color',
    sly.TagValueType.ONEOF_STRING,
    possible_values=colors,
    color=[255, 120, 0],
    hotkey="M",
    applicable_classes=["car", "bicycle"]
)


meta_color_json = meta_color.to_json()
print(meta_color_json)
# Output: {
#     "name":"Color",
#     "value_type":"oneof_string",
#     "color":"#FF7800",
#     "values":[
#         "brown",
#         "white",
#         "black",
#         "red",
#         "blue",
#         "yellow",
#         "grey"
#     ],
#     "hotkey":"M",
#     "applicable_type":"all",
#     "classes":[
#         "car",
#         "bicycle"
#     ]
# }

with_frame_range_length_limits(min_length=None, max_length=None)[source]¶

Return a copy of this TagMeta with the given frame range length limits.

Unlike clone(), both limits are always replaced, so passing None (or 0) disables the corresponding limit instead of keeping the current value.

Parameters:

min_length : int, optional¶: Minimum frame range length, 0 or None to disable.
max_length : int, optional¶: Maximum frame range length, 0 or None to disable.

Raises:

ValueError – If a limit is negative, or min_length is greater than max_length while both are active.

Returns:

New instance of TagMeta object

Return type:

TagMeta

Usage Example:

import supervisely as sly

meta_running = sly.TagMeta('running', sly.TagValueType.NONE)

# tag must cover between 5 and 30 frames
meta_running = meta_running.with_frame_range_length_limits(5, 30)

# drop both limits
meta_running = meta_running.with_frame_range_length_limits()

property applicable_classes : list[str]¶

Applicable classes.

Returns:

List of applicable classes

Return type:

List[str]

Usage Example:

# Imagine we have 2 ObjClasses in our Project
class_car = sly.ObjClass(name='car', geometry_type='rectangle')
class_bicycle = sly.ObjClass(name='bicycle', geometry_type='rectangle')

# You can put a "string" with ObjClass name or use ObjClass.name
meta_vehicle = sly.TagMeta('vehicle', sly.TagValueType.NONE, applicable_classes=["car", class_bicycle.name])

print(meta_vehicle.applicable_classes)
# Output: ['car', 'bicycle']

property applicable_to : str¶

Tag applicability to objects, images, or both.

Returns:

Applicability

Return type:

str

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE, applicable_to=IMAGES_ONLY)

print(meta_dog.applicable_to)
# Output: 'imagesOnly'

property color : list[int, int, int]¶

[R,G,B] color.

Returns:

Color

Return type:

List[int, int, int]

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE, color=[255,120,0])

print(meta_dog.color)
# Output: [255,120,0]

property frame_range_length_limits : tuple[int, int]¶

Both frame range length limits as a (min_length, max_length) pair. 0 in either position means that limit is disabled.

Returns:: Minimum and maximum frame range length
Return type:: Tuple[int, int]

property frame_range_max_length : int¶

Maximum length (in frames, inclusive) of a finished frame range tag. 0 means the limit is disabled.

Returns:

Maximum frame range length

Return type:

int

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE, frame_range_max_length=30)

print(meta_dog.frame_range_max_length)
# Output: 30

property frame_range_min_length : int¶

Minimum length (in frames, inclusive) of a finished frame range tag. 0 means the limit is disabled.

Returns:

Minimum frame range length

Return type:

int

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE, frame_range_min_length=5)

print(meta_dog.frame_range_min_length)
# Output: 5

property has_frame_range_length_limits : bool¶

Whether at least one frame range length limit is active.

Returns:: True if any limit is set to a non-zero value, otherwise False
Return type:: bool

property hotkey : str¶

Hotkey for Tag in annotation tool UI.

Returns:

Hotkey

Return type:

str

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE, hotkey='M')

print(meta_dog.hotkey)
# Output: 'M'

property name : str¶

Name.

Returns:

Name

Return type:

str

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
print(meta_dog.name)
# Output: 'dog'

property possible_values : list[str]¶

Possible values of object. This is a required field if object has “oneof_string” value type.

Raises:

ValueError – if list of possible values is not defined or TagMeta value_type is not “oneof_string”.

Returns:

List of possible values

Return type:

List[str]

Usage Example:

# List of possible values
coat_colors = ["brown", "white", "black", "red", "chocolate", "gold", "grey"]

# TagMeta
meta_coat_color = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING, possible_values=coat_colors)

print(meta_coat_color.possible_values)
# Output: ['brown', 'white', 'black', 'red', 'chocolate', 'gold', 'grey']

# Note that this is a required field if object has "oneof_string" value type.
meta_coat_color = sly.TagMeta('coat color', sly.TagValueType.ONEOF_STRING)
# Output: ValueError: TagValueType is ONEOF_STRING. List of possible values have to be defined.

property sly_id : int¶

Tag ID in Supervisely server.

Returns:

Return type:

int

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE, sly_id=38584)

print(meta_dog.sly_id)
# Output: 38584

property target_type : str¶

Tag target type (scope) - entities, frames or both.

Returns:

Target type

Return type:

str

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE, target_type=TagTargetType.FRAME_BASED)

print(meta_dog.target_type)
# Output: 'framesOnly'

property value_type : str¶

Value type. See possible value types in TagValueType.

Returns:

Value type

Return type:

str

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
meta_dog.value_type == sly.TagValueType.ANY_STRING # True

print(meta_dog.value_type)
# Output: 'any_string'