Quickstart

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 and Documentation for using the programming interface.

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

Requirements

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

• CPython 3.12.10, 3.13.15, 3.14.7, 3.15.0rc 64-bit

• Numpy 2.5.3

• Tifffile 2026.9.20 (optional)

• Imagecodecs 2026.8.16 (optional)

• Matplotlib 3.11.2 (optional)

Revisions

2026.9.22

• Accept buffer objects and avoid unnecessary copies in ImagejRoi.frombytes.

2026.7.30

• Use Java compatible rounding for subpixel coordinates (breaking).

• Recover roi names stored as Latin-1 instead of UTF-16.

• Drop support for Python 3.11 and numpy 2.0 (SPEC0).

• Support Python 3.15.

2026.2.10

• Revise wrapping of integer coordinates again (breaking).

• Bump file version to 229.

• Support groups > 255 (untested).

• Support IMAGE subtype (requires imagecodecs).

• Add point_type and point_size properties for point ROIs.

• Do not return empty paths in path2coords.

• Improve documentation.

2026.1.29

• Fix code review issues.

2026.1.22

• Fix boolean codec in ImagejRoi.properties.

2026.1.20

• Fix reading ImagejRoi.props.

• Add ImagejRoi.properties property to decode and encode ImagejRoi.props.

2026.1.8

• Improve code quality.

• Drop support for Python 3.10.

2025.12.12

• Move tests to separate module.

2025.5.10

• Support Python 3.14.

2025.2.20

• …

Refer to the CHANGES file for older revisions.

Notes

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

• sdt-python

• napari_jroitools

Examples

Import functions and classes used in these examples:

>>> from roifile import (
...     ImagejRoi,
...     roiread,
...     roiwrite,
...     ROI_TYPE,
...     ROI_POINT_SIZE,
...     ROI_OPTIONS,
... )

Create a new ImagejRoi instance from an array of x, y coordinates, then set ROI properties:

>>> roi = ImagejRoi.frompoints([[1.1, 2.2], [3.3, 4.4], [5.5, 6.6]])
>>> roi.roitype = ROI_TYPE.POINT
>>> roi.point_size = ROI_POINT_SIZE.LARGE
>>> 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)
>>> roi2.name = 'test'

Plot the ROI using matplotlib:

>>> roi.plot()

Write the ROIs to a ZIP file:

>>> roiwrite('_test.zip', [roi, roi2], mode='w')

Read the ROIs from the ZIP file:

>>> rois = roiread('_test.zip')
>>> assert len(rois) == 2 and rois[0] == roi and rois[1].name == 'test'

Write the ROIs to an ImageJ formatted TIFF file:

>>> import numpy
>>> import tifffile
>>> tifffile.imwrite(
...     '_test.tif',
...     numpy.zeros((9, 9), 'u1'),
...     imagej=True,
...     metadata={'Overlays': [roi.tobytes(), roi2.tobytes()]},
... )

Read the ROIs embedded in an ImageJ formatted TIFF file:

>>> rois = roiread('_test.tif')
>>> assert len(rois) == 2 and rois[0] == roi and rois[1].name == 'test'

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

python -m roifile _test.roi

For an advanced example, see roifile_demo.py in the source distribution.