roipoly.py

Small python module to select a polygonal region of interest (ROI) in an image that is stored as a numpy array. The usage is similar to the roipoly function present in the image processing toolbox from MATLAB.

Installation

Either from PyPi: pip install roipoly

Or get the latest version from github: pip install git+https://github.com/jdoepfert/roipoly.py

Running the examples

Basic usage:

python examples/basic_example.py

Drawing multiple ROIs:

python examples/multi_roi_example.py

Usage

Creating a ROI

In your python code, import the roipoly module using

from roipoly import RoiPoly

To draw a ROI within an image present as a numpy array, show it first using e.g. pylabs’s imshow:

from matplotlib import pyplot as plt
plt.imshow(image)

Then let the user draw a polygonal ROI within that image:

my_roi = RoiPoly(color='r') # draw new ROI in red color

This lets the user interactively draw a polygon within the image by clicking with the left mouse button to select the vertices of the polygon. To close the polygon, click with the right mouse button. After finishing the ROI, the current figure is closed so that the execution of the code can continue.

Displaying a ROI

To display a created ROI within an image, first display the image as described above using e.g. imshow. Then,

my_roi.display_roi()

shows the created ROI on top of this image.

Display multiple ROIs like so:

for r in [my_roi1, my_roi2, my_roi3]
    r.display_roi()

To additionally show the mean pixel grey value inside a ROI in the image, type

my_roi.display_mean(image)

Note that you can only pass 2D images to display_mean()! If you have e.g. an RGB-image with dimension 3, you need to make the call like so:

mask = my_roi.display_mean(rgb_image[:, :, 0])

Extracting a binary mask image

The function get_mask() creates a binary mask for a certain ROI instance, that is, a 2D numpy array of the size of the (2D) image array, whose elements are True if they lie inside the ROI polygon, and False otherwise.

mask = my_roi.get_mask(image)
plt.imshow(mask) # show the binary signal mask

Note that you can only pass 2D images to get_mask(), If you have e.g. an RGB-image with dimension 3, you need to make the call like so:

mask = my_roi.get_mask(rgb_image[:, :, 0])

The resulting mask image can then be used to e.g. calculate the mean pixel intensity in an image over that ROI:

mean = plt.mean(image[mask])

To get the ROI coordinates [(x1, y1), (x2, y2), …]:

roi_coordinates = my_roi.get_roi_coordinates()

Drawing multiple ROIs

See examples/multi_roi_example.py

Credits

Based on a code snippet originally posted here by Daniel Kornhauser.