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

License:

BSD-3-Clause

Version:

2025.5.10

DOI:

10.5281/zenodo.6941603

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

Revisions

2025.5.10

  • Support Python 3.14.

2025.2.20

  • Drop support for Python 3.9.

2024.9.15

  • Improve typing.

  • Deprecate Python 3.9, support Python 3.13.

2024.5.24

  • Fix docstring examples not correctly rendered on GitHub.

2024.3.20

  • Fix writing generator of ROIs (#9).

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

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:

Examples

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

python -m roifile _test.roi

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

Project details


Download files

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

Source Distribution

roifile-2025.5.10.tar.gz (18.8 kB view details)

Uploaded Source

Built Distribution

roifile-2025.5.10-py3-none-any.whl (17.6 kB view details)

Uploaded Python 3

File details

Details for the file roifile-2025.5.10.tar.gz.

File metadata

  • Download URL: roifile-2025.5.10.tar.gz
  • Upload date:
  • Size: 18.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for roifile-2025.5.10.tar.gz
Algorithm Hash digest
SHA256 8e5d1f799695ac59f52d4d62bb9016de74ef2493b4d83e24ce7fb25e19f53cce
MD5 39728d779721f178973ee099a9ba003d
BLAKE2b-256 ceee8ab570959011aac7d5705b7c284ab90734aed297672711444e21c11ab4d0

See more details on using hashes here.

File details

Details for the file roifile-2025.5.10-py3-none-any.whl.

File metadata

  • Download URL: roifile-2025.5.10-py3-none-any.whl
  • Upload date:
  • Size: 17.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for roifile-2025.5.10-py3-none-any.whl
Algorithm Hash digest
SHA256 92ef64a775167542cd98c4beb7c5f867412c572d1a111f03ee0fede7fdf64155
MD5 68315fd2ef756801905e35dc1e6f98d7
BLAKE2b-256 5b9bf689742c06f377e33090d78e370d013e7e062ab8ac407f03f1105ddfc934

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page