ImageApi

class ImageApi[source]

Bases: supervisely.api.module_api.RemoveableBulkModuleApi

API for working with Image. ImageApi object is immutable.

Parameters
api : Api

API connection to the server

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

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

image_info = api.image.get_info_by_id(image_id) # api usage example

Methods

add_tag

Add tag with given ID to Image by ID.

add_tag_batch

Add tag with given ID to Images by IDs.

check_existing_hashes

Checks existing hashes for Images.

check_image_uploaded

Checks if Image has been uploaded.

copy

Copies Image with given ID to destination Dataset.

copy_batch

Copies Images with given IDs to Dataset.

copy_batch_optimized

Copies Images with given IDs to Dataset.

download

Downloads Image from Dataset to local path by ID.

download_bytes

Download Images with given IDs from Dataset in Binary format.

download_np

Download Image with given id in numpy format.

download_nps

Download Images with given IDs in numpy format.

download_nps_by_hashes

Download Images with given hashes in Supervisely server in numpy format.

download_nps_by_hashes_generator

rtype

Generator[Tuple[str, ndarray], None, None]

download_nps_generator

rtype

Generator[Tuple[int, ndarray], None, None]

download_path

Downloads Image from Dataset to local path by ID.

download_paths

Download Images with given ids and saves them for the given paths.

download_paths_by_hashes

Download Images with given hashes in Supervisely server and saves them for the given paths.

exists

get_filtered_list

List of filtered Images in the given Dataset.

get_free_name

Generates a free name for an entity with the given parent_id and name.

get_info_by_id

Get Image information by ID.

get_info_by_id_batch

Get Images information by ID.

get_info_by_name

get_list

List of Images in the given Dataset.

get_list_all_pages

Get list of all or limited quantity entities from the Supervisely server.

get_list_all_pages_generator

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

get_list_generator

rtype

Iterator[List[ImageInfo]]

get_project_id

Gets Project ID by Image ID.

info_sequence

Get list of all ImageInfo field names.

info_tuple_name

Get string name of ImageInfo NamedTuple.

move

Moves Image with given ID to destination Dataset.

move_batch

Moves Images with given IDs to Dataset.

move_batch_optimized

Moves Images with given IDs to Dataset.

preview_url

Previews Image with the given resolution parameters.

remove

Remove image from supervisely by id.

remove_batch

Remove images from supervisely by ids.

storage_url

Get full Image URL link in Supervisely server.

update_meta

It is possible to add custom JSON data to every image for storing some additional information.

upload_hash

Upload Image from given hash to Dataset.

upload_hashes

Upload images from given hashes to Dataset.

upload_id

Upload Image by ID to Dataset.

upload_ids

Upload Images by IDs to Dataset.

upload_link

Uploads Image from given link to Dataset.

upload_links

Uploads Images from given links to Dataset.

upload_np

Upload given Image in numpy format with given name to Dataset.

upload_nps

Upload given Images in numpy format with given names to Dataset.

upload_path

Uploads Image with given name from given local path to Dataset.

upload_paths

Uploads Images with given names from given local path to Dataset.

url

Gets Image URL by ID.

Attributes

MAX_WAIT_ATTEMPTS

Maximum number of attempts that will be made to wait for a certain condition to be met.

WAIT_ATTEMPT_TIMEOUT_SEC

Number of seconds for intervals between attempts.

InfoType

alias of supervisely.api.module_api.ImageInfo

add_tag(image_id, tag_id, value=None)[source]

Add tag with given ID to Image by ID.

Parameters
image_id : int

Image ID in Supervisely.

tag_id : int

Tag ID in Supervisely.

value : int or str or None, optional

Tag value.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

image_id = 2389126
tag_id = 277083
api.image.add_tag(image_id, tag_id)
add_tag_batch(image_ids, tag_id, value=None, progress_cb=None, batch_size=100, tag_meta=None)[source]

Add tag with given ID to Images by IDs.

Parameters
image_ids : List[int]

List of Images IDs in Supervisely.

tag_id : int

Tag ID in Supervisely.

value : int or str or None, optional

Tag value.

progress_cb : tqdm or callable, optional

Function for tracking progress of adding tag.

batch_size : int, optional

Batch size

tag_meta : TagMeta, optional

Tag Meta. Needed for value validation, omit to skip validation

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

image_ids = [2389126, 2389127]
tag_id = 277083
api.image.add_tag_batch(image_ids, tag_id)
check_existing_hashes(hashes, progress_cb=None)[source]

Checks existing hashes for Images.

Parameters
hashes : List[str]

List of hashes.

progress_cb : tqdm or callable, optional

Function for tracking progress of checking.

Returns

List of existing hashes

Return type

List[str]

Usage example

Checkout detailed example here (you must be logged into your Supervisely account)

# Helpful method when your uploading was interrupted
# You can check what images has been successfully uploaded by their hashes and what not
# And continue uploading the rest of the images from that point

import supervisely as sly

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

# Find project
project = api.project.get_info_by_id(WORKSPACE_ID, PROJECT_ID)

# Get paths of all images in a directory
images_paths = sly.fs.list_files('images_to_upload')

#Calculate hashes for all images paths
hash_to_image = {}
images_hashes = []

for idx, item in enumerate(images_paths):
    item_hash = sly.fs.get_file_hash(item)
    images_hashes.append(item_hash)
    hash_to_image[item_hash] = item

# Get hashes that are already on server
remote_hashes = api.image.check_existing_hashes(images_hashes)
already_uploaded_images = {hh: hash_to_image[hh] for hh in remote_hashes}
check_image_uploaded(hash)[source]

Checks if Image has been uploaded.

Parameters
hash : str

Image hash in Supervisely.

Returns

True if Image with given hash exist, otherwise False

Return type

bool

Usage example
import supervisely as sly

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

image_check_uploaded = api.image.check_image_uploaded("YZKQrZH5C0rBvGGA3p7hjWahz3/pV09u5m30Bz8GeYs=")
print(image_check_uploaded)
# Output: True
copy(dst_dataset_id, id, change_name_if_conflict=False, with_annotations=False)[source]

Copies Image with given ID to destination Dataset.

Parameters
dst_dataset_id : int

Destination Dataset ID in Supervisely.

id : int

Image ID in Supervisely.

change_name_if_conflict : bool, optional

If True adds suffix to the end of Image name when Dataset already contains an Image with identical name, If False and images with the identical names already exist in Dataset raises error.

with_annotations : bool, optional

If True Image will be copied to Dataset with annotations, otherwise only Images without annotations.

Returns

Information about Image. See info_sequence

Return type

ImageInfo

Usage example
import supervisely as sly

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

dst_ds_id = 365184
img_id = 121236920

img_info = api.image.copy(dst_ds_id, img_id, with_annotations=True)
copy_batch(dst_dataset_id, ids, change_name_if_conflict=False, with_annotations=False, progress_cb=None)[source]

Copies Images with given IDs to Dataset.

Parameters
dst_dataset_id : int

Destination Dataset ID in Supervisely.

ids : List[int]

Images IDs in Supervisely.

change_name_if_conflict : bool, optional

If True adds suffix to the end of Image name when Dataset already contains an Image with identical name, If False and images with the identical names already exist in Dataset raises error.

with_annotations : bool, optional

If True Image will be copied to Dataset with annotations, otherwise only Images without annotations.

progress_cb : tqdm or callable, optional

Function for tracking the progress of copying.

Raises

TypeError if type of ids is not list

Raises

ValueError if images ids are from the destination Dataset

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

ds_lemon_id = 1780

ds_lemon_img_infos = api.image.get_list(ds_lemon_id)

lemons_img_ids = [lemon_img_info.id for lemon_img_info in ds_lemon_img_infos]

ds_fruit_id = 2574
ds_fruit_img_infos = api.image.copy_batch(ds_fruit_id, lemons_img_ids, with_annotations=True)
copy_batch_optimized(src_dataset_id, src_image_infos, dst_dataset_id, with_annotations=True, progress_cb=None, dst_names=None, batch_size=500, skip_validation=False, save_source_date=True)[source]

Copies Images with given IDs to Dataset.

Parameters
src_dataset_id : int

Source Dataset ID in Supervisely.

src_image_infos : List [ ImageInfo ]

ImageInfo objects of images to copy.

dst_dataset_id : int

Destination Dataset ID in Supervisely.

with_annotations : bool, optional

If True Image will be copied to Dataset with annotations, otherwise only Images without annotations.

progress_cb : tqdm or callable, optional

Function for tracking the progress of copying.

dst_names : List [ ImageInfo ], optional

ImageInfo list with existing items in destination dataset.

batch_size : int, optional

Number of elements to copy for each request.

skip_validation : bool, optional

Flag for skipping additinal validations.

save_source_date : bool, optional

Save source annotation dates (creation and modification) or create a new date.

Raises

TypeError if type of src_image_infos is not list

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

src_ds_id = 2231
img_infos = api.image.get_list(src_ds_id)

dest_ds_id = 2574
dest_img_infos = api.image.copy_batch_optimized(src_ds_id, img_infos, dest_ds_id)
download(id, path)[source]

Downloads Image from Dataset to local path by ID.

Parameters
id : int

Image ID in Supervisely.

path : str

Local save path for Image.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

img_info = api.image.get_info_by_id(770918)
save_path = os.path.join("/home/admin/work/projects/lemons_annotated/ds1/test_imgs/", img_info.name)

api.image.download_path(770918, save_path)
download_bytes(dataset_id, ids, progress_cb=None)[source]

Download Images with given IDs from Dataset in Binary format.

Parameters
dataset_id : int

Dataset ID in Supervisely, where Images are located.

ids : List[int]

List of Image IDs in Supervisely.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

Returns

List of Images in binary format

Return type

List[bytes]

Usage example
import supervisely as sly

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

img_bytes = api.image.download_bytes(dataset_id, [770918])
print(img_bytes)
# Output: [b'ÿØÿàJFIF\...]
download_np(id, keep_alpha=False)[source]

Download Image with given id in numpy format.

Parameters
id : int

Image ID in Supervisely.

keep_alpha : bool, optional

If True keeps alpha mask for image, otherwise don’t.

Returns

Image in RGB numpy matrix format

Return type

np.ndarray

Usage example
import supervisely as sly

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

image_np = api.image.download_np(770918)
download_nps(dataset_id, ids, progress_cb=None, keep_alpha=False)[source]

Download Images with given IDs in numpy format.

Parameters
dataset_id : int

Dataset ID in Supervisely, where Images are located.

ids : List[int]

List of Images IDs in Supervisely.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

keep_alpha : bool, optional

If True keeps alpha mask for Image, otherwise don’t.

Returns

List of Images in RGB numpy matrix format

Return type

List[np.ndarray]

Usage example
import supervisely as sly

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

image_ids = [770918, 770919, 770920]
image_nps = api.image.download_nps(dataset_id, image_ids)
download_nps_by_hashes(hashes, keep_alpha=False, progress_cb=None)[source]

Download Images with given hashes in Supervisely server in numpy format.

Parameters
hashes : List[str]

List of images hashes in Supervisely.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

Returns

List of images

Return type

class

List[np.ndarray]

Usage example
import supervisely as sly

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

image_ids = [770918, 770919, 770920]
image_hashes = []

for img_id in image_ids:
    img_info = api.image.get_info_by_id(image_id)
    image_hashes.append(img_info.hash)

image_nps = api.image.download_nps_by_hashes(image_hashes)
download_path(id, path)[source]

Downloads Image from Dataset to local path by ID.

Parameters
id : int

Image ID in Supervisely.

path : str

Local save path for Image.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

img_info = api.image.get_info_by_id(770918)
save_path = os.path.join("/home/admin/work/projects/lemons_annotated/ds1/test_imgs/", img_info.name)

api.image.download_path(770918, save_path)
download_paths(dataset_id, ids, paths, progress_cb=None)[source]

Download Images with given ids and saves them for the given paths.

Parameters
dataset_id : int

Dataset ID in Supervisely, where Images are located.

ids : List[int]

List of Image IDs in Supervisely.

paths : List[str]

Local save paths for Images.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

Raises

ValueError if len(ids) != len(paths)

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

local_save_dir = "/home/admin/work/projects/lemons_annotated/ds1/test_imgs"
save_paths = []
image_ids = [771755, 771756, 771757, 771758, 771759, 771760]
img_infos = api.image.get_info_by_id_batch(image_ids)

p = tqdm(desc="Images downloaded: ", total=len(img_infos))
for img_info in img_infos:
    save_paths.append(os.path.join(local_save_dir, img_info.name))

api.image.download_paths(2573, image_ids, save_paths, progress_cb=p)
# Progress:
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 0, "total": 6, "timestamp": "2021-03-15T19:47:15.406Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 1, "total": 6, "timestamp": "2021-03-15T19:47:16.366Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 2, "total": 6, "timestamp": "2021-03-15T19:47:16.367Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 3, "total": 6, "timestamp": "2021-03-15T19:47:16.367Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 4, "total": 6, "timestamp": "2021-03-15T19:47:16.367Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 5, "total": 6, "timestamp": "2021-03-15T19:47:16.368Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 6, "total": 6, "timestamp": "2021-03-15T19:47:16.368Z", "level": "info"}
download_paths_by_hashes(hashes, paths, progress_cb=None)[source]

Download Images with given hashes in Supervisely server and saves them for the given paths.

Parameters
hashes : List[str]

List of images hashes in Supervisely.

paths : List[str]

List of paths to save images.

progress_cb : tqdm or callable, optional

Function for tracking download progress.

Raises

ValueError if len(hashes) != len(paths)

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

dataset_id = 447130
dir_for_save = '/home/admin/Downloads/img'
hashes = []
paths = []
imgs_info = api.image.get_list(dataset_id)
for im_info in imgs_info:
    hashes.append(im_info.hash)
    # It is necessary to save images with the same names(extentions) as on the server
    paths.append(os.path.join(dir_for_save, im_info.name))
api.image.download_paths_by_hashes(hashes, paths)
exists(parent_id, name)[source]
get_filtered_list(dataset_id, filters=None, sort='id', sort_order='asc', force_metadata_for_links=True, limit=None, return_first_response=False)[source]

List of filtered Images in the given Dataset. Differs in a more flexible filter format from the get_list() method.

Parameters
dataset_id : int

Dataset ID in which the Images are located.

filters : List[Dict], optional

List of params to sort output Images.

sort : str, optional

Field name to sort. One of {‘id’ (default), ‘name’, ‘description’, ‘labelsCount’, ‘createdAt’, ‘updatedAt’}.

sort_order : str, optional

Sort order. One of {‘asc’ (default), ‘desc’}

Returns

Objects with image information from Supervisely.

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

# Get list of Images with names containing subsequence '2008'
img_infos = api.image.get_filtered_list(dataset_id, filters=[{ 'type': 'images_filename', 'data': { 'value': '2008' } }])
get_free_name(parent_id, name)

Generates a free name for an entity with the given parent_id and name. Adds an increasing suffix to original name until a unique name is found.

Parameters
parent_id : int

ID of the parent entity.

name : str

Name of the entity.

Returns

Returns free name.

Return type

str

Usage example
import supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


name = "IMG_0315.jpeg"
dataset_id = 55832
free_name = api.image.get_free_name(dataset_id, name)
print(free_name) # IMG_0315_001.jpeg
get_info_by_id(id, force_metadata_for_links=True)[source]

Get Image information by ID.

Parameters
id : int

Image ID in Supervisely.

Returns

Object with image information from Supervisely.

Return type

ImageInfo

Usage example
import supervisely as sly

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

# You can get Image ID by listing all images in the Dataset as shown in get_list
# Or you can open certain image in Supervisely Annotation Tool UI and get last digits of the URL
img_info = api.image.get_info_by_id(770918)
get_info_by_id_batch(ids, progress_cb=None, force_metadata_for_links=True)[source]

Get Images information by ID.

Parameters
ids : List[int]

Images IDs in Supervisely.

progress_cb : tqdm or callable, optional

Function for tracking the progress.

Returns

Objects with image information from Supervisely.

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

img_ids = [376728, 376729, 376730, 376731, 376732, 376733]
img_infos = image.get_info_by_id_batch(img_ids)
get_info_by_name(dataset_id, name, force_metadata_for_links=True)[source]
get_list(dataset_id, filters=None, sort='id', sort_order='asc', limit=None, force_metadata_for_links=True, return_first_response=False)[source]

List of Images in the given Dataset.

Parameters
dataset_id : int

Dataset ID in which the Images are located.

filters : List[Dict], optional

List of params to sort output Images.

sort : str, optional

Field name to sort. One of {‘id’ (default), ‘name’, ‘description’, ‘labelsCount’, ‘createdAt’, ‘updatedAt’}

sort_order : str, optional

Sort order. One of {‘asc’ (default), ‘desc’}

limit : int, optional

Max number of list elements. No limit if None (default).

Returns

Objects with image information from Supervisely.

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

# Get list of Images with width = 1067
img_infos = api.image.get_list(dataset_id, filters=[{ 'field': 'width', 'operator': '=', 'value': '1067' }])
print(img_infos)
# Output: [ImageInfo(id=770915,
#                    name='IMG_3861.jpeg',
#                    link=None,
#                    hash='ZdpMD+ZMJx0R8BgsCzJcqM7qP4M8f1AEtoYc87xZmyQ=',
#                    mime='image/jpeg',
#                    ext='jpeg',
#                    size=148388,
#                    width=1067,
#                    height=800,
#                    labels_count=4,
#                    dataset_id=2532,
#                    created_at='2021-03-02T10:04:33.973Z',
#                    updated_at='2021-03-02T10:04:33.973Z',
#                    meta={},
#                    path_original='/h5un6l2bnaz1vj8a9qgms4-public/images/original/7/h/Vo/...jpg',
#                    full_storage_url='http://app.supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/images/original/7/h/Vo/...jpg'),
#                    tags=[],
# ImageInfo(id=770916,
#           name='IMG_1836.jpeg',
#           link=None,
#           hash='YZKQrZH5C0rBvGGA3p7hjWahz3/pV09u5m30Bz8GeYs=',
#           mime='image/jpeg',
#           ext='jpeg',
#           size=140222,
#           width=1067,
#           height=800,
#           labels_count=3,
#           dataset_id=2532,
#           created_at='2021-03-02T10:04:33.973Z',
#           updated_at='2021-03-02T10:04:33.973Z',
#           meta={},
#           path_original='/h5un6l2bnaz1vj8a9qgms4-public/images/original/C/Y/Hq/...jpg',
#           full_storage_url='http://app.supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/images/original/C/Y/Hq/...jpg'),
#           tags=[]
# ]
get_list_all_pages(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)

Get list of all or limited quantity entities from the Supervisely server.

Parameters
method : str

Request method name

data : dict

Dictionary with request body info

progress_cb : Progress, optional

Function for tracking download progress.

convert_json_info_cb : Callable, optional

Function for convert json info

limit : int, optional

Number of entity to retrieve

return_first_response : bool, optional

Specify if return first response

get_list_all_pages_generator(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

Parameters
method : str

Request method name

data : dict

Dictionary with request body info

progress_cb : Progress, optional

Function for tracking download progress.

convert_json_info_cb : Callable, optional

Function for convert json info

limit : int, optional

Number of entity to retrieve

return_first_response : bool, optional

Specify if return first response

get_project_id(image_id)[source]

Gets Project ID by Image ID.

Parameters
image_id : int

Image ID in Supervisely.

Returns

Project ID where Image is located.

Return type

int

Usage example
import supervisely as sly

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

img_id = 121236920
img_project_id = api.image.get_project_id(img_id)
print(img_project_id)
# Output: 53939
static info_sequence()[source]

Get list of all ImageInfo field names.

Returns

List of ImageInfo field names.`

Return type

List[str]

static info_tuple_name()[source]

Get string name of ImageInfo NamedTuple.

Returns

NamedTuple name.

Return type

str

move(dst_dataset_id, id, change_name_if_conflict=False, with_annotations=False)[source]

Moves Image with given ID to destination Dataset.

Parameters
dst_dataset_id : int

Destination Dataset ID in Supervisely.

id : int

Image ID in Supervisely.

change_name_if_conflict : bool, optional

If True adds suffix to the end of Image name when Dataset already contains an Image with identical name, If False and images with the identical names already exist in Dataset raises error.

with_annotations : bool, optional

If True Image will be copied to Dataset with annotations, otherwise only Images without annotations.

Returns

Information about Image. See info_sequence

Return type

ImageInfo

Usage example
import supervisely as sly

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

dst_ds_id = 365484
img_id = 533336920

img_info = api.image.copy(dst_ds_id, img_id, with_annotations=True)
move_batch(dst_dataset_id, ids, change_name_if_conflict=False, with_annotations=False, progress_cb=None)[source]

Moves Images with given IDs to Dataset.

Parameters
dst_dataset_id : int

Destination Dataset ID in Supervisely.

ids : List[int]

Images IDs in Supervisely.

change_name_if_conflict : bool, optional

If True adds suffix to the end of Image name when Dataset already contains an Image with identical name, If False and images with the identical names already exist in Dataset raises error.

with_annotations : bool, optional

If True Image will be copied to Dataset with annotations, otherwise only Images without annotations.

progress_cb : tqdm or callable, optional

Function for tracking the progress of moving.

Raises

TypeError if type of ids is not list

Raises

ValueError if images ids are from the destination Dataset

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

ds_lemon_id = 1780
ds_kiwi_id = 1233

ds_lemon_img_infos = api.image.get_list(ds_lemon_id)
ds_kiwi_img_infos = api.image.get_list(ds_kiwi_id)

fruit_img_ids = []
for lemon_img_info, kiwi_img_info in zip(ds_lemon_img_infos, ds_kiwi_img_infos):
    fruit_img_ids.append(lemon_img_info.id)
    fruit_img_ids.append(kiwi_img_info.id)

ds_fruit_id = 2574
ds_fruit_img_infos = api.image.move_batch(ds_fruit_id, fruit_img_ids, with_annotations=True)
move_batch_optimized(src_dataset_id, src_image_infos, dst_dataset_id, with_annotations=True, progress_cb=None, dst_names=None, batch_size=500, skip_validation=False, save_source_date=True)[source]

Moves Images with given IDs to Dataset.

Parameters
src_dataset_id : int

Source Dataset ID in Supervisely.

src_image_infos : List [ ImageInfo ]

ImageInfo objects of images to move.

dst_dataset_id : int

Destination Dataset ID in Supervisely.

with_annotations : bool, optional

If True Image will be copied to Dataset with annotations, otherwise only Images without annotations.

progress_cb : tqdm or callable, optional

Function for tracking the progress of moving.

dst_names : List [ ImageInfo ], optional

ImageInfo list with existing items in destination dataset.

batch_size : int, optional

Number of elements to copy for each request.

skip_validation : bool, optional

Flag for skipping additinal validations.

save_source_date : bool, optional

Save source annotation dates (creation and modification) or create a new date.

Raises

TypeError if type of src_image_infos is not list

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

src_ds_id = 2231
img_infos = api.image.get_list(src_ds_id)

dest_ds_id = 2574
dest_img_infos = api.image.move_batch_optimized(src_ds_id, img_infos, dest_ds_id)
preview_url(url, width=None, height=None, quality=70)[source]

Previews Image with the given resolution parameters.

Parameters
url : str

Full Image storage URL.

width : int

Preview Image width.

height : int

Preview Image height.

quality : int

Preview Image quality.

Returns

New URL with resized Image

Return type

str

Usage example
import supervisely as sly

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

image_id = 376729
img_info = api.image.get_info_by_id(image_id)
img_preview_url = api.image.preview_url(img_info.full_storage_url, width=512, height=256)
remove(image_id)[source]

Remove image from supervisely by id.

Parameters
image_id : int

Images ID in Supervisely.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

image_id = 2389126
api.image.remove(image_id)
remove_batch(ids, progress_cb=None, batch_size=50)[source]

Remove images from supervisely by ids.

Parameters
ids : List[int]

List of Images IDs in Supervisely.

progress_cb : tqdm or callable, optional

Function for tracking progress of removing.

Returns

None

Return type

NoneType

Usage example
import supervisely as sly

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

image_ids = [2389126, 2389127]
api.image.remove_batch(image_ids)
storage_url(path_original)[source]

Get full Image URL link in Supervisely server.

Parameters
path_original : str

Original Image path in Supervisely server.

Returns

Full Image URL link in Supervisely server

Return type

str

Usage example
import supervisely as sly

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

image_id = 376729
img_info = api.image.get_info_by_id(image_id)
img_storage_url = api.image.storage_url(img_info.path_original)
update_meta(id, meta)[source]

It is possible to add custom JSON data to every image for storing some additional information. Updates Image metadata by ID. Metadata is visible in Labeling Tool. Supervisely also have 2 apps: import metadata and export metadata

Parameters
id : int

Image ID in Supervisely.

meta : dict

Image metadata.

Raises

TypeError if meta type is not dict

Returns

Image information in dict format with new meta

Return type

dict

Usage example
import os
import json
import supervisely as sly

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

image_info = api.image.get_info_by_id(id=3212008)
print(image_info.meta)
# Output: {}

new_meta = {'Camera Make': 'Canon', 'Color Space': 'sRGB', 'Focal Length': '16 mm'}
new_image_info = api.image.update_meta(id=3212008, meta=new_meta)

image_info = api.image.get_info_by_id(id=3212008)
print(json.dumps(obj=image_info.meta, indent=4))
# Output: {
#     "Camera Make": "Canon",
#     "Color Space": "sRGB",
#     "Focal Length": "16 mm"
# }
upload_hash(dataset_id, name, hash, meta=None)[source]

Upload Image from given hash to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

name : str

Image name.

hash : str

Image hash.

meta : dict, optional

Image metadata.

Returns

Information about Image. See info_sequence

Return type

ImageInfo

Usage example
import supervisely as sly

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

dst_dataset_id = 452984
im_info = api.image.get_info_by_id(193940090)
hash = im_info.hash
# It is necessary to upload image with the same name(extention) as in src dataset
name = im_info.name
meta = {1: 'meta_example'}
new_in_info = api.image.upload_hash(dst_dataset_id, name, hash, meta)
print(json.dumps(new_in_info, indent=4))
# Output: [
#     196793586,
#     "IMG_0748.jpeg",
#     null,
#     "NEjmnmdd7DOzaFAKK/nCIl5CtcwZeMkhW3CHe875p9g=",
#     "image/jpeg",
#     "jpeg",
#     66885,
#     600,
#     500,
#     0,
#     452984,
#     "2021-03-16T09:09:45.587Z",
#     "2021-03-16T09:09:45.587Z",
#     {
#         "1": "meta_example"
#     },
#     "/h5un6l2bnaz1vj8a9qgms4-public/images/original/P/a/kn/W2mzMQg435d6wG0.jpg",
#     "https://app.supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/images/original/P/a/kn/W2mzMQg435hiHJAPgMU.jpg"
# ]
upload_hashes(dataset_id, names, hashes, progress_cb=None, metas=None, batch_size=50, skip_validation=False)[source]

Upload images from given hashes to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

names : List[str]

Images names.

hashes : List[str]

Images hashes.

progress_cb : tqdm or callable, optional

Function for tracking the progress of uploading.

metas : List[dict], optional

Images metadata.

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

src_dataset_id = 447130
hashes = []
names = []
metas = []
imgs_info = api.image.get_list(src_dataset_id)
# Create lists of hashes, images names and meta information for each image
for im_info in imgs_info:
    hashes.append(im_info.hash)
    # It is necessary to upload images with the same names(extentions) as in src dataset
    names.append(im_info.name)
    metas.append({im_info.name: im_info.size})

dst_dataset_id = 452984
progress = sly.Progress("Images upload: ", len(hashes))
new_imgs_info = api.image.upload_hashes(dst_dataset_id, names, hashes, progress.iters_done_report, metas)
# Output:
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 0, "total": 10, "timestamp": "2021-03-16T11:59:07.444Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 10, "total": 10, "timestamp": "2021-03-16T11:59:07.644Z", "level": "info"}
upload_id(dataset_id, name, id, meta=None)[source]

Upload Image by ID to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

name : str

Image name.

id : int

Image ID in Supervisely.

meta : dict, optional

Image metadata.

Returns

Information about Image. See info_sequence

Return type

ImageInfo

Usage example
import supervisely as sly

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

dst_dataset_id = 452984
im_info = api.image.get_info_by_id(193940090)
id = im_info.id
# It is necessary to upload image with the same name(extention) as in src dataset
name = im_info.name
meta = {1: 'meta_example'}
new_in_info = api.image.upload_id(dst_dataset_id, name, id, meta)
print(json.dumps(new_in_info, indent=4))
# Output: [
#     196793605,
#     "IMG_0748.jpeg",
#     null,
#     "NEjmnmdd7DOzaFAKK/nCIl5CtcwZeMkhW3CHe875p9g=",
#     "image/jpeg",
#     "jpeg",
#     66885,
#     600,
#     500,
#     0,
#     452984,
#     "2021-03-16T09:27:12.620Z",
#     "2021-03-16T09:27:12.620Z",
#     {
#         "1": "meta_example"
#     },
#     "/h5un6l2bnaz1vj8a9qgms4-public/images/original/P/a/kn/W2mzMQg435d6wG0AJGJTOsL1FqMUNOPqu4VdzFAN36LqtGwBIE4AmLOQ1BAxuIyB0bHJAPgMU.jpg",
#     "https://app.supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/images/original/P/a/kn/iEaDEkejnfnb1Tz56ka0hiHJAPgMU.jpg"
# ]
upload_ids(dataset_id, names, ids, progress_cb=None, metas=None, batch_size=50, force_metadata_for_links=True, infos=None, skip_validation=False)[source]

Upload Images by IDs to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

names : List[str]

Images names.

ids : List[int]

Images IDs.

progress_cb : tqdm or callable, optional

Function for tracking the progress of uploading.

metas : List[dict], optional

Images metadata.

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

src_dataset_id = 447130

ids = []
names = []
metas = []
imgs_info = api.image.get_list(src_dataset_id)
# Create lists of ids, images names and meta information for each image
for im_info in imgs_info:
    ids.append(im_info.id)
    # It is necessary to upload images with the same names(extentions) as in src dataset
    names.append(im_info.name)
    metas.append({im_info.name: im_info.size})

dst_dataset_id = 452984
progress = sly.Progress("Images upload: ", len(ids))
new_imgs_info = api.image.upload_ids(dst_dataset_id, names, ids, progress.iters_done_report, metas)
# Output:
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 0, "total": 10, "timestamp": "2021-03-16T12:31:36.550Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Images downloaded: ", "current": 10, "total": 10, "timestamp": "2021-03-16T12:31:37.119Z", "level": "info"}

Uploads Image from given link to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

name : str

Image name.

link : str

Link to Image.

meta : dict, optional

Image metadata.

Returns

Information about Image. See info_sequence

Return type

ImageInfo

Usage example
import supervisely as sly

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

img_name = 'Avatar.jpg'
img_link = 'https://m.media-amazon.com/images/M/MV5BMTYwOTEwNjAzMl5BMl5BanBnXkFtZTcwODc5MTUwMw@@._V1_.jpg'

img_info = api.image.upload_link(dataset_id, img_name, img_link)

Uploads Images from given links to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

names : List[str]

Images names.

links : List[str]

Links to Images.

progress_cb : tqdm or callable, optional

Function for tracking the progress of uploading.

metas : List[dict], optional

Images metadata.

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

img_names = ['Avatar.jpg', 'Harry Potter.jpg', 'Avengers.jpg']
img_links = ['https://m.media-amazon.com/images/M/MV5BMTYwOTEwNjAzMl5BMl5BanBnXkFtZTcwODc5MTUwMw@@._V1_.jpg',
             'https://m.media-amazon.com/images/M/MV5BNDYxNjQyMjAtNTdiOS00NGYwLWFmNTAtNThmYjU5ZGI2YTI1XkEyXkFqcGdeQXVyMTMxODk2OTU@._V1_.jpg',
             'https://m.media-amazon.com/images/M/MV5BNjQ3NWNlNmQtMTE5ZS00MDdmLTlkZjUtZTBlM2UxMGFiMTU3XkEyXkFqcGdeQXVyNjUwNzk3NDc@._V1_.jpg']

img_infos = api.image.upload_links(dataset_id, img_names, img_links)
upload_np(dataset_id, name, img, meta=None)[source]

Upload given Image in numpy format with given name to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

name : str

Image name with extension.

img : np.ndarray

image in RGB format(numpy matrix)

meta : dict, optional

Image metadata.

Returns

Information about Image. See info_sequence

Return type

ImageInfo

Usage example
import supervisely as sly

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

img_np = sly.image.read("/home/admin/Downloads/7777.jpeg")
img_info = api.image.upload_np(dataset_id, name="7777.jpeg", img=img_np)
upload_nps(dataset_id, names, imgs, progress_cb=None, metas=None)[source]

Upload given Images in numpy format with given names to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

names : List[str]

Images names.

imgs : List[np.ndarray]

Images in RGB numpy matrix format

progress_cb : tqdm or callable, optional

Function for tracking the progress of uploading.

metas : List[dict], optional

Images metadata.

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
import supervisely as sly

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

img_np_1 = sly.image.read("/home/admin/Downloads/7777.jpeg")
img_np_2 = sly.image.read("/home/admin/Downloads/8888.jpeg")
img_np_3 = sly.image.read("/home/admin/Downloads/9999.jpeg")

img_names = ["7777.jpeg", "8888.jpeg", "9999.jpeg"]
img_nps = [img_np_1, img_np_2, img_np_3]

img_infos = api.image.upload_nps(dataset_id, names=img_names, imgs=img_nps)
upload_path(dataset_id, name, path, meta=None)[source]

Uploads Image with given name from given local path to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

name : str

Image name.

path : str

Local Image path.

meta : dict, optional

Image metadata.

Returns

Information about Image. See info_sequence

Return type

ImageInfo

Usage example
import supervisely as sly

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

img_info = api.image.upload_path(dataset_id, name="7777.jpeg", path="/home/admin/Downloads/7777.jpeg")
upload_paths(dataset_id, names, paths, progress_cb=None, metas=None)[source]

Uploads Images with given names from given local path to Dataset.

Parameters
dataset_id : int

Dataset ID in Supervisely.

names : List[str]

List of Images names.

paths : List[str]

List of local Images pathes.

progress_cb : tqdm or callable, optional

Function for tracking the progress of uploading.

metas : List[dict], optional

Images metadata.

Raises

ValueError if len(names) != len(paths)

Returns

List with information about Images. See info_sequence

Return type

List[ImageInfo]

Usage example
os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

img_names = ["7777.jpeg", "8888.jpeg", "9999.jpeg"]
image_paths = ["/home/admin/Downloads/img/770918.jpeg", "/home/admin/Downloads/img/770919.jpeg", "/home/admin/Downloads/img/770920.jpeg"]

img_infos = api.image.upload_path(dataset_id, names=img_names, paths=img_paths)
url(team_id, workspace_id, project_id, dataset_id, image_id)[source]

Gets Image URL by ID.

Parameters
team_id : int

Team ID in Supervisely.

workspace_id : int

Workspace ID in Supervisely.

project_id : int

Project ID in Supervisely.

dataset_id : int

Dataset ID in Supervisely.

image_id : int

Image ID in Supervisely.

Returns

Image URL

Return type

str

Usage example
import supervisely as sly

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

team_id = 16087
workspace_id = 23821
project_id = 53939
dataset_id = 254737
image_id = 121236920

img_url = api.image.url(team_id, workspace_id, project_id, dataset_id, image_id)
print(url)
# Output: https://app.supervise.ly/app/images/16087/23821/53939/254737#image-121236920