Mask Making from ROIs

SRView
Synergy Research, Inc.
11 April 2005

Introduction

This page describes the SRView facilities for creating masks from image overlays (collections of ROIs). Masks are images, and any image can be used as a mask. The difference is primarily one of intent. Masks are intended to describe regions of other images which are to be masked. Normally, mask images are stored on disk as one byte per pixel, and the pixels are all either 0 or some specific positive value, corresponding to OFF and ON respectively.

This page describes mask creatation from overlays. It is also possible to create a blank mask and then manually paint the ON regions into it. That is explained in the SRView Quick Start chapter.

Making a Mask Using the Script

A special Tcl/Tk script called makeMask.tcl has been written to create mask images from overlays. This script can be invoked from the Scripts menu by selecting Mask make & apply. makeMask.tcl makes a mask image from active ROIs of the currently displayed image. It writes the mask image to disk, loads it into memory, and applies the mask to the displayed image. Use the following procedure to create a mask with makeMask:

Display the image and overlay for which you want to make a mask. If the overlay doesn't exist, draw the desired ROIs on the image (see "Creating an ROI" in the SRView Quick Start section of this manual).
Make the active label the label of the ROIs from which you want to make the mask.
Select Mask make & apply from the Scripts menu. If you are viewing a 4D image, the script will give you the option of making a 3D mask from ROIs from the current time point or a 4D mask using ROIs from all time points.

Within a few seconds the image should change as a result of application of the newly created mask. The default mask style is red transparency.

The mask image will have the same file name as the image from which it was made except "Msk" will be appended to the name just prior to any extensions introduced by a period. Similarly, the mask image will appear in the SRView Images menu with "Msk" appended to the end of the name.

The overlay file for the image must reside in the same directory as the image and have the same name but with a .paf extension. If there is no such file makeMask.tcl will create one before making the mask. If there are unsaved changes to the overlay when makeMask.tcl is called, makeMask.tcl will save those changes before making the mask; your original overlay file will be overwritten with an updated version of the overlay.

Masks are made utilizing only ROIs drawn in the three principal planes of the image: XY, XZ and YZ. ROIs drawn on oblique planes are ignored.

To control selection and application of mask images, follow the instructions provided in the Quick Start guide.

Mask making options

The makeMask script opens a dialog box for the user to control which ROIs are used to make the mask.

Enter 0 to make mask regions only from ROIs having the active label shown in the SRView window. To make a ROI label active, choose the ROI Edit tool and click on the desired ROI. Or go to the ROIs/Masks menu, select ROI Labels, then select a ROI label. The resulting mask will have the Mask On Value, set in the Edit - Settings dialog.

Enter 1 to make a mask from all ROIs. The resulting mask will have the Mask On Value, set in the Edit - Settings dialog.

Enter 2 to make a multi-level mask from all ROIs. The makeMask program will read the ROI labels from the overlay (.paf) file. The ROI labels will be assigned the values 1, 2, 3, ... as different labels are read. Then these values are put into the mask regions generated from the ROIs with the corresponding label. The list of ROI labels is saved in the mask's .hdr file.

makeMask Standalone Program

The makeMask.tcl script utilizes a standalone program from the SRIP package called makeMask. makeMask creates a mask image from an overlay. It takes three arguments from the command line and runs without any user interaction. Although it will normally be much easier to use the script, as previously described, you can run makeMask separately from a ordinary terminal window or invoke it from the command line in SRView's Tcl command window. We mention this option for completeness and because in some cases it may provide a needed additional measure of flexibility in the creation of masks.

makeMask usage

makeMask <image file name> <ROI Label> <timePos> <maskValue> <mask file name>

<image file name> - name of image file for which to make the mask.
<ROI Label> - label of the ROIs from which to make the mask. If <ROI Label> is "ALL" then all ROIs will be used regardless of label. If <ROI Label> is "MULTILEVEL", a multilevel mask is made -- see Mask making options above (Enter 2 ...).
<timePos> - time position of ROIs to use. If a negative number is given, then ROIs at all time points are used. If a positive number is given, then only ROIs at that time point will be used and the mask image will be created with only one time point. If timePos exceeds the maximum time position for this image, an error is returned.
<maskValue> - integer value, 1 to 255, to be used to represent ON pixels in the mask. OFF is always zero. Not used for multilevel mask.
<mask file name> - name of mask file to be created.
A scan analysis (.paf) file of the same name as the image file must be in the same directory as the image file. The ROIs contained in that scan analysis file are used to make the mask. The header of the image file is used to determine the header information for the new mask image. Only the image header is used; the image pixel data are not needed to make the mask, and therefore are not read.

makeMask returns

An image file containing the mask is written to the same directory as the input image file, and with the same name, except the mask file name has "Msk" appended to the base name of the image file. For example, the mask image made from the image file of name foobar.img, would be foobarMsk.img.
makeMask overwrites any existing file of the name used for the mask image.

Error messages are written to stderr.

makeMask invocation

At a terminal window command line simply follow the usage statement above.
At the command line of the Tcl command window in SRView, use the exec command to execute this standalone program:

exec makeMask <image file name> <ROI Label> <timePos> <maskValue> <mask file name>
Be sure you give the full path name to the image file, or change to that directory before invoking makeMask.