Project

class Project[source]

Bases: object

Project is a parent directory for dataset. Project object is immutable.

Parameters
directory : str

Path to project directory.

mode : OpenMode

Determines working mode for the given project.

Usage example
import supervisely as sly
project_path = "/home/admin/work/supervisely/projects/lemons_annotated"
project = sly.Project(project_path, sly.OpenMode.READ)

Methods

copy_data

Makes a copy of the Project.

create_dataset

Creates a subdirectory with given name and all intermediate subdirectories for items and annotations in project directory, and also adds created dataset to the collection of all datasets in the project.

download

Download project from Supervisely to the given directory.

get_classes_stats

get_item_paths

rtype

ItemPaths

get_train_val_splits_by_count

Get train and val items information from project by given train and val counts.

get_train_val_splits_by_dataset

Get train and val items information from project by given train and val datasets names.

get_train_val_splits_by_tag

Get train and val items information from project by given train and val tags names.

get_url

Get URL to datasets list in Supervisely.

remove_classes

Removes given classes from Project.

remove_classes_except

Removes classes from Project with the exception of some classes.

remove_items_without_both_objects_and_tags

Remove items(images and annotations) without objects and tags from Project.

remove_items_without_objects

Remove items(images and annotations) without objects from Project.

remove_items_without_tags

Remove items(images and annotations) without tags from Project.

set_meta

Saves given meta to project directory in json format.

to_detection_task

Makes a copy of the Project, converts annotations to Rectangles and updates project meta.

to_segmentation_task

Makes a copy of the Project, converts annotations to Bitmaps and updates project meta.

upload

Uploads project to Supervisely from the given directory.

validate

Attributes

datasets

Project datasets.

directory

Path to the project directory.

meta

Project meta.

name

Project name.

parent_dir

Project parent directory.

total_items

Total number of items in project.

type

Project type.

class DatasetDict[source]

Bases: supervisely.collection.key_indexed_collection.KeyIndexedCollection

Datasets collection of Project.

item_type

alias of supervisely.project.project.Dataset

add(item)

Add given item to collection.

Parameters
item : KeyObject

ObjClassCollection, TagMetaCollection or TagCollection object.

Returns

New instance of KeyIndexedCollection

Return type

KeyIndexedCollection

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])
# Remember that KeyIndexedCollection object is immutable, and we need to assign new instance of KeyIndexedCollection to a new variable
item_dog = sly.ObjClass('dog', sly.Rectangle)
new_collection = collection.add(item_dog)
add_items(items)

Add items from given list to collection.

Parameters
items : List[KeyObject]

List of ObjClassCollection, TagMetaCollection or TagCollection objects.

Returns

New instance of KeyIndexedCollection

Return type

KeyIndexedCollection

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])
# Remember that KeyIndexedCollection object is immutable, and we need to assign new instance of KeyIndexedCollection to a new variable
item_dog = sly.ObjClass('dog', sly.Rectangle)
item_mouse = sly.ObjClass('mouse', sly.Bitmap)
new_collection = collection.add_items([item_dog, item_mouse])
clone(items=None)

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

Parameters
items : List[KeyObject], optional

List of ObjClassCollection, TagMetaCollection or TagCollection objects.

Returns

New instance of KeyIndexedCollection

Return type

KeyIndexedCollection

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])
# Remember that KeyIndexedCollection object is immutable, and we need to assign new instance of KeyIndexedCollection to a new variable
new_collection = collection.clone()
difference(other)

Find difference between collection and given list of instances.

Parameters
key : List[KeyObject]

List of ObjClassCollection, TagMetaCollection or TagCollection objects.

Returns

KeyIndexedCollection object

Return type

KeyIndexedCollection

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

item_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
items = [item_dog, item_turtle]

diff = collection.difference(items)
print(diff.to_json())
# Output: [
#     {
#         "name": "cat",
#         "value_type": "none",
#         "color": "#8A150F",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     }
# ]
get(key, default=None)

Get item from collection with given key(name).

Parameters
items : str

Name of KeyObject in collection.

default : optional

The value that is returned if there is no key in the collection.

Returns

ObjClassCollection, TagMetaCollection or TagCollection object

Return type

KeyObject

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

item_cat = collection.get('cat')
print(item_cat)
# Output:
# Name:  cat                      Value type:none          Possible values:None       Hotkey                  Applicable toall        Applicable classes[]

item_not_exist = collection.get('no_item', {1: 2})
print(item_not_exist)
# Output:
# {1: 2}
has_key(key)

Check if given key(item name exist in collection).

Parameters
key : str

The key to look for in the collection.

Returns

Is the key in the collection or not

Return type

bool

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

collection.has_key('cat') # True
collection.has_key('hamster') # False
intersection(other)

Find intersection of given list of instances with collection items.

Parameters
key : List[KeyObject]

List of ObjClassCollection, TagMetaCollection or TagCollection objects.

Raises

ValueError if find items with same keys(item names)

Returns

KeyIndexedCollection object

Return type

KeyIndexedCollection

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

item_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
items = [item_dog, item_turtle]

intersection = collection.intersection(items)
print(intersection.to_json())
# Output: [
#     {
#         "name": "turtle",
#         "value_type": "any_string",
#         "color": "#760F8A",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     }
# ]
keys()

Get list of all keys(item names) in collection.

Returns

List of collection keys

Return type

List[str]

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])
keys = collection.keys() # ['cat', 'turtle']
merge(other)

Merge collection and other KeyIndexedCollection object.

Parameters
key : KeyIndexedCollection

KeyIndexedCollection object.

Raises

ValueError if item name from given list is in collection but items in both are different

Returns

KeyIndexedCollection object

Return type

KeyIndexedCollection

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

item_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
other_collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_dog, item_turtle])

merge = collection.merge(other_collection)
print(merge.to_json())
# Output: [
#     {
#         "name": "dog",
#         "value_type": "none",
#         "color": "#8A6C0F",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     },
#     {
#         "name": "cat",
#         "value_type": "none",
#         "color": "#0F4A8A",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     },
#     {
#         "name": "turtle",
#         "value_type": "any_string",
#         "color": "#4F0F8A",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     }
# ]
remove_items(keys)

Remove items from collection by given list of keys. Creates a new instance of KeyIndexedCollection.

Parameters
keys : List[str]

List of keys(item names) in collection.

Returns

New instance of KeyIndexedCollection

Return type

KeyIndexedCollection

to_json()

Convert the KeyIndexedCollection to a json serializable list.

Returns

List of json serializable dicts

Return type

List[dict]

Usage Example
import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])
collection_json = collection.to_json()
# Output: [
#     {
#         "name": "cat",
#         "value_type": "none",
#         "color": "#8A0F12",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     },
#     {
#         "name": "turtle",
#         "value_type": "any_string",
#         "color": "#8A860F",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     }
# ]
dataset_class

alias of supervisely.project.project.Dataset

copy_data(dst_directory, dst_name=None, _validate_item=True, _use_hardlink=False)[source]

Makes a copy of the Project.

Parameters
dst_directory : str

Path to project parent directory.

dst_name : str, optional

Project name.

_validate_item : bool, optional

Checks input files format.

_use_hardlink : bool, optional

If True creates a hardlink pointing to src named dst, otherwise don’t.

Returns

Project object.

Return type

Project

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.total_items)
# Output: 6

new_project = project.copy_data("/home/admin/work/supervisely/projects/", "lemons_copy")
print(new_project.total_items)
# Output: 6
create_dataset(ds_name, ds_path=None)[source]

Creates a subdirectory with given name and all intermediate subdirectories for items and annotations in project directory, and also adds created dataset to the collection of all datasets in the project.

Parameters
ds_name : str

Dataset name.

Returns

Dataset object

Return type

Dataset

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)

for dataset in project.datasets:
    print(dataset.name)

# Output: ds1
#         ds2

project.create_dataset("ds3")

for dataset in project.datasets:
    print(dataset.name)

# Output: ds1
#         ds2
#         ds3
static download(api, project_id, dest_dir, dataset_ids=None, log_progress=False, batch_size=50, cache=None, progress_cb=None, only_image_tags=False, save_image_info=False, save_images=True, save_image_meta=False)[source]

Download project from Supervisely to the given directory.

Parameters
api : Api

Supervisely API address and token.

project_id : int

Supervisely downloadable project ID.

dest_dir : str

Destination directory.

dataset_ids : list [ int ], optional

Dataset IDs.

log_progress : bool, optional

Show uploading progress bar.

batch_size : int, optional

The number of images in the batch when they are loaded to a host.

cache : FileCache, optional

FileCache object.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

only_image_tags : bool, optional

Download project with only images tags (without objects tags).

save_image_info : bool, optional

Download images infos or not.

save_images : bool, optional

Download images or not.

save_image_meta : bool, optional

Download images metadata in JSON format or not.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

# Local destination Project folder
save_directory = "/home/admin/work/supervisely/source/project"

# Obtain server address and your api_token from environment variables
# Edit those values if you run this notebook on your own PC
address = os.environ['SERVER_ADDRESS']
token = os.environ['API_TOKEN']

# Initialize API object
api = sly.Api(address, token)
project_id = 8888

# Download Project
sly.Project.download(api, project_id, save_directory)
project_fs = sly.Project(save_directory, sly.OpenMode.READ)
static get_train_val_splits_by_count(project_dir, train_count, val_count)[source]

Get train and val items information from project by given train and val counts.

Parameters
project_dir : str

Path to project directory.

train_count : int

Number of train items.

val_count : int

Number of val items.

Raises

ValueError if total_count != train_count + val_count

Returns

Tuple with lists of train items information and val items information

Return type

list [ ItemInfo ], list [ ItemInfo ]

Usage example
import supervisely as sly
train_count = 4
val_count = 2
train_items, val_items = sly.Project.get_train_val_splits_by_count(
    project_path,
    train_count,
    val_count
)
static get_train_val_splits_by_dataset(project_dir, train_datasets, val_datasets)[source]

Get train and val items information from project by given train and val datasets names.

Parameters
project_dir : str

Path to project directory.

train_datasets : list [ str ]

List of train datasets names.

val_datasets : list [ str ]

List of val datasets names.

Raises

KeyError if dataset name not found in project

Returns

Tuple with lists of train items information and val items information

Return type

list [ ItemInfo ], list [ ItemInfo ]

Usage example
import supervisely as sly
train_datasets = ['ds1', 'ds2']
val_datasets = ['ds3', 'ds4']
train_items, val_items = sly.Project.get_train_val_splits_by_dataset(
    project_path,
    train_datasets,
    val_datasets
)
static get_train_val_splits_by_tag(project_dir, train_tag_name, val_tag_name, untagged='ignore')[source]

Get train and val items information from project by given train and val tags names.

Parameters
project_dir : str

Path to project directory.

train_tag_name : str

Train tag name.

val_tag_name : str

Val tag name.

untagged : str, optional

Actions in case of absence of train_tag_name and val_tag_name in project.

Raises

ValueError if untagged not in [“ignore”, “train”, “val”]

Returns

Tuple with lists of train items information and val items information

Return type

list [ ItemInfo ], list [ ItemInfo ]

Usage example
import supervisely as sly
train_tag_name = 'train'
val_tag_name = 'val'
train_items, val_items = sly.Project.get_train_val_splits_by_tag(
    project_path,
    train_tag_name,
    val_tag_name
)
static get_url(id)[source]

Get URL to datasets list in Supervisely.

Parameters
id : int

Project ID in Supervisely.

Returns

URL to datasets list.

Return type

str

Usage example
from supervisely import Project

project_id = 10093
datasets_link = Project.get_url(project_id)

print(datasets_link)
# Output: "/projects/10093/datasets"
static remove_classes(project_dir, classes_to_remove=None, inplace=False)[source]

Removes given classes from Project.

Parameters
project_dir : str

Path to project directory.

classes_to_remove : list [ str ], optional

Classes to remove.

inplace : bool, optional

Checkbox that determines whether to change the source data in project or not.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
project = sly.Project(project_path, sly.OpenMode.READ)
classes_to_remove = ['lemon']
project.remove_classes(project_path, classes_to_remove, inplace=True)
static remove_classes_except(project_dir, classes_to_keep=None, inplace=False)[source]

Removes classes from Project with the exception of some classes.

Parameters
project_dir : str

Path to project directory.

classes_to_keep : list [ str ], optional

Classes to keep in project.

inplace : bool, optional

Checkbox that determines whether to change the source data in project or not.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
project = sly.Project(project_path, sly.OpenMode.READ)
project.remove_classes_except(project_path, inplace=True)
static remove_items_without_both_objects_and_tags(project_dir, inplace=False)[source]

Remove items(images and annotations) without objects and tags from Project.

Parameters
project_dir : str

Path to project directory.

inplace : bool, optional

Checkbox that determines whether to change the source data in project or not.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
sly.Project.remove_items_without_both_objects_and_tags(project_path, inplace=True)
static remove_items_without_objects(project_dir, inplace=False)[source]

Remove items(images and annotations) without objects from Project.

Parameters
project_dir : str

Path to project directory.

inplace : bool, optional

Checkbox that determines whether to change the source data in project or not.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
sly.Project.remove_items_without_objects(project_path, inplace=True)
static remove_items_without_tags(project_dir, inplace=False)[source]

Remove items(images and annotations) without tags from Project.

Parameters
project_dir : str

Path to project directory.

inplace : bool, optional

Checkbox that determines whether to change the source data in project or not.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
sly.Project.remove_items_without_tags(project_path, inplace=True)
set_meta(new_meta)[source]

Saves given meta to project directory in json format.

Parameters
new_meta : ProjectMeta

ProjectMeta object.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
proj_lemons = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
proj_kiwi = sly.Project("/home/admin/work/supervisely/projects/kiwi_annotated", sly.OpenMode.READ)

proj_lemons.set_meta(proj_kiwi.meta)

print(project.proj_lemons)
# Output:
# +-------+--------+----------------+--------+
# |  Name | Shape  |     Color      | Hotkey |
# +-------+--------+----------------+--------+
# |  kiwi | Bitmap |  [255, 0, 0]   |        |
# +-------+--------+----------------+--------+
static to_detection_task(src_project_dir, dst_project_dir=None, inplace=False, progress_cb=None)[source]

Makes a copy of the Project, converts annotations to Rectangles and updates project meta.

Parameters
src_project_dir : str

Path to source project directory.

dst_project_dir : str, optional

Path to destination project directory. Must be None If inplace=True.

inplace : bool, optional

Modifies source project If True. Must be False If dst_project_dir is specified.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
source_project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
det_project_path = "/home/admin/work/supervisely/projects/lemons_detection"
sly.Project.to_detection_task(
    src_project_dir=source_project.directory,
    dst_project_dir=det_project_path
)
det_project = sly.Project(det_project_path, sly.OpenMode.READ)
static to_segmentation_task(src_project_dir, dst_project_dir=None, inplace=False, target_classes=None, progress_cb=None, segmentation_type='semantic')[source]

Makes a copy of the Project, converts annotations to Bitmaps and updates project meta.

You will able to get item’s segmentation masks location by dataset.get_seg_path(item_name) method.

Parameters
src_project_dir : str

Path to source project directory.

dst_project_dir : str, optional

Path to destination project directory. Must be None If inplace=True.

inplace : bool, optional

Modifies source project If True. Must be False If dst_project_dir is specified.

target_classes : list [ str ], optional

Classes list to include to destination project. If segmentation_type=”semantic”, background class “__bg__” will be added automatically.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

segmentation_type : str

One of: {“semantic”, “instance”}. If segmentation_type=”semantic”, background class “__bg__” will be added automatically and instances will be converted to non overlapping semantic segmentation mask.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly
source_project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
seg_project_path = "/home/admin/work/supervisely/projects/lemons_segmentation"
sly.Project.to_segmentation_task(
    src_project_dir=source_project.directory,
    dst_project_dir=seg_project_path
)
seg_project = sly.Project(seg_project_path, sly.OpenMode.READ)
static upload(dir, api, workspace_id, project_name=None, log_progress=True, progress_cb=None)[source]

Uploads project to Supervisely from the given directory.

Parameters
dir : str

Path to project directory.

api : Api

Supervisely API address and token.

workspace_id : int

Workspace ID, where project will be uploaded.

project_name : str, optional

Name of the project in Supervisely. Can be changed if project with the same name is already exists.

log_progress : bool, optional

Show uploading progress bar.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

Returns

Project ID and name. It is recommended to check that returned project name coincides with provided project name.

Return type

int, str

Usage example

import supervisely as sly

# Local folder with Project
project_directory = "/home/admin/work/supervisely/source/project"

# Obtain server address and your api_token from environment variables
# Edit those values if you run this notebook on your own PC
address = os.environ['SERVER_ADDRESS']
token = os.environ['API_TOKEN']

# Initialize API object
api = sly.Api(address, token)

# Upload Project
project_id, project_name = sly.Project.upload(
    project_directory,
    api,
    workspace_id=45,
    project_name="My Project"
)
property datasets

Project datasets.

Returns

Datasets

Return type

DatasetDict

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
for dataset in project.datasets:
    print(dataset.name)
    # Output: ds1
    #         ds2
property directory

Path to the project directory.

Returns

Path to the project directory

Return type

str

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.directory)
# Output: '/home/admin/work/supervisely/projects/lemons_annotated'
property meta

Project meta.

Returns

ProjectMeta object

Return type

ProjectMeta

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.meta)
# Output:
# +-------+--------+----------------+--------+
# |  Name | Shape  |     Color      | Hotkey |
# +-------+--------+----------------+--------+
# |  kiwi | Bitmap |  [255, 0, 0]   |        |
# | lemon | Bitmap | [81, 198, 170] |        |
# +-------+--------+----------------+--------+
# Tags
# +------+------------+-----------------+--------+---------------+--------------------+
# | Name | Value type | Possible values | Hotkey | Applicable to | Applicable classes |
# +------+------------+-----------------+--------+---------------+--------------------+
property name

Project name.

Returns

Project name.

Return type

str

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.name)
# Output: 'lemons_annotated'
property parent_dir

Project parent directory.

Returns

Path to project parent directory

Return type

str

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.parent_dir)
# Output: '/home/admin/work/supervisely/projects'
property total_items

Total number of items in project.

Returns

Total number of items in project

Return type

int

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.total_items)
# Output: 12
property type

Project type.

Returns

Project type.

Return type

str

Usage example
import supervisely as sly
project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.type)
# Output: 'images'