image¶

Classes

Functions

Description

Image I/O and basic image processing utilities.

exception ImageExtensionError[source]¶

Bases: Exception

Raised when an image file extension is not supported.

exception ImageReadException[source]¶

Bases: Exception

Raised when an image cannot be read or decoded.

exception UnsupportedImageFormat[source]¶

Bases: Exception

Raised when an image format is not supported even if the extension looks valid.

class CornerAnchorMode[source]¶

Bases: object

String constants describing which corner to use as an anchor (tl/tr/bl/br).

class RotateMode(*values)[source]¶

Bases: Enum

Policies for handling black regions created by rotation.

CROP_BLACK = 1¶

KEEP_BLACK = 0¶

SAVE_ORIGINAL_SIZE = 2¶

blur(image, kernel_size)[source]¶

Blurs an image using the normalized box filter.

Parameters:

image : np.ndarray¶

Image in numpy format(RGB).

kernel_size : int¶

Blurring kernel size.

Returns:

Image in numpy format with blur

Return type:

np.ndarray

Usage Example:

import supervisely as sly

blur_im = sly.image.blur(image_np, 7)

crop(img, rect)[source]¶

Crop part of the image with rectangle size. If rectangle for crop is out of image area it generates ValueError.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

rect¶

Rectangle object for crop.

Returns:

Cropped image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

# If size of rectangle is more then image shape raise ValueError:
try:
    crop_image = sly.image.crop(image_np, sly.Rectangle(0, 0, 5000, 6000))
except ValueError as error:
    print(error)
# Output: Rectangle for crop out of image area!
crop_im = sly.image.crop(image_np, sly.Rectangle(0, 0, 500, 600))

crop_with_padding(img, rect)[source]¶

Crop part of the image with rectangle size. If rectangle for crop is out of image area it generates additional padding.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

rect¶

Rectangle object for crop.

Returns:

Cropped image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

crop_with_padding_image = sly.image.crop_with_padding(image_np, sly.Rectangle(0, 0, 1000, 1200))

data_url_to_numpy(data_url)[source]¶

Convert url string to numpy image(RGB).

Parameters:

img : str

String with image url.

Returns:

Image in numpy format(RGBA)

Return type:

np.ndarray

Usage Example:

import supervisely as sly

image_np = sly.image.data_url_to_numpy(data_url)

draw_text(bitmap, text, anchor_point, corner_snap='tl', font=None, fill_background=True, color=(0, 0, 0, 255), max_text_height=None)[source]¶

Draws given text on bitmap image.

Parameters:

bitmap : np.ndarray¶

Image to draw texts in numpy format.

texts : str

Text to draw on image.

anchor_point : Tuple[int, int]¶

Coordinates of the place on the image where the text will be displayed(row, column).

corner_snap='tl'¶

Corner of image to draw texts.

font : ImageFont.FreeTypeFont, optional¶

Type of text font.

fill_background : bool, optional¶

Define fill text background or not.

color : Union[Tuple[int, int, int, int], Tuple[int, int, int]], optional¶

Text color as a tuple of three or four integers (red, green, blue, alpha) ranging from 0 to 255. If alpha is not provided, it defaults to 255 (fully opaque).

max_text_height : bool, optional¶

The parameter is necessary to draw neatly the fill background of list of texts with different heights. See self.draw_text_sequence for details.

Returns:

Height and width of text

Return type:

Tuple[int, int]

Usage Example:

import supervisely as sly

sly.image.draw_text(image, 'your text', (100, 50), color=(0, 0, 0, 255))

draw_text_sequence(bitmap, texts, anchor_point, corner_snap='tl', col_space=12, font=None, fill_background=True)[source]¶

Draws text labels on bitmap from left to right with col_space spacing between labels.

Parameters:

bitmap : np.ndarray¶

Image to draw texts in numpy format.

texts : List[str]¶

List of texts to draw on image.

anchor_point : Tuple[int, int]¶

Coordinates of the place on the image where the text will be displayed(row, column).

corner_snap='tl'¶

Corner of image to draw texts.

col_space : int, optional¶

Distance between texts.

font : ImageFont.FreeTypeFont, optional¶

Type of text font.

fill_background : bool, optional¶

Define fill text background or not.

Returns:

None

Return type:

None

Usage Example:

import supervisely as sly

sly.image.draw_text_sequence(image, ['some_text', 'another_text'], (10, 10))

drop_image_alpha_channel(img)[source]¶

Converts 4-channel image to 3-channel.

Parameters:

img : np.ndarray¶

Image in numpy format(RGBA).

Returns:

Image in numpy format(RGB)

Return type:

np.ndarray

fliplr(img)[source]¶

Flips the current image horizontally.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

Returns:

Flip image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

fliplr_image = sly.image.fliplr(image_np)

flipud(img)[source]¶

Flips the current image vertically.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

Returns:

Flip image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

flipud_image = sly.image.flipud(image_np)

gaussian_blur(image, sigma_min, sigma_max)[source]¶

Blurs an image using a Gaussian filter.

Parameters:

image : np.ndarray¶

Image in numpy format(RGB).

sigma_min : float¶

Lower bound of Gaussian kernel standard deviation range.

sigma_min¶

Upper bound of Gaussian kernel standard deviation range.

Returns:

Image in numpy format with gaussian blur

Return type:

np.ndarray

Usage Example:

import supervisely as sly

gaussian_blur_im = sly.image.gaussian_blur(image_np, 3.3, 7.5)

get_hash(img, ext)[source]¶

Hash input image with sha256 algoritm and encode result by using Base64.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

ext : str¶

File extension that defines the output format.

Returns:

Hash string

Return type:

str

Usage Example:

import supervisely as sly

hash = sly.image.get_hash(im, 'jpeg')
print(hash)
# Output: fTec3RD7Zxg0aYc0ooa5phPfBrzDe01urlFsgi5IzIQ=

get_labeling_tool_link(url, name='open in labeling tool')[source]¶

Returns html link to labeling tool for given image.

Parameters:

url : str¶

Url to labeling tool, can be obtained by get_labeling_tool_url().

name : Optional[str]¶

Name of the link in HTML, defaults to “open in labeling tool”.

Returns:

HTML link to labeling tool.

Return type:

str

get_labeling_tool_url(team_id, workspace_id, project_id, dataset_id, image_id)[source]¶

Returns url to labeling tool for given image.

Parameters:

team_id : int¶

Team id.

workspace_id : int¶

Workspace id.

project_id : int¶

Project id.

dataset_id : int¶

Dataset id.

image_id : int¶

Image id.

Returns:

Url to labeling tool.

Return type:

str

get_new_labeling_tool_url(dataset_id, image_id)[source]¶

Return a URL to the image in the new Image Labeling Toolbox (v2).

Parameters:

dataset_id : int¶

Dataset ID.

image_id : int¶

Image ID.

Returns:

URL to the image in the new Image Labeling Toolbox (v2).

Return type:

str

get_size_from_bytes(data)[source]¶

Get size of image from bytes.

Parameters:

data : bytes¶

Bytes of image.

Returns:

Height and width of image

Return type:

Tuple[int, int]

has_valid_ext(path)[source]¶

Checks if a given file has a supported extension(‘.jpg’, ‘.jpeg’, ‘.mpo’, ‘.bmp’, ‘.png’, ‘.webp’, ‘.tiff’, ‘.tif’, ‘.nrrd’).

Parameters:

path : str¶

Path to file.

Returns:

True if file extention in list of supported images extensions, False - in otherwise

Return type:

bool

Usage Example:

import supervisely as sly

sly.image.has_valid_ext('/home/admin/work/docs/new_image.jpeg') # True
sly.image.has_valid_ext('/home/admin/work/docs/016_img.py') # False

is_valid_ext(ext)[source]¶

Checks file extension for list of supported images extensions(‘.jpg’, ‘.jpeg’, ‘.mpo’, ‘.bmp’, ‘.png’, ‘.webp’, ‘.tiff’, ‘.tif’, ‘.nrrd’).

Parameters:

ext : str¶

Image extention.

Returns:

True if image extention in list of supported images extensions, False - in otherwise

Return type:

bool

Usage Example:

import supervisely as sly

sly.image.is_valid_ext('.png') # True
sly.image.is_valid_ext('.py') # False

is_valid_format(path)[source]¶

Checks if a given file has a supported format.

Parameters:

path : str¶

Path to file.

Returns:

True if file format in list of supported images formats, False - in otherwise

Return type:

bool

Usage Example:

import supervisely as sly

sly.image.is_valid_format('/images/new_image.jpeg') # True
sly.image.is_valid_format('/images/016_img.py') # False

median_blur(image, kernel_size)[source]¶

Blurs an image using the median filter.

Parameters:

image : np.ndarray¶

Image in numpy format(RGB).

kernel_size : int¶

Blurring kernel size(must be odd and greater than 1, for example: 3, 5, 7).

Returns:

Image in numpy format with median blur

Return type:

np.ndarray

Usage Example:

import supervisely as sly

median_blur_im = sly.image.median_blur(image_np, 5)

np_image_to_data_url(img)[source]¶

Convert image to url string.

Parameters:

img : np.ndarray¶

Image in numpy format(RGBA or RGB).

Returns:

String with image url

Return type:

str

Usage Example:

import supervisely as sly

data_url = sly.image.np_image_to_data_url(im)
print(data_url)
# Output: 'data:image/png;base64,iVBORw0K...'

np_image_to_data_url_backup_rgb(img)[source]¶

Convert image to url string.

Parameters:

img : np.ndarray¶

Image in numpy format(only RGB).

Returns:

String with image url

Return type:

str

Usage Example:

import supervisely as sly

data_url = sly.image.np_image_to_data_url_backup_rgb(im)
print(data_url)
# Output: 'data:image/png;base64,iVBORw0K...'

random_brightness(image, min_factor, max_factor)[source]¶

Randomly changes brightness of the input image.

Parameters:

image : np.ndarray¶

Image in numpy format(RGB).

min_factor : float¶

Lower bound of brightness range.

max_factor : float¶

Upper bound of brightness range.

Returns:

Image in numpy format with new brightness

Return type:

np.ndarray

Usage Example:

import supervisely as sly

rand_brightness_im = sly.image.random_brightness(image_np, 1.5, 8.5)

random_color_scale(image, min_factor, max_factor)[source]¶

Changes image colors by randomly scaling each of RGB components. The scaling factors are sampled uniformly from the given range.

Parameters:

image : np.ndarray¶

Image in numpy format(RGB).

min_factor : float¶

Minimum scale factor.

max_factor : float¶

Maximum scale factor.

Returns:

Image in numpy format with random color scale

Return type:

np.ndarray

Usage Example:

import supervisely as sly

random_color_scale_im = sly.image.random_color_scale(image_np, 0.5, 0.9)

random_contrast(image, min_factor, max_factor)[source]¶

Randomly changes contrast of the input image.

Parameters:

image : np.ndarray¶

Image in numpy format(RGB).

min_factor : float¶

Lower bound of contrast range.

max_factor : float¶

Upper bound of contrast range.

Returns:

Image in numpy format with new contrast

Return type:

np.ndarray

Usage Example:

import supervisely as sly

rand_contrast_im = sly.image.random_contrast(image_np, 1.1, 1.8)

random_noise(image, mean, std)[source]¶

Adds random Gaussian noise to the input image.

Parameters:

image : np.ndarray¶

Image in numpy format(RGB).

mean : float¶

The mean value of noise distribution.

std : float¶

The standard deviation of noise distribution.

Returns:

Image in numpy format with random noise

Return type:

np.ndarray

Usage Example:

import supervisely as sly

random_noise_im = sly.image.random_noise(image_np, 25, 19)

read(path, remove_alpha_channel=True)[source]¶

Loads an image from the specified file and returns it in RGB format.

Parameters:

path : str¶

Path to file.

remove_alpha_channel : bool, optional¶

Define remove alpha channel when reading file or not.

Returns:

Numpy array

Return type:

np.ndarray

Usage Example:

import supervisely as sly

im = sly.image.read('/home/admin/work/docs/image.jpeg')

read_bytes(image_bytes, keep_alpha=False)[source]¶

Loads an byte image and returns it in RGB format.

Parameters:

image_bytes : str¶

Path to file.

keep_alpha : bool, optional¶

Define consider alpha channel when reading bytes or not.

Returns:

Numpy array

Return type:

np.ndarray

Usage Example:

import supervisely as sly

im_bytes = 'ÿØÿàJFIF



\...Ù'
im = sly.image.read_bytes(im_bytes)

resize(img, out_size=None, frow=None, fcol=None)[source]¶

Resize the image to the specified size.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

out_size : Tuple[int, int], optional¶

New image size (height, width).

frow : float, optional¶

Length of output image.

fcol : float, optional¶

Height of output image.

Returns:

Resize image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

resize_image = sly.image.resize(image_np, (300, 500))

resize_inter_nearest(img, out_size=None, frow=None, fcol=None)[source]¶

Resize image to match a certain size. Performs interpolation to up-size or down-size images.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

out_size : Tuple[int, int], optional¶

New image size (height, width).

frow : float, optional¶

Length of output image.

fcol : float, optional¶

Height of output image.

Returns:

Resize image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

resize_image_nearest = sly.image.resize_inter_nearest(image_np, (300, 700))

restore_proportional_size(in_size, out_size=None, frow=None, fcol=None, f=None)[source]¶

Calculate new size of the image.

Parameters:

in_size : Tuple[int, int]¶

Size of input image (height, width).

out_size : Tuple[int, int], optional¶

New image size (height, width).

frow : float, optional¶

Length of output image.

fcol : float, optional¶

Height of output image.

f : float, optional¶

Positive non zero scale factor.

Returns:

Height and width of image

Return type:

Tuple[int, int]

rotate(img, degrees_angle, mode=RotateMode.KEEP_BLACK)[source]¶

Rotates current image.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

degrees_angle : int¶

Angle in degrees for rotating.

mode=RotateMode.KEEP_BLACK¶

One of RotateMode enum values.

Returns:

Rotate image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

# keep_black mode
rotate_im_keep_black = sly.image.rotate(image_np, 45)
# crop_black mode
rotate_im_crop_black = sly.image.rotate(image_np, 45, sly.image.RotateMode.CROP_BLACK)
# origin_size mode
rotate_im_origin_size = sly.image.rotate(image_np, 45, sly.image.RotateMode.SAVE_ORIGINAL_SIZE) * 255

scale(img, factor)[source]¶

Scales current image with the given factor.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

factor : float¶

Scale size.

Returns:

Resize image in numpy format

Return type:

np.ndarray

Usage Example:

import supervisely as sly

scale_image = sly.image.scale(image_np, 0.3)

validate_ext(path)[source]¶

Generate exception error if file extention is not in list of supported images extensions(‘.jpg’, ‘.jpeg’, ‘.mpo’, ‘.bmp’, ‘.png’, ‘.webp’, ‘.tiff’, ‘.tif’, ‘.nrrd’).

Parameters:

path : str¶

Path to file.

Returns:

None

Return type:

None

Usage Example:

import supervisely as sly

sly.image.validate_ext('/home/admin/work/docs/new_image.jpeg')

try:
    sly.image.validate_ext('/home/admin/work/docs/016_img.py')
except ImageExtensionError as error:
    print(error)

# Output: Unsupported image extension: '.py' for file '/home/admin/work/docs/016_img.py'. Only the following extensions are supported: .jpg, .jpeg, .mpo, .bmp, .png, .webp.

validate_format(path)[source]¶

Validate input file format, if file extension is not supported raise ImageExtensionError.

Parameters:

path : str¶

Path to file.

Returns:

None

Return type:

None

Usage Example:

import supervisely as sly

print(sly.image.validate_format('/home/admin/work/docs/new_image.jpeg'))
# Output: None

try:
    sly.image.validate_format('/home/admin/work/docs/016_img.py')
except ImageReadException as error:
    print(error)

# Output: Error has occured trying to read image '/home/admin/work/docs/016_img.py'. Original exception message: "cannot identify image file '/home/admin/work/docs/016_img.py'"

write(path, img, remove_alpha_channel=True)[source]¶

Saves the image to the specified file. It create directory from path if the directory for this path does not exist.

Parameters:

path : str¶

Path to file.

img : np.ndarray¶

Image in numpy array(RGB format).

remove_alpha_channel : bool, optional¶

Define remove alpha channel when writing file or not.

Returns:

None

Return type:

None

Usage Example:

import supervisely as sly

path = '/home/admin/work/docs/new_image.jpeg'
sly.image.write(path, image_np)

write_bytes(img, ext)[source]¶

Compresses the image and stores it in the byte object.

Parameters:

img : np.ndarray¶

Image in numpy format(RGB).

ext : str¶

File extension that defines the output format.

Returns:

Bytes object

Return type:

bytes

Usage Example:

import supervisely as sly

bytes = sly.image.write_bytes(image_np, 'jpeg')
print(type(bytes))
# Output: <class 'bytes'>