Project¶

class Project(directory, mode=None, project_id=None, api=None)[source]¶

Bases: object

A local Supervisely project directory that contains one or more datasets.

Provides access to project metadata and a collection of datasets on disk.

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

Parameters:

directory : str¶: Path to project directory.
mode=None¶: 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

`add_blob_file`	Adds blob file to the project.
`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.
`download_async`	Download project from Supervisely to the given directory in asynchronous mode.
`download_bin`	Download project to the local directory in binary format.
`get_classes_stats`	Get classes stats for the project.
`get_item_paths`	Get item paths for the project.
`get_train_val_splits_by_collections`	Get train and val items information from project by given train and val collections IDs.
`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 project meta to project directory in json format.
`to_coco`	Convert Supervisely project to COCO format.
`to_detection_task`	Makes a copy of the project, converts annotations to `Rectangle` and updates project meta.
`to_pascal_voc`	Convert Supervisely project to Pascal VOC format.
`to_segmentation_task`	Makes a copy of the project, converts annotations to `Bitmap` and updates project meta.
`to_yolo`	Convert Supervisely project to YOLO format.
`upload`	Uploads project to Supervisely from the given directory.
`upload_bin`	Uploads project to Supervisely from the given binary file and suitable only for projects downloaded in binary format.
`validate`

Attributes

`blob_dir`	Directory for project blobs.
`blob_dir_name`
`blob_files`	List of blob files.
`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(items=None)[source]¶

Bases: KeyIndexedCollection

Dataset collection of Project.

Base class for ObjClassCollection, TagMetaCollection and TagCollection instances. It is an analogue of python’s standard Dict. It allows to store objects inherited from KeyObject.

Parameters:

items : list, optional¶: List of ObjClassCollection, TagMetaCollection and TagCollection objects.

:raises DuplicateKeyError, when trying to add object with already existing key

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])
print(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": []
#     }
# ]

# Try to add item with a key that already exists in the collection
dublicate_item = sly.ObjClass('cat', sly.Rectangle)
new_collection = collection.add(dublicate_item)
# Output:
# DuplicateKeyError: "Key 'cat' already exists"

# Add item with a key that not exist in the collection
item_dog = sly.ObjClass('dog', sly.Rectangle)
new_collection = collection.add(item_dog)
print(new_collection.to_json())
# Output: [
#     {
#         "name": "cat",
#         "value_type": "none",
#         "color": "#668A0F",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     },
#     {
#         "name": "turtle",
#         "value_type": "any_string",
#         "color": "#4D0F8A",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     },
#     {
#         "title": "dog",
#         "shape": "rectangle",
#         "color": "#0F7F8A",
#         "geometry_config": {},
#         "hotkey": ""
#     }
# ]

item_type¶: alias of Dataset

add(item)¶

Add given item to collection.

Parameters:

item¶: 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 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=None¶: 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:

other¶: List of items to subtract from the collection.

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:

other¶: List of items to intersect with the collection.

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:

other¶: Other collection to merge with.

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 Dataset

static download(api, project_id, dest_dir, dataset_ids=None, log_progress=True, batch_size=50, cache=None, progress_cb=None, only_image_tags=False, save_image_info=False, save_images=True, save_image_meta=False, resume_download=False, **kwargs)[source]¶

Download project from Supervisely to the given directory.

Parameters:

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¶: Show uploading progress bar.
batch_size : int, optional¶: The number of images in the batch when they are loaded to a host.
cache=None¶: 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.
download_blob_files : bool, optional: Default is False. It will download images in classic way. If True, it will download blob files, if they are present in the project, to optimize download process.
skip_create_readme : bool, optional: Skip creating README.md file. Default is False.

Returns:

None

Return type:

NoneType

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

# Download Project
project_id = 8888
save_directory = "/home/admin/work/supervisely/source/project"
sly.Project.download(api, project_id, save_directory)
project_fs = sly.Project(save_directory, sly.OpenMode.READ)

async static download_async(api, project_id, dest_dir, dataset_ids=None, log_progress=True, semaphore=None, progress_cb=None, only_image_tags=False, save_image_info=False, save_images=True, save_image_meta=False, images_ids=None, resume_download=False, **kwargs)[source]¶

Download project from Supervisely to the given directory in asynchronous mode.

Parameters:

api¶: Supervisely API address and token.
project_id : int¶: Supervisely downloadable project ID.
dest_dir : str¶: Destination directory.
dataset_ids : List[int], optional¶: Filter datasets by IDs.
log_progress : bool¶: Show uploading progress bar.
semaphore : asyncio.Semaphore, optional¶: Semaphore to limit the number of concurrent downloads of items.
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.
images_ids : List[int], optional¶: Filter images by IDs.
resume_download : bool, optional¶: Resume download enables to download only missing files avoiding erase of existing files.
skip_create_readme : bool, optional: Skip creating README.md file. Default is False.

Returns:

None

Return type:

NoneType

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly
from supervisely._utils import run_coroutine

# 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 = 8888
save_directory = "/path/to/save/projects"

coroutine = sly.Project.download_async(api, project_id, save_directory)
run_coroutine(coroutine)

static download_bin(api, project_id, dest_dir=None, dataset_ids=None, batch_size=100, log_progress=True, progress_cb=None, return_bytesio=False)[source]¶

Download project to the local directory in binary format. Faster than downloading project in the usual way. This type of project download is more suitable for creating local backups. It is also suitable for cases where you don’t need access to individual project files, such as images or annotations.

Binary file contains the following data: - ProjectInfo - ProjectMeta - List of DatasetInfo - List of ImageInfo - Dict of Figures - Dict of AlphaGeometries

Parameters:

api¶: Supervisely API address and token.
project_id : int¶: Project ID to download.
dest_dir : str, optional¶: Destination path to local directory.
dataset_ids : List[int], optional¶: Specified list of Dataset IDs which will be downloaded. If you want to download nested datasets, you should specify all nested IDs.
batch_size : int, optional¶: Size of a downloading batch.
log_progress : bool, optional¶: Show downloading logs in the output.
progress_cb : tqdm or callable, optional¶: Function for tracking download progress. Has a higher priority than log_progress.
return_bytesio : bool, optional¶: If True, returns BytesIO object instead of saving it to the disk.

Returns:

Path to the binary file or BytesIO object.

Return type:

str or io.BytesIO

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

# Download Project in binary format
project_id = 8888
save_directory = "/home/admin/work/supervisely/source/project"
project_bin_path = sly.Project.download_bin(api, project_id, save_directory)

static get_train_val_splits_by_collections(project_dir, train_collections, val_collections, project_id, api)[source]¶

Get train and val items information from project by given train and val collections IDs.

Parameters:

project_dir : str¶: Path to project directory.
train_collections : List[int]¶: List of train collections IDs.
val_collections : List[int]¶: List of val collections IDs.
project_id : int¶: Project ID.
api¶: Supervisely API address and token.

Raises:

KeyError – if collection ID not found in project

Returns:

Tuple with lists of train items information and val items information

Return type:

Tuple[List[ItemInfo], List[ItemInfo]]

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:

Tuple[List[ItemInfo], List[ItemInfo]]

Usage Example:

import supervisely as sly

project_dir = "/home/admin/work/supervisely/projects/lemons_annotated"
train_count = 4
val_count = 2
train_items, val_items = sly.Project.get_train_val_splits_by_count(
    project_dir,
    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:

Tuple[List[ItemInfo], List[ItemInfo]]

Usage Example:

import supervisely as sly

project_dir = "/home/admin/work/supervisely/projects/lemons_annotated"
train_datasets = ['ds1', 'ds2']
val_datasets = ['ds3', 'ds4']
train_items, val_items = sly.Project.get_train_val_splits_by_dataset(
    project_dir,
    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:

Tuple[List[ItemInfo], List[ItemInfo]]

Usage Example:

import supervisely as sly

project_dir = "/home/admin/work/supervisely/projects/lemons_annotated"
train_tag_name = 'train'
val_tag_name = 'val'
train_items, val_items = sly.Project.get_train_val_splits_by_tag(
    project_dir,
    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)

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 Rectangle 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', bg_name='__bg__', bg_color=None)[source]¶

Makes a copy of the project, converts annotations to Bitmap and updates project meta. You will able to get item’s segmentation masks location by 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 will be added automatically (by default “__bg__”).
progress_cb : tqdm or callable, optional¶: Function for tracking download progress.
segmentation_type : str¶: One of: {“semantic”, “instance”}. If segmentation_type=”semantic”, background class will be added automatically (by default “__bg__”) and instances will be converted to non overlapping semantic segmentation mask.
bg_name : str, optional¶: Default background class name, used for semantic segmentation.
bg_color : list, optional. Default is [0, 0, 0]¶: Default background class color, used for semantic segmentation.

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.

If you have a metadata.json files in the project directory for images, you will be able to upload images with added custom sort parameter. To do this, use context manager api.image.add_custom_sort() with the desired key name from the metadata.json file which will be used for sorting. More about project struture: https://developer.supervisely.com/getting-started/supervisely-annotation-format/project-structure#project-structure-example Refer to the example section for usage details.

Parameters:

dir : str¶: Path to project directory.
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¶: 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 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()

# Upload Project
project_directory = "/home/admin/work/supervisely/source/project"
project_id, project_name = sly.Project.upload(
    project_directory,
    api,
    workspace_id=45,
    project_name="My Project"
)

# Upload project with added custom sort order
# This context manager processes every image and adds a custom sort order
# if `meta` is present in the image info file or image meta file.
# Otherwise, it will be uploaded without a custom sort order.
with api.image.add_custom_sort(key="key_name"):
    project_id, project_name = sly.Project.upload(
        project_directory,
        api,
        workspace_id=45,
        project_name="My Project"
    )

static upload_bin(api, file, workspace_id, project_name=None, with_custom_data=True, log_progress=True, progress_cb=None, skip_missed=False, project_description=None)[source]¶

Uploads project to Supervisely from the given binary file and suitable only for projects downloaded in binary format. This method is a counterpart to download_bin(). Faster than uploading project in the usual way.

Parameters:

api¶: Supervisely API address and token.
file : str or io.BytesIO¶: Path to the binary file or BytesIO object.
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.
with_custom_data : bool, optional¶: If True, custom data from source project will be added to a new project.
log_progress : bool, optional¶: Show uploading progress bar.
progress_cb : tqdm or callable, optional¶: Function for tracking upload progress for datasets. Has a higher priority than log_progress.
skip_missed : bool, optional¶: Skip missed images.
project_description : str, optional¶: Description of the destination project in Supervisely.

Returns:

ProjectInfo object.

Return type:

ProjectInfo

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

# Upload Project
project_dir = "/path/to/project/dir"
project_info = sly.Project.upload_bin(
    api,
    project_dir,
    workspace_id=45,
    project_name="My Project"
)

add_blob_file(file_name)[source]¶

Adds blob file to the project.

Parameters:

file_name : str¶: File name.

Returns:

None

Return type:

NoneType

Usage Example:

import supervisely as sly

project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
project.add_blob_file("blob_file.tar")

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.

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.

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

get_classes_stats(dataset_names=None, return_objects_count=True, return_figures_count=True, return_items_count=True)[source]¶

Get classes stats for the project.

Parameters:

dataset_names : List[str]¶: List of dataset names.
return_objects_count : bool¶: Return objects count.
return_figures_count : bool¶: Return figures count.
return_items_count : bool¶: Return items count.

Returns:

Dictionary with classes stats.

Return type:

dict

Usage Example:

import supervisely as sly

project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
classes_stats = project.get_classes_stats()
print(classes_stats)
# Output:
# {
#     "images": {
#         "apple": 10,
#         "banana": 20,
#     },
#     "labels": {
#         "apple": 10,
#         "banana": 20,
#     },
# }

get_item_paths(item_name)[source]¶: Get item paths for the project. Not Implemented for Project class.

set_meta(new_meta)[source]¶

Saves given project meta to project directory in json format.

Parameters:

new_meta¶: Project meta.

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]   |        |
# +-------+--------+----------------+--------+

to_coco(dest_dir=None, copy_images=False, with_captions=False, log_progress=True, progress_cb=None)[source]¶

Convert Supervisely project to COCO format.

Parameters:

dest_dir : str, optional¶: Destination directory.
copy_images : bool¶: Copy images to the destination directory.
with_captions : bool¶: Return captions for images.
log_progress : bool¶: Show uploading progress bar.
progress_cb : callable, optional¶: Function for tracking conversion progress (for all items in the project).

Returns:

None

Return type:

NoneType

Usage Example:

import supervisely as sly

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

# Convert Project to COCO format
sly.Project(project_directory).to_coco(log_progress=True)

# or

from supervisely.convert import to_coco
to_coco(project_directory, dest_dir="./coco_project")

to_pascal_voc(dest_dir=None, train_val_split_coef=0.8, log_progress=True, progress_cb=None)[source]¶

Convert Supervisely project to Pascal VOC format.

Parameters:

dest_dir : str, optional¶: Destination directory.
train_val_split_coef : float, optional¶: Coefficient for splitting images into train and validation sets.
log_progress : bool¶: Show uploading progress bar.
progress_cb : callable, optional¶: Function for tracking conversion progress (for all items in the project).

Returns:

None

Return type:

NoneType

Usage Example:

import supervisely as sly

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

# Convert Project to YOLO format
sly.Project(project_directory).to_pascal_voc(log_progress=True)

# or

from supervisely.convert import to_pascal_voc
to_pascal_voc(project_directory, dest_dir="./pascal_voc_project")

to_yolo(dest_dir=None, task_type='detect', log_progress=True, progress_cb=None, val_datasets=None)[source]¶

Convert Supervisely project to YOLO format.

Parameters:

dest_dir : str, optional¶: Destination directory.
task_type : str, optional¶: Task type for YOLO format. Possible values: ‘detection’, ‘segmentation’, ‘pose’.
log_progress : bool¶: Show uploading progress bar.
progress_cb : callable, optional¶: Function for tracking conversion progress (for all items in the project).
val_datasets : List[str], optional¶: List of dataset names for validation. Full dataset names are required (e.g., ‘ds0/nested_ds1/ds3’). If specified, datasets from the list will be marked as val, others as train. If not specified, the function will determine the validation datasets automatically.

Returns:

None

Return type:

NoneType

Usage Example:

import supervisely as sly

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

# Convert Project to YOLO format
sly.Project(project_directory).to_yolo(log_progress=True)

# or

from supervisely.convert import to_yolo
to_yolo(project_directory, dest_dir="./yolo_project")

property blob_dir : str¶

Directory for project blobs. Blobs are .tar files with images. Used for fast data transfer.

Returns:

Path to project blob 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.blob_dir)
# Output: '/home/admin/work/supervisely/projects/lemons_annotated/blob'

property blob_files : list[str]¶

List of blob files.

Returns:

List of blob files

Return type:

list

Usage Example:

import supervisely as sly

project = sly.Project("/home/admin/work/supervisely/projects/lemons_annotated", sly.OpenMode.READ)
print(project.blob_files)
# Output: []

property datasets : supervisely.project.project.Project.DatasetDict¶

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 : str¶

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 : supervisely.project.project_meta.ProjectMeta¶

Project meta.

Returns:

Project meta.

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 : str¶

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 : str¶

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 : int¶

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 : str¶

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'