Label¶

class Label(geometry, obj_class, tags=None, description='', binding_key=None, smart_tool_input=None, sly_id=None, status=None)[source]¶

Bases: LabelBase

Supervisely Label. Contains geometry and tags for the single object on the image.

Parameters:

geometry¶

Label geometry.

obj_class¶

ObjClass object.

tags=None¶

TagCollection or List of Tag objects.

description : str, optional¶

Label description.

binding_key : str, optional¶

Label binding key in labeling tool.

smart_tool_input : dict, optional¶

Smart Tool parameters that were used for labeling.

sly_id : int, optional¶

Label unique identifier in Supervisely.

status=None¶

Sets labeling status. Shows how label was created and corrected.

Usage Example:

import supervisely as sly

# Simple Label example
class_kiwi = sly.ObjClass('kiwi', sly.Rectangle)
figure = sly.Rectangle(0, 0, 300, 300)
label_kiwi = sly.Label(figure, class_kiwi)

# More complex Label example
# Tag
meta_kiwi = sly.TagMeta('kiwi_tag', sly.TagValueType.ANY_STRING)
tag_kiwi = sly.Tag(meta_kiwi, 'Hello')
# ObjClass
class_kiwi = sly.ObjClass('kiwi', sly.Rectangle)

# Label
geometry_figure = sly.Rectangle(0, 0, 300, 300)
label = sly.Label(figure, class_kiwi, sly.TagCollection([tag_kiwi]), 'Label description')
# or sly.Label(figure, class_kiwi, [tag_kiwi], 'Label description')

Methods

add_tag	Adds Tag to the current Label.
add_tags	Adds multiple Tags to the current Label.
clone	Makes a copy of Label with new fields, if fields are given, otherwise it will use fields of the original Label.
convert	Converts Label geometry to another geometry shape.
crop	Clones the current Label and crops it.
draw	Draws current Label on image.
draw_contour	Draws Label geometry contour on the given image.
fliplr	Clones the current Label and flips it horizontally.
flipud	Clones the current Label and flips it vertically.
from_json	Convert a json dict to Label.
get_mask	Returns 2D boolean mask of the label.
relative_crop	Clones the current Label and crops it, but return results with coordinates relative to the given Rectangle.
resize	Clones the current Label and resizes it.
rotate	Clones the current Label and rotates it.
scale	Clones the current Label and scales it.
to_json	Convert the Label to a json dictionary.
translate	Clones the current Label and shifts it by a certain number of pixels.

Attributes

area	Label area.
binding_key	Keyboard shortcut key for binding the label to the object.
description	Description of the Label.
geometry	Geometry of the current Label.
labeler_login	Labeler login.
obj_class	ObjClass of the current Label.
sly_id	Returns the unique identifier of the Label on Supervisely platform.
smart_tool_input	Smart Tool parameters that were used for labeling.
status	Labeling status.
tags	TagCollection of the Label.

classmethod from_json(data, project_meta)¶

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

Parameters:

data : dict¶

Label in json format as a dict.

project_meta¶

ProjectMeta object.

Returns:

Label object

Return type:

LabelBase

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

meta = api.project.get_meta(PROJECT_ID)

data = {
    "classTitle": "dog",
    "tags": [
        {
            "name": "dog",
            "value": "Woof"
        }
    ],
    "points": {
        "exterior": [[100, 100], [900, 700]],
        "interior": []
    },
    "nnCreated": false,
    "nnUpdated": false
}

label_dog = sly.Label.from_json(data, meta)

add_tag(tag)¶

Adds Tag to the current Label.

Parameters:

tag¶

Tag to be added.

Returns:

Label object

Return type:

LabelBase

Usage Example:

import supervisely as sly

# Create label
class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(0, 0, 500, 600), class_dog)

# Create tag
meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
tag_dog = sly.Tag(meta_dog)

# Add Tag
# Remember that Label object is immutable, and we need to assign new instance of Label to a new variable
new_label = label_dog.add_tag(tag_dog)

add_tags(tags)¶

Adds multiple Tags to the current Label.

Parameters:

tags¶

List of Tags to be added.

Returns:

Label object

Return type:

LabelBase

Usage Example:

import supervisely as sly

# Create label
class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(0, 0, 500, 600), class_dog)

# Create tags
meta_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
tag_dog = sly.Tag(meta_dog)

meta_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
tag_cat = sly.Tag(meta_cat)

tags_arr = [tag_dog, tag_cat]

# Add Tags
# Remember that Label object is immutable, and we need to assign new instance of Label to a new variable
new_label = label_dog.add_tags(tags_arr)

clone(geometry=None, obj_class=None, tags=None, description=None, binding_key=None, smart_tool_input=None, status=None)¶

Makes a copy of Label with new fields, if fields are given, otherwise it will use fields of the original Label.

Parameters:

geometry=None¶

Label geometry.

obj_class=None¶

ObjClass class.

tags=None¶

Label tags.

description : str, optional¶

Label description.

binding_key : str, optional¶

Label binding key.

smart_tool_input : dict, optional¶

Smart Tool parameters that were used for labeling.

status=None¶

Sets labeling status. Specifies if the label was created by NN model, manually or created by NN and then manually corrected.

Returns:

New instance of Label object

Return type:

LabelBase

Usage Example:

import supervisely as sly
import numpy as np

# Original Label
class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(150, 150, 500, 400), class_dog)

# Let's clone our Label, but with different Geometry coordinates
# Remember that Label object is immutable, and we need to assign new instance of Label to a new variable
clone_label_dog = label_dog.clone(sly.Rectangle(100, 100, 500, 500), class_dog)

# Let's clone our Label with new TagCollection and description
meta_breed = sly.TagMeta('breed', sly.TagValueType.ANY_STRING)
tag_breed = sly.Tag(meta_breed, 'German Shepherd')
tags = sly.TagCollection([tag_breed])

# Remember that Label object is immutable, and we need to assign new instance of Label to a new variable
clone_label_dog_2 = label_dog.clone(tags=tags, description='Dog breed german shepherd')

# Note that you can't clone Label if ObjClass geometry type differ from the new given geometry
mask = np.array([[0, 0, 0, 0, 0],
                [0, 1, 1, 1, 0],
                [0, 1, 0, 1, 0],
                [0, 1, 1, 1, 0],
                [0, 0, 0, 0, 0]], dtype=np.uint8)

mask_bool = mask==1

clone_label_dog = label_dog.clone(sly.Label(sly.Bitmap(mask_bool), class_dog))
# In this case RuntimeError will be raised

convert(new_obj_class)¶

Converts Label geometry to another geometry shape.

Parameters:

new_obj_class¶

ObjClass with new geometry shape.

Returns:

List of Labels with converted geometries

Return type:

List[LabelBase]

Usage Example:

import supervisely as sly

# Create label
class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(0, 0, 500, 600), class_dog)

print(label_dog.geometry.to_json())
# {'geometryType': 'rectangle'}

label_cat = sly.ObjClass('cat', sly.Bitmap)

convert_label = label_dog.convert(label_cat)
for label_bitmap in convert_label:
    print(label_bitmap.geometry.to_json())
    # Output: {'geometryType': 'bitmap'}

crop(rect)¶

Clones the current Label and crops it. Mostly used for internal implementation. See usage example in crop_labels().

Parameters:

rect¶

Rectangle object.

Returns:

List of Labels with new geometries

Return type:

List[LabelBase>]

draw(bitmap, color=None, thickness=1, draw_tags=False, tags_font=None, draw_class_name=False, class_name_font=None)¶

Draws current Label on image. Modifies Mask. Mostly used for internal implementation. See usage example in draw().

Parameters:

bitmap : np.ndarray¶

image.

color : List[int, int, int], optional¶

Drawing color in [R, G, B].

thickness : int, optional¶

Thickness of the drawing figure.

draw_tags : bool, optional¶

Determines whether to draw tags on bitmap or not.

tags_font : FreeTypeFont, optional¶

Font of tags to be drawn, uses FreeTypeFont from PIL.

draw_class_name : bool, optional¶

Draw the class name on the bitmap. If the draw_tags parameter is set to True, the class name will use the same font as the tags_font.

class_name_font : FreeTypeFont, optional¶

Font of class name to be drawn, uses FreeTypeFont from PIL.

Returns:

None

Return type:

None

draw_contour(bitmap, color=None, thickness=1, draw_tags=False, tags_font=None, draw_class_name=False, class_name_font=None)¶

Draws Label geometry contour on the given image. Modifies mask. Mostly used for internal implementation. See usage example in draw_contour().

Parameters:

bitmap : np.ndarray¶

image.

color : List[int, int, int], optional¶

Drawing color in [R, G, B].

thickness : int, optional¶

Thickness of the drawn contour.

draw_tags : bool, optional¶

Determines whether to draw tags on bitmap or not.

tags_font : FreeTypeFont, optional¶

Font of tags to be drawn, uses FreeTypeFont from PIL.

draw_class_name : bool, optional¶

Draw the class name on the bitmap. If the draw_tags parameter is set to True, the class name will use the same font as the tags_font.

class_name_font : FreeTypeFont, optional¶

Font of class name to be drawn, uses FreeTypeFont from PIL.

Returns:

None

Return type:

None

fliplr(img_size)¶

Clones the current Label and flips it horizontally. Mostly used for internal implementation. See usage example in fliplr().

Parameters:

img_size : Tuple[int, int]¶

Input image size (height, width) of the Annotation to which Label belongs.

Returns:

New instance of Label with flipped geometry

Return type:

LabelBase

flipud(img_size)¶

Clones the current Label and flips it vertically. Mostly used for internal implementation. See usage example in flipud().

Parameters:

img_size : Tuple[int, int]¶

Input image size (height, width) of the Annotation to which Label belongs.

Returns:

New instance of Label with flipped geometry

Return type:

LabelBase

get_mask(img_size)¶

Returns 2D boolean mask of the label. With shape as img_size (height, width) and filled with True values inside the label and False values outside. dtype = np.bool shape = img_size

Parameters:

img_size : Tuple[int, int]¶

size of the image (height, width)

Returns:

2D boolean mask of the Label

Return type:

np.ndarray

relative_crop(rect)¶

Clones the current Label and crops it, but return results with coordinates relative to the given Rectangle. Mostly used for internal implementation. See usage example in relative_crop().

Parameters:

rect¶

Rectangle object.

Returns:

List of Labels with new geometries

Return type:

List[LabelBase]

resize(in_size, out_size)¶

Clones the current Label and resizes it. Mostly used for internal implementation. See usage example in resize().

Parameters:

in_size : Tuple[int, int]¶

Input image size (height, width) of the Annotation to which Label belongs.

out_size : Tuple[int, int]¶

Desired output image size (height, width) of the Annotation to which Label belongs.

Returns:

New instance of Label with resized geometry

Return type:

LabelBase

rotate(rotator)¶

Clones the current Label and rotates it. Mostly used for internal implementation. See usage example in rotate().

Parameters:

rotator¶

ImageRotator object.

Returns:

New instance of Label with rotated geometry

Return type:

LabelBase

scale(factor)¶

Clones the current Label and scales it. Mostly used for internal implementation. See usage example in scale().

Parameters:

factor : float¶

Scale factor.

Returns:

New instance of Label with scaled geometry

Return type:

LabelBase

to_json()¶

Convert the Label to a json dictionary. Read more about Supervisely format.

Returns:

Json format as a dict

Return type:

dict

Usage Example:

import supervisely as sly

meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, 'Woof')
class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(100, 100, 700, 900), class_dog, sly.TagCollection([tag_dog]), description='Insert Label description here')

label_dog_json = label_dog.to_json()
print(label_dog_json)
# Output: {
#    "classTitle": "dog",
#    "description": "",
#    "tags": [
#        {
#            "name": "dog",
#            "value": "Woof"
#        }
#    ],
#    "points": {
#        "exterior": [[100, 100],[900, 700]],
#        "interior": []
#    },
#    "geometryType": "rectangle",
#    "shape": "rectangle",
#    "nnCreated": false,
#    "nnUpdated": false
# }

translate(drow, dcol)¶

Clones the current Label and shifts it by a certain number of pixels. Mostly used for internal implementation.

Parameters:

drow : int¶

Horizontal shift.

dcol : int¶

Vertical shift.

Returns:

New instance of Label with translated geometry

Return type:

LabelBase

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

# Get image and annotation from API
project_id = 117139
image_id = 194190568
meta_json = api.project.get_meta(project_id)
meta = sly.ProjectMeta.from_json(meta_json)
ann_info = api.annotation.download(image_id)
ann = sly.Annotation.from_json(ann_info.annotation, meta)
img = api.image.download_np(image_id)
new_img = copy.deepcopy(img)
ann.draw_pretty(img, thickness=3) # before

# Translate label with name 'lemon'
new_labels = []
for label in ann.labels:
    if label.obj_class.name == 'lemon':
        translate_label = label.translate(250, -350)
        new_labels.append(translate_label)
    else:
        new_labels.append(label)

ann = ann.clone(labels=new_labels)
ann.draw_pretty(new_img, thickness=3)  # after

property area : float¶

Label area.

Returns:

Area of current geometry in LabelBase.

Return type:

float

Usage Example:

import supervisely as sly

# Create label
class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(0, 0, 500, 600), class_dog)

figure_area = label_dog.area
print(figure_area)
# Output: 301101.0

property binding_key¶

Keyboard shortcut key for binding the label to the object.

property description : str¶

Description of the Label.

Returns:

Description

Return type:

str

Usage Example:

class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(150, 150, 400, 500), class_dog, description="Insert Label description here")

print(label_dog.description)
# Output: 'Insert Label description here'

property geometry : supervisely.geometry.geometry.Geometry¶

Geometry of the current Label.

Returns:

Geometry object

Return type:

Geometry

Usage Example:

class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(150, 150, 400, 500), class_dog)

label_json = label_dog.geometry.to_json()
print(label_json)
# Output: {
#    "points": {
#        "exterior": [
#            [
#                150,
#                150
#            ],
#            [
#                500,
#                400
#            ]
#        ],
#        "interior": []
#    }
# }

property labeler_login¶

Labeler login. Specifies the login of the user who labeled the label.

property obj_class : supervisely.annotation.obj_class.ObjClass¶

ObjClass of the current Label.

Returns:

ObjClass object

Return type:

ObjClass

Usage Example:

class_dog = sly.ObjClass('dog', sly.Rectangle)
label_dog = sly.Label(sly.Rectangle(150, 150, 400, 500), class_dog)

label_dog_json = label_dog.obj_class.to_json()
print(label_dog_json)
# Output: {
#    "title": "dog",
#    "shape": "rectangle",
#    "color": "#0F8A12",
#    "geometry_config": {},
#    "hotkey": ""
# }

property sly_id : int | None¶

Returns the unique identifier of the Label on Supervisely platform. NOTE: This can be None, when working with local project.

Returns:

Label unique identifier.

Return type:

int or None

property smart_tool_input¶

Smart Tool parameters that were used for labeling.

Usage Example:

smtool_input = {
    "crop": [
        [85.69912274538524, 323.07711452375236],
        [1108.5635719011857, 1543.1199742240174],
    ],
    "visible": True,
    "negative": [],
    "positive": [[597, 933], [474.5072466934964, 1381.6437133813354]],
}

property status : supervisely.annotation.label.LabelingStatus¶

Labeling status. Specifies if the Label was created by NN model, manually or created by NN and then manually corrected.

property tags : supervisely.annotation.tag_collection.TagCollection¶

TagCollection of the Label.

Returns:

TagCollection object

Return type:

TagCollection

Usage Example:

meta_dog = sly.TagMeta('dog', sly.TagValueType.ANY_STRING)
tag_dog = sly.Tag(meta_dog, 'Woof')
class_dog = sly.ObjClass('dog', sly.Rectangle)

label_dog = sly.Label(sly.Rectangle(100, 100, 700, 900), class_dog, sly.TagCollection([tag_dog]))

label_dog_json = label_dog.tags.to_json()
print(label_dog_json)
# Output: [
#    {
#        "name": "dog",
#        "value": "Woof"
#    }
# ]