roifile

What it is and what it does

Roifile is a Python library for working with ImageJ ROI files, an undocumented format used by ImageJ to store regions of interest, geometric shapes, paths, and text annotations for image overlays. It lets you read ROI data from .roi files, ZIP archives, or embedded in TIFF metadata; create new ROI objects programmatically from coordinate arrays; modify ROI properties like type, size, and labels; and write the results back to disk or TIFF files. The package depends only on numpy at runtime, with optional support for tifffile (to embed ROIs in TIFF files), imagecodecs (for certain image types), and matplotlib (for plotting overlays).

The library is designed for scientific and image-analysis workflows where you need to programmatically manipulate or batch-process ImageJ annotations. It includes a command-line viewer to inspect ROI files and full round-trip support—you can read a ROI, modify it, and write it back with the same format and properties preserved. The format itself has limitations: integer coordinates are constrained to the range -5000..60536, and the implementation follows ImageJ's Java reference implementation for compatibility.

Use it for:

• Batch convert or migrate ImageJ ROI annotations between .roi, ZIP, and TIFF formats
• Programmatically create geometric annotations (points, polygons, paths) and embed them in TIFF images for ImageJ
• Read and modify ROI metadata (names, types, display properties) in automated image-processing pipelines
• Extract coordinate data from ImageJ overlays for downstream analysis or visualization in other tools
• View and inspect ROI file contents from the command line without opening ImageJ

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Read, write, create, and plot ImageJ ROI format files, which store regions of interest, geometric shapes, paths, and text overlays for image annotation.

Yes. The package is actively maintained, has no known vulnerabilities, installs with minimal friction, and solves a specific and well-defined problem for anyone working with ImageJ ROI files in Python. The permissive BSD-3-Clause license poses no restrictions. Install it if you need to read, write, or manipulate ImageJ annotations programmatically.

Install

roifile on PyPI

pip install roifile

uv add roifile

poetry add roifile

Installing roifile

Before you install

Low install friction with a single runtime dependency (numpy). Active maintenance with a release 15 days old; the package has been in development since 2020 and currently supports Python 3.12–3.15.

License in practice

BSD-3-Clause is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install roifile

from roifile import ImagejRoi

roi = ImagejRoi.frompoints([[1.1, 2.2], [3.3, 4.4]])
roi.tofile('output.roi')

roi_read = ImagejRoi.fromfile('output.roi')
print(roi_read.coordinates())

Requires Python 3.12 or later; numpy must be installed as a runtime dependency.

Verify before relying

• Whether optional dependencies (tifffile, imagecodecs, matplotlib) are required for specific use cases or fully optional
• Performance characteristics when handling large ROI collections or complex geometric shapes

Package facts

Evidence: roifile-2026.7.30-py3-none-any.whl

Tags

More Graphics packages