https://github.com/cgohlke/roifile

Read and write ImageJ ROI format.

Science Score: 39.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 3 DOI reference(s) in README
○
Academic publication links
○
Committers with academic emails
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (12.1%) to scientific vocabulary

Keywords

format-reader imagej python region-of-interest

Last synced: 5 months ago · JSON representation

Repository

Read and write ImageJ ROI format.

Basic Info

Host: GitHub
Owner: cgohlke
License: bsd-3-clause
Language: Python
Default Branch: master
Homepage: https://pypi.org/project/roifile
Size: 244 KB

Statistics

Stars: 74
Watchers: 6
Forks: 7
Open Issues: 1
Releases: 12

Topics

format-reader imagej python region-of-interest

Created almost 6 years ago · Last pushed 10 months ago

Metadata Files

Readme Changelog License

README.rst

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

- `CPython `_ 3.10.11, 3.11.9, 3.12.10, 3.13.3 64-bit
- `NumPy `_ 2.2.5
- `Tifffile `_ 2025.5.10 (optional)
- `Matplotlib `_ 3.10.3 (optional)

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:

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

Owner

Name: Christoph Gohlke
Login: cgohlke
Kind: user
Location: Irvine, California

Website: https://www.cgohlke.com
Repositories: 52
Profile: https://github.com/cgohlke

GitHub Events

Total

Create event: 2
Issues event: 1
Release event: 2
Watch event: 11
Push event: 3
Fork event: 1

Last Year

Create event: 2
Issues event: 1
Release event: 2
Watch event: 11
Push event: 3
Fork event: 1

Name	Email	Commits
Christoph Gohlke	c**e@c**m	87

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 9
Total pull requests: 1
Average time to close issues: 13 days
Average time to close pull requests: about 23 hours
Total issue authors: 8
Total pull request authors: 1
Average comments per issue: 1.78
Average comments per pull request: 3.0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 1
Pull requests: 0
Average time to close issues: N/A
Average time to close pull requests: N/A
Issue authors: 1
Pull request authors: 0
Average comments per issue: 0.0
Average comments per pull request: 0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

csachs (2)
ViriatoII (1)
ericsua (1)
bpavie (1)
Bisho2122 (1)
stilley2 (1)
christianrickert (1)
nal10 (1)

Pull Request Authors

fabiansvara (1)

Top Labels

Issue Labels

bug (1) question (1)

Pull Request Labels

Packages

Total packages: 3
Total downloads:
- pypi 36,200 last-month

Total dependent packages: 16
(may contain duplicates)
Total dependent repositories: 6
(may contain duplicates)
Total versions: 48
Total maintainers: 1

proxy.golang.org: github.com/cgohlke/roifile

Documentation: https://pkg.go.dev/github.com/cgohlke/roifile#section-documentation
License: bsd-3-clause
Latest release: v2025.5.10+incompatible
published 10 months ago

Versions: 19
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent packages count: 5.5%

Average: 5.7%

Dependent repos count: 5.9%

Last synced: 6 months ago

pypi.org: roifile

Read and write ImageJ ROI format

Homepage: https://www.cgohlke.com
Documentation: https://roifile.readthedocs.io/
License: BSD-3-Clause
Latest release: 2025.5.10
published 10 months ago

Versions: 19
Dependent Packages: 15
Dependent Repositories: 6
Downloads: 36,200 Last month

Rankings

Dependent packages count: 1.0%

Downloads: 2.9%

Dependent repos count: 6.0%

Average: 7.1%

Stargazers count: 10.2%

Forks count: 15.3%

Maintainers (1)

cgohlke

Last synced: 6 months ago

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.

Homepage: https://www.cgohlke.com/
License: BSD-3-Clause
Latest release: 2022.9.19
published over 3 years ago

Versions: 10
Dependent Packages: 1
Dependent Repositories: 0

Rankings

Dependent packages count: 28.8%

Dependent repos count: 34.0%

Average: 38.9%

Stargazers count: 43.0%

Forks count: 49.6%

Last synced: 6 months ago

Dependencies

setup.py pypi

numpy >=1.19.2

https://github.com/cgohlke/roifile

Science Score: 39.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.rst

Owner

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

proxy.golang.org: github.com/cgohlke/roifile

Rankings

pypi.org: roifile

Rankings

Maintainers (1)

conda-forge.org: roifile

Rankings

Dependencies