StorageFolder - Encord

StorageFolder Objects

class StorageFolder()

Represents a storage folder within the Encord system.

uuid

@property
def uuid() -> UUID

Gets the unique identifier of the folder.

Returns:

UUID - The UUID of the folder.

parent_uuid

@property
def parent_uuid() -> Optional[UUID]

Gets the unique identifier of the parent folder.

Returns:

Optional[UUID] - The UUID of the parent folder, or None if there is no parent.

parent

@property
def parent() -> Optional["StorageFolder"]

Gets the parent folder.

Returns:

Optional[StorageFolder] - The parent StorageFolder object, or None if there is no parent.

name

@property
def name() -> str

Gets the name of the folder.

Returns:

str - The name of the folder.

description

@property
def description() -> str

Gets the description of the folder.

Returns:

str - The description of the folder.

client_metadata

@property
def client_metadata() -> Optional[Dict[str, Any]]

Gets the client metadata of the folder.

Returns:

Optional[Dict[str, Any]]: The client metadata as a dictionary, or None if there is no metadata.

path_to_root

@property
def path_to_root() -> List[PathElement]

Gets the path elements from the current folder to the root.

Returns:

List[PathElement] - A list of PathElement objects representing the path to the root.

list_items

def list_items(*,
               search: Optional[str] = None,
               is_in_dataset: Optional[bool] = None,
               item_types: Optional[List[StorageItemType]] = None,
               order: FoldersSortBy = FoldersSortBy.NAME,
               get_signed_urls: bool = False,
               desc: bool = False,
               page_size: int = 100) -> Iterable["StorageItem"]

Lists items in the folder.

Arguments:

search Optional[str] - Search string to filter items by name.
is_in_dataset Optional[bool] - Filter items by whether they are linked to any dataset. True and False select only linked and only unlinked items, respectively. None includes all items regardless of their dataset links.
item_types Optional[List[StorageItemType]] - Filter items by type.
order FoldersSortBy - Sort order. Defaults to FoldersSortBy.NAME.
get_signed_urls bool - Whether to get signed URLs for the items. Defaults to False.
desc bool - Sort in descending order. Defaults to False.
page_size int - Number of items to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

Iterable[StorageItem] - Iterable of items in the folder.

delete

def delete() -> None

Deletes the folder.

upload_image

def upload_image(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Uploads an image to a folder in Encord storage.

Arguments:

file_path Union[Path, str] - Path to the image file (e.g., ‘/home/user/data/image.png’).
title Optional[str] - The image title. If unspecified, this will be the file name.
client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the image. Should be a dictionary that is JSON-serializable.
cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID - The UUID of the newly created image item.

Raises:

AuthorizationError - If the user is not authorized to access the folder.
EncordException - If the image could not be uploaded, e.g., due to being in an unsupported format.

upload_video

def upload_video(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    video_metadata: Optional[CustomerProvidedVideoMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Uploads a video to a folder in Encord storage.

Arguments:

file_path Union[Path, str] - Path to the video file (e.g., ‘/home/user/data/video.mp4’).
title Optional[str] - The video title. If unspecified, this will be the file name. This title should include an extension. For example, “encord_video.mp4”.
client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the video. Should be a dictionary that is JSON-serializable.
video_metadata Optional[CustomerProvidedVideoMetadata] - Optional media metadata for a video file; if provided, Encord service will skip frame synchronization checks and will use the values specified here to render the video in the label editor.
cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID - The UUID of the newly created video item.

Raises:

AuthorizationError - If the user is not authorized to access the folder.
EncordException - If the video could not be uploaded, e.g., due to being in an unsupported format.

re_encode_videos

def re_encode_videos(storage_items: List[UUID], process_title: str,
                     force_full_reencoding: bool) -> UUID

Re-encodes the specified video items.

Arguments:

storage_items List[UUID] - List of UUIDs representing the video items to be re-encoded.
process_title str - Title for the re-encoding process.
force_full_reencoding bool - Flag to force full re-encoding.

Returns:

UUID - The UUID of the re-encoding process.

get_re_encoding_status

def get_re_encoding_status(process_hash: UUID) -> ReencodeVideoItemsResponse

Retrieves the status of a re-encoding process.

Arguments:

process_hash UUID - The UUID of the re-encoding process.

Returns:

ReencodeVideoItemsResponse - Response object containing the status of the re-encoding process.

create_dicom_series

def create_dicom_series(
    file_paths: Sequence[Union[str, Path]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Uploads a DICOM series to a folder in Encord storage.

Arguments:

file_paths Sequence[Union[str, Path]] - A list of paths to DICOM files, e.g., [‘/home/user/data/DICOM_1.dcm’, ‘/home/user/data/DICOM_2.dcm’].
title Optional[str] - The title of the DICOM series. If unspecified, this will be randomly generated. This title should NOT include an extension. For example, “encord_image_group”.
client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the DICOM series. Should be a dictionary that is JSON-serializable.
cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID - The UUID of the newly created DICOM series item.

Raises:

AuthorizationError - If the user is not authorized to access the folder.
EncordException - If the series could not be uploaded, e.g., due to being in an unsupported format.

create_image_group

def create_image_group(
    file_paths: Collection[Union[Path, str]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Creates an image group in Encord storage. Choose this type of image upload for non-sequential images that are logically connected (e.g., multiple views of the same object). See also :meth:.Folder.create_image_sequence and :meth:.Folder.upload_image.

Arguments:

file_paths Collection[Union[Path, str]] - A list of paths to images, e.g., [‘/home/user/data/img1.png’, ‘/home/user/data/img2.png’].
title Optional[str] - The title of the image group. If unspecified, this will be randomly generated. This title should NOT include an extension. For example, “encord_image_group”.
client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the image group. Should be a dictionary that is JSON-serializable.
cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID - The UUID of the newly created image group item.

Raises:

AuthorizationError - If the user is not authorized to access the folder.
EncordException - If the images could not be uploaded, e.g., due to being in an unsupported format.

create_image_sequence

def create_image_sequence(
    file_paths: Collection[Union[Path, str]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Creates an image sequence in Encord storage. Choose this type of image upload for sequential images (a timelapse or similar). A compressed video will be created from the images.

See also :meth:.Folder.create_image_group and :meth:.Folder.upload_image.

Arguments:

file_paths Collection[Union[Path, str]] - A list of paths to images, e.g., [‘/home/user/data/img1.png’, ‘/home/user/data/img2.png’].
title Optional[str] - The title of the image sequence. If unspecified, this will be randomly generated. This title should NOT include an extension. For example, “front camera 2024-04-01”.
client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the image sequence. Should be a dictionary that is JSON-serializable.
cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID - The UUID of the newly created image sequence item.

Raises:

AuthorizationError - If the user is not authorized to access the folder.
EncordException - If the images could not be uploaded, e.g., due to being in an unsupported format.

upload_audio

def upload_audio(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    audio_metadata: Optional[CustomerProvidedAudioMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Upload audio to a Folder in Encord storage.

Arguments:

file_path - File path to audio. For example: ‘/home/user/data/audio.mp3’ title: The audio title. If unspecified, the file name is the title. This title should include an extension. For example “encord_audio.mp3”. client_metadata: Optional custom metadata to be associated with the audio. Should be a dictionary that is JSON-serializable. audio_metadata: Optional media metadata for an audio file; if provided, Encord service skips scanning the audio file cloud_upload_settings: Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID of the newly created audio item.

Raises:

AuthorizationError - If the user is not authorized to access the folder.
EncordException - If the audio could not be uploaded. For example, due to being in an unsupported format.

audio_metadata

audio_metadata for audio files; if provided, frame synchronization checks are skipped.
- duration: float - Audio duration in seconds.
- file_size: int - Size of the audio file in bytes.
- mime_type: str - MIME type of the audio file (for example: audio/mpeg or audio/wav).
- sample_rate: int - Sample rate (int) in Hz.
- bit_depth: int - Size of each sample (int) in bits.
- codec: str - Codec (for example: mp3, pcm).
- num_channels: int - Number of channels.

add_private_data_to_folder_start

def add_private_data_to_folder_start(integration_id: str,
                                     private_files: Union[str, Dict, Path,
                                                          TextIO],
                                     ignore_errors: bool = False) -> UUID

Starts the process of adding private data to a folder in Encord storage.

Arguments:

integration_id str - The integration ID for the folder.
private_files Union[str, Dict, Path, TextIO] - The private files to be added.
ignore_errors bool - If True, errors will be ignored during the upload process.

Returns:

UUID - The UUID of the upload job.

add_private_data_to_folder_get_result

def add_private_data_to_folder_get_result(
        upload_job_id: UUID,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> UploadLongPollingState

Retrieves the result of adding private data to a folder in Encord storage.

Arguments:

upload_job_id UUID - The UUID of the upload job.
timeout_seconds int - The timeout in seconds for the upload job.

Returns:

UploadLongPollingState - The state of the upload job.

list_subfolders

def list_subfolders(*,
                    search: Optional[str] = None,
                    dataset_synced: Optional[bool] = None,
                    order: FoldersSortBy = FoldersSortBy.NAME,
                    desc: bool = False,
                    page_size: int = 100) -> Iterable["StorageFolder"]

Lists subfolders of the current folder.

Arguments:

search Optional[str] - Search string to filter folders by name.
dataset_synced Optional[bool] - Include or exclude folders that are mirrored by a dataset. If None, no filtering is applied.
order FoldersSortBy - Sort order for the folders. See :class:encord.storage.FoldersSortBy for available options.
desc bool - If True, sort in descending order.
page_size int - Number of folders to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

Iterable[StorageFolder] - An iterable of :class:encord.StorageFolder objects.

find_subfolders

def find_subfolders(search: Optional[str] = None,
                    dataset_synced: Optional[bool] = None,
                    order: FoldersSortBy = FoldersSortBy.NAME,
                    desc: bool = False,
                    page_size: int = 100) -> Iterable["StorageFolder"]

Recursively searches for storage folders, starting from this folder.

Arguments:

search Optional[str] - Search string to filter folders by name.
dataset_synced Optional[bool] - Include or exclude folders that are mirrored by a dataset. If None, no filtering is applied.
order FoldersSortBy - Sort order for the folders. See :class:encord.storage.FoldersSortBy for available options.
desc bool - If True, sort in descending order.
page_size int - Number of folders to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

Iterable[StorageFolder] - An iterable of :class:encord.StorageFolder objects.

create_subfolder

def create_subfolder(
        name: str,
        description: Optional[str] = None,
        client_metadata: Optional[Dict[str, Any]] = None) -> "StorageFolder"

Create a new subfolder of this folder. See also :meth:encord.user_client.EncordUserClient.create_storage_folder.

Arguments:

name - The name of the folder.
description - The description of the folder.
client_metadata - Optional arbitrary metadata to be associated with the folder. Should be a dictionary that is JSON-serializable.

Returns:

The created storage folder. See :class:encord.storage.StorageFolder for details.

find_items

def find_items(search: Optional[str] = None,
               is_in_dataset: Optional[bool] = None,
               item_types: Optional[List[StorageItemType]] = None,
               order: FoldersSortBy = FoldersSortBy.NAME,
               desc: bool = False,
               get_signed_urls: bool = False,
               page_size: int = 100) -> Iterable["StorageItem"]

Recursively search for storage items, starting from this folder.

Arguments:

search Optional[str] - Search string to filter items by name.
is_in_dataset Optional[bool] - Filter items by whether they are linked to any dataset. True and False select only linked and only unlinked items, respectively. None includes all items regardless of their dataset links.
item_types Optional[List[StorageItemType]] - Filter items by type.
order FoldersSortBy - Sort order.
desc bool - Sort in descending order.
get_signed_urls bool - If True, return signed URLs for the items.
page_size int - Number of items to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

Iterable[StorageItem] - An iterable of items in the folder and its subfolders.

Raises:

ValueError - If neither search nor item_types are provided.

get_summary

def get_summary() -> StorageFolderSummary

Get a summary of the folder (total size, number of items, etc).

Returns:

StorageFolderSummary - A summary of the folder.

See Also:

:class:encord.StorageFolderSummary for the exact set of information provided.

update

def update(name: Optional[str] = None,
           description: Optional[str] = None,
           client_metadata: Optional[Dict[str, Any]] = None,
           bundle: Optional[Bundle] = None) -> None

Update the folder’s modifiable properties. Any parameters that are not provided will not be updated.

Arguments:

name Optional[str] - New folder name.
description Optional[str] - New folder description.
client_metadata Optional[Dict[str, Any]] - New client metadata.
bundle Optional[Bundle] - Optional :class:encord.http.Bundle to use for the operation. If provided, the operation will be bundled into a single server call with other item updates using the same bundle.

Returns:

None

move_to_folder

def move_to_folder(
        target_folder: Optional[Union["StorageFolder", UUID]]) -> None

Move the folder to another folder (specify folder object or UUID), or to the root level if target_folder is None.

Arguments:

target_folder Optional[Union[StorageFolder, UUID]] - The target folder to move to, or None to move to the root level.

Returns:

None

move_items_to_folder

def move_items_to_folder(target_folder: Union["StorageFolder", UUID],
                         items_to_move: Sequence[Union[UUID, "StorageItem"]],
                         allow_mirror_dataset_changes: bool = False) -> None

Move items (list of StorageItem objects or UUIDs) to another folder (specify folder object or UUID).

Arguments:

target_folder Union[StorageFolder, UUID] - Target folder to move items to.
items_to_move Sequence[Union[UUID, StorageItem]] - List of items to move. All the items should be immediate children of the current folder.
allow_mirror_dataset_changes bool - If True, allow moving items that are linked to a mirror dataset. By default, moving such items is prohibited, as it would result in data units being removed from a dataset, potentially deleting related annotations and other data.

Returns:

None

delete_storage_items

def delete_storage_items(item_uuids: List[UUID],
                         remove_unused_frames: bool = True) -> None

Delete storage items by their UUIDs.

Arguments:

item_uuids List[UUID] - List of UUIDs of items to delete. All the items should be immediate children of the current folder.
remove_unused_frames bool - If True (default), remove individual images or DICOM files from image groups or DICOM series that are not used in any other item.

Returns:

None

list_groups

def list_groups() -> Iterable[StorageFolderGroup]

List all groups that have access to this folder.

add_group

def add_group(group_hash: Union[List[UUID], UUID], user_role: StorageUserRole)

Allow access to this folder for members of a group.

Arguments:

group_hash - Group hash, or a list of group hashes to be added.
user_role - User role that the group will be given.

Returns:

None

remove_group

def remove_group(group_hash: Union[List[UUID], UUID])

Revoke access to the folder from the members of a group.

Arguments:

group_hash - Group hash, or a list of group hashes to be removed.

Returns:

None

refetch_data

def refetch_data() -> None

Refetch data for the folder.

Returns:

None

Was this page helpful?

ProjectUser StorageItem

On this page

StorageFolder Objects
uuid
parent_uuid
parent
name
description
client_metadata
path_to_root
list_items
delete
upload_image
upload_video
re_encode_videos
get_re_encoding_status
create_dicom_series
create_image_group
create_image_sequence
upload_audio
add_private_data_to_folder_start
add_private_data_to_folder_get_result
list_subfolders
find_subfolders
create_subfolder
find_items
get_summary
update
move_to_folder
move_items_to_folder
delete_storage_items
list_groups
add_group
remove_group
refetch_data

Get Started

General

SDK Ref

Index

Ontologies

Projects

Labels

Datasets

DICOM

Active API & SDK

​StorageFolder Objects

​uuid

​parent_uuid

​parent

​name

​description

​client_metadata

​path_to_root

​list_items

​delete

​upload_image

​upload_video

​re_encode_videos

​get_re_encoding_status

​create_dicom_series

​create_image_group

​create_image_sequence

​upload_audio

audio_metadata

​add_private_data_to_folder_start

​add_private_data_to_folder_get_result

​list_subfolders

​find_subfolders

​create_subfolder

​find_items

​get_summary

​update

​move_to_folder

​move_items_to_folder

​delete_storage_items

​list_groups

​add_group

​remove_group

​refetch_data

StorageFolder Objects

uuid

parent_uuid

parent

name

description

client_metadata

path_to_root

list_items

delete

upload_image

upload_video

re_encode_videos

get_re_encoding_status

create_dicom_series

create_image_group

create_image_sequence

upload_audio

add_private_data_to_folder_start

add_private_data_to_folder_get_result

list_subfolders

find_subfolders

create_subfolder

find_items

get_summary

update

move_to_folder

move_items_to_folder

delete_storage_items

list_groups

add_group

remove_group

refetch_data