4.5.1. discorpy.util.utility

Module of utility methods:

  • Generate a dot-pattern, line-pattern, and chessboard image.

  • Find corresponding points between the distorted and undistorted space.

  • Unwarp a color image with an option to keep the original field of view.

  • Unwarping an image or video using the ‘remap’ function in Opencv for fast performance.

Functions:

make_dot_pattern([height, width, ...])

Generate a dot-pattern image.

make_line_pattern([height, width, ...])

Generate a dot-pattern image.

make_chessboard([height, width, size, ...])

Generate a chessboard image.

find_point_to_point(points, xcenter, ...[, ...])

Calculate corresponding points between distorted and undistorted space.

unwarp_color_image_backward(mat, xcenter, ...)

Unwarp a color image using a backward model.

mapping_cv2(mat, xmat, ymat[, method, border])

Apply a geometric transformation to a 2D array using Opencv.

unwarp_image_backward_cv2(mat, xcenter, ...)

Unwarp an image using the backward model with the Opencv 'remap' function for fast performance.

unwarp_video_cv2(cam_obj, xcenter, ycenter, ...)

Unwarp frames from Opencv video object using the backward model.
discorpy.util.utility.make_circle_mask(width, ratio)[source]

Create a circle mask.

Parameters:

  • width (int) – Width of a square array.

  • ratio (float) – Ratio between the diameter of the mask and the width of the array.

Returns:

array_like – Square array.

discorpy.util.utility.make_dot_pattern(height=1800, width=2000, dot_distance=90, dot_size=15, margin=150)[source]

Generate a dot-pattern image.

Parameters:

  • height (int) – Height of the image.

  • width (int) – Width of the image.

  • dot_distance (int) – Distance between two dots.

  • dot_size (int) – Size of each dot.

  • margin (int) – Blank area between the dots and the edges.

Returns:

array_like – Dot-pattern image.

discorpy.util.utility.make_line_pattern(height=1800, width=2000, line_distance=90, line_size=7, margin=100)[source]

Generate a dot-pattern image.

Parameters:

  • height (int) – Height of the image.

  • width (int) – Width of the image.

  • line_distance (int) – Distance between two dots.

  • line_size (int) – Size of each dot.

  • margin (int) – Blank area between the lines and the edges.

Returns:

array_like – Dot-pattern image.

discorpy.util.utility.make_chessboard(height=1800, width=2000, size=100, margin=100, margin_grayscale=0.95)[source]

Generate a chessboard image.

Parameters:

  • height (int) – Height of the image.

  • width (int) – Width of the image.

  • size (int) – Size of each cell.

  • margin (int) – Blank area between the chessboard and the edges.

  • margin_grayscale (float) – Gray scale of margin area (0: black 1: white).

Returns:

array_like – Chessboard image.

discorpy.util.utility.find_point_to_point(points, xcenter, ycenter, list_fact, output_order='xy')[source]

Calculate corresponding points between distorted and undistorted space. This function can be used both ways: - Given the input is a distorted point and a forward model, the output is the undistorted point. - Given the input is an undistorted point and a backward model, the output is the distorted point.

Parameters:

  • points (tuple of point indexes.) – Tuple of (row_index, column_index) of the point. Note that the format is ij-index not xy-coordinate.

  • xcenter (float) – Center of distortion in x-direction.

  • ycenter (float) – Center of distortion in y-direction.

  • list_fact (list of float) – Polynomial coefficients of the backward/forward model.

  • output_order ({“xy”, “yx”}) – To select the order of the output. “yx” <-> “ij”.

Returns:

tuple of float – x- and y-coordinate of the point in another space.

discorpy.util.utility.unwarp_color_image_backward(mat, xcenter, ycenter, list_fact, order=1, mode='reflect', pad=False, pad_mode='constant')[source]

Unwarp a color image using a backward model.

Parameters:

  • mat (array_like) – 2D/3D array.

  • xcenter (float) – Center of distortion in x-direction.

  • ycenter (float) – Center of distortion in y-direction.

  • list_fact (list of float) – Polynomial coefficients of the backward model.

  • order (int, optional.) – The order of the spline interpolation.

  • mode ({‘reflect’, ‘grid-mirror’, ‘constant’, ‘grid-constant’, ‘nearest’,) – ‘mirror’, ‘grid-wrap’, ‘wrap’}, optional To determine how to handle image boundaries.

  • pad (bool, int, or tuple of int.) – Use to keep the original view. If pad is True, the pad width is calculated automatically.

  • pad_mode (str) – To select a method for padding: ‘reflect’, ‘edge’, ‘mean’, ‘linear_ramp’, ‘symmetric’,…

Returns:

array_like – 2D/3D array. Distortion-corrected image.

discorpy.util.utility.mapping_cv2(mat, xmat, ymat, method=None, border=None)[source]

Apply a geometric transformation to a 2D array using Opencv.

Parameters:

  • mat (array_like.) – 2D/3D array.

  • xmat (array_like) – 2D array of the x-coordinates. Origin is at the left of the image.

  • ymat (array_like) – 2D array of the y-coordinates. Origin is at the top of the image.

  • method (opencv-object) – To select interpolation method. Note to use the prefix: cv2.<method> https://tinyurl.com/3afmv6jc

  • border (opencv-object) – To select method for boundary handling. Note to use the prefix: cv2.<method> https://tinyurl.com/52xzkwt2

Returns:

array_like

discorpy.util.utility.unwarp_image_backward_cv2(mat, xcenter, ycenter, list_fact, method=None, border=None, pad=False, pad_mode='constant')[source]

Unwarp an image using the backward model with the Opencv ‘remap’ function for fast performance.

Parameters:

  • mat (array_like) – Input image. Can be a color image.

  • xcenter (float) – Center of distortion in x-direction.

  • ycenter (float) – Center of distortion in y-direction.

  • list_fact (list of float) – Polynomial coefficients of the backward model.

  • method (opencv-object) – To select interpolation method. Note to use the prefix: cv2.<method> https://tinyurl.com/3afmv6jc

  • border (opencv-object) – To select method for boundary handling. Note to use the prefix: cv2.<method> https://tinyurl.com/52xzkwt2

  • pad (bool, int, or tuple of int.) – Use to keep the original view. If pad is True, the pad width is calculated automatically.

  • pad_mode (str) – To select a method for padding: ‘reflect’, ‘edge’, ‘mean’, ‘linear_ramp’, ‘symmetric’,…

Returns:

array_like – Distortion-corrected image.

discorpy.util.utility.unwarp_video_cv2(cam_obj, xcenter, ycenter, list_fact, method=None, border=None, pad=True, pad_mode='constant')[source]

Unwarp frames from Opencv video object using the backward model.

Parameters:

  • cam_obj (obj) – Opencv camera object. e.g. cv2.VideoCapture(0)

  • xcenter (float) – Center of distortion in x-direction.

  • ycenter (float) – Center of distortion in y-direction.

  • list_fact (list of float) – Polynomial coefficients of the backward model.

  • method (opencv-object) – To select interpolation method. Note to use the prefix: cv2.<method> https://tinyurl.com/3afmv6jc

  • border (opencv-object) – To select method for boundary handling. Note to use the prefix: cv2.<method> https://tinyurl.com/52xzkwt2

  • pad (bool, int, or tuple of int.) – Use to keep the original view. If pad is True, the pad width is calculated automatically.

  • pad_mode (str) – To select a method for padding: ‘reflect’, ‘edge’, ‘mean’, ‘linear_ramp’, ‘symmetric’,…

Returns:

Generator