pwspy.dataTypes.Roi

class pwspy.dataTypes.Roi(name, number, mask, verts, filePath=None, fileFormat=None)[source]

Bases: object

This class represents a single Roi used to select a specific region of an image. Each Roi is identified by a name and a number. The recommended file format is HDF2, in this format multiple rois of the same name but differing numbers can be saved in a single HDF file. The Roi consists of a mask (a boolean array specifying which pixels are included in the Roi), a set of of vertices (a 2 x N array specifying the vertices of the polygon enclosing the mask, this is useful if you want to adjust the Roi later. Rather than calling the constructor directly you will generally create one of these objects through one of the class methods that construct one for you.

Parameters
  • name (str) – The name used to identify this ROI. Multiple ROIs can share the same name but must have unique numbers.

  • number (int) – The number used to identify this ROI. Each ROI with the same name must have a unique number.

  • mask (ndarray) – A 2D boolean array where the True values indicate pixels that are within the ROI.

  • verts (ndarray) – A sequence of 2D coordinates indicating the border of the ROI. While this information is partially redundant with the mask it is useful for many applications and can be complicated to calculate from mask.

  • filePath (Optional[str]) – The path to the file that this object was loaded from.

  • fileFormat (Optional[FileFormats]) – The format of the file that this object was loaded from.

class FileFormats(value)[source]

Bases: enum.Enum

An enumerator of the different file formats that an ROI can be saved to.

static deleteRoi(directory, name, num, fformat=None)[source]

Delete the dataset associated with the Roi object specified by name and num.

Parameters
  • directory (str) – The path to the folder containing the Roi file.

  • name (str) – The name used to identify this ROI.

  • number – The number used to identify this ROI.

  • fformat (Optional[FileFormats]) – The format of the file.

Raises

FileNotFoundError – If the file isn’t found.

classmethod fromHDF(directory, name, number)[source]

Load an Roi from an HDF file.

Parameters
  • directory (str) – The path to the directory containing the HDF file.

  • name (str) – The name used to identify this ROI.

  • number (int) – The number used to identify this ROI.

Raises

OSError – If the file was not found

Return type

Roi

Returns

A new instance of Roi loaded from file

Examples

myRoi = Roi.fromHDF(‘~/Desktop’, ‘nucleus’, 1)

classmethod fromHDF_legacy(directory, name, number)[source]

Load an Roi from an older version of the HDF file format which did not include the vertices parameter.

Parameters
  • directory (str) – The path to the directory containing the HDF file.

  • name (str) – The name used to identify this ROI.

  • number (int) – The number used to identify this ROI.

Raises

OSError – If the file was not found

Return type

Roi

Returns

A new instance of Roi loaded from file

classmethod fromMask(name, number, mask)[source]

Use rasterio to create find the vertices of a mask. :type name: str :param name: The name used to identify this ROI. Multiple ROIs can share the same name but must have unique numbers. :type number: int :param number: The number used to identify this ROI. Each ROI with the same name must have a unique number. :type mask: ndarray :param mask: A boolean array. The mask have only one contiguous True region

Return type

Roi

Returns

A new instance of Roi

classmethod fromMat(directory, name, number)[source]

Load an Roi from a .mat file saved in matlab. This file format is not reccomended as it does not include the vertices parameter which is useful for visually rendering and readjusting the Roi.

Parameters
  • directory (str) – The path to the directory containing the HDF file.

  • name (str) – The name used to identify this ROI.

  • number (int) – The number used to identify this ROI.

Return type

Roi

Returns

A new instance of Roi loaded from file

classmethod fromVerts(name, number, verts, dataShape)[source]

Automatically generate the mask for an Roi using just the vertices of an enclosing polygon.

Parameters
  • name (str) – The name used to identify this ROI. Multiple ROIs can share the same name but must have unique numbers.

  • number (int) – The number used to identify this ROI. Each ROI with the same name must have a unique number.

  • verts (ndarray) – A sequence of 2D (x, y) coordinates indicating the border of the ROI.

  • dataShape (Tuple[float, float]) – A tuple giving the shape of the array that this Roi is associated with.

Return type

Roi

Returns

A new instance of Roi

Examples

myRoi = Roi.fromVerts(‘nucleus’, 1, polyVerts, (1024, 1024))

getBoundingBox()[source]
Returns

(top, left, bottom, right)

Return type

A tuple of length 4 giving the coordinates of the rectangle that encloses this ROI in the form

getBoundingPolygon()[source]

Return a matplotlib Polygon representing the bounding polygon of the mask. In the case where a mask was saved but vertices were not this uses the ‘Concave Hull` method to estimate the vertices of the bounding polygon of the mask.

Return type

Polygon

Returns

A matplotlib Polygon representing the border of the Roi

getImage(ax, alpha=0.5, value=0.5, cmap='Reds', **kwargs)[source]

Return a matplotlib AxesImage representing the mask of the Roi. The image will be displayed on ax.

Parameters
  • ax (plt.Axes) – The matplotlib Axes to add the plot to.

  • alpha (float) – The transparency of the image

  • value (float) – A number between 0 and 1 to determine the color of the overlay.

  • cmap – The Matplotlib colormap that will be used to determine color.

  • kwargs – These keyword arguments will be passed to the matplotlib.imshow function.

Return type

AxesImage

Returns

A reference to the matplotlib AxesImage.

static getValidRoisInPath(path)[source]

Search the path for valid roi files and return the detected rois as a list of tuple where each tuple contains the name, number, and file format for the Roi.

Parameters

path (str) – The path to the folder containing the Roi files.

Returns

name: The detected Roi name number: The detected Roi number fformat: The file format of the file that the Roi is stored in

Return type

A list of tuples containing

classmethod loadAny(directory, name, number)[source]

Attempt loading any of the known file formats.

Parameters
  • directory (str) – The path to the directory containing the HDF file.

  • name (str) – The name used to identify this ROI.

  • number (int) – The number used to identify this ROI.

Returns

A new instance of Roi loaded from file

toHDF(directory, overwrite=False)[source]

Save the Roi to an HDF file in the specified directory. The filename is automatically chosen based on the name parameter of the Roi. Multiple Roi’s with the same name will be saved into the same file if they have differing number parameters. If overwrite is true then any existing dataset will be replaced, otherwise an error will be raised.

Parameters
  • directory (str) – The path of the folder to save the new HDF file to. The file will be named automatically based on the name attribute of the Roi

  • overwrite (Optional[bool]) – If True then if an Roi with the same number as this Roi is found it will be overwritten.

transform(matrix)[source]

Return a copy of this Roi that has been transformed by an affine transform matrix like the one returned by opencv.estimateRigidTransform. This can be obtained using the functions in the utility.machineVision module.

Parameters

matrix (ndarray) – A 2x3 numpy array representing an affine transformation.

Return type

Roi

Returns

A new instance of Roi representing this Roi after transformation.