ROI management

ROI management is integrated into DataViewer. A region of interest (ROI) is a named shape used to summarize pixels over space and time. Drawing and editing remain in memory until you save a .roi file.

Draw rectangles, ellipses, and polygons

1. Open the ROIs tab.
2. Choose Rectangle, Ellipse, or Polygon.
3. Drag a rectangle or ellipse. For a polygon, click successive vertices and double-click the final vertex.
4. Move or resize the active shape. Press N to rename it while drawing.
5. Double-click inside the ROI, or press Enter, to confirm. Press Escape or use the cancel item in its context menu to discard it.

An ROI remains editable until it is confirmed by double-clicking inside it or pressing Enter.

During drawing	After confirmation
An ellipse remains adjustable while its handles are visible.	After confirmation, the ellipse is added to the table and its trace is displayed.
Click successive vertices to shape a polygon.	The confirmed polygon appears as a named table row.

Threshold-based ROIs

Threshold analyzes the currently displayed frame. The left preview overlays pixels that pass the threshold; the centre preview separates connected candidate ROIs.

1. Enter a base name and choose above threshold or below threshold.
2. Set the value directly, drag the slider, or choose Auto set to start at the masked-image mean plus or minus two standard deviations.
3. Increase Min pixels to remove small regions. Remove holes keeps results compatible with the ROI model; optional smoothing removes narrow bridges and irregular borders.
4. Inspect the candidate count and both previews, then choose Create ROIs.

The threshold dialog previews the selected pixels and connected candidate ROIs before adding anything to the table.

Allen Atlas selection and placement

1. Search for an anatomical label or expand the Neocortex tree.
2. Check an area or module. Selecting a result synchronizes the map and tree.
3. Right-click a module in the Tree to choose Merge module or Unmerge module.
4. Choose OK. DataViewer opens a placement box and live preview over the current image. The estimated Bregma and Lambda positions are shown as a red and green dot, respectively, for placement aid only.
5. Move, resize, or adjust placement. Confirm to add the selected areas; cancel restores the previous ROI list.

The creator searches and selects regions; final placement occurs in DataViewer.

Placement preview	Confirmed atlas areas
Move and resize the placement box while comparing the outlines with the image.	Confirmation adds the selected atlas areas to the ROI table.

Scientific limitation
The atlas overlay is a user-positioned two-dimensional approximation. It does not estimate a transform, verify anatomical correspondence, or replace visual quality control. The positions of Bregma and Lambda are rough estimates: the Allen Mouse Brain Atlas does not provide mouse-skull landmark coordinates. See the Allen Brain Map Community Forum discussion.

ROI table and editing

Each ROI has one row. Visible shows or hides its image overlay and temporal trace. Select enters edit mode and marks the ROI for deletion or grouped operations. Double-click inside an edited ROI, or press Enter, to keep a geometry change; press Escape to restore the stored shape.

Click a Name cell to rename the ROI. Names are kept unique. Click the Color cell to open the color picker; the overlay, label, table cell, and temporal trace update together. The remaining columns report type, centroid, size, pixel count, and intensity statistics for the currently displayed frame. These intensity values are recalculated whenever the frame changes.

Select several rows to move or resize them as a group. Right-click the group to access Boolean operations:

Operation	Result
Merge	Combines all selected pixels.
Intersect	Keeps only pixels shared by all selected ROIs.
XOR	Keeps pixels belonging to an odd number of selected ROIs.
Subtract	Subtracts later-selected ROIs from the first-selected ROI; selection order matters.

An operation is blocked when it would produce holes that the current ROI model cannot represent. Deleting selected or all ROIs always asks for confirmation.

Logical mask interaction

A logical mask defines the part of the image included during ROI creation and related calculations. Pixels outside the active mask are dimmed in the image view.

1. Open the Utilities tab and choose Logical Mask to start a manual mask.
2. Draw a polygon around the image area to include. Right-click and choose Add mask polygon when the mask needs several separate regions; all confirmed polygons are combined.
3. Move the polygons or their handles to refine the boundary. Double-click a polygon, press Enter, or right-click and choose Confirm logical mask to apply it. Press Escape to cancel.
4. To start from an automatically estimated boundary, right-click Logical Mask and choose Create Automatic Mask. Refine the proposed polygons before confirming them.

An automatic draft is an editable starting point. Refine its polygons and confirm only when the included image area is correct.

How the automatic mask is calculated

DataViewer first calculates the average image across the frames in the active view. This means the calculation follows the data currently being displayed, including the selected event view or UMT entry when applicable. Pixels without a finite value are ignored.

The initial mask contains the brightest 10% of pixels in that average image. DataViewer then joins nearby bright fragments, fills enclosed holes, removes isolated regions smaller than 0.1% of the image area, and lightly removes narrow bridges or protrusions. These cleanup distances are scaled to the image dimensions rather than fixed to one pixel size.

Up to the six largest remaining connected regions are converted into editable polygons. The result is only a starting estimate: inspect, move, reshape, add, or remove polygons before confirming the mask. If no usable region is found, create the mask manually.

Confirmation applies the mask immediately and saves it in DataParams.mat. Existing ROIs are clipped to the included area; DataViewer reports the changes and asks before deleting any ROI that would become empty. Right-click Logical Mask and choose Clear Existing Mask to return to full-image inclusion.

Save, load, import, and export

Action	Details
Save	Writes a .roi file containing the shapes, names, colors, image context, and measurements.
Load	Replaces or appends. A size mismatch offers scaling or compatibility choices.
Import	Reads compatible ROI arrays from a selected file or MATLAB workspace variable, validates size, and rebuilds identifiers.
Export ROI data	Writes selected spatial measurements, continuous traces, or event-aligned traces to CSV.

See the tutorial Working with ROIs and Organization of .roi files.