There didn't appear to be an easy way to import ImageJ ROI files into Matlab, and the existing function I found didn't seem to work. This function imports ROIs and ROI sets without needing Java.

This function reads the binary ImageJ region-of-interest (ROI) file format directly, as “documented” in RoiDecoder.java. (As a software developer, I have to question the wisdom of pointing someone to the code as the only documentation of a binary file format…) ImageJ allows several different types of ROI definition. ReadImageJROI only extracts the raw data from the ROI file; for simple ROIs this is probably enough, but for complex, compound ROIs, more work may be required to find the pixels included in the ROI.

Download and install

Download ReadImageJROI.m and save it somewhere on the Matlab path. No extra toolboxes or functions should be required (and please tell me if something is missing!)

Usage

[sROI] = ReadImageJROI(strFilename)
[cvsROIs] = ReadImageJROI(cstrFilenames)
[cvsROIs] = ReadImageJROI(strROIArchiveFilename)

strFilename is the full path to a .roi file. A list of ROI files can be passed as a cell array of filenames, in cstrFilenames. An ImageJ ROI set archive can be access by providing a .zip filename in strROIArchiveFilename. Single ROIs are returned as Matlab structures, with variable fields depending on the ROI type. Multiple ROIs are returned as a cell array of ROI structures.

Structure fields

The field .strName is guaranteed to exist, and contains the ROI name (the filename minus .roi).

The field .strType is guaranteed to exist, and defines the ROI type: {Rectangle, Oval, Line, Polygon, Freehand, Traced, PolyLine, FreeLine, Angle, Point, NoROI}.

The field .vnRectBounds is guaranteed to exist, and defines a vector containing the rectangular bounds of the ROI: [nTop, nLeft, nBottom, nRight].

The field .nVersion is guaranteed to exist, and defines the version number of the ROI format.

ROI Types

Rectangle

.strType = 'Rectangle';
.nArcSize — The arc size of the rectangle's rounded corners

For a composite, “shape” ROI

.strSubtype = 'Shape';
.vfShapeSegments — A long, complicated vector of complicated shape segments. This vector is in the format passed to the ImageJ ShapeROI constructor. I won't decode this for you! :(

Oval

.strType = 'Oval';

Line

.strType = 'Line';
.vnLinePoints — The end points of the line [nX1, nY1, nX2, nY2]

With arrow

.strSubtype = 'Arrow';
.bDoubleHeaded — Does the line have two arrowheads?
.bOutlined — Is the arrow outlined?
.nArrowStyle — The ImageJ style of the arrow (unknown interpretation)
.nArrowHeadSize — The size of the arrowhead (unknown units)

Polygon

.strType = 'Polygon';
.mnCoordinates — An [Nx2] matrix, specifying the coordinates of the polygon vertices. Each row has the format [nX nY].

Freehand

.strType = 'Freehand';
.mnCoordinates — An [Nx2] matrix, specifying the coordinates of the polygon vertices. Each row has the format [nX nY].

Ellipse subtype

.strSubtype = 'Ellipse';
.vfEllipsePoints — A vector containing the ellipse control points: [fX1 fY1 fX2 fY2].
.fAspectRatio — The aspect ratio of the ellipse.

Traced

.strType = 'Traced';
.mnCoordinates — An [Nx2] matrix, specifying the coordinates of the line vertices. Each row has the format [nX nY].

PolyLine

.strType = 'PolyLine';
.mnCoordinates — An [Nx2] matrix, specifying the coordinates of the line vertices. Each row has the format [nX nY].

FreeLine

.strType = 'FreeLine';
.mnCoordinates — An [Nx2] matrix, specifying the coordinates of the line vertices. Each row has the format [nX nY].

Angle

.strType = 'Angle';
.mnCoordinates — A [3x2] matrix, specifying the coordinates of the angle vertices. Each row has the format [nX nY].

Point

.strType = 'Point';
.mnCoordinates — An [Nx2] matrix, specifying the coordinates of the points. Each row has the format [nX nY].

NoROI

.strType = 'NoROI';

Additional fields

Additionally, ROIs from later versions (.nVersion ≥ 218) may have the following fields:
.nStrokeWidth — The width of the line stroke
.nStrokeColor — The encoded color of the stroke (ImageJ color format)
.nFillColor — The encoded fill color for the ROI (ImageJ color format)

If the ROI contains text

.strSubtype = 'Text';
.nFontSize — The desired font size
.nFontStyle — The style of the font (unknown format)
.strFontName — The name of the font to render the text with
.strText — A string containing the text

Publications

This work was published in Frontiers in Neuroinformatics: DR Muir and BM Kampa. 2014. FocusStack and StimServer: A new open source MATLAB toolchain for visual stimulation and analysis of two-photon calcium neuronal imaging data, Frontiers in Neuroinformatics. Please cite our publication in lieu of thanks, if you use this code.