roifile


Nameroifile JSON
Version 2024.9.15 PyPI version JSON
download
home_pagehttps://www.cgohlke.com
SummaryRead and write ImageJ ROI format
upload_time2024-09-15 16:53:51
maintainerNone
docs_urlNone
authorChristoph Gohlke
requires_python>=3.9
licenseBSD
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            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: 2024.9.15
: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.10.11, 3.11.9, 3.12.5, 3.13.0rc2
- `Numpy <https://pypi.org/project/numpy/>`_ 2.2.1
- `Tifffile <https://pypi.org/project/tifffile/>`_ 2024.8.30 (optional)
- `Matplotlib <https://pypi.org/project/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
<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/>`_
- `napari_jroitools <https://github.com/jayunruh/napari_jroitools>`_

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

            

Raw data

            {
    "_id": null,
    "home_page": "https://www.cgohlke.com",
    "name": "roifile",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": null,
    "author": "Christoph Gohlke",
    "author_email": "cgohlke@cgohlke.com",
    "download_url": "https://files.pythonhosted.org/packages/16/e9/6981c0b954963e9c8235d55ff0fa7f40e017cc8205fcbfb8a6591c58a77e/roifile-2024.9.15.tar.gz",
    "platform": "any",
    "description": "Read and write ImageJ ROI format\r\n================================\r\n\r\nRoifile is a Python library to read, write, create, and plot `ImageJ`_ ROIs,\r\nan undocumented and ImageJ application specific format to store regions of\r\ninterest, geometric shapes, paths, text, and whatnot for image overlays.\r\n\r\n.. _ImageJ: https://imagej.net\r\n\r\n:Author: `Christoph Gohlke <https://www.cgohlke.com>`_\r\n:License: BSD 3-Clause\r\n:Version: 2024.9.15\r\n:DOI: `10.5281/zenodo.6941603 <https://doi.org/10.5281/zenodo.6941603>`_\r\n\r\nQuickstart\r\n----------\r\n\r\nInstall the roifile package and all dependencies from the\r\n`Python Package Index <https://pypi.org/project/roifile/>`_::\r\n\r\n    python -m pip install -U \"roifile[all]\"\r\n\r\nView overlays stored in a ROI, ZIP, or TIFF file::\r\n\r\n    python -m roifile file.roi\r\n\r\nSee `Examples`_ for using the programming interface.\r\n\r\nSource code, examples, and support are available on\r\n`GitHub <https://github.com/cgohlke/roifile>`_.\r\n\r\nRequirements\r\n------------\r\n\r\nThis revision was tested with the following requirements and dependencies\r\n(other versions may work):\r\n\r\n- `CPython <https://www.python.org>`_ 3.10.11, 3.11.9, 3.12.5, 3.13.0rc2\r\n- `Numpy <https://pypi.org/project/numpy/>`_ 2.2.1\r\n- `Tifffile <https://pypi.org/project/tifffile/>`_ 2024.8.30 (optional)\r\n- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.9.2 (optional)\r\n\r\nRevisions\r\n---------\r\n\r\n2024.9.15\r\n\r\n- Improve typing.\r\n- Deprecate Python 3.9, support Python 3.13.\r\n\r\n2024.5.24\r\n\r\n- Fix docstring examples not correctly rendered on GitHub.\r\n\r\n2024.3.20\r\n\r\n- Fix writing generator of ROIs (#9).\r\n\r\n2024.1.10\r\n\r\n- Support text rotation.\r\n- Improve text rendering.\r\n- Avoid array copies.\r\n- Limit size read from files.\r\n\r\n2023.8.30\r\n\r\n- Fix linting issues.\r\n- Add py.typed marker.\r\n\r\n2023.5.12\r\n\r\n- Improve object repr and type hints.\r\n- Drop support for Python 3.8 and numpy < 1.21 (NEP29).\r\n\r\n2023.2.12\r\n\r\n- Delay import of zipfile.\r\n- Verify shape of coordinates on write.\r\n\r\n2022.9.19\r\n\r\n- Fix integer coordinates to -5000..60536 conforming with ImageJ (breaking).\r\n- Add subpixel_coordinates in frompoints for out-of-range integer coordinates.\r\n\r\n2022.7.29\r\n\r\n- \u2026\r\n\r\nRefer to the CHANGES file for older revisions.\r\n\r\nNotes\r\n-----\r\n\r\nThe ImageJ ROI format cannot store integer coordinate values outside the\r\nrange of -5000..60536.\r\n\r\nRefer to the ImageJ `RoiDecoder.java\r\n<https://github.com/imagej/ImageJ/blob/master/ij/io/RoiDecoder.java>`_\r\nsource code for a reference implementation.\r\n\r\nOther Python packages handling ImageJ ROIs:\r\n\r\n- `ijpython_roi <https://github.com/dwaithe/ijpython_roi>`_\r\n- `read-roi <https://github.com/hadim/read-roi/>`_\r\n- `napari_jroitools <https://github.com/jayunruh/napari_jroitools>`_\r\n\r\nExamples\r\n--------\r\n\r\nCreate a new ImagejRoi instance from an array of x, y coordinates:\r\n\r\n>>> roi = ImagejRoi.frompoints([[1.1, 2.2], [3.3, 4.4], [5.5, 6.6]])\r\n>>> roi.roitype = ROI_TYPE.POINT\r\n>>> roi.options |= ROI_OPTIONS.SHOW_LABELS\r\n\r\nExport the instance to an ImageJ ROI formatted byte string or file:\r\n\r\n>>> out = roi.tobytes()\r\n>>> out[:4]\r\nb'Iout'\r\n>>> roi.tofile('_test.roi')\r\n\r\nRead the ImageJ ROI from the file and verify the content:\r\n\r\n>>> roi2 = ImagejRoi.fromfile('_test.roi')\r\n>>> roi2 == roi\r\nTrue\r\n>>> roi.roitype == ROI_TYPE.POINT\r\nTrue\r\n>>> roi.subpixelresolution\r\nTrue\r\n>>> roi.coordinates()\r\narray([[1.1, 2.2],\r\n       [3.3, 4.4],\r\n       [5.5, 6.6]], dtype=float32)\r\n>>> roi.left, roi.top, roi.right, roi.bottom\r\n(1, 2, 7, 8)\r\n>>> roi2.name = 'test'\r\n\r\nPlot the ROI using matplotlib:\r\n\r\n>>> roi.plot()\r\n\r\nWrite the ROIs to a ZIP file:\r\n\r\n>>> roiwrite('_test.zip', [roi, roi2], mode='w')\r\n\r\nRead the ROIs from the ZIP file:\r\n\r\n>>> rois = roiread('_test.zip')\r\n>>> assert len(rois) == 2 and rois[0] == roi and rois[1].name == 'test'\r\n\r\nWrite the ROIs to an ImageJ formatted TIFF file:\r\n\r\n>>> import tifffile\r\n>>> tifffile.imwrite(\r\n...     '_test.tif',\r\n...     numpy.zeros((9, 9), 'u1'),\r\n...     imagej=True,\r\n...     metadata={'Overlays': [roi.tobytes(), roi2.tobytes()]},\r\n... )\r\n\r\nRead the ROIs embedded in an ImageJ formatted TIFF file:\r\n\r\n>>> rois = roiread('_test.tif')\r\n>>> assert len(rois) == 2 and rois[0] == roi and rois[1].name == 'test'\r\n\r\nView the overlays stored in a ROI, ZIP, or TIFF file from a command line::\r\n\r\n    python -m roifile _test.roi\r\n\r\nFor an advanced example, see `roifile_demo.py` in the source distribution.\r\n",
    "bugtrack_url": null,
    "license": "BSD",
    "summary": "Read and write ImageJ ROI format",
    "version": "2024.9.15",
    "project_urls": {
        "Bug Tracker": "https://github.com/cgohlke/roifile/issues",
        "Homepage": "https://www.cgohlke.com",
        "Source Code": "https://github.com/cgohlke/roifile"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1e55d78704af96e26c5b064eda998af479f098f2dc9f3d77ac7bce4600a6752b",
                "md5": "f5382917a4083760b72375b1808e11fa",
                "sha256": "433460978422b510437f5f3090e9eb288e2e3dfa7a3119481a424632ad69707a"
            },
            "downloads": -1,
            "filename": "roifile-2024.9.15-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f5382917a4083760b72375b1808e11fa",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 17239,
            "upload_time": "2024-09-15T16:53:50",
            "upload_time_iso_8601": "2024-09-15T16:53:50.401460Z",
            "url": "https://files.pythonhosted.org/packages/1e/55/d78704af96e26c5b064eda998af479f098f2dc9f3d77ac7bce4600a6752b/roifile-2024.9.15-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "16e96981c0b954963e9c8235d55ff0fa7f40e017cc8205fcbfb8a6591c58a77e",
                "md5": "fc1f128108688283476e3be90d9e5677",
                "sha256": "5a4e6925bec15c1d9e2805601176eeabc0be808f5a6e77b62bb67776116f8f3c"
            },
            "downloads": -1,
            "filename": "roifile-2024.9.15.tar.gz",
            "has_sig": false,
            "md5_digest": "fc1f128108688283476e3be90d9e5677",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 18356,
            "upload_time": "2024-09-15T16:53:51",
            "upload_time_iso_8601": "2024-09-15T16:53:51.789969Z",
            "url": "https://files.pythonhosted.org/packages/16/e9/6981c0b954963e9c8235d55ff0fa7f40e017cc8205fcbfb8a6591c58a77e/roifile-2024.9.15.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-09-15 16:53:51",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "cgohlke",
    "github_project": "roifile",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "roifile"
}
        
Elapsed time: 1.62185s