roifile

library2026.2.10pypypi✓ verified 88d ago

roifile is a Python library for reading and writing ImageJ ROI (Region of Interest) files. It supports the native ImageJ ROI binary format (.roi) and can extract ROIs from ZIP archives. Current version is 2026.2.10, with a release cadence of roughly monthly updates. Requires Python >=3.11.

data serialization

pip install roifile

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ROIFILE

roifile

datapythonv2026.2.10

Install

3.7s avg

Import

283ms

Disk

89MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2025.12.12 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.288s · 89.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.7s · import 0.278s · 86MB

89MB installed

● package 89MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

roifile

✓ import roifile

✗ from roifile import roiread

roiread is not a top-level function; use roifile.roiread() or roifile.ImagejRoi.fromfile()

roifile.roiread

✓ from roifile import roiread

Correct import for the convenience function

roifile.ImagejRoi

✓ from roifile import ImagejRoi

Main class for ROI objects

Reads an ImageJ ROI file, prints its type and coordinates, then creates a new ROI from a list of points and saves it.

import roifile # Read an ROI from a file roi = roifile.roiread('example.roi') print('ROI type:', roi.roitype) print('Coordinates:', roi.coordinates()) # Create a new ROI and save import numpy as np new_roi = roifile.ImagejRoi.frompoints(np.array([[0,0], [10,0], [10,10], [0,10]])) new_roi.tofile('square.roi')

Debug

Known issues

gotcharoiread() returns a single ImagejRoi object; if your .roi file contains multiple subregions (e.g., composite ROI), it may raise an error or return unexpected results. Use ImagejRoi.fromfile() for complex files.

fix

Use roifile.ImagejRoi.fromfile('file.roi') which handles multi-part ROIs.

affects: all

breakingVersion 2024.x changed subpixel coordinates to be represented as floats by default. Older code expecting integer coordinates may break.

fix

Access coordinates via roi.coordinates(subpixel=False) to get integer arrays if needed.

affects: >=2024.0.0

deprecatedroifile.roi2dict() and roifile.dict2roi() are deprecated and will be removed in a future version.

fix

Use ImagejRoi properties directly or json serialization via roi.tojson() and ImagejRoi.fromjson().

affects: >=2023.0.0

Errors

Common errors & fixes

AttributeError: module 'roifile' has no attribute 'roiread'

roiread was renamed to roifile.roiread in version 2022.0.0 or import path confusion.

fix

Use: from roifile import roiread

ValueError: Unsupported ROI type: 0

The ROI file is corrupted or not a valid ImageJ ROI.

fix

Verify the file is a valid .roi file; try re-saving from ImageJ.

Upgrade

Version history

2026.2.10latest on PyPI · released Feb 11, 2026

Audit

Dependencies

numpyrequiredROI data is represented as NumPy arrays

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cgohlke/roifile ↗

packagehttps://pypi.org/project/roifile/ ↗

homepagehttps://www.cgohlke.com ↗