lightly.api

The lightly.api module provides access to the Lightly web-app.

.upload

Upload to Lightly API

lightly.api.upload.upload_dataset(dataset: lightly.data.dataset.LightlyDataset, dataset_id: str, token: str, max_workers: int = 8, mode: str = 'thumbnails', verbose: bool = True)

Uploads images from a directory to the Lightly cloud solution.

Args:

dataset

The dataset to upload.

dataset_id:

The unique identifier for the dataset.

token:

Token for authentication.

max_workers:

Maximum number of workers uploading images in parallel.

max_requests:

Maximum number of requests a single worker can do before he has to wait for the others.

mode:

One of [full, thumbnails, metadata]. Whether to upload thumbnails, full images, or metadata only.

Raises:

ValueError if dataset is too large. RuntimeError if the connection to the server failed. RuntimeError if dataset already has an initial tag.

lightly.api.upload.upload_embeddings_from_csv(path_to_embeddings: str, dataset_id: str, token: str, max_upload: int = 32, embedding_name: str = 'default', verbose: bool = True)

Uploads embeddings from a csv file to the cloud solution.

The csv file should be in the format specified by lightly. See the documentation on lightly.utils.io for more information.

Args:

path_to_embeddings:

Path to csv file containing embeddings.

dataset_id:

The unique identifier for the dataset.

token:

Token for authentication.

max_upload:

Size of a batch of embeddings which is uploaded at once.

embedding_name:

Name the embedding will have on the Lightly web-app.

Raises:

RuntimeError if there is an error during the upload of a batch of embeddings.

lightly.api.upload.upload_file_with_signed_url(file, url: str) → bool

Upload a file to the cloud storage using a signed URL.

Args:

filename:

Path to a file for upload.

url:

Signed url for push.

Returns:

A boolean value indicating successful upload.

Raises:

RuntimeError if put request failed.

lightly.api.upload.upload_images_from_folder(path_to_folder: str, dataset_id: str, token: str, max_workers: int = 8, mode: str = 'thumbnails', size: int = - 1, verbose: bool = True)

Uploads images from a directory to the Lightly cloud solution.

Args:

path_to_folder:

Path to the folder which holds the input images.

dataset_id:

The unique identifier for the dataset.

token:

Token for authentication.

max_workers:

Maximum number of workers uploading images in parallel.

max_requests:

Maximum number of requests a single worker can do before he has to wait for the others.

mode:

One of [full, thumbnails, metadata]. Whether to upload thumbnails, full images, or metadata only.

size:

Desired output size. If negative, default output size is used. If size is a sequence like (h, w), output size will be matched to this. If size is an int, smaller edge of the image will be matched to this number. i.e, if height > width, then image will be rescaled to (size * height / width, size).

Raises:

ValueError if dataset is too large. RuntimeError if the connection to the server failed. RuntimeError if dataset already has an initial tag.

.download

Download from Lightly API

lightly.api.download.get_samples_by_tag(tag_name: str, dataset_id: str, token: str, mode: str = 'list', filenames: List[str] = None)

Get the files associated with a given tag and dataset.

Asks the servers for all samples in a given tag and dataset. If mode is mask or indices, the list of all filenames must be specified. Can return either the list of all filenames in the tag, or a mask or indices indicating which of the provided filenames are in the tag.

Args:

tag_name:

Name of the tag to query.

dataset_id:

The unique identifier of the dataset.

token:

Token for authentication.

mode:

Return type, must be in [“list”, “mask”, “indices”].

filenames:

List of all filenames.

Returns:

Either list of filenames, binary mask, or list of indices specifying the samples in the requested tag.

Raises:

ValueError, AssertionError

.utils

Communication Utility

lightly.api.utils.PIL_to_bytes(img, ext: str = 'png', quality: int = None)

Return the PIL image as byte stream. Useful to send image via requests.

lightly.api.utils.check_filename(basename)

Checks the length of the filename.

Args:

basename:

Basename of the file.

lightly.api.utils.check_image(image)

Checks whether an image is corrupted or not.

The function reports the metadata, and opens the file to check whether it is corrupt or not.

Args:

image:

PIL image from which metadata will be computed.

Returns:

A dictionary of metadata of the image.

lightly.api.utils.get_meta_from_img(img)

Calculates metadata from PIL image.

• Mean

• Standard Deviation

• Signal To Noise

• Sharpness

• Size in Bytes

• Shape

• Sum of Values

• Sum of Squares

Args:

PIL Image.

Returns:

A dictionary containing the metadata of the image.

lightly.api.utils.get_request(dst_url, params=None, max_backoff=32, max_retries=5)

Makes a GET request with random offset retries.

Args:

dst_url:

Url the GET request is made to.

params:

GET parameters.

max_backoff:

Maximal backoff before throwing timing out.

max_retries:

Maximum number of retries before timing out.

Returns:

The server response.

Raises:

RuntimeError if the request fails.

lightly.api.utils.get_thumbnail_from_img(img, size: int = 80)

Compute the thumbnail of the image.

Args:

img:

PIL Image.

size:

Size of the thumbnail.

Returns:

Thumbnail as PIL Image.

lightly.api.utils.getenv(key: str, default: str)

Return the value of the environment variable key if it exists, or default if it doesn’t.

lightly.api.utils.image_mean(np_img: numpy.ndarray)

Return mean of each channel.

lightly.api.utils.image_std(np_img: numpy.ndarray)

Return standard deviation of each channel.

lightly.api.utils.post_request(dst_url, data=None, json=None, max_backoff=32, max_retries=5)

Makes a POST request with random offset retries.

Args:

dst_url:

Url the GET request is made to.

data:

POST data.

json:

POST json.

max_backoff:

Maximal backoff before throwing timing out.

max_retries:

Maximum number of retries before timing out.

Returns:

The server response.

Raises:

RuntimeError if the request fails.

lightly.api.utils.put_request(dst_url, data=None, params=None, json=None, max_backoff=32, max_retries=5)

Makes a PUT request with random offset retries.

Args:

dst_url:

Url the PUT request is made to.

data:

PUT data.

params:

PUT parameters.

json:

PUT json.

max_backoff:

Maximal backoff before throwing timing out.

max_retries:

Maximum number of retries before timing out.

Returns:

The server response.

Raises:

RuntimeError if the request fails.

lightly.api.utils.resize_image(image, max_width: int, max_height: int)

Resize the image if it is too large for the web-app.

lightly.api.utils.shape(np_img: numpy.ndarray)

Shape of the image as np.ndarray.

lightly.api.utils.sharpness(img)

Calculate the sharpness of the image using a Laplacian Kernel.

lightly.api.utils.signal_to_noise_ratio(img, axis: int = None, ddof: int = 0)

Calculate the signal to noise ratio of the image.

lightly.api.utils.size_in_bytes(img)

Return the size of the image in bytes.

lightly.api.utils.sum_of_squares(np_img: numpy.ndarray)

Return the sum of the squared pixel values of each channel.

lightly.api.utils.sum_of_values(np_img: numpy.ndarray)

Return the sum of the pixel values of each channel.