Quickstart

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

python -m pip install -U "roifile[all]"

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.17, 3.14.10, 3.15.2 64-bit

• Numpy 2.5.4

• Tifffile 2026.9.20 (optional)

• Imagecodecs 2026.10.10 (optional)

• Matplotlib 3.11.2 (optional)

Revisions

2026.11.6

• Fix undefined enum values overwriting UNKNOWN member value (breaking).

• Fix autoname to use center of bounding box (breaking).

• Fix writing names, properties, and text with non-BMP characters.

• Fix unwrapping of empty bounding boxes.

• Fix coordinates of subpixel RECT and OVAL ROIs.

• Fix various edge cases in reading, writing, and hexcolor.

• Raise ValueError on oversized data and skip non-ROI ZIP entries (breaking).

• Add text_draw_string_mode field.

• Improve plotting (closed and filled shapes, colors, pixel offset).

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

• …

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.