# ROIs

 This page or section is a WORK IN PROGRESS, and still unfinished!

In image processing, two of the most often needed yet complex operations are segmentation and registration. Regions of interest (ROIs) are an effective way of expressing and visualizing the results of a segmentation. For the current implementation of ROIs in ImageJ, see the imglib2-roi repository.

# Introduction

The base interface for all ROIs is MaskPredicate. MaskPredicate extends Java’s Predicate whose test(...) method is used to determine if a given point is inside or outside a ROI.

ROIs are further separated into discrete and continuous space ROIs, which can be bounded or unbounded. Mask is the base interface for all discrete space ROIs, and MaskInterval is the base interface for all bounded discrete space ROIs. Similarly, RealMask is the base interface for all continuous space ROIs, and RealMaskRealInterval is the base interface for all bounded continuous space ROIs.

Concrete implementations of geometric ROIs (i.e. ellipsoids, polylines, etc.) can be retrieve from GeomMasks. The below example creates a 3D sphere centered at (12.5, 6, 93.25) with a radius of 0.5.

final double[] center = new double[] { 12.5, 6, 93.25 };


## Naming

All n-dimensional geometric ROIs should be named with the name of their 3D counterpart. For example, an n-dimensional hyper-ellipsoid would just be named ‘ellipsoid’. If a ROI implementation is not n-dimensional, its dimensionality should be stated in the name. For example, Polygon2D which is a 2D polygon.

Additionally, ROIs prefixed with “Writable” are mutable. ROIs without this prefix are assumed to be immutable.

## BoundaryType

The boundary behavior of a ROI is given by its BoundaryType enum which has three values.

• CLOSED - all points on the boundary are considered inside
• OPEN - all points on the boundary are considered outside
• UNSPECIFIED - some points on the boundary may be inside while others are outside

## KnownConstant

The KnownConstant enum is used for determining if a ROI returns false for all locations, or true for all locations. This is useful for determining if the result of an operation between ROIs results in “empty” space or “all” space.

• ALL_FALSE - ROI is known to return false for all locations
• ALL_TRUE - ROI is known to return true for all locations
• UNKNOWN - it is undetermined what the ROI returns for all locations, most ROIs have this

# Combining ROIs

ROIs can be combined via a number of operations, namely: and, or, negate, minus, and xor. RealMasks also have a transform operation. Combined ROIs are CompositeMaskPredicates, which preserves the provenance of the composite ROI. For each CompositeMaskPredicate it is possible to retrieve the operator and operands. This results in a “tree” of ROIs.

The below example creates a composite ROI: <source lang=”java> final Sphere s1 = new ClosedWritableSphere( new double[] { 0, 0, 0 }, 3.5 ); final Sphere s2 = new ClosedWritableSphere( new double[] { 1, 2, 0 }, 1.5 ); final Sphere s3 = new ClosedWritableSphere( new double[] { 2, 2, 0 }, 1.5 ); final RealMaskRealInterval composite = s1.and( s2.minus( s3 ) ).and( s3 ).or( s1.minus( s3.negate() ) );

</source>

The resulting composite ROI has the resulting “tree”:

leaf  (net.imglib2.roi.geom.real.ClosedWritableSphere@a4)
|   |   +--leaf  (net.imglib2.roi.geom.real.ClosedWritableSphere@a4)
|   |       +--leaf  (net.imglib2.roi.geom.real.ClosedWritableSphere@7d)
|   |       +--leaf  (net.imglib2.roi.geom.real.ClosedWritableSphere@8a)
|   +--leaf  (net.imglib2.roi.geom.real.ClosedWritableSphere@8a)
+--leaf  (net.imglib2.roi.geom.real.ClosedWritableSphere@a4)
+--leaf  (net.imglib2.roi.geom.real.ClosedWritableSphere@8a)


Note that the same ROI can be used in multiple operations within the same composite.

## BoundaryType of Composites

The boundary behavior of a ROI may change as a result of the operation. The below outlines the composite BoundaryType logic, used when composite ROIs are formed.