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: 6 days 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 (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2024-09-15T16:55:02.000Z (4 months ago)
• Last Synced: 2024-12-14T05:06:34.233Z (20 days ago)
• Topics: format-reader, imagej, python, region-of-interest
• Language: Python
• Homepage: https://pypi.org/project/roifile
• Size: 202 KB
• Stars: 68
• Watchers: 7
• Forks: 7
• Open Issues: 0
• 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: 2024.9.15

: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.10.11, 3.11.9, 3.12.5, 3.13.0rc2

- `Numpy `_ 2.2.1

- `Tifffile `_ 2024.8.30 (optional)

- `Matplotlib `_ 3.9.2 (optional)

Revisions

---------

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:

- `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 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.