VideoProject¶

class VideoProject[source]¶

Bases: supervisely.project.project.Project

VideoProject is a parent directory for video dataset. VideoProject object is immutable.

Parameters

directory : str: Path to video project directory.
mode : OpenMode: Determines working mode for the given project.

Usage example

import supervisely as sly
project_path = "/home/admin/work/supervisely/projects/videos_example"
project = sly.Project(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 video project from Supervisely to the given directory.
`download_async`	Download video project from Supervisely to the given directory asynchronously.
`download_bin`	Download video project snapshot in Arrow/Parquet-based binary format.
`get_classes_stats`
`get_item_paths`	rtype `ItemPaths`
`get_train_val_splits_by_collections`	Not available for VideoProject class.
`get_train_val_splits_by_count`	Not available for VideoProject class.
`get_train_val_splits_by_dataset`	Not available for VideoProject class.
`get_train_val_splits_by_tag`	Not available for VideoProject 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 `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`	Upload video project from given directory in Supervisely.
`upload_bin`	Restore a video project from an Arrow/Parquet-based binary snapshot.
`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.

dataset_class¶: alias of supervisely.project.video_project.VideoDataset

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

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

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

Return type: BytesIO

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

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

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 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, download_videos=True, save_video_info=False, log_progress=True, progress_cb=None, resume_download=False)[source]¶

Download video project from Supervisely to the given directory.

Parameters

api : Api: Supervisely Api class object.
project_id : int: Project ID in Supervisely.
dest_dir : str: Directory to download video project.
dataset_ids : list [ int ], optional: Datasets IDs in Supervisely to download.
download_videos : bool, optional: Download videos from Supervisely video project in dest_dir or not.
save_video_info : bool, optional: Save video infos or not.
log_progress : bool: Log download progress or not.
progress_cb : tqdm, optional: Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

# Local destination Project folder
save_directory = "/home/admin/work/supervisely/source/video_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 Video Project
sly.VideoProject.download(api, project_id, save_directory)
project_fs = sly.VideoProject(save_directory, sly.OpenMode.READ)

async static download_async(api, project_id, dest_dir, semaphore=None, dataset_ids=None, download_videos=True, save_video_info=False, log_progress=True, progress_cb=None, include_custom_data=False, resume_download=False, **kwargs)[source]¶

Download video project from Supervisely to the given directory asynchronously.

Parameters

api : Api: Supervisely Api class object.
project_id : int: Project ID in Supervisely.
dest_dir : str: Directory to download video project.
semaphore : asyncio.Semaphore or int, optional: Semaphore to limit the number of concurrent downloads of items.
dataset_ids : list [ int ], optional: Datasets IDs in Supervisely to download.
download_videos : bool, optional: Download videos from Supervisely video project in dest_dir or not.
save_video_info : bool, optional: Save video infos or not.
log_progress : bool: Log download progress or not.
progress_cb : tqdm, optional: Function for tracking download progress.
include_custom_data : bool, optional: Include custom data in the download.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly
from supervisely._utils import run_coroutine

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

save_directory = "/home/admin/work/supervisely/source/video_project"
project_id = 8888

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

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

Download video project snapshot in Arrow/Parquet-based binary format.

Result is a .tar.zst archive containing:

project_info.json
project_meta.json
key_id_map.json
manifest.json
datasets.parquet
videos.parquet
objects.parquet
figures.parquet

Parameters

api : Api: Supervisely API client.
project_id : int: Source project ID.
dest_dir : Optional[str]: Directory to save the resulting .tar.zst file. Required if return_bytesio is False.
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. Cannot be greater than 100 due to API limitations. Default is 50.
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-like callable or a function accepting an integer increment.
return_bytesio : bool: If True, return the snapshot as io.BytesIO. If False, write the snapshot to dest_dir and return the output file path.

Returns

Either output file path (.tar.zst) when return_bytesio is False, or an in-memory snapshot stream when return_bytesio is True.

Return type

Union[str, io.BytesIO]

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

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static get_train_val_splits_by_count(project_dir, train_count, val_count)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static get_train_val_splits_by_dataset(project_dir, train_datasets, val_datasets)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static get_train_val_splits_by_tag(project_dir, train_tag_name, val_tag_name, untagged='ignore')[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static get_url(id)[source]¶

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"

classmethod read_single(dir)[source]¶: Read project from given ditectory. Generate exception error if given dir contains more than one subdirectory :param dir: str :return: VideoProject class object

static remove_classes(project_dir, classes_to_remove=None, inplace=False)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static remove_classes_except(project_dir, classes_to_keep=None, inplace=False)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static remove_items_without_both_objects_and_tags(project_dir, inplace=False)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static remove_items_without_objects(project_dir, inplace=False)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

static remove_items_without_tags(project_dir, inplace=False)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

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)[source]¶

Restore a video project from a snapshot and return ProjectInfo.

Return type: ProjectInfo

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

set_meta(new_meta)¶

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

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

static to_detection_task(src_project_dir, dst_project_dir=None, inplace=False, progress_cb=None)[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

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

static to_segmentation_task(src_project_dir, dst_project_dir=None, inplace=False, target_classes=None, progress_cb=None, segmentation_type='semantic')[source]¶

Not available for VideoProject class. :raises: NotImplementedError in all cases.

Return type: None

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 or TaskType, 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")

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

Upload video project from given directory in Supervisely.

Parameters

dir : str: Directory with video project.
api : Api: Api class object.
workspace_id : int: Workspace ID in Supervisely to upload video project.
project_name : str: Name of video project.
log_progress : bool: Logging progress of download video project or not.

Returns

New video project ID in Supervisely and project name

Return type

int, str

Usage example

import supervisely as sly

# Local folder with Video Project
project_directory = "/home/admin/work/supervisely/source/video_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 Video Project
project_id, project_name = sly.VideoProject.upload(
    project_directory,
    api,
    workspace_id=45,
    project_name="My Video 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]¶

Restore a video project from an Arrow/Parquet-based binary snapshot.

Parameters

api : Api: Supervisely API client.
file : Union[str, io.BytesIO]: Snapshot file path (.tar.zst) or in-memory snapshot stream.
workspace_id : int: Target workspace ID where the project will be created.
project_name : Optional[str]: 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.
with_custom_data : bool: If True, restore project/dataset/video custom data (when present in the snapshot).
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-like callable or a function accepting an integer increment.
skip_missed : bool: If True, skip videos that are missing on server when restoring by hash.
project_description : str, optional: Description of the destination project in Supervisely.

Returns

Info of the newly created project.

Return type

ProjectInfo

property blob_dir¶

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

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