Improutils

Subpackages

Submodules

improutils.other module

improutils.other.artificial_circle_image(size)[source]

Create an image of given size filled with circles.

Parameters:: size (int) – size of the image
Return type:: Artificial image with circles

improutils.other.create_file_path(folder, file_name)[source]

Create path for filename inside a folder.

Parameters:

folder (string) – Base folder directory in string notation. If the directory does not exist, it is created.
file_name (string) – File name that should be inside the base folder.

Return type:

Path to the file.

improutils.other.create_slider(min, max, description)[source]

Create an integer range slider widget.

Parameters:

min (int) – The minimum value for the range slider.
max (int) – The maximum value for the range slider.
description (str) – The label to display alongside the slider.

Returns:

An IntRangeSlider widget with the specified bounds and label.

Return type:

ipywidgets.IntRangeSlider

improutils.other.midpoint(ptA, ptB)[source]

Return the midpoint between two points.

Parameters:

ptA (array | tuple | ndarray) – The first 2D point considered
ptB (array | tuple | ndarray) – The second 2D point considered

Return type:

The 2D midpoint

improutils.other.multicolor_segmentation(func, colors)[source]

Interactive HSV thresholding for multiple colors with saving and returning thresholds that are picked by the user.

Parameters:

func (function) – function with arguments hue = h_range (int, range: 0-360), saturation = s_range (int, range: 0-255), value = v_range (int, range: 0-255)
colors (list) – list of colors that the user can choose from, e.g. [‘red’, ‘green’, ‘blue’], these colors will be used as keys in the output dictionary

Returns:

color_thresholds – Returns a dictionary with the chosen thresholds for each color, e.g. {‘red’: (0, 0, 0), ‘green’: (0, 0, 0), ‘blue’: (0, 0, 0)}, can be also empty if no thresholds were saved

Return type:

dict

improutils.other.order_points(pts)[source]

Sort the points based on their coordinates, in top-left, top-right, bottom-right, and bottom-left order.

Parameters:: pts (ndarray) – 4 2D Points to be sorted.
Return type:: Sorted points, the coordinates in top-left, top-right, bottom-right, and bottom-left order

improutils.other.pcd_to_depth(pcd, height, width)[source]

Reduce point-cloud to coordinates, point cloud [x, y, z, rgb] -> depth[x, y, z].

Parameters:

pcd (array) – point cloud
height (int) – height of captured img
width (int) – width of a captured img

Return type:

Array of coordinates.

improutils.other.plot_distortion(k1: float, k2: float, k3: float, k4: float, k5: float, k6: float, p1: float, p2: float) → None[source]

Vizualization of distortion parameters and their influence. Plots radial, tangential and compounded (radial + tangential) distortion grid using the Brown-Conrady (OpenCV) model.

Parameters:

k1 (float) – Radial distortion coefficient.
k2 (float) – Radial distortion coefficient.
k3 (float) – Radial distortion coefficient.
k4 (float) – Radial distortion coefficient.
k5 (float) – Radial distortion coefficient.
k6 (float) – Radial distortion coefficient.
p1 (float) – Tangential distortion coefficient.
p2 (float) – Tangential distortion coefficient.

Return type:

None

Module contents

class improutils.HeightEstimator(ref_measurements, vl, vz)[source]

Bases: object

Estimate real world object height based on two points (top and bottom) measured on image plane.

calc_height(top_point, bottom_point)[source]

Calculate real-world height from image-plane measurements.

Given the top and bottom points of an object in the image plane, this function estimates the real-world height of the object.

Parameters:

top_point (ndarray) – Top point of the object in the reference direction, in inhomogeneous format.
bottom_point (ndarray) – Ground plane point of the object in inhomogeneous format.

Returns:

Real-world height of the object.

Return type:

float

class improutils.ShapeDescriptors[source]

Bases: object

An internal class for computing shape descriptors. Not to be used by the programmer.

aspect_ratio(max_diameter)[source]: Compute the aspect ratio of a shape as the ratio of minimum to maximum diameter.

compactness(max_diameter)[source]: Compute the compactness of a shape based on area and maximum diameter.

convexity(convex_perimeter)[source]: Compute the convexity of a shape as the ratio of convex perimeter to actual perimeter.

extent(bounding_rectangle_area)[source]: Compute the extent of a shape as the ratio of area to bounding rectangle area.

form_factor(perimeter)[source]: Compute the form factor of a shape based on area and perimeter.

roundness(max_diameter)[source]: Compute the roundness of a shape based on area and maximum diameter.

solidity(convex_area)[source]: Compute the solidity of a shape as the ratio of area to its convex hull area.

improutils.apply_fft(image)[source]

Apply FFT on the image.

Parameters:

image (2D array) – Image to perform FFT on.

Returns:

mag_spec (2D array) – Normalized magnitude spectrum.
fftcls_shift (2D array) – Centered product of FFT.

improutils.apply_mask(img, mask_bin)[source]

Apply binary mask on the image.

Parameters:

img (ndarray) – Input image.
mask_bin (ndarray) – Binary mask to be applied.

Return type:

Masked image.

improutils.artificial_circle_image(size)[source]

Create an image of given size filled with circles.

Parameters:: size (int) – size of the image
Return type:: Artificial image with circles

improutils.aspect_ratio(contour)[source]

Determine the contour’s aspect ratio.

Aka “poměr stran”.

Parameters:: contour (ndarray) – The contour for the calculation.
Return type:: The number, describing the contour’s property

improutils.black_hat(img, kernel_size=3, iterations=1, kernel=None)[source]

Apply the black hat morphological operation on the input image.

Parameters:

img (numpy.ndarray) – The input image.
kernel_size (int, optional) – The size of the kernel used for the operation. Default is 3.
iterations (int, optional) – The number of times the operation is applied. Default is 1.
kernel (numpy.ndarray, optional) – The kernel used for the operation. If not provided, a square kernel of size kernel_size will be used.

Return type:

The image after applying the black hat operation.

improutils.calibration_stats(reprojection_error: float, camera_matrix: ndarray, dist_coeffs: ndarray, std_deviations_intrinsics: ndarray | None = None, per_view_errors: ndarray | None = None, view_names: List[str] | None = None, pixel_size: float | Tuple[float, float] | None = None) → None[source]

Print calibration statistics.

RMS re-projection error, estimated intrinsics and distortion parameters, with standard deviations, focal length in millimeters, and per-view reprojection errors.

Parameters:

reprojection_error (float) – Re-projection error from cv2.calibrateCamera.
camera_matrix (np.ndarray) – Camera matrix from cv2.calibrate.
dist_coeffs (np.ndarray) – Distortion coefficients from cv2.calibrateCamera.
std_deviations_intrinsics (np.ndarray, optional) – Standard deviations of intrinsics from cv2.calibrateCameraExtended. Defaults to None.
per_view_errors (np.ndarray, optional) – Per-view errors from cv2.calibrateCameraExtended. Defaults to None.
view_names (List[str], optional) – Image names for which the chessboard was detected. Defaults to None.
pixel_size (Union[float, Tuple[float, float]], optional) – Size of physical pixels of a camera in micrometers (e.g., 4.8, 5.86, or [5.86, 4.8] for non-square pixels). Defaults to None.

improutils.camera_calibration(calib_path: str, chess_shape: Tuple[int, int], cv2_flags: int = 0, extensions: List[str] = ['jpg', 'jpeg', 'png', 'tiff', 'bmp']) → Tuple[float, ndarray, ndarray, List[ndarray], List[ndarray], ndarray, ndarray, ndarray, Dict[str, ndarray]][source]

Calibrate camera from images with chessboard pattern, using OpenCV’s cv2.calibrateCameraExtended function.

Parameters:

calib_path (str) – Path to the folder containing chessboard pattern images.
chess_shape (Tuple[int, int]) – Interior corner count in the format of rows, columns.
cv2_flags (int, optional) – Additional OpenCV flags for cv2.calibrateCameraExtended. Defaults to 0.
extensions (List[str], optional) – Allowed image extensions. Defaults to [“jpg”, “jpeg”, “png”, “tiff”].

Returns:

Returns the output from cv2.calibrateCameraExtended and a dictionary with image names as keys and images with drawn chessboard corners as values.

Return type:

Tuple[float, np.ndarray, np.ndarray, Tuple[np.ndarray], Tuple[np.ndarray], np.ndarray, np.ndarray, np.ndarray, Dict[str,np.ndarray]]

Raises:

ValueError – If calibration images have different sizes.
ValueError – If no calibration images were found or could not be read from the provided path.
ValueError – If no chessboard patterns were detected in the images.

improutils.close(img, kernel_size=3, iterations=1, kernel=None)[source]

Apply morphological closing operation on the input image.

Parameters:

img (numpy.ndarray) – The input image.
kernel_size (int, optional) – The size of the kernel used for the closing operation. Default is 3.
iterations (int, optional) – The number of times the closing operation is applied. Default is 1.
kernel (numpy.ndarray, optional) – The custom kernel used for the closing operation. If not provided, a square kernel of size kernel_size will be used.

Return type:

The image after applying the closing operation.

improutils.color_picker(img)[source]

Interactive tool to pick colors from an image.

Displays the input image in a window and allows the user to click on points to sample their colors. Each selected color is printed in the console and annotated on the image. Press ‘q’, ‘Q’, or ‘Esc’ to exit.

Parameters:: img (ndarray) – Input image in which colors will be sampled. Can be grayscale or color (BGR) image.
Returns:: This function does not return a value. Selected colors are printed to the console and annotated on the displayed image.
Return type:: None

improutils.compactness(contour)[source]

Determine the contour’s compactness.

Aka “kompaktnost, hutnost”.

Parameters:: contour (ndarray) – The contour for the calculation.
Return type:: The number, describing the contour’s property

improutils.compute_vanishing_points(image, clip_factor=6, reestimate=False)[source]

Rectified image with vanishing point computed using ransac.

Parameters:

image (ndarray) – Image which has to be rectified.
clip_factor (float, optional) – Proportion of image in multiples of image size to be retained if gone out of bounds after homography.
reestimate (bool) – If ransac results are to be reestimated using least squares with inlers. Turn this off if getting bad results.

Returns:

warped_img – Rectified image.

Return type:

ndarray

improutils.connect_camera(serial_number)[source]

Connect the camera specified with its serial number.

Parameters:: serial_number (string) – The camera’s serial number.
Returns:: camera
Return type:: object

improutils.contour_to_image(contour, img_bin, size=None)[source]

Create a new image from the contour.

Parameters:

contour (ndarray) – Contour that represents the area from image to be cropped.
img_bin (ndarray) – Input binary image.
size (tuple) – Optional size of the created image. If it’s not used, the image’s size is the same as the size of bounding rectangle of the input contour.

Return type:

Output cropped image.

improutils.convert_pt_from_homogenous(pt)[source]

Convert input point in homogeneous coordinates to inhomogeneous.

Parameters:: pt (ndarray) – Input point in homogeneous coordinates.
Returns:: _ – Input point in inhomogeneous coordinates.
Return type:: tuple

improutils.convert_pt_to_homogenous(pt)[source]

Convert the input point from inhomogeneous coordinates to homogeneous ones.

Parameters:: pt (ndarray) – Input point in inhomogeneous coordinates.
Returns:: _ – Input point in homogeneous coordinates.
Return type:: ndarray

improutils.convert_pts_from_homogenous(pts)[source]

Convert input points in homogeneous coordinates to inhomogeneous.

Parameters:: pts (array_like, shape (n_points, n_dims + 1) in homogeneous coordinates.) – Input points in homogeneous coordinates.
Returns:: inhomogeneous_pts – Points in inhomogeneous coordinates.
Return type:: ndarray, shape (n_points, n_dims)

improutils.convert_pts_to_homogenous(pts)[source]

Convert input points from inhomogeneous to homogeneous coordinates.

Parameters:: pts (array_like, shape (n_points, n_dims)) – Inhomogeneous input points.
Returns:: homogeneous_pts – Points in homogeneous coordinates, with a 1 appended as the last component.
Return type:: ndarray, shape (n_points, n_dims + 1)

improutils.convexity(contour)[source]

Determine the contour’s convexity.

Aka “konvexita, vypouklost”.

Parameters:: contour (ndarray) – The contour for the calculation.
Return type:: The number, describing the contour’s property

improutils.copy_to(src, dst, mask)[source]

Copy source image pixel to destination image using mask matrix.

This function is Python alternative to C++/Java OpenCV’s Mat.copyTo(). More: https://docs.opencv.org/trunk/d3/d63/classcv_1_1Mat.html#a626fe5f96d02525e2604d2ad46dd574f

Parameters:

src (numpy.ndarray) – Source image
dst (numpy.ndarray) – Destination image
mask (numpy.ndarray) – Binary image that specifies which pixels are copied. Value 1 means true

Return type:

Destination image with copied pixels from source image

improutils.correct_frame(frame, camera_matrix, dist_coeffs)[source]: Return an undistorted frame.

improutils.create_file_path(folder, file_name)[source]

Create path for filename inside a folder.

Parameters:

folder (string) – Base folder directory in string notation. If the directory does not exist, it is created.
file_name (string) – File name that should be inside the base folder.

Return type:

Path to the file.

improutils.create_filter_mask(size, rows, columns)[source]

Create a filter mask specified by rows and columns.

Specified rows and columns are set to 255, others 0.

Parameters:

size (tuple of int) – Tuple of two integers (height, width) defining the dimensions of the output mask.
rows (array-like of int) – Indices of rows to set to 255.
columns (array-like of int) – Indices of columns to set to 255.

Returns:

filter_mask – 2D array mask containing 255 and 0 values.

Return type:

2D array

Raises:

TypeError – If size is not a tuple with 2 int values.

improutils.create_slider(min, max, description)[source]

Create an integer range slider widget.

Parameters:

min (int) – The minimum value for the range slider.
max (int) – The maximum value for the range slider.
description (str) – The label to display alongside the slider.

Returns:

An IntRangeSlider widget with the specified bounds and label.

Return type:

ipywidgets.IntRangeSlider

improutils.crop(img, tl_x, tl_y, br_x, br_y)[source]

Crop an image by added coordinates.

Parameters:

img (ndarray) – Input image.
tl_x (int) – TOP-LEFT corner’s x-coordinate
tl_y (int) – TOP-LEFT corner’s y-coordinate
br_x (int) – BOTTOM-RIGHT corner’s x-coordinate
br_y (int) – BOTTOM-RIGHT corner’s y-coordinate

Return type:

Output image.

improutils.crop_by_bounding_rect(img_bin)[source]

Crop binary image by ONE bounding rectangle corresponding to ALL objects in the binary image.

Parameters:: img_bin (ndarray) – Input binary image.
Return type:: Output cropped image.

improutils.crop_contour(contour, img)[source]

Crop contour in respect to its bounding rectangle.

It’s the fastest method, but could include other parts of image than just contour if the contour is irregulary shaped.

Parameters:

contour (ndarray) – Contour that represents the area from image to be cropped. The bounding rectangle of contour is used.
img (ndarray) – Input image.

Return type:

Output cropped image.

improutils.dilate(img, kernel_size=3, iterations=1, kernel=None)[source]

Dilate an image using the specified kernel.

Parameters:

img (numpy.ndarray) – The input image to be dilated.
kernel_size (int, optional) – The size of the kernel used for dilation. Default is 3.
iterations (int, optional) – The number of times the dilation is applied. Default is 1.
kernel (numpy.ndarray, optional) – The custom kernel to be used for dilation. If not provided, a square kernel of size kernel_size will be used.

Return type:

The dilated image.

improutils.draw_lines(img, lines)[source]

Draw lines coming from HoughLines procedure into image.

Parameters:

img (ndarray) – Input image.
lines (ndarray) – array of lines - output of cv2.HoughLines.

Return type:

Output image.

improutils.draw_real_sizes(img, rect, width_text, height_text, lbl_size_scale=2, lbl_color=(0, 0, 255), lbl_thickness=8)[source]

Draw real sizes of rotated rectangle into the image.

Parameters:

img (ndarray) – Input image.
rect (tuple) – Rotated rectangle.
width_text (string) – Width of the rectangle in the form of string.
height_text (string) – Height of the rectangle in the form of string.
lbl_size_scale (double) – Scale of text.
lbl_color (tuple) – Color of text.
lbl_thickness (int) – Thickness of text.

Return type:

Output image.

improutils.draw_text(img, text, point, text_scale, text_color, text_thickness)[source]

Draw rotated text into the image.

Parameters:

img (ndarray) – Input image.
text (string) – Text to be drawn.
point (tuple) – Point where text is drawn.
text_scale (double) – Scale of text.
text_color (tuple) – Color of text.
text_thickness (int) – Thickness of text.

Return type:

Output image.

improutils.erode(img, kernel_size=3, iterations=1, kernel=None)[source]

Erode an image using the specified kernel.

Parameters:

img (numpy.ndarray) – The input image to be eroded.
kernel_size (int, optional) – The size of the kernel used for erosion. Default is 3.
iterations (int, optional) – The number of times erosion is applied. Default is 1.
kernel (numpy.ndarray, optional) – The custom kernel to be used for erosion. If not provided, a square kernel of size kernel_size will be used.

Return type:

The eroded image.

improutils.extent(contour)[source]

Determine the contour’s extent.

Aka “dosah, rozměrnost”.

Parameters:: contour (ndarray) – The contour for the calculation.
Return type:: The number, describing the contour’s property

improutils.fill_holes(img_bin, close=False, size=5)[source]

Fill the holes in found contours. It could merge the contour using close input with appropriate size.

Parameters:

img_bin (ndarray) – Input binary image.
close (boolean) – If it should merge contours with missing points using close operation.
size (int) – Size of the close operation element.
fill (bool, optional) – If True, filled contours are drawn; if False, contours are drawn as outlines. Default is True.

Return type:

Output binary image.

improutils.filter_mag_spec(mag_spec, filter_mask)[source]

Filter input spectrum using filter_mask image.

Parameters:

mag_spec (2D ndarray) – Image with magnitude spectrum.
filter_mask (2D array) – Filter binary mask image containing values to keep (255) and filter out (0).

Returns:

result – Vizualization of spectrum after filtering.

Return type:

2D ndarray

improutils.filtration_box(img, filter_size)[source]

Filter image noise using box blur algorithm.

Parameters:

img (numpy.ndarray) – Input image.
filter_size (int) – Size of box blur filter.

Return type:

Output image.

improutils.filtration_gauss(img, filter_size, sigma_x)[source]

Filter image noise using Gaussian blur algorithm.

Parameters:

img (numpy.ndarray) – Input image.
filter_size (int) – Size of Gaussian filter.
sigma_x (float) – Gaussian kernel standard deviation in the X direction.

Return type:

Output image.

improutils.filtration_median(img, filter_size)[source]

Filter image noise using median blur algorithm.

Parameters:

img (numpy.ndarray) – Input image.
filter_size (int) – Odd number - size of median filter.

Return type:

Output image.

improutils.find_contours(img_bin, min_area=0, max_area=inf, fill=True, external=True)[source]

Find contours in a binary image and filter them by area.

The function counts the filtered contours and draws them on a new binary image. Contours can be optionally filled or just outlined, and either external or all contours can be considered.

Parameters:

img_bin (ndarray) – Input binary image.
min_area (int, optional) – Minimum contour area to keep (smaller contours are discarded). Default is 0.
max_area (int or float, optional) – Maximum contour area to keep (larger contours are discarded). Default is np.inf.
fill (bool, optional) – If True, filled contours are drawn; if False, contours are drawn as outlines. Default is True.
external (bool, optional) – If True, only external contours are considered; if False, all contours are considered. Default is True.

Returns:

contour_drawn (ndarray) – Output binary image with drawn filtered contours.
count (int) – Number of filtered contours.
contours (list of ndarray) – List of filtered contour arrays.

improutils.find_holes(img_bin, min_area=0, max_area=inf, fill=True)[source]

Find inner contours (holes) in a binary image and filter them by area.

The function identifies contours that are inside other contours (holes), filters them based on the specified minimum and maximum area, and draws them on a new binary image. Contours can be optionally filled or outlined.

Parameters:

img_bin (ndarray) – Input binary image.
min_area (int, optional) – Minimum contour area to keep (smaller contours are discarded). Default is 0.
max_area (int or float, optional) – Maximum contour area to keep (larger contours are discarded). Default is np.inf.
fill (bool, optional) – If True, filled contours are drawn; if False, contours are drawn as outlines. Default is True.

Returns:

contours_drawn (ndarray) – Output binary image with drawn filtered hole contours.
count (int) – Number of filtered hole contours.
contours (list of ndarray) – List of filtered hole contour arrays.

improutils.form_factor(contour)[source]

Determine the contour’s form factor.

Aka “špičatost”.

Parameters:: contour (ndarray) – The contour for the calculation.
Return type:: The number, describing the contour’s property

improutils.get_center(contour)[source]

Get the center of a contour in pixels in tuple format.

Parameters:: contour (ndarray) – input contour.
Return type:: A tuple with x and y coordinates of the contour’s center.

improutils.inverse_fft(fft_shift, filter_mask=None)[source]

Apply inverse FFT.

Parameters:

fft_shift (2D array) – Shifted computed FFT
filter_mask (2D array) – 2D array mask containing 255 and 0 values.

Returns:

img_back – Image made by inverse FFT.

Return type:

2D array

improutils.load_camera_calib(input_file)[source]

Load camera calibration from specified input file.

Parameters:: input_file (string) – Input file with calibration data in YAML format.
Returns:: Returns a tuple where first element is camera matrix array and second element is dist coefficients array. These arrays might be empty if the file isn’t found or in correct format.
Return type:: tuple(ndarray, ndarray)

improutils.load_image(file_path)[source]

Load an image from a file.

The function calls cv2.imread() to load image from the specified file and then return it. If the image cannot be read, the AssertError exception is thrown.

For more info about formats, see cv2.imread() documentation

Parameters:: file_path (string) – A path to an image file
Return type:: Loaded image in numpy.ndarray

improutils.midpoint(ptA, ptB)[source]

Return the midpoint between two points.

Parameters:

ptA (array | tuple | ndarray) – The first 2D point considered
ptB (array | tuple | ndarray) – The second 2D point considered

Return type:

The 2D midpoint

improutils.morphological_gradient(img, kernel_size=3, iterations=1, kernel=None)[source]

Apply morphological gradient operation on the input image.

Parameters:

img (numpy.ndarray) – The input image.
kernel_size (int, optional) – The size of the kernel used for morphological operations. Defaults to 3.
iterations (int, optional) – The number of times the morphological operation is applied. Defaults to 1.
kernel (numpy.ndarray, optional) – The custom kernel used for morphological operations. If not provided, a square kernel of size kernel_size will be used.

Return type:

The image after applying the morphological gradient operation.

improutils.multicolor_segmentation(func, colors)[source]

Interactive HSV thresholding for multiple colors with saving and returning thresholds that are picked by the user.

Parameters:

func (function) – function with arguments hue = h_range (int, range: 0-360), saturation = s_range (int, range: 0-255), value = v_range (int, range: 0-255)
colors (list) – list of colors that the user can choose from, e.g. [‘red’, ‘green’, ‘blue’], these colors will be used as keys in the output dictionary

Returns:

color_thresholds – Returns a dictionary with the chosen thresholds for each color, e.g. {‘red’: (0, 0, 0), ‘green’: (0, 0, 0), ‘blue’: (0, 0, 0)}, can be also empty if no thresholds were saved

Return type:

dict

improutils.negative(img)[source]

Convert image to its negative.

Parameters:: img (ndarray) – Input image.
Return type:: Output image.

improutils.normalize(img)[source]

Normalize image using min-max normalization from its values to values 0 - 255.

Parameters:: img (ndarray) – Input image.

improutils.normalize2BGR_image(img)[source]

Normalize image using min-max and converts it to BGR.

Parameters:: img (ndarray) – Input image
Returns:: _ – Normalized image in BGR
Return type:: ndarray

improutils.ocr(img_bin, config='', lang=None)[source]

Detect text in the image.

Parameters:

img_bin (ndarray) – Input binary image. White objects on black background.
config (str) – Model config, refer to: https://tesseract-ocr.github.io/tessdoc/ImproveQuality.html, https://muthu.co/all-tesseract-ocr-options/ for correct use. Defaults to ‘’.
lang (str | None) – Language code, e.g. eng for English and ces for Czech. For list of language codes, refer to: https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions.html. Selected language must be installed using sudo apt-get install tesseract-ocr-langcode where langcode is the language code. English is installed by default. Defaults to None.

Return type:

The recognized text in the image.

improutils.open(img, kernel_size=3, iterations=1, kernel=None)[source]

Applz the morphological opening operation on the input image.

Parameters:

img (numpy.ndarray) – The input image.
kernel_size (int, optional) – The size of the kernel used for the opening operation. Default is 3.
iterations (int, optional) – The number of times the opening operation is applied. Default is 1.
kernel (numpy.ndarray, optional) – The custom kernel used for the opening operation. If not provided, a square kernel of size kernel_size will be used.

Return type:

The image after applying the morphological opening operation.

improutils.order_points(pts)[source]

Sort the points based on their coordinates, in top-left, top-right, bottom-right, and bottom-left order.

Parameters:: pts (ndarray) – 4 2D Points to be sorted.
Return type:: Sorted points, the coordinates in top-left, top-right, bottom-right, and bottom-left order

improutils.pcd_to_depth(pcd, height, width)[source]

Reduce point-cloud to coordinates, point cloud [x, y, z, rgb] -> depth[x, y, z].

Parameters:

pcd (array) – point cloud
height (int) – height of captured img
width (int) – width of a captured img

Return type:

Array of coordinates.

improutils.plot_distortion(k1: float, k2: float, k3: float, k4: float, k5: float, k6: float, p1: float, p2: float) → None[source]

Vizualization of distortion parameters and their influence. Plots radial, tangential and compounded (radial + tangential) distortion grid using the Brown-Conrady (OpenCV) model.

Parameters:

k1 (float) – Radial distortion coefficient.
k2 (float) – Radial distortion coefficient.
k3 (float) – Radial distortion coefficient.
k4 (float) – Radial distortion coefficient.
k5 (float) – Radial distortion coefficient.
k6 (float) – Radial distortion coefficient.
p1 (float) – Tangential distortion coefficient.
p2 (float) – Tangential distortion coefficient.

Return type:

None

improutils.plot_images(*imgs, titles=[], channels='bgr', normalize=False, ticks_off=True, title_size=32)[source]

Plot multiple images in one figure.

Parameters:

*imgs (list) – Arbitrary number of images to be shown.
titles (list) – Titles for each image.
channels (string) – Colour channels. Possible values are “bgr”, “rgb” or “mono”.
normalize (bool) – If True, image will be normalized.
ticks_off (bool) – If True, axis decorations will be hidden.
title_size (int) – Size of the title.

Return type:

None

improutils.polar_warp(img, size=None, full_radius=True, inverse=False)[source]

Apply a polar warp to an image.

This function performs a polar coordinate transformation on the input image. It can optionally produce a full-radius warp or use an inverse mapping.

Parameters:

img (ndarray) – Input image to be warped.
size (tuple of int, optional) – Size of the destination image as (height, width). Default is None, which transforms size to (pi*Rm,Rm), see cv2.warpPolar documentation.
full_radius (bool, optional) – If True, the warp uses the full radius of the image (diagonal from center to corner). If False, only the vertical radius is used. Default is True.
inverse (bool, optional) – If True, applies the inverse warp mapping. Default is False.

Returns:

Warped image in polar coordinates.

Return type:

ndarray

improutils.qr_decode(img, detection_result, is_bgr=True, reader=<qreader.QReader object>)[source]

Decode a single QR code on the given image, described by a detection_result.

For further info refer to: https://github.com/Eric-Canas/qreader

Internally, this method will run the pyzbar decoder, using the information of the detection_result, to apply different image preprocessing techniques that heavily increase the decoding rate.

Parameters:

img (np.ndarray) – The image to be read. It is expected to be RGB or BGR (uint8). Format (HxWx3). Can also be grayscale (HxW), in which case it will be converted to BGR.
detection_result (dict[str, np.ndarray|float|tuple[float|int, float|int]]) – One of the detection dicts returned by the detect method. Note that qr_detect() returns a tuple of these dicts. This method expects just one of them.
is_bgr (bool) – If True, the received image is expected to be BGR instead of RGB. Defaults to True.
reader (QReader) – Initialized QReader class, use qr_init_reader(model_size, min_confidence, reencode_to) with different parameters if you wish. Defaults to qr_init_reader().

Returns:

decoded_strings – The decoded content of the QR code or None if it can not be read.

Return type:

str OR None

improutils.qr_detect(img, is_bgr=True, reader=<qreader.QReader object>)[source]

Detect QR codes in the image and returns a tuple of dictionaries with all the detection information.

For further info refer to: https://github.com/Eric-Canas/qreader

Parameters:

img (np.ndarray) – The image to be read. It is expected to be RGB or BGR (uint8). Format (HxWx3).
is_bgr (bool) – If True, the received image is expected to be BGR instead of RGB. Defaults to True.
reader (QReader) – Initialized QReader class, use qr_init_reader(model_size, min_confidence, reencode_to) with different parameters if you wish. Defaults to qr_init_reader().

Returns:

detections –

A tuple of dictionaries containing the following keys:

’confidence’: float. The confidence of the detection.
’bbox_xyxy’: np.ndarray. The bounding box of the detection in the format [x1, y1, x2, y2].
’cxcy’: tuple[float, float]. The center of the bounding box in the format (x, y).
’wh’: tuple[float, float]. The width and height of the bounding box in the format (w, h).
’polygon_xy’: np.ndarray. The accurate polygon that surrounds the QR code, with shape (N, 2).
’quad_xy’: np.ndarray. The quadrilateral that surrounds the QR code, with shape (4, 2). Fitted from the polygon.
’padded_quad_xy’: np.ndarray. An expanded version of quad_xy, with shape (4, 2), that always include all the points within polygon_xy.

All these keys (except ‘confidence’) have a ‘n’ (normalized) version. For example, ‘bbox_xyxy’ is the bounding box in absolute coordinates, while ‘bbox_xyxyn’ is the bounding box in normalized coordinates (from 0. to 1.).

Return type:

tuple[dict[str, np.ndarray|float|tuple[float|int, float|int]]]:

improutils.qr_detect_and_decode(img, return_detections=False, is_bgr=True, reader=<qreader.QReader object>)[source]

Detect and decodes QR codes in the given image and return the decoded strings (or None, if any of them was detected but not decoded).

For further info refer to: https://github.com/Eric-Canas/qreader

Parameters:

img (np.ndarray) – The image to be read. It is expected to be RGB or BGR (uint8). Format (HxWx3). Can also be grayscale (HxW), in which case it will be converted to BGR.
return_detections (bool) – If True, it will return the full detection results together with the decoded QRs. If False, it will return only the decoded content of the QR codes. Defaults to False.
is_bgr (bool) – If True, the received image is expected to be BGR instead of RGB. Defaults to True.
reader (QReader) – Initialized QReader class, use qr_init_reader(model_size, min_confidence, reencode_to) with different parameters if you wish. Defaults to qr_init_reader().

Returns:

detections – If return_detections is True, it will return a tuple of tuples. Each tuple will contain the detection result (a dictionary with the keys ‘confidence’, ‘bbox_xyxy’, ‘polygon_xy’…) and the decoded QR code (or None if it can not be decoded). If return_detections is False, it will return a tuple of strings with the decoded QR codes (or None if it can not be decoded).

Return type:

improutils.qr_init_reader(model_size='s', min_confidence=0.5, reencode_to='shift_jis')[source]

Initialize a QR code reader.

If you want to use the detect or decode QR codes on multiple occasions, it is recommended to initialize the reader once and then pass it to the functions. For further info refer to: https://github.com/Eric-Canas/qreader

Parameters:

model_size (str) – The size of the model to use. It can be ‘n’ (nano), ‘s’ (small), ‘m’ (medium) or ‘l’ (large). Larger models are more accurate but slower. Defaults to ‘s’.
min_confidence (float) – The minimum confidence of the QR detection to be considered valid. Values closer to 0.0 can get more False Positives, while values closer to 1.0 can lose difficult QRs. Default (and recommended): 0.5.
reencode_to (str | None) – The encoding to reencode the utf-8 decoded QR string. If None, it won’t re-encode. If you find some characters being decoded incorrectly, try to set a Code Page (https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers) that matches your specific charset. Recommendations that have been found useful: ‘shift-jis’ for Germanic languages ‘cp65001’ for Asian languages Defaults to ‘shift_jis’.

Returns:

reader – Initialized QR code reader.

Return type:

QReader

improutils.reindex_image_files(source_dir, output_dir=None)[source]

Read all images in source_dir and rename them to continuous integers.

Based on their original order, changes their filenames to be continuous integers (starting from 0). Then, they can be easily read by cv2.VideoCapture. Image format is kept.

Parameters:

source_dir (string) – Input images directory that have to be renamed.
output_dir (Optional[string]) – Output directory for renamed files. If not specified, renaming is done inplace in source_dir.

Return type:

None

improutils.resize(image, size, method=3)[source]

Resize the image to the preffered size.

Method of resizing is well suited for making the images smaller rather than larger (cv2.INTER_AREA). For making images larger, use other cv2.INTER_### instead.

Parameters:

image (ndarray) – Contour that represents the area from image to be cropped.
size (tuple) – New size of the resized image.
method (int) – Optional argument. For more information see cv2.INTER_### parameters.

Return type:

Output resized image.

improutils.rotate(image, angle, image_center=None)[source]

Rotate the input image by specified angle.

Parameters:

image (ndarray) – Image to be rotated.
angle (float) – Rotation angle.
image_center (Optional[tuple(int, int)]) – Center of rotation.

Returns:

Returns the rotated input image by specified angle.

Return type:

ndarray

improutils.roundness(contour)[source]

Determine the contour’s roundness.

Aka “kulatost”.

Parameters:: contour (ndarray) – The contour for the calculation.
Return type:: The number, describing the contour’s property

improutils.save_camera_calib(output_file, camera_matrix, dist_coefs)[source]

Save camera calibration data to a YAML file.

This function stores the camera matrix and distortion coefficients in the specified output file. If the parent directory does not exist, it is created automatically.

Parameters:

output_file (str) – Path to the output YAML file where calibration data will be saved.
camera_matrix (ndarray) – Camera intrinsic matrix.
dist_coefs (ndarray) – Distortion coefficients of the camera.

Return type:

None

improutils.save_image(image, file_path)[source]

Save an image to a file.

The function calls cv2.imwrite() to save an image to the specified file. The image format is chosen based on the filename extension.

Parameters:

image (numpy.ndarray) – Pixel values
file_path (string) – A path to an image file

Return type:

True if image is saved successfully

improutils.segmentation_adaptive_threshold(img, size, constant=0)[source]

Segment image into black & white using calculated adaptive threshold using Gaussian function in pixel neighbourhood.

Parameters:

img (ndarray) – Input image.
size (int) – Size of used gaussian. Lowest value is 3. Algorithm uses only odd numbers.
constant (int) – Value that is added to calculated threshlod. It could be negative as well as zero as well as positive number.

Returns:

img – Output binary image.

Return type:

ndarray

improutils.segmentation_auto_threshold(img)[source]

Segment image into black & white using automatic threshold.

Parameters:: img (ndarray) – Input image.
Return type:: Output image.

improutils.segmentation_one_threshold(img, threshold)[source]

Segment image into black & white using one threshold.

Parameters:

img (ndarray) – Input image.
threshold (int) – Pixels with value lower than threshold are considered black, the others white.

Return type:

Output image.

improutils.segmentation_two_thresholds(img, lower, higher)[source]

Segment image into black & white using two thresholds.

Parameters:

img (ndarray) – Input image.
lower (int) – Pixels with value lower than threshold are considered black, the others white.
higher (int) – Pixels with value higher than threshold are considered black, the others white.

Return type:

Output image.

improutils.show_camera_window(*imgs, scale=1)[source]

Open input images in separate windows.

Parameters:

*imgs (list) – Arbitrary number of images to be shown.
scale (double) – Scale of shown image window.

Return type:

None

improutils.show_images(*imgs, scale=1, window_name='Image preview')[source]

Display multiple images in separate resizable windows.

Each image in the input list is shown in its own window. The user can click on the images to print the (x, y) coordinates of mouse clicks. The preview is terminated by pressing the ‘q’, ‘Q’, or ‘Esc’ key.

Parameters:

*imgs (ndarray) – One or more images to display. Each image can be grayscale or color (BGR).
scale (float, optional) – Scaling factor for the displayed image windows. Default is 1.
window_name (str, optional) – Base name for the displayed windows. Default is “Image preview”.

Return type:

None

Notes

Known bug for Mac users: see https://gitlab.fit.cvut.cz/bi-svz/bi-svz/issues/13

improutils.solidity(contour)[source]

Determine the contour’s solidity.

Aka “plnost, celistvost”.

Parameters:: contour (ndarray) – The contour for the calculation.
Return type:: The number, describing the contour’s property

improutils.to_3_channels(image)[source]: Convert 1 channel image to 3 channels.

improutils.to_angle(hue_intensity)[source]

Convert hue intensity value of brightness image in opencv into hue angle in HUE definition.

For further info visit: https://www.docs.opencv.org/trunk/df/d9d/tutorial_py_colorspaces.html.

Parameters:: hue_intensity (int) – Intensity value of brightness image (0-179).
Return type:: Integer value that represents the HUE angle (0-359).

improutils.to_gray(img_bgr)[source]

Convert image to monochrome.

Parameters:: img_bgr (ndarray) – Input image.
Return type:: Output image.

improutils.to_hsv(img_bgr)[source]

Convert image to HSV (hue, saturation, value) color space.

Parameters:: img_bgr (ndarray) – Input image.
Return type:: Output image.

improutils.to_intensity(hue_angle)[source]

Convert color angle in HUE definition into intensity value of brightness image in opencv.

For further info visit: https://www.docs.opencv.org/trunk/df/d9d/tutorial_py_colorspaces.html.

Parameters:: hue_angle (int) – Angle in HUE definition (0-359).
Return type:: Integer value that represents the same HUE value but in opencv brightness image (0-179).

improutils.to_rgb(img_bgr)[source]

Convert image to RGB (red, green, blue) color space from BGR.

Parameters:: img_bgr (ndarray) – Input image.
Return type:: Output image.

improutils.top_hat(img, kernel_size=3, iterations=1, kernel=None)[source]

Apply the top hat morphological operation on the input image.

Parameters:

img (numpy.ndarray) – The input image.
kernel_size (int, optional) – The size of the kernel used for the operation. Default is 3.
iterations (int, optional) – The number of times the operation is applied. Default is 1.
kernel (numpy.ndarray, optional) – The custom kernel to be used for the operation. If not provided, a square kernel of size kernel_size will be used.

Return type:

The image after applying the top hat operation.

improutils.warp_to_cartesian(img, size=None, full_radius=True)[source]

Warp an image from polar coordinates back to Cartesian coordinates.

This function applies an inverse polar coordinate transformation to the input image using the polar_warp helper function.

Parameters:

img (ndarray) – Input image to be warped.
size (tuple of int, optional) – Size of the output image as (height, width). Default is None, which preserves the original image size.
full_radius (bool, optional) – If True, uses the full image diagonal as the radius for the warp. If False, uses only the vertical radius. Default is True.

Returns:

Image warped back to Cartesian coordinates.

Return type:

ndarray

improutils.warp_to_polar(img, size=None, full_radius=True)[source]

Warp an image to polar coordinates.

This function applies a polar coordinate transformation to the input image using the polar_warp helper function.

Parameters:

img (ndarray) – Input image to be warped.
size (tuple of int, optional) – Size of the output image as (height, width). Default is None, which preserves the original image size.
full_radius (bool, optional) – If True, uses the full image diagonal as the radius for the warp. If False, uses only the vertical radius. Default is True.

Returns:

Image warped to polar coordinates.

Return type:

ndarray