Previous IDL Reference Guide: Procedures and Functions Next

XROI

Syntax | Arguments | Keywords | Examples | Version History

The XROI procedure is a utility for interactively defining regions of interest (ROIs), and obtaining geometry and statistical data about these ROIs.

This routine is written in the IDL language. Its source code can be found in the file xroi.pro in the lib/utilities subdirectory of the IDL distribution.


Note
See Using XROI, for detailed information describing importing images, modifying image and ROI colors, retrieving ROI information and growing regions.

Syntax

XROI [, ImageData] [, R] [, G] [, B] [, /BLOCK] [[, /FLOATING] , GROUP=widget_ID] [, /MODAL] [, REGIONS_IN=value] [, REGIONS_OUT=value] [, REJECTED=variable] [, RENDERER={0 | 1}] [, ROI_COLOR=[r, g, b] or variable] [, ROI_GEOMETRY=variable] [, ROI_SELECT_COLOR=[r, g, b] or variable] [, STATISTICS=variable] [, TITLE=string] [, TOOLS=string/string array {valid values are 'Translate-Scale', 'Rectangle', 'Ellipse', 'Freehand Draw', 'Polygon Draw', and 'Selection'}] [, X_SCROLL_SIZE=value] [, Y_SCROLL_SIZE=value]

Arguments

ImageData

ImageData is both an input and output argument. It is an array representing an 8-bit or 24-bit image to be displayed. ImageData can be any of the following:

If ImageData is not supplied, the user will be prompted for a file via DIALOG_PICKFILE. On output, ImageData will be set to the current image data. (The current image data can be different than the input image data if the user imported an image via the File Import Image menu item.)

R, G, B

R, G, and B are arrays of bytes representing red, green, or blue color table values, respectively. R, G, and B are both input and output arguments. On input, these values are applied to the image if the image is 8-bit. To get the red, green, or blue color table values for the image on output from XROI, specify a named variable for the appropriate argument. (If the image is 24-bit, this argument will output a 256-element byte array containing the values given at input, or BINDGEN(256) if the argument was undefined on input.)

Keywords

BLOCK

Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER.


Note
Only the outermost call to XMANAGER can block. Therefore, to have XROI block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example.

FLOATING

Set this keyword, along with the GROUP keyword, to create a floating top-level base widget. If the windowing system provides Z-order control, floating base widgets appear above the base specified as their group leader. If the windowing system does not provide Z-order control, the FLOATING keyword has no effect.


Note
Floating widgets must have a group leader. Setting this keyword without also setting the GROUP keyword causes an error.

GROUP

Set this keyword to the widget ID of the widget that calls XROI. When this keyword is specified, the death of the caller results in the death of XROI.

MODAL

Set this keyword to block other IDL widgets from receiving events while XROI is active.

REGIONS_IN

Set this keyword to an array of IDLgrROI references. This allows you to open XROI with previously defined regions of interest (see Example: Save ROI Data). This is also useful when using a loop to open multiple images in XROI. By using the same named variable for both the REGIONS_IN and REGIONS_OUT keywords, you can reuse the same ROIs in multiple images (see Example: Preserving ROIs Among Images). This keyword also accepts –1, or OBJ_NEW() (Null object) to indicate that there are no ROIs to read in. This allows you to assign the result of a previous REGIONS_OUT to REGIONS_IN without worrying about the case where the previous REGIONS_OUT is undefined.

REGIONS_OUT

Set this keyword to a named variable that will contain an array of IDLgrROI references. This keyword is assigned the null object reference if there are no ROIs defined. By using the same named variable for both the REGIONS_IN and REGIONS_OUT keywords, you can reuse the same ROIs in multiple images (see Example: Preserving ROIs Among Images).


Note
This keyword must be used in conjunction with the BLOCK keyword.

REJECTED

Set this keyword to a named variable that will contain those REGIONS_IN that are not in REGIONS_OUT. The objects defined in the variable specified for REJECTED can be destroyed with a call to OBJ_DESTROY, allowing you to perform cleanup on objects that are not required (see Example: Preserving ROIs Among Images). This keyword is assigned the null object reference if no REGIONS_IN are rejected by the user.


Note
This keyword must be used in conjunction with the BLOCK keyword.

RENDERER

Set this keyword to an integer value to indicate which graphics renderer to use when drawing objects within the window. Valid values are:

ROI_COLOR

This keyword is both an input and an output parameter. Set this keyword to a
3-element byte array, [r, g, b], indicating the color of ROI outlines when they are not selected. This color will be used by XROI unless and until the color is changed by the user via the "Unselected Outline Color" portion of the "ROI Outline Colors" dialog (which is accessed by selecting Edit ROI Outline Colors). If this keyword is assigned a named variable, that variable will be set to the current [r, g, b] value at the time that XROI returns.

ROI_GEOMETRY

Set this keyword to a named variable that will contain an array of anonymous structures, one for each ROI that is valid when this routine returns. The structures will contain the following fields:

Table 3-145: Fields of the structure returned by ROI_GEOMETRY

Table 3-145: Fields of the structure returned by ROI_GEOMETRY
Field
Description
area
The area of the region of interest, in square pixels.
centroid
The coordinates (x, y, z) of the centroid of the region of interest, in pixels.
perimeter
The perimeter of the region of interest, in pixels.

If there are no valid regions of interest when this routine returns, ROI_GEOMETRY will be undefined.


Note
If there are no REGIONS_IN, XROI must either be modal or must block control flow in order for ROI_GEOMETRY to be defined upon exit from XROI. Otherwise, XROI will return before an ROI can be defined, and ROI_GEOMETRY will therefore be undefined.


Note
This keyword must be used in conjunction with the BLOCK keyword.

ROI_SELECT_COLOR

This keyword is both an input and an output parameter. Set this keyword to a
3-element byte array, [r, g, b], indicating the color of ROI outlines when they are selected. This color will be used by XROI unless and until the color is changed by the user via the "Selected Outline Color" portion of the "ROI Outline Colors" dialog (which is accessed by selecting Edit ROI Outline Colors). If this keyword is assigned a named variable, that variable will be set to the current [r, g, b] value at the time that XROI returns.

STATISTICS

Set this keyword to a named variable to receive an array of anonymous structures, one for each ROI that is valid when this routine returns. The structures will contain the following fields:

Table 3-146: Fields of the structure returned by STATISTICS

Table 3-146: Fields of the structure returned by STATISTICS
Field
Description
count
Number of pixels in region.
minimum
Minimum pixel value.
maximum
Maximum pixel value.
mean
Mean pixel value.
stddev
Standard deviation of pixel values.

If ImageData is 24-bit, or if there are no valid regions of interest when the routine exits, STATISTICS will be undefined.


Note
If there are no REGIONS_IN, XROI must either be modal or must block control flow in order for STATISTICS to be defined upon exit from XROI. Otherwise, XROI will return before an ROI can be defined, and STATISTICS will therefore be undefined.

TITLE

Set this keyword to a string to appear in the XROI title bar.

TOOLS

Set this keyword a string or vector of strings from the following list to indicate which ROI manipulation tools should be supported when XROI is run:

If more than one string is specified, a series of bitmap buttons will appear at the top of the XROI widget in the order specified (to the right of the fixed set of bitmap buttons used for saving regions, displaying region information, copying to clipboard, and flipping the image). If only one string is specified, no additional bitmap buttons will appear, and the manipulation mode is implied by the given string. If this keyword is not specified, bitmap buttons for all three manipulation tools are included on the XROI toolbar.

X_SCROLL_SIZE

Set this keyword to the width of the scroll window. If this keyword is larger than the image width then it will be set to the image width. The default is to use the image width or the screen width, whichever is smaller.

Y_SCROLL_SIZE

Set this keyword to the height of the scroll window. If this keyword is larger than the image height then it will be set to the image height. The default is to use the image height or the screen height, whichever is smaller.

Using XROI

XROI displays a top-level base with a menu, toolbar and draw widget. After defining an ROI, the ROI Information window appears, as shown in the following figure:

Figure 3-182: The XROI Utility

Figure 3-182: The XROI Utility

As you move the mouse over an image, the x and y pixel locations are shown in the status line on the bottom of the XROI window. For 8-bit images, the data value (z) is also shown. If an ROI is defined, the status line also indicates the mouse position relative to the ROI using the text "Inside", "Outside", "On Edge," or "On Vertex."

The XROI Toolbar

The XROI toolbar contains the following buttons:

Save:
Opens a file selection dialog for saving the currently defined ROIs to a save file.
Info:
Opens the ROI Information window.
Copy:
Copies the contents of the display area to the clipboard.
Flip:
Flips image vertically. Note that only the image is flipped; any ROIs that have been defined do not move.

Depending on the value of the TOOLS keyword, the XROI toolbar may also contain the following buttons:

Translate/ Scale:
Click this button to translate or scale ROIs. Mouse down inside the bounding box selects a region, mouse motion translates (repositions) the region. Mouse down on a scale handle of the bounding box enables scaling (stretching, enlarging and shrinking) of the region according to mouse motion. Mouse up finishes the translation or scaling.
Draw Rectangle:
Click this button to draw rectangular ROIs. Mouse down positions one corner of the rectangle, mouse motions creates the rectangle, positioning the rectangle's opposite corner, mouse up finishes the rectangular region.
Draw Ellipse:
Click this button to draw elliptical ROIs. Mouse down positions the center of the ellipse, mouse motion positions the corner of the ellipse's imaginary bounding box, mouse up finishes the elliptical region.
Draw Freehand:
Click this button to draw freehand ROIs. Mouse down begins a region, mouse motion adds vertices to the region (following the path of the mouse), mouse up finishes the region.
Draw Polygon:
Click this button to draw polygon ROIs. Mouse down begins a region, subsequent mouse clicks add vertices, double-click finishes the region.
Select:
Click this button to select an ROI region. Clicking the image causes a cross hairs symbol to be drawn at the nearest vertex of the selected ROI.

Importing an Image into XROI

To import an image into XROI, select File Import Image. This opens a DIALOG_READ_IMAGE dialog, which can be used to preview and select an image.

Changing the Image Color Table

To change the color table properties for the current image, select Edit Image Color Table. This opens the CW_PALETTE_EDITOR dialog, which is a compound widget used to edit color palettes. See CW_PALETTE_EDITOR for more information. This menu item is grayed out if the image does not have a color palette.

Changing the ROI Outline Colors

To change the outline colors for selected and unselected ROIs, select Edit ROI Outline Colors. This opens the ROI Outline Colors dialog, which consists of two CW_RGBSLIDER widgets for interactively adjusting the ROI outline colors. The left widget is used to define the color for the selected ROI, and the right widget is used to define the color of unselected ROIs. You can select the RGB, CMY, HSV, or HLS color system from the Color System drop-down list.

Viewing ROI Information

To view geometry and statistical data about the currently selected ROI, click the Info button or select Edit ROI Information. This opens the ROI Information dialog, which displays area, perimeter, number of pixels, minimum and maximum pixel values, mean, and standard deviation. Values for statistical information (minimum, maximum, mean, and standard deviation) appear as "N/A" for 24-bit images.

Viewing a Histogram Plot for an ROI

To view a histogram for an ROI, use either the shortcut menu or the ROI Information dialog.

To view an ROI's histogram plot using the shortcut menu:

  1. Position the cursor on the line defining the boundary of an ROI in the drawing window and click the right mouse button. This selects the region and brings up its shortcut menu.

    2.  

  2. Select the Plot Histogram menu option from the shortcut menu.

To view an ROI's histogram plot using the ROI Information dialog:

  1. Open the ROI Information dialog by clicking the Info button or selecting Edit ROI Information.

    2.  

  2. Select a region from the list and click the Histogram button on the ROI Information dialog.

Either of the previous methods opens an iTool showing the ROI's histogram that can be used to interactively control the plot properties.


Note
XROI's histogram plot feature now supports RGB images.

Growing an ROI

Once a region has been created, it may be used as a source ROI for region growing. Region growing is a process of generating one or more new ROIs based upon the image pixel values that fall within the source ROI and the values of the neighboring pixels. New pixels are added to the new grown region if those image pixel values fall within a specified threshold.


Note
This option is an interactive implementation of the REGION_GROW function.

To create a new, grown region, do the following:

  1. Within the draw area, click the right mouse button on the ROI that is to be grown. This will select the region and bring up its shortcut menu.

    2.  

  2. Select Grow Region By threshold or select Grow Region By std. dev. multiple from the shortcut menu to control how the region is grown.

    3.  

    The By threshold option grows the region to include all neighboring pixels that fall within a specified threshold range. By default, the range is defined by the minimum and maximum pixel values occurring within the original region. To specify a different threshold range, see Using the Region Grow Properties Dialog in the following section.

     

    The By std. dev. multiple option grows a region to include all neighboring pixels that fall within the range of:

     

    Mean +/- StdDevMultiplier * StdDev

     

    where Mean is the mean value of the pixel values within the source ROI, StdDevMultiplier is a multiplier that is set using the Region Grow Properties dialog (described below), and StdDev is the sample standard deviation of the pixel values within the original region.

Using the Region Grow Properties Dialog

The Region Grow Properties dialog allows you to view and edit the properties associated with a region growing process. To bring up the Region Grow Properties dialog, do one of the following:

This brings up the Region Grow Properties dialog, shown in the following figure.

 

Figure 3-183: XROI's Region Grow Properties Dialog

Figure 3-183: XROI's Region Grow Properties Dialog

The Region Grow Properties dialog offers the following options:

Table 3-147: Options of the Region Grow Properties Dialog 

Table 3-147: Options of the Region Grow Properties Dialog 
Option
Description
Pixel search method:
Describes which pixels are searched when growing the original ROI. The option are:
  • 4-neighbor — Searches only the four neighboring pixels that share a common edge with the current pixel. This is the default.

    •  

  • 8-neighbor — Searches all eight neighboring pixels, including those that are located diagonally relative to the original pixel and share a common corner.
Threshold range:
Represents the minimum and maximum image pixel values that are to be included in the grown region when using the Grow Region By threshold option (described in Growing an ROI). By default, the range of pixel values used are those occurring in the ROI to be grown.
To change the threshold values, uncheck Use source ROI threshold and enter the minimum and maximum threshold values in the Min: and Max: fields provided.
Standard deviation multiplier:
Represents the factor by which the sample standard deviation of the original ROI's pixel values is multiplied. This factor only applies when the Grow Region By std. dev. multiple option (described in Growing an ROI) is used.
Change the multiplier value by typing the value into the Standard deviation multiplier field provided.
For RGB image, use:
Determines the basis of region growing for an RGB (rather than indexed) image. The image data values used when growing a RGB region can be one of the following:
  • Luminosity — Uses the luminosity values associated with an RGB image. This is the default method. Luminosity is computed as:

    •  

    Luminosity = (0.3 * Red) + (0.59 * Green) + (0.11 * Blue)

     

  • Red Channel, Green Channel or Blue Channel — Uses the ROI's red, green or blue channel as a basis for region growing. Click the channel's associated button to specify the channel to be used.
Note - For indexed images, the image data itself is always used for region growing.
Acceptance criteria:
Determines which contours of the grown region are accepted as new regions, (which will also be displayed in the draw area and in the ROI Information dialog list of regions). The region growing process can result in a large number of contours, some of which may be considered insignificant. By default, no more than two regions (those with the greatest geometrical area) are accepted. Modify the acceptance criteria by altering the following values:
  • Maximum number of regions: — Specifies the upper limit of the number of regions to create when growing an ROI.

    •  

  • Minimum area per region: — Specifies that only contours having a geometric area (computed in device coordinates) of at least the value stated are accepted and displayed.

    •  

  • Accept all regions: — Select this option to accept all generated contours, regardless of count or area.

Deleting an ROI

An ROI can be deleted using either the shortcut menu or using the ROI Information dialog.

To delete an ROI using the shortcut menu:

  1. Click the right mouse button on the line defining the boundary of the ROI in the drawing area that you wish to delete. This selects the region and bring up the shortcut menu.

    2.  

  2. Select the Delete menu option from the shortcut menu.

To delete an ROI using the ROI Information dialog:

  1. Click the Info button or select Edit ROI Information. This opens the ROI Information dialog.

    2.  

  2. In the ROI Information dialog, select the ROI you wish to delete from the list of ROIs. You can also select an ROI by clicking the Select button on the XROI toolbar, then clicking on an ROI on the image.

    3.  

  3. Click the Delete ROI button.

Examples

See the following examples:

Example: Open Image File in XROI

This example opens a single image in XROI: 

image = READ_PNG(FILEPATH('mineral.png', $  
   SUBDIR=['examples', 'data']))  
XROI, image

Example: Preserving ROIs Among Images

This example reads 3 images from the file mr_abdomen.dcm, and calls XROI for each image. A single list of regions is maintained, saving the user from having to redefine regions on each image: 

PRO docs_xroi_maintain_rois  
  
; Read 3 images from mr_abdomen.dcm and open each one in XROI:  
FOR i=0,2 DO BEGIN  
   image = READ_DICOM(FILEPATH('mr_abdomen.dcm',$  
      SUBDIR=['examples', 'data']), IMAGE_INDEX=i)  
   XROI, image, r, g, b, REGIONS_IN = regions, $  
      REGIONS_OUT = regions, $  
      ROI_SELECT_COLOR = roi_select_color, $  
      ROI_COLOR = roi_color, REJECTED = rejected, /BLOCK  
   OBJ_DESTROY, rejected  
ENDFOR  
  
OBJ_DESTROY, regions  
  
END

Perform the following steps:

  1. Run the example code and draw an ROI on the first image, then close that XROI window. Note that the next image contains the ROI defined in the first image. This is accomplished by setting REGIONS_IN and REGIONS_OUT to the same named variable in the FOR loop of the above code.

    2.  

  2. Draw another ROI on the second image.

    3.  

  3. Click the Select button and select the first ROI. Then click the Info button to open the ROI Information window, and click the Delete ROI button.

    4.  

  4. Close the second XROI window. Note that the third image contains the ROI defined in the second image, but not the ROI deleted on the second image. This example sets the REJECTED keyword to a named variable, and calls OBJ_DESTROY on that variable. Use of the REJECTED keyword is not necessary to prevent deleted ROIs from appearing on subsequent images, but allows you perform cleanup on objects that are no longer required.

Example: Save ROI Data

XROI's File Save ROIs option allows you to save selected regions of interest. This example shows how to restore such a save file. Suppose you have a file named mineralRoi.sav that contains regions of interest selected in the mineral.png image file. You would need to complete the following steps to restore the file:

  1. First, restore the file, mineralRoi.sav. Provide a value for the RESTORE procedure's RESTORED_OBJECTS keyword. Using the scenario stated above, you could enter the following:
    2. RESTORE, 'mineralRoi.sav', RESTORED_OBJECTS = myRoi

     

  2. Pass the restored object data containing your regions of interest into XROI by specifying myRoi as the value for REGIONS_IN as follows:
    3. XROI, READ_PNG(FILEPATH('mineral.png', SUBDIRECTORY = $  
    ['examples', 'data'])), REGIONS_IN = myRoi

     

    This opens the previously selected regions of interest in the XROI utility.

Example: Save the XROI Utility with ROI Data

You can easily share your own IDL routines or utilities with other IDL users by using the SAVE routine to create a binary file of your compiled code. The following example creates a SAVE file of the XROI utility (a .pro file) and from within this file, restores a secondary SAVE file containing selected regions of interest.

  1. Type XROI at the command line to open the XROI utility.

    2.  

  2. In the file selection dialog, select mineral.png from the examples/data subdirectory of the IDL distribution.

    3.  

  3. Select the Draw Polygon toolbar button and roughly outline the three large, angular areas of the image.

    4.  

  4. Select File Save ROIs and name the file mineralROI.sav. This creates a SAVE file containing the regions of interest selected within the image.

    5.  

  5. In the IDL Editor or any text editor, enter the following routine:
    6. PRO myXRoi  
  
; Restore ROI object data by specifying a value for the 
; RESTORED_OBJECTS keyword.  
RESTORE, 'mineralROI.sav', RESTORED_OBJECTS = myROI  
  
; Open XROI, specifying the previously defined value for the
; restored object data as the value for "REGIONS_IN".  
XROI, READ_PNG(FILEPATH('mineral.png', $  
   SUBDIRECTORY = ['examples', 'data'])), $  
   REGIONS_IN = myROI, /BLOCK  
  
END

     

    Save the routine as myXRoi.pro

     

  6. Exit and restart IDL or enter .FULL_RESET_SESSION at the IDL command line before creating a SAVE file to avoid saving unwanted session information.

    7.  

  7. Compile the program you just created:
    8. .COMPILE myXRoi.pro

     

  8. Use RESOLVE_ALL to iteratively compile any uncompiled user-written or library procedures or functions that are called in any already-compiled procedure or function:
    9. RESOLVE_ALL

     


    Note
    RESOLVE_ALL does not resolve procedures or functions that are called via quoted strings such as CALL_PROCEDURE, CALL_FUNCTION, or EXECUTE, or in keywords that can contain procedure names such as TICKFORMAT or EVENT_PRO. You must manually compile these routines.

     

  9. Create a SAVE file named myXRoi.sav, containing all of the XROI utility routines. When the SAVE procedure is called with the ROUTINES keyword and no arguments, it creates a SAVE file containing all currently compiled routines. Because the routines associated with the XROI utility are the only ones that are currently compiled in our IDL session, we can create a SAVE file as follows:
    10. SAVE, /ROUTINES, FILENAME='myXRoi.sav'

     

  10. It is not necessary to use RESTORE to open myXRoi.sav. If the SAVE file uses the .sav extension and has the same base name as the main level routine, and all necessary files (in this case, mineralROI.sav and myXRoi.sav) are stored in the current working directory, simply type the name of the file, minus the .sav extension, at the command line:
    11. myXRoi

The following figure will appear, showing the selected regions of interest.

 

Figure 3-184: Example of Restoring the XROI Utility and ROI Image Data

Figure 3-184: Example of Restoring the XROI Utility and ROI Image Data

Version History

5.4
Introduced
5.6
Added X_SCROLL_SIZE and Y_SCROLL_SIZE keywords

See Also

CW_DEFROI, DEFROI, IIMAGE

  IDL Online Help (March 06, 2007)