cellphe.processing package

Submodules

cellphe.processing.image module

cellphe.processing.image

Functions related to processing images.

class cellphe.processing.image.SubImage(sub_image: array, type_mask: array, centroid: array)[source]

Bases: object

Represents a sub-image, that is a portion of an image corresponding to a specific region-of-interest (ROI).

Properties:
  • sub_image: A 2D array representing the image truncated to the bounds

    of the ROI.

  • type_mask: A 2D array the same size as the sub-image detailing which

    pixels are either inside the ROI (1), outside (-1), or on the ROI border (0).

  • centroid: A 1D array of length 2 containing the (x,y) points at the

    centre of the ROI.

centroid: array
sub_image: array
type_mask: array
cellphe.processing.image.create_type_mask_fill_polygon(roi)[source]

Creates a type mask for a given ROI in an image.

This returns a 2D integer array representing the sub-image of the cell that the ROI covers, where:

  • Pixels outside the cell are given a value of -1

  • Pixels on the ROI border are assigned 0

  • Pixels inside the ROI border are assigned 1

This implementation is based the following algorithm: https://www.alienryderflex.com/polygon_fill/

Parameters:

  • image – 2D array of the image pixels.

  • roi – 2D array of x,y coordinates.

Returns:

Returns a 2D array representing the image where the values are either -1, 0, or 1.

cellphe.processing.image.create_type_mask_flood_fill(roi: array) → array[source]

Creates a type mask for a given ROI in an image.

This returns a 2D integer array representing the sub-image of the cell that the ROI covers, where:

  • Pixels outside the cell are given a value of -1

  • Pixels on the ROI border are assigned 0

  • Pixels inside the ROI border are assigned 1

This method uses a floodfill algorithm, implemented in skimage.

Parameters:

  • image – 2D array of the image pixels.

  • roi – 2D array of x,y coordinates.

Returns:

Returns a 2D array representing the image where the values are either -1, 0, or 1.

cellphe.processing.image.create_type_mask_flood_fill_negative(roi: array) → array[source]

Creates a type mask for a given ROI in an image.

This returns a 2D integer array representing the sub-image of the cell that the ROI covers, where:

  • Pixels outside the cell are given a value of -1

  • Pixels on the ROI border are assigned 0

  • Pixels inside the ROI border are assigned 1

This method uses a floodfill algorithm, implemented in skimage.

Parameters:

  • image – 2D array of the image pixels.

  • roi – 2D array of x,y coordinates.

Returns:

Returns a 2D array representing the image where the values are either -1, 0, or 1.

cellphe.processing.image.create_type_mask_matplotlib(roi: array) → array[source]

Creates a type mask for a given ROI in an image.

This returns a 2D integer array representing the sub-image of the cell that the ROI covers, where:

  • Pixels outside the cell are given a value of -1

  • Pixels on the ROI border are assigned 0

  • Pixels inside the ROI border are assigned 1

This method uses matplotlib’s Path module and ‘contains_points’ methods on all the points in the image subset to see if they reside within the ROI.

Parameters:

  • image – 2D array of the image pixels.

  • roi – 2D array of x,y coordinates.

Returns:

Returns a 2D array representing the image where the values are either -1, 0, or 1.

cellphe.processing.image.create_type_mask_ray_cast_4(roi: array) → array[source]

Creates a type mask for a given ROI in an image.

This returns a 2D integer array representing the sub-image of the cell that the ROI covers, where:

  • Pixels outside the cell are given a value of -1

  • Pixels on the ROI border are assigned 0

  • Pixels inside the ROI border are assigned 1

This is a modified Ray Casting algorithm that rather than defining interior pixels as those that lie within an odd number of boundary crossings in 1 direction, it identifies them as lying within a relaxed boundary on all 4 sides. The relaxed boundary includes any points after the first boundary crossing. This is because there are known limitations with the odd-numbered approach with this dataset, which using all 4 directions is attempting to resolve.

Parameters:

  • image – 2D array of the image pixels.

  • roi – 2D array of x,y coordinates.

Returns:

Returns a 2D array representing the image where the values are either -1, 0, or 1.

cellphe.processing.image.create_type_mask_skimage(roi: array) → array[source]

Creates a type mask for a given ROI in an image.

This returns a 2D integer array representing the sub-image of the cell that the ROI covers, where:

  • Pixels outside the cell are given a value of -1

  • Pixels on the ROI border are assigned 0

  • Pixels inside the ROI border are assigned 1

This method uses skimage’s grid_points_in_poly, a point in polygon algorithm similar to Matplotlib’s.

Parameters:

  • image – 2D array of the image pixels.

  • roi – 2D array of x,y coordinates.

Returns:

Returns a 2D array representing the image where the values are either -1, 0, or 1.

cellphe.processing.image.extract_subimage(image: array, roi: array, method: str = 'flood_fill_negative') → SubImage[source]

Extracts a sub-image and relevant statistics from a given image and ROI.

Parameters:

  • image – The image as a 2D Numpy array.

  • roi – The region of interest as an Mx2 Numpy array.

Returns:

A SubImage instance.

cellphe.processing.image.find_crossing_points(corners: array, shape: array) → array[source]

Finds the crossing points for a ray entering a given polygon. This implementation is based the following algorithm: https://www.alienryderflex.com/polygon_fill/

Parameters:

  • corners – The corners that define the polygon. Must be ordered either clockwise or anti-clockwise.

  • shape – The maximum shape of the polygon in (height, width).

Returns:

A 2D array of shape (height, width) of type integer, where each value corresponds to the number of boundary crossings at this pixel.

cellphe.processing.image.normalise_image(image: array, lower: int, upper: int) → array[source]

Normalises an image to a specified range.

Parameters:

  • image – The image to normalise as a 2D numpy array.

  • lower – The lower bound of the target normalisation range, as an integer.

  • upper – The upper boundo of the target normalisation range, as an integer.

Returns:

The normalised image as a 2D numpy array.

cellphe.processing.roi module

cellphe.processing.roi

Functions related to processing ROIs.

cellphe.processing.roi.boundary_vertices(roi: array) → array[source]

Returns the vertices that lie directly on the boundary of an ROI, i.e. removing any additional vertices that do not directly impact on the interior area.

Parameters:

roi – 2D array of x,y coordinates.

Returns:

A 2D array of x,y coordinates.

cellphe.processing.roi.get_corner_mask(mat: array) → array[source]

Finds the corners of a masked boundary.

The boundary must be split up into its constituent dimensions, so that the input mat is a 2D array where the first dimension (rows) each hold another dimension, be it rows, columns, or diagonals in the original matrix. The data should 0s and 1s, where a 1 indicates a boundary pixel and a 0 otherwise.

Corners (shown in parentheses) are found as points where the pixels either change from 0 -> (1) -> 1, or 1 -> (1) -> 0. These are identified by taking the second difference, which will equal to -1 in both cases. The rows are padded with starting and trailing 0s in case the boundary lies on the dimension edge.

Parameters:

mat – A 2D array containing the dimensions of the original matrix. See the description and usage for more details.

Returns:

A boolean array the same dimensions as mat, where a True indicates that that vertex is a corner.

cellphe.processing.roi.get_diagonals(mat: array) → list[array][source]

Retrieves the diagonals (both forward and backward) from a matrix.

NB: There’s a manual version here, which was found to be slower than Numpy but it’s a useful resource providing the equations relating x,y to the diagonal positions. https://stackoverflow.com/a/43311126/1020006

Parameters:

mat – A 2D Numpy array.

Returns:

A 2D matrix containing the diagonals on each row, right padded with zeros.

cellphe.processing.roi.interpolate_between_points(coords: array) → array[source]

Interpolates between the ROI coordinates to ensure there aren’t any breaks in the boundary.

All the downstream CellPhe analysis assumes that there aren’t any gaps in the ROIs. This function guarantees that.

Parameters:

coords – A 2D Numpy array of coordinate pairs in the form (x,y).

Returns:

An array in the same format as coords with either the same number of coordinates, or more.

cellphe.processing.roi.roi_corners(roi: array) → array[source]

Gets the corners from an ROI, i.e. any vertex that connect 2 sides.

Parameters:

roi – 2D array of x,y coordinates.

Returns:

A 2D array of x,y coordinates.

cellphe.processing.roi.save_rois(rois: list[dict], filename: str = 'rois.zip')[source]

Saves ROIs to disk.

Parameters:

  • rois – List of dicts, each one representing an ROI with elements: - coords: 2D numpy array containing the ROI coordinates. - CellID: Cell ID - FrameID: Frame ID - filename: Filename to save the ROI to

  • filename – Filename of output archive.

Returns:

None, writes to disk as a side-effect.

Module contents

Functions related to processing datasets.