LabelingJobApi

class LabelingJobApi[source]

Bases: supervisely.api.module_api.RemoveableBulkModuleApi, supervisely.api.module_api.ModuleWithStatus

API for working with Labeling Jobs. LabelingJobApi object is immutable.

Parameters
api : Api

API connection to the server.

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()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

jobs = api.labeling_job.get_list(9) # api usage example

Methods

archive

Archives Labeling Job with given ID.

create

Creates Labeling Job and assigns given Users to it.

exists

Checks if an entity with the given parent_id and name exists

get_activity

rtype

DataFrame

get_annotations

Return annotations for given image ids from labeling job with given id.

get_free_name

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

get_info_by_id

Get Labeling Job information by ID.

get_info_by_name

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

get_list

Get list of information about Labeling Job in the given Team.

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_project_meta

Returns project meta with classes and tags used in the labeling job with given id.

get_stats

Get stats of given Labeling Job ID.

get_status

Get status of Labeling Job with given ID.

info_sequence

NamedTuple LabelingJobInfo information about Labeling Job.

info_tuple_name

NamedTuple name - LabelingJobInfo.

raise_for_status

remove

Remove an entity with the specified ID from the Supervisely server.

remove_batch

Remove entities in batches from the Supervisely server.

set_status

Sets Labeling Job status.

stop

Makes Labeling Job unavailable for labeler with given User ID.

wait

Wait for a Labeling Job to change to the expected target status.

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 supervisely.api.module_api.LabelingJobInfo

class Status[source]

Bases: supervisely.collection.str_enum.StrEnum

Labeling Job status.

COMPLETED = 'completed'
IN_PROGRESS = 'in_progress'
ON_REVIEW = 'on_review'
PENDING = 'pending'
STOPPED = 'stopped'
archive(id)[source]

Archives Labeling Job with given ID.

Parameters
id : int

Labeling Job ID in Supervisely.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

api.labeling_job.archive(23)
create(name, dataset_id, user_ids, readme=None, description=None, classes_to_label=None, objects_limit_per_image=None, tags_to_label=None, tags_limit_per_image=None, include_images_with_tags=None, exclude_images_with_tags=None, images_range=None, reviewer_id=None, images_ids=[])[source]

Creates Labeling Job and assigns given Users to it.

Parameters
name : str

Labeling Job name in Supervisely.

dataset_id : int

Dataset ID in Supervisely.

user_ids : List[int]

User IDs in Supervisely to assign Users as labelers to Labeling Job.

readme : str, optional

Additional information about Labeling Job.

description : str, optional

Description of Labeling Job.

classes_to_label : List[str], optional

List of classes to label in Dataset.

objects_limit_per_image : int, optional

Limit the number of objects that the labeler can create on each image.

tags_to_label : List[str], optional

List of tags to label in Dataset.

tags_limit_per_image : int, optional

Limit the number of tags that the labeler can create on each image.

include_images_with_tags : List[str], optional

Include images with given tags for processing by labeler.

exclude_images_with_tags : List[str], optional

Exclude images with given tags for processing by labeler.

images_range : List[int, int], optional

Limit number of images to be labeled for each labeler.

reviewer_id : int, optional

User ID in Supervisely to assign User as Reviewer to Labeling Job.

images_ids : List[int], optional

List of images ids to label in dataset

Returns

List of information about new Labeling Job. See info_sequence

Return type

List[LabelingJobInfo]

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

user_name = 'alex'
dataset_id = 602
new_label_jobs = api.labeling_job.create(user_name, dataset_id, user_ids=[111, 222], readme='Readmy text',
                                         description='Work for labelers', objects_limit_per_image=5, tags_limit_per_image=3)
print(new_label_jobs)
# Output: [
#     [
#         92,
#         "alex (#1) (#3)",
#         "Readmy text",
#         "Work for labelers",
#         13,
#         29,
#         "Labelling Workspace",
#         494,
#         "Test Dataset",
#         602,
#         "ds1",
#         8,
#         "alex",
#         111,
#         "quantigo273",
#         8,
#         "alex",
#         "2021-03-25T11:04:34.031Z",
#         null,
#         null,
#         "pending",
#         false,
#         3,
#         0,
#         0,
#         0,
#         0,
#         [],
#         [],
#         [
#             null,
#             null
#         ],
#         5,
#         3,
#         [],
#         [],
#         [],
#         [
#             {
#                 "reviewStatus": "none",
#                 "id": 287244,
#                 "name": "IMG_0813"
#             },
#             {
#                 "reviewStatus": "none",
#                 "id": 287246,
#                 "name": "IMG_0432"
#             },
#             {
#                 "reviewStatus": "none",
#                 "id": 287245,
#                 "name": "IMG_0315"
#             }
#         ]
#     ],
#     [
#         93,
#         "alex (#2) (#3)",
#         "Readmy text",
#         "Work for labelers",
#         13,
#         29,
#         "Labelling Workspace",
#         494,
#         "Test Dataset",
#         602,
#         "ds1",
#         8,
#         "alex",
#         222,
#         "quantigo19",
#         8,
#         "alex",
#         "2021-03-25T11:04:34.031Z",
#         null,
#         null,
#         "pending",
#         false,
#         3,
#         0,
#         0,
#         0,
#         0,
#         [],
#         [],
#         [
#             null,
#             null
#         ],
#         5,
#         3,
#         [],
#         [],
#         [],
#         [
#             {
#                 "reviewStatus": "none",
#                 "id": 287248,
#                 "name": "IMG_8454"
#             },
#             {
#                 "reviewStatus": "none",
#                 "id": 287249,
#                 "name": "IMG_6896"
#             },
#             {
#                 "reviewStatus": "none",
#                 "id": 287247,
#                 "name": "IMG_1942"
#             }
#         ]
#     ]
# ]
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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


name = "IMG_0315.jpeg"
dataset_id = 55832
exists = api.image.exists(dataset_id, name)
print(exists) # True
get_annotations(id, image_ids, project_meta=None)[source]

Return annotations for given image ids from labeling job with given id.

Parameters
id : int

Labeling Job ID in Supervisely.

image_ids : int

Image IDs in Supervisely.

project_meta : ProjectMeta, optional

Project meta of the labeling job with given id. Can be retrieved with get_project_meta().

Returns

Annotation for given image id from labeling job with given id.

Return type

Annotation

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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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)[source]

Get Labeling Job information by ID.

Parameters
id : int

Labeling Job ID in Supervisely.

Returns

Information about Labeling Job. See info_sequence

Return type

LabelingJobInfo

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

label_job_info = api.labeling_job.get_info_by_id(2)
print(label_job_info)
# Output: [
#     2,
#     "Annotation Job (#1) (#1) (dataset_01)",
#     "",
#     "",
#     4,
#     8,
#     "First Workspace",
#     58,
#     "tutorial_project",
#     54,
#     "dataset_01",
#     4,
#     "anna",
#     4,
#     "anna",
#     4,
#     "anna",
#     "2020-04-08T15:10:12.618Z",
#     "2020-04-08T15:10:19.833Z",
#     "2020-04-08T15:13:39.788Z",
#     "completed",
#     false,
#     3,
#     0,
#     1,
#     2,
#     2,
#     [],
#     [],
#     [
#         1,
#         5
#     ],
#     null,
#     null,
#     [],
#     [],
#     [],
#     [
#         {
#             "reviewStatus": "rejected",
#             "id": 283,
#             "name": "image_03"
#         },
#         {
#             "reviewStatus": "accepted",
#             "id": 282,
#             "name": "image_02"
#         },
#         {
#             "reviewStatus": "accepted",
#             "id": 281,
#             "name": "image_01"
#         }
#     ]
# ]
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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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(team_id, created_by_id=None, assigned_to_id=None, project_id=None, dataset_id=None, show_disabled=False)[source]

Get list of information about Labeling Job in the given Team.

Parameters
team_id : int

Team ID in Supervisely.

created_by_id : int, optional

ID of the User who created the LabelingJob.

assigned_to_id : int, optional

ID of the assigned User.

project_id : int, optional

Project ID in Supervisely.

dataset_id : int, optional

Dataset ID in Supervisely.

show_disabled : bool, optional

Show disabled Labeling Jobs.

Returns

List of information about Labeling Jobs. See info_sequence

Return type

List[LabelingJobInfo]

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

label_jobs = api.labeling_job.get_list(4)
print(label_jobs)
# Output: [
#     [
#         2,
#         "Annotation Job (#1) (#1) (dataset_01)",
#         "",
#         "",
#         4,
#         8,
#         "First Workspace",
#         58,
#         "tutorial_project",
#         54,
#         "dataset_01",
#         4,
#         "anna",
#         4,
#         "anna",
#         4,
#         "anna",
#         "2020-04-08T15:10:12.618Z",
#         "2020-04-08T15:10:19.833Z",
#         "2020-04-08T15:13:39.788Z",
#         "completed",
#         false,
#         3,
#         0,
#         1,
#         2,
#         2,
#         [],
#         [],
#         [
#             1,
#             5
#         ],
#         null,
#         null,
#         [],
#         [],
#         [],
#         null
#     ],
#     [
#         3,
#         "Annotation Job (#1) (#2) (dataset_02)",
#         "",
#         "",
#         4,
#         8,
#         "First Workspace",
#         58,
#         "tutorial_project",
#         55,
#         "dataset_02",
#         4,
#         "anna",
#         4,
#         "anna",
#         4,
#         "anna",
#         "2020-04-08T15:10:12.618Z",
#         "2020-04-08T15:15:46.749Z",
#         "2020-04-08T15:17:33.572Z",
#         "completed",
#         false,
#         2,
#         0,
#         0,
#         2,
#         2,
#         [],
#         [],
#         [
#             1,
#             5
#         ],
#         null,
#         null,
#         [],
#         [],
#         [],
#         null
#     ]
# ]
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

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

get_project_meta(id)[source]

Returns project meta with classes and tags used in the labeling job with given id.

Parameters
id : int

Labeling Job ID in Supervisely.

Returns

Project meta of the labeling job with given id.

Return type

ProjectMeta

get_stats(id)[source]

Get stats of given Labeling Job ID.

Parameters
id : int

Labeling Job ID in Supervisely.

Returns

Dict with information about given Labeling Job

Return type

dict

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

status = api.labeling_job.get_stats(3)
print(status)
# Output: {
#     "job": {
#         "editingDuration": 0,
#         "annotationDuration": 720,
#         "id": 3,
#         "name": "Annotation Job (#1) (#2) (dataset_02)",
#         "startedAt": "2020-04-08T15:15:46.749Z",
#         "finishedAt": "2020-04-08T15:17:33.572Z",
#         "imagesCount": 2,
#         "finishedImagesCount": 2,
#         "tagsStats": [
#             {
#                 "id": 24,
#                 "color": "#ED68A1",
#                 "images": 1,
#                 "figures": 1,
#                 "name": "car_color"
#             },
#             {
#                 "id": 19,
#                 "color": "#A0A08C",
#                 "images": 0,
#                 "figures": 1,
#                 "name": "cars_number"
#             },
#             {
#                 "id": 20,
#                 "color": "#D98F7E",
#                 "images": 1,
#                 "figures": 1,
#                 "name": "like"
#             },
#             {
#                 "id": 23,
#                 "color": "#65D37C",
#                 "images": 0,
#                 "figures": 1,
#                 "name": "person_gender"
#             },
#             {
#                 "parentId": 23,
#                 "color": "#65D37C",
#                 "images": 0,
#                 "figures": 1,
#                 "name": "person_gender (male)"
#             },
#             {
#                 "parentId": 23,
#                 "color": "#65D37C",
#                 "images": 0,
#                 "figures": 0,
#                 "name": "person_gender (female)"
#             },
#             {
#                 "id": 21,
#                 "color": "#855D79",
#                 "images": 1,
#                 "figures": 1,
#                 "name": "situated"
#             },
#             {
#                 "parentId": 21,
#                 "color": "#855D79",
#                 "images": 1,
#                 "figures": 1,
#                 "name": "situated (inside)"
#             },
#             {
#                 "parentId": 21,
#                 "color": "#855D79",
#                 "images": 0,
#                 "figures": 0,
#                 "name": "situated (outside)"
#             },
#             {
#                 "id": 22,
#                 "color": "#A2B4FA",
#                 "images": 0,
#                 "figures": 1,
#                 "name": "vehicle_age"
#             },
#             {
#                 "parentId": 22,
#                 "color": "#A2B4FA",
#                 "images": 0,
#                 "figures": 1,
#                 "name": "vehicle_age (modern)"
#             },
#             {
#                 "parentId": 22,
#                 "color": "#A2B4FA",
#                 "images": 0,
#                 "figures": 0,
#                 "name": "vehicle_age (vintage)"
#             }
#         ]
#     },
#     "classes": [
#         {
#             "id": 43,
#             "color": "#F6FF00",
#             "shape": "rectangle",
#             "totalDuration": 0,
#             "imagesCount": 0,
#             "avgDuration": null,
#             "name": "bike",
#             "labelsCount": 0
#         },
#         {
#             "id": 42,
#             "color": "#BE55CE",
#             "shape": "polygon",
#             "totalDuration": 0,
#             "imagesCount": 0,
#             "avgDuration": null,
#             "name": "car",
#             "labelsCount": 0
#         },
#         {
#             "id": 41,
#             "color": "#FD0000",
#             "shape": "polygon",
#             "totalDuration": 0,
#             "imagesCount": 0,
#             "avgDuration": null,
#             "name": "dog",
#             "labelsCount": 0
#         },
#         {
#             "id": 40,
#             "color": "#00FF12",
#             "shape": "bitmap",
#             "totalDuration": 0,
#             "imagesCount": 0,
#             "avgDuration": null,
#             "name": "person",
#             "labelsCount": 0
#         }
#     ],
#     "images": {
#         "total": 2,
#         "images": [
#             {
#                 "id": 285,
#                 "reviewStatus": "accepted",
#                 "annotationDuration": 0,
#                 "totalDuration": 0,
#                 "name": "image_01",
#                 "labelsCount": 0
#             },
#             {
#                 "id": 284,
#                 "reviewStatus": "accepted",
#                 "annotationDuration": 0,
#                 "totalDuration": 0,
#                 "name": "image_02",
#                 "labelsCount": 0
#             }
#         ]
#     }
# }
get_status(id)[source]

Get status of Labeling Job with given ID.

Parameters
id : int

Labeling job ID in Supervisely.

Returns

Labeling Job Status

Return type

Status

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

job_status = api.labeling_job.get_status(4)
print(job_status) # pending
static info_sequence()[source]

NamedTuple LabelingJobInfo information about Labeling Job.

Example
LabelingJobInfo(id=2,
                name='Annotation Job (#1) (#1) (dataset_01)',
                readme='',
                description='',
                team_id=4,
                workspace_id=8,
                workspace_name='First Workspace',
                project_id=58,
                project_name='tutorial_project',
                dataset_id=54,
                dataset_name='dataset_01',
                created_by_id=4,
                created_by_login='anna',
                assigned_to_id=4,
                assigned_to_login='anna',
                reviewer_id=4,
                reviewer_login='anna',
                created_at='2020-04-08T15:10:12.618Z',
                started_at='2020-04-08T15:10:19.833Z',
                finished_at='2020-04-08T15:13:39.788Z',
                status='completed',
                disabled=False,
                images_count=3,
                finished_images_count=0,
                rejected_images_count=1,
                accepted_images_count=2,
                progress_images_count=2,
                classes_to_label=[],
                tags_to_label=[],
                images_range=(1, 5),
                objects_limit_per_image=None,
                tags_limit_per_image=None,
                filter_images_by_tags=[],
                include_images_with_tags=[],
                exclude_images_with_tags=[],
                entities=None)
static info_tuple_name()[source]

NamedTuple name - LabelingJobInfo.

remove(id)

Remove an entity with the specified ID from the Supervisely server.

Parameters
id : int

Entity ID in Supervisely.

Usage example
import supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


image_id = 19369643
api.image.remove(image_id)
remove_batch(ids, progress_cb=None, batch_size=50)

Remove entities in batches from the Supervisely server. All entity IDs must belong to the same nesting (for example team, or workspace, or project, or dataset). Therefore, it is necessary to sort IDs before calling this method.

Parameters
ids : List[int]

IDs of entities in Supervisely.

progress_cb : Callable

Function for control remove progress.

Usage example
import supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


image_ids = [19369645, 19369646, 19369647]
api.image.remove_batch(image_ids)
set_status(id, status)[source]

Sets Labeling Job status.

Parameters
id : int

Labeling Job ID in Supervisely.

status : str

New Labeling Job status

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
from supervisely.api.labeling_job_api.LabelingJobApi.Status import COMPLETED

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

api.labeling_job.set_status(id=9, status="completed")
stop(id)[source]

Makes Labeling Job unavailable for labeler with given User ID.

Parameters
id : int

User ID in Supervisely.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

api.labeling_job.stop(9)
wait(id, target_status, wait_attempts=None, wait_attempt_timeout_sec=None)[source]

Wait for a Labeling Job to change to the expected target status.

Parameters
id : int

Labeling Job ID in Supervisely.

target_status : str

Expected result status of Labeling Job.

wait_attempts : int, optional

Number of attempts to retry, when WaitingTimeExceeded raises.

wait_attempt_timeout_sec : int, optional

Time between attempts.

Raises

WaitingTimeExceeded, if waiting time exceeded

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

api.labeling_job.wait(4, 'completed', wait_attempts=2, wait_attempt_timeout_sec=1)
# supervisely.api.module_api.WaitingTimeExceeded: Waiting time exceeded