{"id":24537,"library":"roifile","title":"roifile - Read and write ImageJ ROI format","description":"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.","status":"active","version":"2026.2.10","language":"python","source_language":"en","source_url":"https://github.com/cgohlke/roifile","tags":["imagej","roi","image-processing","bio-formats","numpy"],"install":[{"cmd":"pip install roifile","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"ROI data is represented as NumPy arrays","package":"numpy","optional":false}],"imports":[{"note":"roiread is not a top-level function; use roifile.roiread() or roifile.ImagejRoi.fromfile()","wrong":"from roifile import roiread","symbol":"roifile","correct":"import roifile"},{"note":"Correct import for the convenience function","wrong":"","symbol":"roifile.roiread","correct":"from roifile import roiread"},{"note":"Main class for ROI objects","wrong":"","symbol":"roifile.ImagejRoi","correct":"from roifile import ImagejRoi"}],"quickstart":{"code":"import roifile\n\n# Read an ROI from a file\nroi = roifile.roiread('example.roi')\nprint('ROI type:', roi.roitype)\nprint('Coordinates:', roi.coordinates())\n\n# Create a new ROI and save\nimport numpy as np\nnew_roi = roifile.ImagejRoi.frompoints(np.array([[0,0], [10,0], [10,10], [0,10]]))\nnew_roi.tofile('square.roi')","lang":"python","description":"Reads an ImageJ ROI file, prints its type and coordinates, then creates a new ROI from a list of points and saves it."},"warnings":[{"fix":"Use roifile.ImagejRoi.fromfile('file.roi') which handles multi-part ROIs.","message":"roiread() 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Access coordinates via roi.coordinates(subpixel=False) to get integer arrays if needed.","message":"Version 2024.x changed subpixel coordinates to be represented as floats by default. Older code expecting integer coordinates may break.","severity":"breaking","affected_versions":">=2024.0.0"},{"fix":"Use ImagejRoi properties directly or json serialization via roi.tojson() and ImagejRoi.fromjson().","message":"roifile.roi2dict() and roifile.dict2roi() are deprecated and will be removed in a future version.","severity":"deprecated","affected_versions":">=2023.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use: from roifile import roiread","cause":"roiread was renamed to roifile.roiread in version 2022.0.0 or import path confusion.","error":"AttributeError: module 'roifile' has no attribute 'roiread'"},{"fix":"Verify the file is a valid .roi file; try re-saving from ImageJ.","cause":"The ROI file is corrupted or not a valid ImageJ ROI.","error":"ValueError: Unsupported ROI type: 0"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}