Read and write ImageJ ROI format

February 11, 2026 · View on GitHub

.. This file is generated by setup.py

Read and write ImageJ ROI format

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.

.. _ImageJ: https://imagej.net

:Author: Christoph Gohlke <https://www.cgohlke.com>_ :License: BSD-3-Clause :Version: 2026.2.10 :DOI: 10.5281/zenodo.6941603 <https://doi.org/10.5281/zenodo.6941603>_

Quickstart

Install the roifile package and all dependencies from the Python Package Index <https://pypi.org/project/roifile/>_::

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 <https://github.com/cgohlke/roifile>_.

Requirements

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

  • CPython <https://www.python.org>_ 3.11.9, 3.12.10, 3.13.12, 3.14.3 64-bit
  • NumPy <https://pypi.org/project/numpy>_ 2.4.2
  • Tifffile <https://pypi.org/project/tifffile/>_ 2026.1.28 (optional)
  • Imagecodecs <https://pypi.org/project/imagecodecs/>_ 2026.1.14 (optional)
  • Matplotlib <https://pypi.org/project/matplotlib/>_ 3.10.8 (optional)

Revisions

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 <https://github.com/imagej/ImageJ/blob/master/ij/io/RoiDecoder.java>_ source code for a reference implementation.

Other Python packages handling ImageJ ROIs:

  • ijpython_roi <https://github.com/dwaithe/ijpython_roi>_
  • read-roi <https://github.com/hadim/read-roi/>_
  • sdt-python <https://github.com/schuetzgroup/sdt-python>_
  • napari_jroitools <https://github.com/jayunruh/napari_jroitools>_

Examples

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

.. code-block:: python

>>> 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:

.. code-block:: python

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

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

.. code-block:: python

>>> 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:

.. code-block:: python

>>> roi.plot()

Write the ROIs to a ZIP file:

.. code-block:: python

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

Read the ROIs from the ZIP file:

.. code-block:: python

>>> 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:

.. code-block:: python

>>> 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:

.. code-block:: python

>>> 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 a command line::

python -m roifile _test.roi

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