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.

Install the roifile package and all dependencies from the Python Package Index:

python -m pip install -U roifile[all]

View overlays stored in a ROI, ZIP, or TIFF file:

python -m roifile file.roi

See Examples for using the programming interface.

Source code, examples, and support are available on GitHub.

This revision was tested with the following requirements and dependencies (other versions may work):

• CPython 3.9.13, 3.10.11, 3.11.4, 3.12.1
• Numpy 1.26.3
• Tifffile 2023.12.9 (optional)
• Matplotlib 3.8.2 (optional)

2024.1.10

• Support text rotation.
• Improve text rendering.
• Avoid array copies.
• Limit size read from files.

2023.8.30

• Fix linting issues.
• Add py.typed marker.

2023.5.12

• Improve object repr and type hints.
• Drop support for Python 3.8 and numpy < 1.21 (NEP29).

2023.2.12

• Delay import of zipfile.
• Verify shape of coordinates on write.

2022.9.19

• Fix integer coordinates to -5000..60536 conforming with ImageJ (breaking).
• Add subpixel_coordinates in frompoints for out-of-range integer coordinates.

2022.7.29

• Update metadata.

2022.3.18

• Fix creating ROIs from float coordinates exceeding int16 range (#7).
• Fix bottom-right bounds in ImagejRoi.frompoints.

2022.2.2

• Add type hints.
• Change ImagejRoi to dataclass.
• Drop support for Python 3.7 and numpy < 1.19 (NEP29).

2021.6.6

• …

Refer to the CHANGES file for older revisions.

The ImageJ ROI format cannot store integer coordinate values outside the range of -5000..60536.

Refer to the ImageJ RoiDecoder.java source code for a reference implementation.

Other Python packages handling ImageJ ROIs:

• ijpython_roi
• read-roi
• napari_jroitools

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

>>> roi = ImagejRoi.frompoints([[1.1, 2.2], [3.3, 4.4], [5.5, 6.6]])
>>> roi.roitype = ROI_TYPE.POINT
>>> roi.options |= ROI_OPTIONS.SHOW_LABELS

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

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

Read the ImageJ ROI from the file and verify the content:

>>> roi2 = ImagejRoi.fromfile('_test.roi')
>>> roi2 == roi
True
>>> roi.roitype == ROI_TYPE.POINT
True
>>> roi.subpixelresolution
True
>>> roi.coordinates()
array([[1.1, 2.2],
       [3.3, 4.4],
       [5.5, 6.6]], dtype=float32)
>>> roi.left, roi.top, roi.right, roi.bottom
(1, 2, 7, 8)

Plot the ROI using matplotlib:

>>> roi.plot()

View the overlays stored in a ROI, ZIP, or TIFF file from a command line:

python -m roifile _test.roi