dosertools.image_processing package — dosertools 2022 documentation

# dosertools.image_processing package

## Submodules

## dosertools.image_processing.binary module

dosertools.image_processing.binary.add_saved_params_to_dict(save_location: Union[str, bytes, os.PathLike], params_dict: dict)

  Adds parameters saved with binaries from tiffs to parameters from file name

  Parameters

    - save_location (path-like) – folder where file containing parameters was saved

    - params_dict (dict) – existing parameters dictionary

  Returns

    add_saved_params_to_dict (dict) – dictionary containing parameters from csv and from existing dictionary

dosertools.image_processing.binary.binaries_to_diameter_time(binary_location: Union[str, bytes, os.PathLike], window: numpy.array, params_dict: dict) → pandas.core.frame.DataFrame

  Converts binary image series into normalized diameter vs. time data

  Parameters

    - binary_location (path-like) – folder where binary images are located

    - window (np.array) – array of the boundaries of the image to analyze in the format [left, top, right, bottom]

    - params_dict – dictionary of parameters from file name and metadata saved with binary images requires parameters nozzle_diameter and fps

  Returns

    binary_to_diameter_time (pd.DataFrame) – dataframe of time and D/D0 from the binary images

dosertools.image_processing.binary.binary_images_to_csv(images_location: Union[str, bytes, os.PathLike], csv_location: Union[str, bytes, os.PathLike], fps: float, optional_settings: dict = {}) → None

  Converts from binary images to csv of normalized diameter versus time

  Parameters

    - save_location (path-like) – The path to the folder that contains “bin” folder of binary images and csv of parameter metadata, should be named with relevent experimental information. Save location used in tiff_handling functions. ex. folder named “20210929_6M-PEO-0p01wtpt_fps25k_1”

    - csv_location (path-like) – The path to the folder in which csv should be saved.

    - fps (float) – Frames per second for the video (likely parsed from file name)

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    skip_existing (bool) – Determines the behavior when a file already appears exists when a function would generate it. True to skip any existing files. False to overwrite (or delete and then write, where overwriting would generate an error). Default is True.

  Returns

    Saved csv on disk.

dosertools.image_processing.binary.bottom_border(image: numpy.ndarray) → int

  Finds bottom border of supplied image.

  Finds bottom border of supplied image for analysis by finding the row with the maximum number of white pixels below the half the height of the image (the bottom half). Return the index of the row with the first maximum number of white pixels.

  Parameters

    image (np.ndarray (scikit.io.imread)) – Image from scikit.io.imread import to find the bottom border of the section to analyze

  Returns

    bottom_border (int) – Index of last row to include in analysis, chosen as row with the most white pixels in the binary below the bottom half of the image

dosertools.image_processing.binary.calculate_min_diameter(image: numpy.ndarray, window: numpy.array) → float

  Finds the minimum diameter of the liquid bridge for a given image

  Finds the minimum diameter in the window for a given image. Calculates a diameter profile that is the number of pixels from the first white pixel to the last white pixel. Returns 0 if there are any rows that are fully black within the window (bottom is calculated on a per-image basis using bottom_border). Returns the average of any values that are within 2 pixels of the minimum measured diameter if there are no fully black rows. Averaging attempting to reduce stepping due to the finite size of pixels relative to the thin liquid bridge.

  Parameters

    - image (np.ndarray (scikit.io.imread)) – image of which to find the minimum diameter of the liquid bridge

    - window (np.array) – array of the boundaries of the image to analyze in the format [left, top, right, bottom] bottom will be replaced with the result of bottom_border(image)

  Returns

    min_diameter (float) – minimum diameter measured for the image in the window

## dosertools.image_processing.tiff_handling module

dosertools.image_processing.tiff_handling.bg_drop_top_edge(bg_median: numpy.ndarray)

  Determines the top edge of the background drop on the substrate.

  Detects the lowest edge in the background image. Uses Sobel edge detection.

  Parameters

    bg_median (np.ndarray) – median of the background video from produce_background_image

  Returns

    bg_drop_top_edge (list) – list of pixel y-values for the top edge of the background

dosertools.image_processing.tiff_handling.convert_tiff_image(image: numpy.ndarray, bg_median: numpy.ndarray, params_dict: dict, image_number: int, images_location: Union[str, bytes, os.PathLike], folders_exist: Tuple[bool, bool, bool], optional_settings: dict = {}) → None

  Fully converts a raw tiff to binary png image.

  Crops, perforns background subtraction, and binarizies. Always saves the binarized image as a .png, optional to save the intermediate steps.

  Parameters

    - image (np.ndarray) – The image to convert and save

    - bg_median (np.ndarray) – The single background image produced from produce_background_image

    - params_dict (dict) – Dictionary of parameters with the crop information added

    - images_location (path-like) – The folder where file should be saved

    - folders_exist (Tuple of three bools) – Booleans indicating whether the binary, crop, and bg_sub folders already existed to allow convert_tiff_image image to skip the relevant saves if optional_settings has skip_existing = True

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    - save_crop (bool) – True to save intermediate cropped images (i.e. experimental video images cropped but not background-subtracted or binarized). Default is False.

    - save_bg_sub (bool) – True to save background-subtracted images (i.e. experimental video images cropped and background-subtracted but not binarized). Default is False.

    - skip_existing (bool) – Determines the behavior when a file already appears exists when a function would generate it. True to skip any existing files. False to overwrite (or delete and then write, where overwriting would generate an error). Default is True.

  Returns

    Image sequence (video) saved on the hard drive at save_location

dosertools.image_processing.tiff_handling.convert_tiff_sequence_to_binary(experimental_video: skimage.io.collection.ImageCollection, bg_median: numpy.ndarray, params_dict: dict, save_location: Union[str, bytes, os.PathLike], folders_exist: Tuple[bool, bool, bool], optional_settings: dict = {})

  Takes as arguments the skimage image sequence holding the experimental video and the background image to subtract.

  Performs, sequentially, cropping, background subtraction, and binarization by the Mean method, and saves the binary images.

  Parameters

    - experimental_video (skimage.io.collection.ImageCollection) – The video identified as the experiment video from the researcher

    - bg_median (np.ndarray) – The single background image produced from produce_background_image

    - params_dict (dict) – Dictionary of parameters with the crop information added

    - save_location (path-like) – The folder where file should be saved

    - folders_exist (Tuple of three bools) – Booleans indicating whether the binary, crop, and bg_sub folders already existed to allow convert_tiff_image image to skip the relevant saves if optional_settings has skip_existing = True

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    - save_crop (bool) – True to save intermediate cropped images (i.e. experimental video images cropped but not background-subtracted or binarized). Default is False.

    - save_bg_sub (bool) – True to save background-subtracted images (i.e. experimental video images cropped and background-subtracted but not binarized). Default is False.

  Returns

    Image(s) saved locally in save_location

dosertools.image_processing.tiff_handling.crop_single_image(image: numpy.ndarray, params_dict: dict, optional_settings: dict = {}) → numpy.ndarray

  Crops a single image according to parameters from params_dict

  Parameters

    - image (np.ndarray (scikit.io.imread)) – The video identified as the experiment video from the researcher

    - params_dict (dict) – Dictionary of parameters with the crop information added

  Returns

    cropped_image (np.ndarray) – The input image, cropped according to values in parameters dictionary

dosertools.image_processing.tiff_handling.define_image_parameters(video: skimage.io.collection.ImageCollection, optional_settings: dict = {}) → dict

  From the given video, determines the first-guess for the cropping operation.

  Based on the nozzle width and safety factors crop_width_coefficient, crop_height_coefficient, etc.

  Parameters

    - video (skimage.io.collection.ImageCollection) – The video containing a clear image of the nozzle, we default to the raw experimental video

    - optional_settings (dict) –

  Returns

    params_dict (dict) – Dictionary of parameters with the crop information added

dosertools.image_processing.tiff_handling.export_params(images_location: Union[str, bytes, os.PathLike], params_dict: dict)

  Exports image parameters to a file to be stored with processed images.

  Parameters

    - images_location (path-like) – Path in which to save the parameters.

    - params_dict (dict) – Dictonary of parameters to save.

dosertools.image_processing.tiff_handling.mean_binarize_single_image(background_subtracted_image: numpy.ndarray) → numpy.ndarray

  Performs global binarization on an image according to the Otsu method

  Parameters

    background_subtracted_image (np.ndarray) – The cropped image with the background subtraction performed

  Returns

    binary_otsu (np.ndarray) – The binarized version of the input image

dosertools.image_processing.tiff_handling.produce_background_image(background_video: skimage.io.collection.ImageCollection, params_dict: dict, optional_settings: dict = {}) → numpy.ndarray

  Produces the background image from which the experimental video will be subtracted.

  Parameters

    - background_video (skimage.io.collection.ImageCollection) – The video identified as the background video from the researcher

    - params_dict (dict) – Dictionary of parameters with the crop information added

  Returns

    bg_median (np.ndarray) – The median of the frames in the background. We prefer median because it is less sensitive to random noise and the values are likely to be integers

dosertools.image_processing.tiff_handling.remove_bg_drop(bg_median: numpy.ndarray)

  Removes the background drop on the substrate from the background image.

  Using the edge from bg_drop_top_edge, replaces all pixels at or below it with the maximum in the background.

  Parameters

    bg_median (np.ndarray) – median of the background video from produce_background_image

  Returns

    bg_new (np.ndarray) – bg_median with the drop at the bottom set to the maximum value

dosertools.image_processing.tiff_handling.save_image(image: numpy.ndarray, image_number: int, save_location: Union[str, bytes, os.PathLike], extension: str)

  Saves a single image to the hard drive in save_location

  Parameters

    - image (np.ndarray) – The image to save

    - image_number (int) – Part of the filename. The frame number of this particular image in the video

    - save_location (path-like) – The folder where file should be saved

    - extension (str) – The file extension, eg, .tiff, .png

  Returns

    Image saved on the hard drive at save_location

dosertools.image_processing.tiff_handling.subtract_background_single_image(cropped_image: numpy.ndarray, bg_median: numpy.ndarray) → numpy.ndarray

  Performs background subtraction from a cropped image.

  Assumes cropped_image and bg_median are the same size.

  Parameters

    - cropped_image (np.ndarray) – The initial image, cropped according to values in parameters dictionary

    - bg_median (np.ndarray) – The single background image produced from produce_background_image

  Returns

    background_subtracted_image (np.ndarray) – The cropped image with the background subtraction performed

dosertools.image_processing.tiff_handling.tiffs_to_binary(experimental_video_folder: Union[str, bytes, os.PathLike], background_video_folder: Union[str, bytes, os.PathLike], images_location: Union[str, bytes, os.PathLike], optional_settings: dict = {})

  Processes experimental and background video into binarized video.

  Given a experimental video folder and a background video folder, processes the videos into a folder of binarized images in the target directory. Can also produce cropped and background subtracted images given optional settings.

  Parameters

    - experimental_video_folder (path-like) – Points to the folder which contains the experimental video to analyse.

    - background_video_folder (path-like) – Points to the folder which contains the background video used in analysis.

    - images_location (path-like) – The folder where folders of images should be saved.

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    - save_crop (bool) – True to save intermediate cropped images (i.e. experimental video images cropped but not background-subtracted or binarized). Default is False.

    - save_bg_sub (bool) – True to save background-subtracted images (i.e. experimental video images cropped and background-subtracted but not binarized). Default is False.

    - bg_drop_removal (bool) – True to remove the background drop from the background that is subtracted from the image before binarization. False to not alter the background. Default is False.

    - skip_existing (bool) – Determines the behavior when a file already appears exists when a function would generate it. True to skip any existing files. False to overwrite (or delete and then write, where overwriting would generate an error). Default is True.

    - verbose (bool) – Determines whether processing functions print statements as they progress through major steps. True to see print statements, False to hide non-errors/warnings. Default is False.

    - image_extension (string) – The extension for images in the video folder. TIFF recommended. Default is “tif”. Do not include “.”.

  Returns

    Image sequence(s) (video) saved on the hard drive at images_location

dosertools.image_processing.tiff_handling.top_border(bg_median: numpy.ndarray) → int

  Finds the top border of interest given a background image.

  Finds the last row of the nozzle in the background image to use as the top border in further image analysis.

  Parameters

    bg_median (np.ndarray) – Background image corresponding to a particular run.

  Returns

    top_border (int) – Last row of the nozzle.

## Module contents