https://github.com/cgohlke/roifile
Read and write ImageJ ROI format.
https://github.com/cgohlke/roifile
format-reader imagej python region-of-interest
Last synced: about 2 months ago
JSON representation
Read and write ImageJ ROI format.
- Host: GitHub
- URL: https://github.com/cgohlke/roifile
- Owner: cgohlke
- License: bsd-3-clause
- Created: 2020-02-22T19:22:04.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-05-10T19:40:48.000Z (10 months ago)
- Last Synced: 2025-11-27T19:55:21.459Z (4 months ago)
- Topics: format-reader, imagej, python, region-of-interest
- Language: Python
- Homepage: https://pypi.org/project/roifile
- Size: 244 KB
- Stars: 82
- Watchers: 5
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.rst
- License: LICENSE
Awesome Lists containing this project
README
..
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 `_
:License: BSD-3-Clause
:Version: 2026.1.8
: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):
- `CPython `_ 3.11.9, 3.12.10, 3.13.11, 3.14.2 64-bit
- `NumPy `_ 2.4.0
- `Tifffile `_ 2025.12.20 (optional)
- `Matplotlib `_ 3.10.8 (optional)
Revisions
---------
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
- Drop support for Python 3.9.
2024.9.15
- …
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 `_
- `napari_jroitools `_
Examples
--------
Create a new ImagejRoi instance from an array of x, y coordinates:
.. code-block:: python
>>> 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:
.. 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.