VolumeProject¶

class VolumeProject(directory, mode)[source]¶

Bases: VideoProject

A local Supervisely project for 3D volume data.

Contains one or more VolumeDataset datasets with volumes and their annotations. Also provides binary snapshot export/import via download_bin() / upload_bin().

VolumeProject is a parent directory for volume datasets. VolumeProject object is immutable. :param directory: Path to volume project directory. :type directory: str :param mode: Determines working mode for the given project. :type mode: OpenMode

Usage Example:

import supervisely as sly

project_path = "/home/admin/work/supervisely/projects/volumes_project"
project = sly.VolumeProject(project_path, sly.OpenMode.READ)

Methods

`add_blob_file`	Adds blob file to the project.
`build_snapshot`	Create a video project snapshot in Arrow/Parquet+tar.zst format and return it as BytesIO.
`copy_data`	Makes a copy of the VideoProject.
`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 volume project from Supervisely to the given directory.
`download_async`
`download_bin`	Download a Volume Project snapshot into a Parquet-backed binary blob (`.tar.zst` file or in-memory BytesIO).
`get_classes_stats`
`get_item_paths`	Get item paths for the project.
`get_train_val_splits_by_collections`	Not available for VolumeProject class.
`get_train_val_splits_by_count`	Not available for VolumeProject class.
`get_train_val_splits_by_dataset`	Not available for VolumeProject class.
`get_train_val_splits_by_tag`	Not available for VolumeProject class.
`get_url`	Get URL to video datasets list in Supervisely.
`read_single`	Read project from given ditectory.
`remove_classes`	Not available for VideoProject class.
`remove_classes_except`	Not available for VideoProject class.
`remove_items_without_both_objects_and_tags`	Not available for VideoProject class.
`remove_items_without_objects`	Not available for VideoProject class.
`remove_items_without_tags`	Not available for VideoProject class.
`restore_snapshot`	Restore a video project from a snapshot and return ProjectInfo.
`set_key_id_map`	Save given KeyIdMap object to project dir in json format.
`set_meta`	Saves given project meta to project directory in json format.
`to_coco`	Convert Supervisely project to COCO format.
`to_detection_task`	Not available for VideoProject class.
`to_pascal_voc`	Convert Supervisely project to Pascal VOC format.
`to_segmentation_task`	Not available for VideoProject class.
`to_yolo`	Convert Supervisely project to YOLO format.
`upload`	Uploads volume project to Supervisely from the given directory.
`upload_bin`	Restore a volume project from a Parquet blob produced by `download_bin()`.
`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.
`key_id_map`
`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

Key-indexed collection of VolumeDataset datasets.

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 VolumeDataset

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

items()¶

Get list of all items in collection.

Returns:

List of ObjClassCollection, TagMetaCollection or TagCollection objects

Return type:

List[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])
items = collection.items()
print(items)
# Output:
# [<supervisely.annotation.tag_meta.TagMeta object at 0x7fd08eae4340>,
#  <supervisely.annotation.tag_meta.TagMeta object at 0x7fd08eae4370>]

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 VolumeDataset

classmethod read_single(dir)¶: Read project from given ditectory. Generate exception error if given dir contains more than one subdirectory :param dir: str :returns: New instance of VideoProject object. :rtype: VideoProject

static build_snapshot(api, project_id, dataset_ids=None, batch_size=50, log_progress=True, progress_cb=None, schema_version='v2.0.0')¶

Create a video project snapshot in Arrow/Parquet+tar.zst format and return it as BytesIO.

Parameters:

api¶: Supervisely API client.
project_id : int¶: Source project ID.
dataset_ids : Optional[List[int]]¶: Optional list of dataset IDs to include. If provided, only those datasets (and their videos/annotations) will be included in the snapshot.
batch_size : int¶: Batch size for downloading video annotations.
log_progress : bool¶: If True, shows progress (uses internal tqdm progress bars) when progress_cb is not provided.
progress_cb : Optional[Union[tqdm, Callable]]¶: Optional progress callback. Can be a tqdm or callable, accepting an integer increment.
schema_version : str¶: Snapshot schema version. Controls the internal Parquet layout/fields. Supported values are the keys from get_video_snapshot_schema (currently: “v2.0.0”).

Returns:

In-memory snapshot stream (io.BytesIO).

Return type:

io.BytesIO

static download(api, project_id, dest_dir, dataset_ids=None, download_volumes=True, log_progress=False, progress_cb=None, **kwargs)[source]¶

Download volume 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.
download_volumes : bool, optional¶: Download volume data files or not.
log_progress : bool¶: Show uploading progress bar.
progress_cb : tqdm or callable, optional¶: Function for tracking the download progress.

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/vlm_project"
sly.VolumeProject.download(api, project_id, save_directory)
project_fs = sly.VolumeProject(save_directory, sly.OpenMode.READ)

static download_bin(api, project_id, dest_dir=None, dataset_ids=None, download_volumes=True, log_progress=False, progress_cb=None, return_bytesio=False, schema_version='v2.0.0', batch_size=50, *args, **kwargs)[source]¶

Download a Volume Project snapshot into a Parquet-backed binary blob (.tar.zst file or in-memory BytesIO).

The snapshot stores:

Project info and meta
Dataset tree (dataset infos)
Volume infos (optionally)
Volume annotations (for the included volumes)

The resulting binary snapshot can be restored later with upload_bin().

Parameters:

api¶: Supervisely API client.
project_id : int¶: Source Volume Project ID on the server.
dest_dir : str, optional¶: Local folder where the snapshot file will be written. Required when return_bytesio=False.
dataset_ids : List[int], optional¶: Optional list of dataset IDs to include. If provided, only these datasets will be included (recursively, preserving tree structure where applicable).
download_volumes : bool, optional¶: If False, only project/meta/dataset tree is stored (volume infos and annotations are skipped). This is useful for structure-only snapshots.
log_progress : bool¶: If True, show a progress bar (unless a custom progress_cb is provided).
progress_cb : tqdm or callable, optional¶: Optional callback (or tqdm-like object) called with incremental progress.
return_bytesio : bool, optional¶: If True, return an in-memory BytesIO with snapshot bytes. If False, write snapshot to dest_dir and return the file path.
schema_version : str, optional¶: Snapshot schema version. Controls the internal Parquet layout/fields. Supported values are the keys from get_volume_snapshot_schema() (currently: "v2.0.0").
batch_size : int, optional¶: Batch size for API calls determining how many items to download in one request. Default is 50.

Returns:

Snapshot file path (when return_bytesio=False) or a BytesIO (when return_bytesio=True).

Return type:

str or io.BytesIO

Raises:

ValueError – If dest_dir is not provided and return_bytesio is False.
RuntimeError – If required optional dependencies (e.g. pyarrow) are missing.

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

# 1) Save snapshot to disk
out_path = sly.VolumeProject.download_bin(
    api,
    project_id=123,
    dest_dir="/tmp/vol_project_snapshot",
    download_volumes=True,
    log_progress=True,
)

# 2) Create an in-memory snapshot (BytesIO) and restore it
blob = sly.VolumeProject.download_bin(
    api,
    project_id=123,
    return_bytesio=True,
    download_volumes=False,  # structure-only
)
restored = sly.VolumeProject.upload_bin(api, blob, workspace_id=45, project_name="Restored")

static get_train_val_splits_by_collections(project_dir, train_collections, val_collections, project_id, api)[source]¶: Not available for VolumeProject class. :raises NotImplementedError: in all cases.

static get_train_val_splits_by_count(project_dir, train_count, val_count)[source]¶: Not available for VolumeProject class. :raises NotImplementedError: in all cases.

static get_train_val_splits_by_dataset(project_dir, train_datasets, val_datasets)[source]¶: Not available for VolumeProject class. :raises NotImplementedError: in all cases.

static get_train_val_splits_by_tag(project_dir, train_tag_name, val_tag_name, untagged='ignore')[source]¶: Not available for VolumeProject class. :raises NotImplementedError: in all cases.

static get_url(id)¶

Get URL to video datasets list in Supervisely.

Parameters:

id : int¶: VideoProject ID in Supervisely.

Returns:

URL to datasets list.

Return type:

str

Usage Example:

from supervisely import VideoProject

project_id = 10093
datasets_link = VideoProject.get_url(project_id)

print(datasets_link)
# Output: "/projects/10093/datasets"

static remove_classes(project_dir, classes_to_remove=None, inplace=False)¶: Not available for VideoProject class. :raises NotImplementedError: in all cases.

static remove_classes_except(project_dir, classes_to_keep=None, inplace=False)¶: Not available for VideoProject class. :raises NotImplementedError: in all cases.

static remove_items_without_both_objects_and_tags(project_dir, inplace=False)¶: Not available for VideoProject class. :raises NotImplementedError: in all cases.

static remove_items_without_objects(project_dir, inplace=False)¶: Not available for VideoProject class. :raises NotImplementedError: in all cases.

static remove_items_without_tags(project_dir, inplace=False)¶: Not available for VideoProject class. :raises NotImplementedError: in all cases.

static restore_snapshot(api, snapshot_bytes, workspace_id, project_name=None, with_custom_data=True, log_progress=True, progress_cb=None, skip_missed=False, project_description=None)¶: Restore a video project from a snapshot and return ProjectInfo.

static to_detection_task(src_project_dir, dst_project_dir=None, inplace=False, progress_cb=None)¶: Not available for VideoProject class. :raises NotImplementedError: in all cases.

static to_segmentation_task(src_project_dir, dst_project_dir=None, inplace=False, target_classes=None, progress_cb=None, segmentation_type='semantic')¶: Not available for VideoProject class. :raises NotImplementedError: in all cases.

static upload(directory, api, workspace_id, project_name=None, log_progress=True, progress_cb=None)[source]¶

Uploads volume project to Supervisely from the given directory.

Parameters:

directory : 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 the 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 Volume Project
project_directory = "/home/admin/work/supervisely/source/vlm_project"
project_id, project_name = sly.VolumeProject.upload(
    project_directory,
    api,
    workspace_id=45,
    project_name="My Volume Project"
)

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

Restore a volume project from a Parquet blob produced by download_bin().

Parameters:

api¶: Supervisely API client.
file : Union[str, io.BytesIO]¶: Snapshot file path (.tar.zst) or an in-memory BytesIO stream.
workspace_id : int¶: Target workspace ID where the project will be created.
project_name : str, optional¶: Optional new project name. If not provided, the name from the snapshot will be used. If the name already exists in the workspace, a free name will be chosen.
log_progress : bool¶: If True, show a progress bar (unless a custom progress_cb is provided).
progress_cb : tqdm or callable, optional¶: Optional callback (or tqdm-like object) called with incremental progress.
skip_missed_entities : bool: If True, skip volumes that cannot be restored because their source hash is missing in the snapshot payload. If False, such cases raise an error.
project_description : str, optional¶: Description of the destination project in Supervisely.
with_custom_data : bool, optional¶: Whether to include custom_data from the snapshot in the restored project. Default is True.

Returns:

ProjectInfo object.

Return type:

ProjectInfo

Raises:

RuntimeError – If the snapshot contains volumes without hashes and skip_missed is False.

add_blob_file(file_name)¶

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

Makes a copy of the VideoProject.

Parameters:

dst_directory : str¶: Path to video project parent directory.
dst_name : str, optional¶: Video 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:

New instance of VideoProject object.

Return type:

VideoProject

Usage Example:

import supervisely as sly

project = sly.VideoProject("/home/admin/work/supervisely/projects/videos_example", sly.OpenMode.READ)
print(project.total_items)
# Output: 6

new_project = project.copy_data("/home/admin/work/supervisely/projects/", "videos_example_copy")
print(new_project.total_items)
# Output: 6

create_dataset(ds_name, ds_path=None)¶

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_item_paths(item_name)¶: Get item paths for the project. Not Implemented for Project class.

set_key_id_map(new_map)¶: Save given KeyIdMap object to project dir in json format. :param new_map: KeyIdMap object. :type new_map: KeyIdMap

set_meta(new_meta)¶

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

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

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

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.VolumeProject("/home/admin/work/supervisely/projects/volumes", sly.OpenMode.READ)
print(project.type)
# Output: 'volumes'