cvtk

cvtk.imread(source, exif_transpose: bool = True, req_timeout: int = 60) → Image

Open image from various sources

This function opens image from various sources, including file, url, bytes, base64, PIL image, and numpy array and convert it to the PIL.Image.Image class instance. The format of input image is automatically estimated in the function. Image will be transposed based on the EXIF orientation tag if exif_transpose is set to True. Note that, if ‘cv2’ format is selected, the image will be in BGR format, compatible with OpenCV.

Parameters:

• source (str, pathlib.Path, bytes, PIL.Image.Image, np.ndarray) – Image source, can be a file path, url, bytes, base64, PIL image, or numpy array.

• exif_transpose (bool) – Whether to transpose the image based on the EXIF orientation tag.

• req_timeout (int) – The timeout for the request to get image from url. Default is 60 seconds.

Returns:

Image data.

Return type:

PIL.Image.Image

Examples

>>> im = imread('image.jpg')

cvtk.imconvert(im: str | Path | bytes | Image | ndarray, format: str = 'PIL') → str | Path | bytes | Image | ndarray

Convert image format

Convert image format from any format to the specific format.

Parameters:

• im (ImageSourceTypes) – Image source, can be a file path, url, bytes, base64, PIL image, or numpy array.

• format (str) – The format of the returned image. Default is ‘PIL’. Options are ‘cv2’ (or ‘cv’, ‘array’), ‘bytes’, ‘base64’, and ‘PIL’.

Returns:

Image data in the specified format.

Return type:

ImageSourceTypes

Examples

>>> im = imread('image.jpg')
>>> imconvert(im, 'cv2')

cvtk.imwrite(im: str | Path | bytes | Image | ndarray, filename: str, quality: int = 95) → None

Save image to file

Parameters:

im – ImageSourceTypes: Image source, can be a file path, url, bytes, base64, PIL image, or numpy array.

Examples

>>> imsave(imread('image.jpg'), 'image.jpg')
>>> imsave(imread('image.jpg'), 'image.jpg', 100)

cvtk.imshow(im: str | Path | bytes | Image | ndarray | list[str | Path | bytes | Image | ndarray], ncol: int | None = None, nrow: int | None = None) → object

Display image using matplotlib.pyplot

Parameters:

• im – ImageSourceTypes: Image or list of images to display.

• ncol – int: Number of columns to display the images. Default is None (automatically set).

• nrow – int: Number of rows to display the images. Default is None (automatically set).

cvtk.imlist(source: str | list[str], ext: str | list[str] = ['.jpg', '.jpeg', '.png', '.tiff'], ignore_case: bool = True) → list[str]

List all image files from the given sources

The function recevies image sources as a file path, directory path, or a list of file and directory paths. If the source is a directory, the function will recursively search for image files with the given extensions.

Parameters:

• source – str | list[str]: The directory path.

• ext – list[str]: The list of file extensions to search for. Default is [‘.jpg’, ‘jpeg’, ‘.png’, ‘.tiff’].

• ignore_case – bool: Whether to ignore the case of the file extension. Default is True.

Returns:

List of image files in the directory.

Return type:

list

cvtk.imresize(im: str | Path | bytes | Image | ndarray, shape: list[int, int] | tuple[int, int] | None = None, scale: float | None = None, shortest: int | None = None, longest: int | None = None, resample: object = 2) → Image

Resize the image

Resize the image to the given shape, scale, shortest, or longest side.

Parameters:

• im – ImageSourceTypes: Image source, can be a file path, url, bytes, base64, PIL image, or numpy array.

• shape – tuple: The shape of the resized image (height, width).

• scale – float: The scale factor to resize the image.

• shortest – int: The shortest side of the image.

• longest – int: The longest side of the image.

• resample – int: The resampling filter. Default is PIL.Image.BILINEAR.

Returns:

The resized image.

Return type:

PIL.Image.Image

Examples

>>> imresize('image.jpg', shape=(256, 256))
>>> imresize('image.jpg', scale=0.5)
>>> imresize('image.jpg', shortest=256)
>>> imresize('image.jpg', longest=256)

class cvtk.Annotation(labels: list[str], bboxes: list[list] | list[tuple] | None = None, masks: list[list[int]] | ndarray | None = None, scores: list[float] | None = None)

A class to store image annotations including bounding boxes and masks

The class store image annotations of the coordinates of bounding boxes, the binary masks, and the labels and scores corresponding to the bounding boxes or masks. The areas of bounding boxes or masks are automatically calculated from bouding boxes or masks and stored in this class.

Parameters:

• labels – The labels for the bounding boxes or masks.

• bboxes – The list of bounding boxes in the format of (x1, y1, x2, y2).

• masks – NumPy array or 2-d list of maks.

• scores – The list of scores.

labels

The labels for the bounding boxes or masks.

bboxes

The list of bounding boxes in the format of (x1, y1, x2, y2).

masks

NumPy array or 2-d list of maks.

scores

The list of scores.

areas

The list of areas of bounding boxes or masks.

Examples

>>> labels = ['leaf', 'flower', 'root']
>>> bboxes = [[0, 0, 10, 10],
...           [10, 10, 20, 20],
...           [20, 20, 30, 30]]
>>> masks = [np.random.randint(2, (240, 321)).tolist(),
...          np.random.randint(2, (240, 321)).tolist(),
...          np.random.randint(2, (240, 321)).tolist()]
>>> scores = [0.9, 0.8, 0.7]
>>>
>>> ann = Annotation(labels, bboxes, masks, scores)
>>>
>>> ann[0]
{'label': 'leaf', 'bbox': (0, 0, 10, 10), 'mask': array([[0, 1, 0, ..., 0, 1, 0],
...                                                        [1, 0, 0, ..., 1, 0, 0],
...                                                        ...,
...                                                        [0, 1, 0, ..., 0, 1, 0],
...                                                        [1, 0, 0, ..., 1, 0, 0]]),
... 'score': 0.9, 'area': 100}
>>>
>>> ann.labels
['leaf', 'flower', 'root']
>>>
>>> ann.dump()
'[{"label": "leaf", "bbox": [0, 0, 10, 10], "mask": [[0, 1, 0, ..., 0, 1, 0], [1, 0, 0, ..., 1, 0, 0], ..., [0, 1, 0, ..., 0, 1, 0], [1, 0, 0, ..., 1, 0, 0]], "score": 0.9, "area": 100}, {"label": "flower", "bbox": [10, 10, 20, 20], "mask": [[0, 1, 0, ..., 0, 1, 0], [1, 0, 0, ..., 1, 0, 0], ..., [0, 1, 0, ..., 0, 1, 0], [1, 0, 0, ..., 1, 0, 0]], "score": 0.8, "area": 100}, {"label": "root", "bbox": [20, 20, 30, 30], "mask": [[0, 1, 0, ..., 0, 1, 0], [1, 0, 0, ..., 1, 0, 0], ..., [0, 1, 0, ..., 0, 1, 0], [1, 0, 0, ..., 1, 0, 0]], "score": 0.7, "area": 100}]'

dump(indent: int | None = None, ensure_ascii: bool = True) → str

Dump the annotation data to string in JSON format.

Parameters:

• indent (int) – The indentation of the JSON string. Default is None.

• ensure_ascii (bool) – Ensure the string is ASCII. Default is True.

Returns:

JSON string of the annotation data.

Return type:

str

Examples

>>> ann = ImageAnnotation(['leaf', 'flower', 'root'], [[0, 0, 10, 10], [10, 10, 20, 20], [20, 20, 30, 30]])
>>> ann.dump()
'[{"label": "leaf", "bbox": [0, 0, 10, 10], "mask": null, "score": null, "area": 100}, {"label": "flower", "bbox": [10, 10, 20, 20], "mask": null, "score": null, "area": 100}, {"label": "root", "bbox": [20, 20, 30, 30], "mask": null, "score": null, "area": 100}]'

class cvtk.Image(source, annotations: Annotation | None = None)

A class to store image data and annotations

The class store image data and annotations including bounding boxes and masks.

Parameters:

• source – The path to the image file.

• annotations – The annotations for the image.

file_path

The path to the image file.

annotations

The annotations for the image.

size

The size of the image (width, height).

width

The width of the image.

height

The height of the image.

Examples

>>> im = Image('image.jpg')
>>> im.size
(321, 240)
>>> im.width
321
>>> im.height
240
>>>
>>> labels = ['leaf', 'flower', 'root']
>>> bboxes = [[0, 0, 10, 10],
...           [10, 10, 20, 20],
...           [20, 20, 30, 30]]
>>> ann = ImageAnnotation(labels, bboxes)
>>> im = Image('image.jpg', ann)
>>> im.annotations
<cvtk.base.ImageAnnotation object at 0x7f9d5f4b0f10>
>>>

draw(format: str = 'bbox', output: str | None = None, cutoff: float = 0.5, label: bool = True, score: bool = True, font: ImageFont | None = None, col: dict | None = None) → Image

Plot an image with annotations

Plot an image with annotations including bounding boxes and masks.

Parameters:

• format – The format of the annotations to plot. Default is ‘bbox’. Options are ‘bbox’, ‘segm’, ‘mask’.

• output – The path to save the plotted image. Default is None.

• cutoff – The cutoff score to plot the annotations. Default is 0.5.

• label – Whether to plot the labels. Default is True.

• score – Whether to plot the scores. Default is True.

• cols – The color dictionary for the annotations. Default is None.

class cvtk.ImageDeck(images: Image | list[Image])

A class to store a deck of images

The class store a deck of images and annotations including bounding boxes and masks.

Parameters:

images – The list of images.

append(image: Image)

Append an image to the deck

dump(output: str, format: str = 'cvtk', datalabel: str | None = None, indent: int | None = None, ensure_ascii: bool = True)

Dump the images in the deck to a file

extend(images: Image | list[Image])

Extend images to the deck

format(format: str = 'cvtk', datalabel: str | None = None) → dict

Format the images in the deck

class cvtk.JsonComplexEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Convert objects to JSON serializable format

Examples

>>> obj = {'a': np.array([0, 1, 2]), 'b': [0, 1, 2], 'c': 'hello wolrd'}
>>> json.dumps(obj, cls=JsonComplexEncoder)

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)