forensicfit.core.tape module#

tape.py

This module contains classes for handling and analyzing measurements from tape in the context of the ForensicFit application. These measurements are represented as images which are processed and analyzed using a variety of computer vision techniques.

The module includes the following classes:

  • Tape: A class that represents an image of a tape measurement. It

provides functionalities to load and process the image, extract relevant information, and perform various operations such as binarization and smearing.

  • TapeAnalyzer: A class that inherits from the Tape class, adding

analysis functionalities. It can calculate the tape’s boundary, plot it, and compute and store analysis metadata.

The Tape class represents a single tape measurement and provides basic image processing operations. The TapeAnalyzer class extends this functionality by adding methods to analyze the tape’s boundary and other features, which can be useful in forensic applications.

Author: Pedram Tavadze Email: petavazohi@gmail.com

class forensicfit.core.tape.Tape(image, label=None, surface=None, stretched=False, **kwargs)[source]#

Bases: Image

Tape class is used for preprocessing tape images for machine learning.

This class takes in a tape image, detects the edges, auto crops the image and returns the results in 3 different methods: coordinate_based, bin_based, and max_contrast.

Parameters:

  • image (np.ndarray) – The image to be processed. It must be a 2D numpy array.

  • label (str, optional) – The label associated with the tape, by default None.

  • surface (str, optional) – The surface the tape is on, by default None.

  • stretched (bool, optional) – Flag indicating whether the tape is stretched or not, by default False.

  • **kwargs – Arbitrary keyword arguments.

metadata#

A dictionary storing metadata of the image such as flipping information, splitting information, label, material, surface, stretched status, and mode.

Type:

dict

Raises:

AssertionError – If image is not a numpy array or not a 2D array.

Attributes:
shape

Returns the shape of the image.

Methods

apply_filter(mode, **kwargs)

Applies different types of filters to the image

convert_to_gray()

Converts the image to grayscale.

convert_to_rgb()

Converts the image to RGB color space.

copy()

Creates a copy of the current image instance.

crop(x_start, x_end, y_start, y_end)

Crops the image using the specified x and y coordinates.

exposure_control([mode])

modifies the exposure

flip_h()

Flips the image horizontally.

flip_v()

Flips the image vertically.

from_buffer(buffer, metadata[, ext, ...])

Create an Image object from a given buffer and its corresponding metadata.

from_dict(values, metadata)

Create an Image object from a dictionary of values and metadata.

from_file(filepath)

Create an Image object from a given file path.

get(k[,d])

isolate([x_start, x_end, y_start, y_end])

Isolates a rectangular section from the image.

items()

keys()

plot([savefig, cmap, ax, show, zoom])

Plots the current image.

resize([size, dpi])

Resizes the image according to the specified dimensions or dpi.

rotate(angle)

Rotates the image by a specified angle.

show([wait, savefig])

param wait:

DESCRIPTION. The default is 0.

split_v(side[, correct_tilt, pixel_index])

Splits the tape image vertically.

to_buffer([ext])

Converts the Image instance into a bytes object.

to_file(filepath)

Writes the Image instance to a file.

values()

__init__(image, label=None, surface=None, stretched=False, **kwargs)[source]#
split_v(side, correct_tilt=True, pixel_index=None)[source]#

Splits the tape image vertically.

Parameters:

  • side (str) – The side of the image to be processed.

  • correct_tilt (bool, optional) – If set to True, tilt correction is applied on the image, by default True.

  • pixel_index (int, optional) – The index of the pixel where the image is to be split, by default None.

Return type:

None

Notes

Changes the ‘image’, ‘split_v’, ‘image_tilt’, ‘tilt_corrected’, ‘resolution’ fields of the metadata attribute.

class forensicfit.core.tape.TapeAnalyzer(tape, mask_threshold=60, gaussian_blur=(15, 15), n_divisions=6, auto_crop=False, correct_tilt=False, padding='tape', remove_background=True)[source]#

Bases: Analyzer

The TapeAnalyzer class is a specialized Analyzer used to preprocess duct tape images.

This class is used to process images of duct tape to prepare them for machine learning tasks. It includes functionality for Gaussian blur, auto-cropping, tilt correction, and background removal.

Parameters:

  • tape (Tape, optional) – An instance of the Tape class representing the tape image to be analyzed.

  • mask_threshold (int, optional) – The threshold used for masking during the image preprocessing. The default is 60.

  • gaussian_blur (tuple, optional) – The kernel size for the Gaussian blur applied during the preprocessing. The default is (15, 15).

  • n_divisions (int, optional) – The number of divisions to be used in the analysis. The default is 6.

  • auto_crop (bool, optional) – A flag indicating whether the image should be auto-cropped. The default is False.

  • correct_tilt (bool, optional) – A flag indicating whether the image tilt should be corrected. The default is False.

  • padding (str, optional) – The padding method used in the analysis. The default is ‘tape’.

  • remove_background (bool, optional) – A flag indicating whether the background should be removed from the image. The default is True.

Attributes:
shape

A property that provides the shape of the image contained in the Analyzer instance.

x_interval

Calculate the maximum x-coordinate value among the boundary points.

xmax

X coordinate of minimum pixel of the boundary

xmin

Calculate the minimum x-coordinate value among the boundary points.

ymax

Calculate the maximum y-coordinate value among the boundary points.

ymin

Calculate the minimum y-coordinate value among the boundary points.

Methods

apply_filter(mode, **kwargs)

auto_crop_y()

Automatically crop the image in the y-direction.

exposure_control([mode])

flip_h()

Flips the image horizontally and updates the relevant metadata.

flip_v()

Flips the image vertically and updates the relevant metadata.

from_buffer(buffer, metadata[, ext])

Receives an io byte buffer with the corresponding metadata and creates an instance of the class.

from_dict(image, metadata)

Class method to create an instance of the TapeAnalyzer class from provided image data and metadata.

get_bin_based([window_background, ...])

This method returns the edges detected in the image segmented into a given number of bins.

get_coordinate_based([n_points, x_trim_param])

This method returns the coordinate-based representation of the detected edge in the image.

get_image_tilt([plot])

Calculate the tilt angle of the image.

get_max_contrast([window_background, ...])

This method generates a binary image representation of the detected edge in the image.

load_dict()

Abstract method for loading a dictionary.

load_metadata()

Loads additional metadata about the image.

plot(which[, cmap, zoom, savefig, ax, show, ...])

Plots different kinds of data based on the given parameters.

plot_boundary([savefig, color, ax, show])

Plots the detected boundary of the image.

preprocess()

The preprocess method applies various image processing techniques to prepare the image for analysis.

resize([size, dpi])

Resize the image associated with this analyzer.

to_buffer([ext])

Converts the current instance of the Analyzer class to a byte buffer, which can be useful for serialization or for writing to a file.
__init__(tape, mask_threshold=60, gaussian_blur=(15, 15), n_divisions=6, auto_crop=False, correct_tilt=False, padding='tape', remove_background=True)[source]#
preprocess()[source]#

The preprocess method applies various image processing techniques to prepare the image for analysis.

This method performs several image preprocessing tasks including color inversion if necessary, conversion to grayscale, Gaussian blur, contour detection, and retrieval of the largest contour.

Parameters:

  • calculate_tilt (bool, optional) – A flag indicating whether the image tilt should be calculated. The default is True.

  • auto_crop (bool, optional) – A flag indicating whether the image should be auto-cropped. The default is True.

Return type:

None.

Notes

The original image is processed and the largest contour of the processed image is stored in the metadata under the ‘boundary’ key.

flip_v()[source]#

Flips the image vertically and updates the relevant metadata.

The flip_v method flips the image vertically, i.e., around the y-axis. It also updates the associated metadata such as the boundary, coordinates, slopes and dynamic positions if they are present in the metadata. The ‘flip_v’ metadata attribute is also toggled.

Parameters:

None –

Return type:

None

Notes

The original image is flipped vertically, and the corresponding changes are reflected in the metadata. The ‘flip_v’ metadata attribute is also toggled to reflect whether a vertical flip has been performed.

flip_h()[source]#

Flips the image horizontally and updates the relevant metadata.

The flip_h method flips the image horizontally, i.e., around the x-axis. It also updates the associated metadata such as the boundary, coordinates, slopes and dynamic positions if they are present in the metadata. The ‘flip_h’ metadata attribute is also toggled.

Parameters:

None –

Return type:

None

Notes

The original image is flipped horizontally, and the corresponding changes are reflected in the metadata. The ‘flip_h’ metadata attribute is also toggled to reflect whether a horizontal flip has been performed.

load_metadata()[source]#

Loads additional metadata about the image.

This method retrieves the minimum and maximum values of the x and y coordinates and their intervals from the TapeAnalyzer object, casts them to integers and stores them in the metadata attribute.

Parameters:

None –

Return type:

None

Notes

The original metadata of the TapeAnalyzer object is updated with the minimum and maximum x and y values and their intervals, and these values are cast to integers.

classmethod from_dict(image, metadata)[source]#

Class method to create an instance of the TapeAnalyzer class from provided image data and metadata.

Parameters:

  • image (np.ndarray) – The image data to initialize the TapeAnalyzer instance.

  • metadata (dict) – Dictionary containing metadata for the TapeAnalyzer instance.

Raises:

Exception – If the provided image is empty or None.

Returns:

An instance of TapeAnalyzer initialized with the provided image data and metadata.

Return type:

TapeAnalyzer

Notes

This class method provides an alternative way to create an instance of the TapeAnalyzer class, particularly when the necessary image data and metadata are available in advance.

get_image_tilt(plot=False)[source]#

Calculate the tilt angle of the image.

This function calculates the tilt angle of the image by applying a linear fit to the upper and lower boundaries of the image. It first divides the x-axis into ‘n_divisions’ segments, then it finds the top and bottom boundaries by searching for points within each segment that are within the top and bottom y-intervals respectively. For each segment, a linear fit is applied to the found boundary points, resulting in a set of slopes. The process is done separately for the top and bottom boundaries.

For each set of slopes, the one with the smallest standard deviation of the y-coordinates is selected. If no points are found in a segment, no slope is added for that segment.

The final tilt angle is the arctan of the average of the selected top and bottom slopes, converted to degrees.

Return type:

float

Parameters:

plot (bool, optional) – If True, the function will plot the boundary conditions that were used for the fit. The top boundary conditions are plotted in blue, and the bottom ones in red. Default is False.

Returns:

The tilt angle of the image in degrees.

Return type:

float

Notes

If the standard deviation of the y-coordinates of the boundaries used for the fit exceeds 10, the respective y-coordinate is set to the corresponding image boundary (y_max for the top, y_min for the bottom). The function also updates the ‘crop_y_top’, ‘crop_y_bottom’ and ‘image_tilt’ keys in the metadata of the TapeAnalyzer instance.

property xmin: int#

Calculate the minimum x-coordinate value among the boundary points.

This function computes the minimum value along the x-axis (horizontal direction in image) from the set of coordinates that form the boundary of the image. These boundaries have been identified and stored in the ‘boundary’ attribute of the object, which is a numpy array of shape (N, 2), where N is the number of boundary points and the 2 columns represent the x and y coordinates, respectively.

Returns:

The minimum x-coordinate value of the boundary points in the image.

Return type:

int

Notes

The boundary points should be pre-calculated and stored in the ‘boundary’ attribute before calling this function. If the ‘boundary’ attribute is not set, or if it is empty, this function may raise an error or return an unexpected result.

property xmax: int#

X coordinate of minimum pixel of the boundary

Returns:

xmax – X coordinate of minimum pixel of the boundary

Return type:

int

property x_interval: int#

Calculate the maximum x-coordinate value among the boundary points.

This function computes the maximum value along the x-axis (horizontal direction in image) from the set of coordinates that form the boundary of the image. These boundaries have been identified and stored in the ‘boundary’ attribute of the object, which is a numpy array of shape (N, 2), where N is the number of boundary points and the 2 columns represent the x and y coordinates, respectively.

Returns:

The maximum x-coordinate value of the boundary points in the image.

Return type:

int

Notes

The boundary points should be pre-calculated and stored in the ‘boundary’ attribute before calling this function. If the ‘boundary’ attribute is not set, or if it is empty, this function may raise an error or return an unexpected result.

property ymin: int#

Calculate the minimum y-coordinate value among the boundary points.

This function computes the minimum value along the y-axis (vertical direction in image) from the set of coordinates that form the boundary of the image. These boundaries have been identified and stored in the ‘boundary’ attribute of the object, which is a numpy array of shape (N, 2), where N is the number of boundary points and the 2 columns represent the x and y coordinates, respectively.

Returns:

The minimum y-coordinate value of the boundary points in the image.

Return type:

int

Notes

The boundary points should be pre-calculated and stored in the ‘boundary’ attribute before calling this function. If the ‘boundary’ attribute is not set, or if it is empty, this function may raise an error or return an unexpected result.

property ymax: int#

Calculate the maximum y-coordinate value among the boundary points.

This function computes the maximum value along the y-axis (vertical direction in image) from the set of coordinates that form the boundary of the image. These boundaries have been identified and stored in the ‘boundary’ attribute of the object, which is a numpy array of shape (N, 2), where N is the number of boundary points and the 2 columns represent the x and y coordinates, respectively.

Returns:

The maximum y-coordinate value of the boundary points in the image.

Return type:

int

Notes

The boundary points should be pre-calculated and stored in the ‘boundary’ attribute before calling this function. If the ‘boundary’ attribute is not set, or if it is empty, this function may raise an error or return an unexpected result.

auto_crop_y()[source]#

Automatically crop the image in the y-direction.

This function removes pixels from the top and bottom of the image based on the values stored in metadata.crop_y_bottom and metadata.crop_y_top, respectively. This can be useful for focusing on specific regions of interest in the image and removing unnecessary or distracting parts of the image.

Notes

The cropping limits are determined by the metadata.crop_y_bottom and metadata.crop_y_top attributes. Before calling this method, these attributes should be calculated or set. If these attributes are not set, the function may throw an error or return an unexpected result.

After cropping, the original image stored in the ‘image’ attribute is replaced by the cropped image. If you need to keep the original image as well, you should create a copy before calling this function.

Return type:

None

get_coordinate_based(n_points=64, x_trim_param=6)[source]#

This method returns the coordinate-based representation of the detected edge in the image. The edge is segmented into ‘n_points’ horizontal slices, and for each slice, the average x and y coordinates of the edge points within that slice are calculated. The method can also account for vertically flipped images.

Return type:

dict

Parameters:

  • n_points (int, optional) – The number of slices into which the edge is divided. The default is 64.

  • x_trim_param (int, optional) – A parameter to determine the range in the x-direction for edge point consideration. The x-range is divided by this parameter to define the x-range for edge detection. A smaller value of x_trim_param results in a larger x-range. The default is 6.

Returns:

A dictionary containing the calculated coordinate-based representation. The dictionary includes the number of points, the x_trim_param used, and three numpy arrays: ‘coordinates’ with the average (x, y) coordinates for each slice, ‘stds’ with the standard deviations of the x-coordinates within each slice, and ‘slopes’ with the slope and intercept of the least-square linear fit to the edge points within each slice.

Return type:

dict

get_bin_based(window_background=50, window_tape=1000, dynamic_window=True, n_bins=10, overlap=0, border='avg')[source]#

This method returns the edges detected in the image segmented into a given number of bins. Each bin is a slice of the image, vertically defined and extending horizontally to include a given number of pixels on both sides of the edge. The slices can have overlaps and their horizontal positions can be adjusted dynamically based on the edge location within the slice.

Return type:

List[Tuple[int, int]]

Parameters:

  • window_background (int, optional) – Number of pixels to be included in each slice on the background side of the edge. The default is 50.

  • window_tape (int, optional) – Number of pixels to be included in each slice on the tape side of the edge. The default is 1000.

  • dynamic_window (bool, optional) – Whether to adjust the horizontal position of the slices based on the edge location within the slice. The default is True.

  • n_bins (int, optional) – Number of slices into which the edge is divided. The default is 10.

  • overlap (int, optional) – The number of rows of overlap between consecutive slices. If positive, slices will overlap, if negative, there will be gaps between them. The default is 0.

  • border (str, optional) – Determines the method of edge detection within each slice. Options are ‘avg’ for the average position or ‘min’ for the minimum position of edge pixels in the slice. The default is ‘avg’.

Returns:

A list of tuples specifying the x-range and y-range of each slice in the format: [(x_start, x_end), (y_start, y_end)]

Return type:

List[Tuple[int, int]]

get_max_contrast(window_background=100, window_tape=600)[source]#

This method generates a binary image representation of the detected edge in the image. It generates a new image where all pixels are set to 0 (black), except for the ones at the detected edge location, which are set to 1 (white).

This can help in visualizing the edge or in performing further analysis, as the edge is distinctly highlighted against a uniform background.

Return type:

ndarray

Parameters:

  • window_background (int, optional) – Number of pixels to be included in each slice on the background side of the edge. These pixels will be set to black in the resulting image. The default is 100.

  • window_tape (int, optional) – Number of pixels to be included in each slice on the tape side of the edge. These pixels will be set to black in the resulting image. The default is 600.

Returns:

edge_bw – A 2D numpy array representing the image. All pixels are black (0), except the ones at the detected edge location, which are white (1).

Return type:

np.ndarray