Skip to main content

Read and write ImageJ ROI format

Project description

Roifile is a Python library to read, write, create, and plot ImageJ ROIs, an undocumented and ImageJ application specific format to store regions of interest, geometric shapes, paths, text, and whatnot for image overlays.

Author:Christoph Gohlke
Organization:Laboratory for Fluorescence Dynamics, University of California, Irvine
License:BSD 3-Clause


This release has been tested with the following requirements and dependencies (other versions may work):


Add enums for point types and sizes.
Support group attribute. Add roiread and roiwrite functions (#3). Use UUID as default name of ROI in ImagejRoi.frompoints (#2).
Support writing to ZIP file. Support os.PathLike file names.
Fix int32 to hex color conversion. Fix coordinates of closing path. Fix reading TIFF files with no overlays.
Split positions from counters.
Initial release.


The ImageJ ROI format cannot store integer coordinate values outside the range of -32768 to 32767 (16-bit signed).

Other Python packages handling ImageJ ROIs:


Create a new ImagejRoi instance from an array of x, y coordinates:

>>> roi = ImagejRoi.frompoints([[1.1, 2.2], [3.3, 4.4], [5.4, 6.6]])
>>> roi.coordinates()
array([[1.1, 2.2],
       [3.3, 4.4],
       [5.4, 6.6]], dtype=float32)
>>> roi.left, roi.left, roi.right, roi.bottom
(1, 1, 5, 6)

Export the instance to an ImageJ ROI formatted byte string or file:

>>> out = roi.tobytes()
>>> out[:4]
>>> roi.tofile('_test.roi')

Read the ImageJ ROI from the file:

>>> roi2 = ImagejRoi.fromfile('_test.roi')
>>> roi2 == roi

Plot the ROI using matplotlib:

>>> roi.plot()

To view the overlays stored in a ROI, ZIP, or TIFF file from a command line, run python -m roifile _test.roi.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for roifile, version 2021.6.6
Filename, size File type Python version Upload date Hashes
Filename, size roifile-2021.6.6-py3-none-any.whl (12.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size roifile-2021.6.6.tar.gz (13.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page