image¶

Classes

`CornerAnchorMode`
`RotateMode`

Functions

`blur`(image, kernel_size)	Blurs an image using the normalized box filter.
`crop`(img, rect)	Crop part of the image with rectangle size.
`crop_with_padding`(img, rect)	Crop part of the image with rectangle size.
`data_url_to_numpy`(data_url)	Convert url string to numpy image(RGB).
`draw_text`(bitmap, text, anchor_point[, ...])	Draws given text on bitmap image.
`draw_text_sequence`(bitmap, texts, anchor_point)	Draws text labels on bitmap from left to right with col_space spacing between labels.
`drop_image_alpha_channel`(img)	Converts 4-channel image to 3-channel.
`fliplr`(img)	Flips the current image horizontally.
`flipud`(img)	Flips the current image vertically.
`gaussian_blur`(image, sigma_min, sigma_max)	Blurs an image using a Gaussian filter.
`get_hash`(img, ext)	Hash input image with sha256 algoritm and encode result by using Base64.
`get_labeling_tool_link`(url[, name])	Returns html link to labeling tool for given image.
`get_labeling_tool_url`(team_id, workspace_id, ...)	Returns url to labeling tool for given image.
`has_valid_ext`(path)	Checks if a given file has a supported extension('.jpg', '.jpeg', '.mpo', '.bmp', '.png', '.webp', '.tiff', '.tif', '.nrrd').
`is_valid_ext`(ext)	Checks file extension for list of supported images extensions('.jpg', '.jpeg', '.mpo', '.bmp', '.png', '.webp', '.tiff', '.tif', '.nrrd').
`is_valid_format`(path)	Checks if a given file has a supported format.
`median_blur`(image, kernel_size)	Blurs an image using the median filter.
`np_image_to_data_url`(img)	Convert image to url string.
`np_image_to_data_url_backup_rgb`(img)	Convert image to url string.
`random_brightness`(image, min_factor, max_factor)	Randomly changes brightness of the input image.
`random_color_scale`(image, min_factor, max_factor)	Changes image colors by randomly scaling each of RGB components.
`random_contrast`(image, min_factor, max_factor)	Randomly changes contrast of the input image.
`random_noise`(image, mean, std)	Adds random Gaussian noise to the input image.
`read`(path[, remove_alpha_channel])	Loads an image from the specified file and returns it in RGB format.
`read_bytes`(image_bytes[, keep_alpha])	Loads an byte image and returns it in RGB format.
`resize`(img[, out_size, frow, fcol])	Resize the image to the specified size.
`resize_inter_nearest`(img[, out_size, frow, fcol])	Resize image to match a certain size.
`restore_proportional_size`(in_size[, ...])	Calculate new size of the image.
`rotate`(img, degrees_angle[, mode])	Rotates current image.
`scale`(img, factor)	Scales current image with the given factor.
`validate_ext`(path)	Generate exception error if file extention is not in list of supported images extensions('.jpg', '.jpeg', '.mpo', '.bmp', '.png', '.webp', '.tiff', '.tif', '.nrrd').
`validate_format`(path)	Validate input file format, if file extension is not supported raise ImageExtensionError.
`write`(path, img[, remove_alpha_channel])	Saves the image to the specified file.
`write_bytes`(img, ext)	Compresses the image and stores it in the byte object.

Description

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)

Before¶	After¶

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

Before¶	After¶

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

Before¶	After¶

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 : CornerAnchorMode, optional: 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))

Before¶	After¶

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 : CornerAnchorMode, optional: 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

NoneType

Usage example

import supervisely as sly

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

Before¶	After¶

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)

Before¶	After¶

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)

Before¶	After¶

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)

Before¶	After¶

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

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)

Before¶	After¶

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)

Before¶	After¶

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)

Before¶	After¶

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)

Before¶	After¶

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)

Before¶	After¶

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

Before¶	After¶

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

Before¶	After¶

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, optional: 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

Before¶	After keep_black mode¶	After crop_black mode¶	After origin_size mode¶

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)

Before¶	After¶

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

NoneType

Usage example

import supervisely as sly

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

try:
    print(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

NoneType

Usage example

import supervisely as sly

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

try:
    print(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

NoneType

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