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.3.20
: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.9.13, 3.10.11, 3.11.8, 3.12.2
- `Numpy <https://pypi.org/project/numpy/>`_ 1.26.4
- `Tifffile <https://pypi.org/project/tifffile/>`_ 2024.2.12 (optional)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.8.3 (optional)
Revisions
---------
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)
Plot the ROI using matplotlib:
>>> roi.plot()
View the overlays stored in a ROI, ZIP, or TIFF file from a command line::
python -m roifile _test.roi
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/71/f3/903a2ab4e1bd285a392ad313df9f55482f0bd37ee5d74a8f0b8cae327fba/roifile-2024.3.20.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.3.20\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.9.13, 3.10.11, 3.11.8, 3.12.2\r\n- `Numpy <https://pypi.org/project/numpy/>`_ 1.26.4\r\n- `Tifffile <https://pypi.org/project/tifffile/>`_ 2024.2.12 (optional)\r\n- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.8.3 (optional)\r\n\r\nRevisions\r\n---------\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\r\nPlot the ROI using matplotlib:\r\n\r\n>>> roi.plot()\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",
"bugtrack_url": null,
"license": "BSD",
"summary": "Read and write ImageJ ROI format",
"version": "2024.3.20",
"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": "b80dc8881882852416d0d9bcd96bc6a1a54e80f6bae0eeba5c96c7b39f1e0403",
"md5": "3d641d8ee31496cb00f49c5b37421bd0",
"sha256": "84b0af1394d0f0e50d04a5b107e64bf90f9712c1102ee397103f6a71917b974d"
},
"downloads": -1,
"filename": "roifile-2024.3.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d641d8ee31496cb00f49c5b37421bd0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16528,
"upload_time": "2024-03-20T16:41:48",
"upload_time_iso_8601": "2024-03-20T16:41:48.314308Z",
"url": "https://files.pythonhosted.org/packages/b8/0d/c8881882852416d0d9bcd96bc6a1a54e80f6bae0eeba5c96c7b39f1e0403/roifile-2024.3.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "71f3903a2ab4e1bd285a392ad313df9f55482f0bd37ee5d74a8f0b8cae327fba",
"md5": "3e50c0c90ac9fd8d2c698b3531627aed",
"sha256": "e2ac3b91f171fb7379edaaf99d95fe07dafbd9216ae3676f5e3cf34ce1feb200"
},
"downloads": -1,
"filename": "roifile-2024.3.20.tar.gz",
"has_sig": false,
"md5_digest": "3e50c0c90ac9fd8d2c698b3531627aed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17204,
"upload_time": "2024-03-20T16:41:49",
"upload_time_iso_8601": "2024-03-20T16:41:49.437919Z",
"url": "https://files.pythonhosted.org/packages/71/f3/903a2ab4e1bd285a392ad313df9f55482f0bd37ee5d74a8f0b8cae327fba/roifile-2024.3.20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-20 16:41:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cgohlke",
"github_project": "roifile",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "roifile"
}
JSON
