VideoTagApi

class VideoTagApi(api)[source]

Bases: TagApi

API for working with VideoTag. VideoTagApi object is immutable.

Parameters:
api

Api object to use for API connection.

Methods

add

Add VideoTag to video.

add_tag

Add VideoTag to video.

add_tags_collection_to_objects

Add a TagCollection to each figure/object.

add_to_entities_json

Bulk add tags to entities (images, videos, pointclouds, volumes) in a project.

add_to_objects

Add tags to existing figures/objects.

append_to_entity

Add tags to entity in project with given ID.

append_to_objects

Add Tags to Annotation Objects for a specific entity (image etc.).

append_to_objects_json

Add Tags to Annotation Objects for specific entity (image etc.).

convert_info_to_json

Convert information about an entity to a dictionary.

create

Create a single tag meta (tag definition) in a project.

create_bulk

Create tag metas (tag definitions) in a project.

download_list

Download VideoTagCollection with all tags of the video.

exists

Checks if an entity with the given parent_id and name exists

get_free_name

Generates a free name for an entity with the given parent_id and name.

get_info_by_id

Get information about an entity by its ID from the Supervisely server.

get_info_by_name

Get information about an entity by its name from the Supervisely server.

get_list

Get list of tags for a given project ID.

get_list_all_pages

Get list of all or limited quantity entities from the Supervisely server.

get_list_all_pages_generator

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

get_list_idx_page_async

Get the list of items for a given page number.

get_list_page_generator_async

Yields list of images in dataset asynchronously page by page.

get_name_to_id_map

Get dictionary with mapping tag name to tag ID for a given project ID.

info_sequence

NamedTuple TagInfo information about Tag.

info_tuple_name

Get string name of NamedTuple for class.

remove

Remove tag from video.

remove_from_video

Remove tag from video.

update_annotation_object_custom_data

Update custom data of an annotation object tag assignment.

update_custom_data

Update custom data of an entity tag assignment - an image, video, volume or point cloud tag.

update_figure_custom_data

Update custom data of a figure (object) tag assignment.

update_frame_range

Update VideoTag frame range in video.

update_meta

Update an existing tag meta (tag definition) on the server.

update_value

Update VideoTag value.

Attributes

MAX_WAIT_ATTEMPTS

Maximum number of attempts that will be made to wait for a certain condition to be met.

WAIT_ATTEMPT_TIMEOUT_SEC

Number of seconds for intervals between attempts.

InfoType

alias of TagInfo

classmethod convert_info_to_json(info)

Convert information about an entity to a dictionary.

Parameters:
info : NamedTuple

Information about the entity.

Returns:

Dictionary with information about the entity.

Return type:

dict

static info_sequence()

NamedTuple TagInfo information about Tag.

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

info_sequence = api.video.tag.info_sequence()
static info_tuple_name()

Get string name of NamedTuple for class.

Returns:

NamedTuple name.

Return type:

str

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

tuple_name = api.video.tag.info_tuple_name()
print(tuple_name) # TagInfo
add(video_id, tag, update_id_inplace=True)[source]

Add VideoTag to video.

Parameters:
video_id : int

Video ID in Supervidely.

tag

VideoTag object.

update_id_inplace=True

Specify if

Returns:

VideoTag ID in Supervisely

Return type:

int

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 19402023

tag_meta = sly.TagMeta('Animal', sly.TagValueType.NONE)
# Tag has to exists in project.
tag = VideoTag(tag_meta)

api.video.tag.add(video_id=video_id, tag=tag)
add_tag(project_meta_tag_id, video_id, value=None, frame_range=None, is_finished=True, non_final_value=False)[source]

Add VideoTag to video.

Parameters:
project_meta_tag_id : int

TagMeta ID in Supervisely.

video_id : int

Video ID in Supervidely.

value : str or int

New VideoTag value.

frame_range : List[int]

New VideoTag frame range.

is_finished : bool

Specify if the tag is finished.

non_final_value : bool

Specify if the tag value is non-final.

Returns:

API response in JSON format.

Return type:

dict

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

new_frame_range = [5, 10]
response = api.video.tag.add_tag(project_meta_tag_id, video_id, 'tag_value', frame_range)
add_tags_collection_to_objects(project_id, tags_map, batch_size=100, log_progress=False, is_video_multi_view=False, entity_id=None)

Add a TagCollection to each figure/object.

  • Images projects: mapping is {figure_id: TagCollection, ...}

  • Video / pointcloud / volume / pointcloud episodes projects: mapping is {object_id: TagCollection, ...}

All objects must belong to entities of the same project.

Parameters:
project_id : int

Project ID in Supervisely.

tags_map : Dict[int, Any]

Dictionary with mapping figure/object ID to tags collection.

batch_size : int

Number of tags to add in one request.

log_progress : bool

If True, will display a progress bar.

is_video_multi_view : bool

If True, indicates that the entity is a multi-view video.

entity_id : Optional[int]

ID of the entity in Supervisely to add a tag to its objects. Required if is_video_multi_view is True.

Returns:

List of tags infos as dictionaries.

Return type:

List[Dict[str, Union[str, int, None]]]

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

project_id = 12345

tag_meta = sly.TagMeta("tag_name", sly.TagValueType.ANY_STRING)
meta = sly.ProjectMeta(tag_metas=[tag_meta])
meta = sly.ProjectMeta.from_json(api.project.update_meta(project_id, meta))
tag_meta = meta.get_tag_meta("tag_name")

# for images project:
tag_map = {
    652959: sly.TagCollection([sly.Tag(tag_meta, value="v1"), sly.Tag(tag_meta, value="v2"), ...]),
    652958: sly.TagCollection([sly.Tag(tag_meta, value="v3"), sly.Tag(tag_meta, value="v4"), ...]),
    ...
}
api.image.tag.add_tags_to_objects(project_id, tag_map)

# for videos projects (frameRange is optional):
tag_map = {
    652959: sly.VideoTagCollection([sly.VideoTag(tag_meta, value="v1", frameRange=[1, 10]), ...]),
    652958: sly.VideoTagCollection([sly.VideoTag(tag_meta, value="v2", frameRange=[4, 12]), ...]),
    ...
}
api.video.tag.add_to_objects_json_batch(project_id, tag_map)
add_to_entities_json(project_id, tags_list, batch_size=100, log_progress=False)

Bulk add tags to entities (images, videos, pointclouds, volumes) in a project. Not supported for pointcloud episodes projects. All entities must belong to the same project. The frameRange field in a tag object within the tags list is optional and is supported only for video projects.

The tags_list example:

[{“tagId”: 12345, “entityId”: 54321, “value”: “tag_value”}, …].

or with frameRange:

[{“tagId”: 12345, “entityId”: 54321, “value”: “tag_value”, “frameRange”: [1, 10]}, …].

Parameters:
project_id : int

Project ID in Supervisely.

tags_list

List of tag object infos as dictionaries (e.g. {“tagId”: 12345, “entityId”: 54321, “value”: “tag_value”}).

batch_size : int

Number of tags to add in one request.

log_progress : bool

If True, will display a progress bar.

Returns:

List of tags IDs.

Return type:

List[int]

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

tags_list = [
    {
        "tagId": 25926,
        "entityId": 652959,
        "value": None,  # optional for tag with type 'None'
        "frameRange": [1, 10],  # optional (only for video)
    },
    {
        "tagId": 25927,
        "entityId": 652959,
        "value": "v1"
    },
    {
        "tagId": 25927,
        "entityId": 652958,
        "value": "v2"
    }
]
api.image.tag.add_to_entities_json(project_id=12345, tags_list=tags_list)
add_to_objects(project_id, tags_list, batch_size=100, log_progress=False, progress=None, is_video_multi_view=False, entity_id=None)

Add tags to existing figures/objects.

  • Images projects: tags are added to existing figures (labels). Example element of tags_list: {"tagId": 12345, "figureId": 54321, "value": "tag_value"}.

  • Video / pointcloud / volume / pointcloud episodes projects: tags are added to existing objects. frameRange is optional and is supported only for video and pointcloud episodes projects. Example element of tags_list: {"tagId": 12345, "objectId": 54321, "value": "tag_value"}, or {"tagId": 12345, "objectId": 54321, "value": "tag_value", "frameRange": [1, 10]}.

All objects must belong to entities of the same project.

Parameters:
project_id : int

Project ID in Supervisely.

tags_list : List[dict]

List of tag object infos as dictionaries.

batch_size : int

Number of tags to add in one request.

log_progress : bool

If True, will display a progress bar.

progress : Optional[tqdm_sly]

Progress bar object to display progress.

is_video_multi_view : bool

If True, indicates that the entity is a multi-view video.

entity_id : Optional[int]

ID of the entity in Supervisely to add a tag to its objects. Required if is_video_multi_view is True.

Returns:

List of tags infos as dictionaries.

Return type:

List[Dict[str, Union[str, int, None]]]

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

tags_list = [
    {
        "tagId": 25926,
        "figureId": 652959,
        "value": None,  # optional for tag with type 'None'
        "frameRange": [1, 10],  # optional (only for video / pointcloud episodes)
    },
    {
        "tagId": 25927,
        "figureId": 652959,
        "value": "v1"
    },
    {
        "tagId": 25927,
        "figureId": 652958,
        "value": "v2",
    }
]
response = api.image.tag.add_to_figures(12345, tag_list)

print(response)
# Output:
#    [
#        {
#            "id": 80421101,
#            "tagId": 25926,
#            "figureId": 652959,
#            "value": None
#        },
#        {
#            "id": 80421102,
#            "tagId": 25927,
#            "figureId": 652959,
#            "value": "v1"
#        },
#        {
#            "id": 80421103,
#            "tagId": 25927,
#            "figureId": 652958,
#            "value": "v2"
#        }
#    ]
append_to_entity(entity_id, project_id, tags, key_id_map=None)

Add tags to entity in project with given ID.

Parameters:
entity_id : int

ID of the entity in Supervisely to add a tag to

project_id : int

Project ID in Supervisely.

tags

Collection of tags

key_id_map=None

KeyIdMap object. See class KeyIdMap.

Returns:

List of tags IDs

Return type:

list

append_to_objects(entity_id, project_id, objects, key_id_map, is_video_multi_view=False)

Add Tags to Annotation Objects for a specific entity (image etc.).

Parameters:
entity_id : int

ID of the entity in Supervisely to add a tag to its objects

project_id : int

Project ID in Supervisely. Uses to get tag name to tag ID mapping.

objects

Collection of annotation objects.

key_id_map

KeyIdMap object.

is_video_multi_view : bool

If True, indicates that the entity is a multi-view video.

Returns:

List of tags IDs

Return type:

list

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

img_id = 19373170
img_info = api.
append_to_objects_json(entity_id, tags_json, project_id=None, is_video_multi_view=False)

Add Tags to Annotation Objects for specific entity (image etc.).

Parameters:
entity_id : int

ID of the entity in Supervisely to add a tag to its objects

tags_json : dict

Collection of tags in JSON format

project_id : int, optional

Project ID in Supervisely. Uses to get tag name to tag ID mapping. Not required if multi_view is True.

is_video_multi_view : bool

If True, indicates that the entity is a multi-view video.

Returns:

List of tags IDs

Return type:

list

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

tags_list = [
    {"tagId": 25926, "objectId": 652959, "value": None},
    {"tagId": 25927, "objectId": 652959, "value": "v1"},
    {"tagId": 25927, "objectId": 652958, "value": "v2"},
]
response = api.video.tag.append_to_objects_json(12345, tags_list)

print(response)
# Output:
#    [
#        80421101,
#        80421102,
#        80421103
#    ]
create(project_id, tag_meta)

Create a single tag meta (tag definition) in a project.

Parameters:
project_id : int

Project ID in Supervisely.

tag_meta : TagMeta

Tag meta to create. Its name must be unique within the project.

Raises:

ValueError – If the TagMeta references a class that the project does not have.

Returns:

Created tag meta with “id” and “title”

Return type:

dict

Usage Example:
import supervisely as sly

api = sly.Api.from_env()

# frame range tag that must cover between 5 and 30 frames
tag = api.video.tag.create(
    project_id=123,
    tag_meta=sly.TagMeta(
        "running",
        sly.TagValueType.NONE,
        target_type=sly.TagTargetType.FRAME_BASED,
        frame_range_min_length=5,
        frame_range_max_length=30,
    ),
)
create_bulk(project_id, tag_metas)

Create tag metas (tag definitions) in a project.

Tag names must be unique within the project. TagMeta.applicable_classes holds class names, while the endpoint expects class IDs, so the names are resolved against the project’s classes - one extra request, and only when at least one tag meta restricts its classes.

Parameters:
project_id : int

Project ID in Supervisely.

tag_metas : TagMeta or List[TagMeta]

Tag metas to create. A single TagMeta is also accepted.

Raises:

ValueError – If a TagMeta references a class that the project does not have.

Returns:

List of created tag metas, each with “id” and “title”

Return type:

List[dict]

Usage Example:
import supervisely as sly

api = sly.Api.from_env()

created = api.video.tag.create_bulk(
    project_id=123,
    tag_metas=[
        sly.TagMeta(
            "running",
            sly.TagValueType.NONE,
            target_type=sly.TagTargetType.FRAME_BASED,
            frame_range_min_length=5,
            frame_range_max_length=30,
        ),
        sly.TagMeta(
            "standing",
            sly.TagValueType.NONE,
            target_type=sly.TagTargetType.FRAME_BASED,
        ),
    ],
)
download_list(id, project_meta)[source]

Download VideoTagCollection with all tags of the video.

Parameters:
id : int

Video ID in Supervidely.

project_meta_tag_id : int

TagMeta ID in Supervisely.

Returns:

All tags of the video in VideoTagCollection format.

Return type:

VideoTagCollection

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 19402023
project_id = 17209

meta_json = api.project.get_meta(project_id)
project_meta = sly.ProjectMeta.from_json(meta_json)

tags_collection = api.video.tag.download_list(video_id, project_meta)
exists(parent_id, name)

Checks if an entity with the given parent_id and name exists

Parameters:
parent_id : int

ID of the parent entity.

name : str

Name of the entity.

Returns:

Returns True if entity exists, and False if not

Return type:

bool

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
exists = api.image.exists(dataset_id, name)
print(exists) # True
get_free_name(parent_id, name)

Generates a free name for an entity with the given parent_id and name. Adds an increasing suffix to original name until a unique name is found.

Parameters:
parent_id : int

ID of the parent entity.

name : str

Name of the entity.

Returns:

Returns free name.

Return type:

str

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
free_name = api.image.get_free_name(dataset_id, name)
print(free_name) # IMG_0315_001.jpeg
get_info_by_id(id)

Get information about an entity by its ID from the Supervisely server.

Parameters:
id : int

ID of the entity.

get_info_by_name(parent_id, name, fields=[])

Get information about an entity by its name from the Supervisely server.

Parameters:
parent_id : int

ID of the parent entity.

name : str

Name of the entity for which the information is being retrieved.

fields : List[str]

The list of api fields which will be returned with the response.

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55832
name = "IMG_0315.jpeg"
info = api.image.get_info_by_name(dataset_id, name)
print(info)
# Output: ImageInfo(id=19369643, name='IMG_0315.jpeg', ...)
get_list(project_id, filters=None)

Get list of tags for a given project ID.

Parameters:
project_id : int

Project ID in Supervisely.

filters : List[Dict[str, str]], optional

List of parameters to sort output tags. See: https://api.docs.supervisely.com/#tag/Advanced/paths/~1tags.list/get

Returns:

List of the tags from the project with given id.

Return type:

list

get_list_all_pages(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)

Get list of all or limited quantity entities from the Supervisely server.

Parameters:
method : str

Request method name

data : dict

Dictionary with request body info

progress_cb : Progress, optional

Function for tracking download progress.

convert_json_info_cb : Callable, optional

Function for convert json info

limit : int, optional

Number of entity to retrieve

return_first_response : bool, optional

Specify if return first response

Returns:

List of entities.

Return type:

List[dict]

get_list_all_pages_generator(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

Parameters:
method : str

Request method name

data : dict

Dictionary with request body info

progress_cb : Progress, optional

Function for tracking download progress.

convert_json_info_cb : Callable, optional

Function for convert json info

limit : int, optional

Number of entity to retrieve

return_first_response : bool, optional

Specify if return first response

async get_list_idx_page_async(method, data)

Get the list of items for a given page number. Page number is specified in the data dictionary.

Parameters:
method : str

Method to call for listing items.

data : dict

Data to pass to the API method.

Returns:

List of items.

Return type:

Tuple[int, List[NamedTuple]]

async get_list_page_generator_async(method, data, pages_count=None, semaphore=None)

Yields list of images in dataset asynchronously page by page.

Parameters:
method : str

Method to call for listing items.

data : dict

Data to pass to the API method.

pages_count : int, optional

Preferred number of pages to retrieve if used with a per_page limit. Will be automatically adjusted if the pagesCount differs from the requested number.

semaphore=None

Semaphore for limiting the number of simultaneous requests.

Returns:

List of images in dataset.

Return type:

AsyncGenerator[List[ImageInfo]]

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

method = 'images.list'
data = {'datasetId': 123456}

loop = sly.utils.get_or_create_event_loop()
images = loop.run_until_complete(api.image.get_list_generator_async(method, data))
get_name_to_id_map(project_id, refresh=False)

Get dictionary with mapping tag name to tag ID for a given project ID.

Parameters:
project_id : int

Project ID in Supervisely.

refresh : bool

Read the project’s tags again even if a map is cached.

Returns:

Dictionary with mapping tag name to tag id for a given project ID.

Return type:

dict

Inside an open ApiContext the map is cached, and a tag meta added meanwhile is not in it - pass refresh=True to read it again.

remove(tag)[source]

Remove tag from video.

:param VideoTag in Supervisely. :type tag: VideoTag :returns: None :rtype: None

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

api.video.tag.remove(video_tag)
remove_from_video(tag_id)[source]

Remove tag from video.

Parameters:
tag_id : int

VideoTag ID in Supervisely.

Returns:

None

Return type:

None

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

api.video.tag.remove_from_video(video_tag_id)
update_annotation_object_custom_data(tag_id, custom_data, update_strategy=None)

Update custom data of an annotation object tag assignment.

Parameters:
tag_id : int

ID of the annotation object tag assignment.

custom_data : dict

Arbitrary JSON. See update_custom_data().

update_strategy : str, optional

TagCustomDataUpdateStrategy value, or None.

Returns:

The stored custom data after the update

Return type:

dict

Usage Example:
stored = api.video.tag.update_annotation_object_custom_data(
    tag_id=311,
    custom_data={"track_quality": "good", "frames_checked": [0, 120]},
)
update_custom_data(tag_id, custom_data, update_strategy=None)

Update custom data of an entity tag assignment - an image, video, volume or point cloud tag.

Parameters:
tag_id : int

ID of the tag assignment, not of the project tag meta.

custom_data : dict

Arbitrary JSON. Nested objects and arrays are allowed; keys are never renamed or stripped.

update_strategy : str, optional

TagCustomDataUpdateStrategy value. merge (the server default) deep-merges into the stored object; replace overwrites it wholesale and is what removes a key. None leaves the choice to the server.

Returns:

The stored custom data after the update

Return type:

dict

Usage Example:
import supervisely as sly
from supervisely.api.entity_annotation.tag_api import (
    TagCustomDataUpdateStrategy,
)

api = sly.Api.from_env()

stored = api.image.tag.update_custom_data(
    tag_id=1024,
    custom_data={"confidence": 0.92, "source": "model_v3"},
    update_strategy=TagCustomDataUpdateStrategy.REPLACE,
)
print(stored)
# Output: {'confidence': 0.92, 'source': 'model_v3'}
update_figure_custom_data(tag_id, custom_data, update_strategy=None)

Update custom data of a figure (object) tag assignment.

Parameters:
tag_id : int

ID of the figure tag assignment.

custom_data : dict

Arbitrary JSON. See update_custom_data().

update_strategy : str, optional

TagCustomDataUpdateStrategy value, or None.

Returns:

The stored custom data after the update

Return type:

dict

Usage Example:
stored = api.image.tag.update_figure_custom_data(
    tag_id=5077,
    custom_data={"occluded": True, "verified_by": "qa_team"},
)
update_frame_range(tag_id, frame_range)[source]

Update VideoTag frame range in video.

Parameters:
tag_id : int

VideoTag ID in Supervisely.

frame_range : List[int]

New VideoTag frame range.

Returns:

None

Return type:

None

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

new_frame_range = [5, 10]
api.video.tag.update_frame_range(video_tag_id, new_frame_range)
update_meta(id, project_id=None, name=None, color=None, hotkey=None, applicable_to=None, applicable_classes=None, target_type=None, frame_range_min_length=None, frame_range_max_length=None)

Update an existing tag meta (tag definition) on the server.

This is a partial update: only the arguments you pass are changed. Pass 0 to drop a frame range length limit - there is no separate on/off switch on the server side, a limit is active only while its value is non-zero.

The endpoint requires “title” and “color” in every request, so pass either both of them or project_id, which lets the current values be read from the server.

Note

Against instances that predate the fix for supervisely/issues#6077, this endpoint reset applicableType and erased the class list whenever a partial settings body omitted them - so even an edit that only touched a frame range limit wiped both, and the class list could not be edited on its own. On such instances pass applicable_to explicitly, or use update_meta() instead.

Parameters:
id : int

Tag meta ID in Supervisely.

project_id : int, optional

Project the tag belongs to. Only needed to look up the current name and color when they are not passed explicitly.

name : str, optional

New tag name.

color : str or List[int], optional

New color as a HEX string (“#FF7800”) or an [R, G, B] list.

hotkey : str, optional

New single-character hotkey.

applicable_to : str, optional

TagApplicableTo: ALL, IMAGES_ONLY, OBJECTS_ONLY.

applicable_classes : List[str], optional

Names of the classes the tag is restricted to, as on TagMeta. Only meaningful for OBJECTS_ONLY. Resolved to the IDs this endpoint expects, so project_id is required alongside. An empty list clears the restriction.

target_type : str, optional

TagTargetType: ALL, FRAME_BASED, GLOBAL. Videos and point cloud episodes only.

frame_range_min_length : int, optional

Minimum length (in frames, inclusive) of a finished frame range tag. 0 removes the limit, None keeps the stored value.

frame_range_max_length : int, optional

Maximum length (in frames, inclusive) of a finished frame range tag. 0 removes the limit, None keeps the stored value.

Raises:

ValueError – If nothing to update is given, the current name and color can neither be derived nor looked up, or the frame range limits are negative or min is greater than max.

Returns:

Updated tag meta with “id” and “title”

Return type:

dict

Usage Example:
import supervisely as sly

api = sly.Api.from_env()

# tighten the limits
api.video.tag.update_meta(
    id=456, project_id=123, frame_range_min_length=10, frame_range_max_length=20
)

# drop the upper limit, keep the lower one
api.video.tag.update_meta(id=456, project_id=123, frame_range_max_length=0)
update_value(tag_id, tag_value)[source]

Update VideoTag value.

Parameters:
tag_id : int

VideoTag ID in Supervisely.

tag_value : str or int

New VideoTag value.

Returns:

None

Return type:

None

Usage Example:
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

api.video.tag.update_value(video_tag_id, 'new_tag_value')