by Ben-chin Cha (04/30/01)


The multiroi_pick program is an IDL widget application. It allows the user flexiblly to define multiple ROIs and generate reports through dynamically picking/unpicking elements from a 2D image array.

The free-hand drawing option of the multiroi_pick program calls the IDL provided DEFROI function to let the user define the rough region of interest. Then the user can use the modifying ROI option to refine the ROI by picking/unpicking the elements from the drawing area. It is possible that the single ROI may be composed by disjoint smaller regions from the drawing area.

It allows the user freely to add a new ROI or delete an existing ROI. For fine meshes it allows the user to add or delete elements from an selected ROI by zoom in the ROI and clicking the elements. Each selected elements is hashed and marked with a number indicates which ROI # it belongs to.

The ROI definition file can be easily created and loaded into multiroi_pick program, and the statistic report can be easily created and saved for the selected ROIs.

Command Syntax

Please refer User's Reference Guide for MULTIROI_PICK for command syntax.


Setup Requirement for Unix System

At APS all IDL programs are installed in the /usr/local/epics/extensions/bin/$HOST_ARCH directory. For proper operation of these programs, a user first has to make sure that the IDL 5.0 or later is used. For example, use IDL 5.2 release, set the following :
	source /usr/local/rsi/idl_5.2/bin/idl_setup 
In order to access IDL programs installed in the local epics/extensions/bin, a user has to make sure that the following two environment variables are set before invoking IDL :
         setenv EPICS_EXTENSIONS /usr/local/epics/extensions
and make sure the directory /usr/local/epics/extensions/bin/$HOST_ARCH is in his/her IDL search path.

Setup Requirement for W95 TIFF File

In order to get the TIFF file saved under W95 process the same color table as show in the original IDL drawing, the W95 window display must be set to use 256 colors instead of True color.

The W95 display must be properly set first before running IDL on W95. To set the display by use the W95 Start menu

	Start->Settings->Control Panel

Select the "Display Icon" to invoke the Display Properties dialog 
Select the  "Settings" Tablet, 
Set the "Color palette" to 256 Color
Press the "Apply" button,  and confirm it
Close the Display Properties dialog

Access MULTIROI_PICK Program

To access the MULTIROI_PICK program in IDL just enter the following command at the IDL prompt:
This commnad will automatically load the program into the IDL session . The variables IM specifies the 2D image array, Before calling the MULTIROI_PICK, the input variable 2D array IM must be defined first.


The multiple 2D statistic ROI dialog consists of three columns of widgets: Image Info Areas, ROIs control Options, and ROIs Report Controls. The 2D image array is drawn in a 300x300 pixel area with the maximum color effect and 'Ranbow+White' color table used. The selected elements are shaded with hash lines and marked with the ROI #.

Because the TV drawing region is only 300x300, for fine meshes of 2D image array, the ROI # for the selected region may be not readable due to the overlap of the numbers of densely selected elements in a small drawing area. Only for coarse 2D image array, the numbers of selected elements can be clearly readable.

Image Info Areas

The image info areas consists of a TV image drawing area, a scrollable message of mouse button instruction area. At the upper left corner of the TV area the appropriate operation mode of the TV is displayed. The program responds to the mouse clicking according to the operation mode which it falls into.

A user has to pay attention to both the scroll message text area and the TV message area in order to properly picking and unpicking the elements. Always remember to click the right mouse button to get out of the element picking mode or out of the reading cursor coordinate operation.

Image Drawing Area

The drawing area is 400x400 pixels wide. The image itself is drawn in 300x300 pixels with 50 pixels margin around the image. The image is plotted against the index number, such that the axis values reflect the index number for the image. The image is shown in maximum color scale effect. The default color table used is 'Ranbow + White'

Scroll Message Info Area

The scroll message info area gives the hint of the mouse button functions for defining of various multi-ROI modes. Steps of click mouse button depend on the option mode picked by the user. The user should follow the information provided in this area to properly define the corresponding ROI and terminate the TV mouse clicking operation.

Cursor Info Area

The upper left corner area is reserved for displaying the cursor position values or indicating which option mode selected by the user. Always use the RMB (right mouse button) to terminate the TV screen element picking or cursor value read mode.

If color image exposure problem or something else went wrong in the TV image area, always try to use the RMB (right mouse button) to get out of the TV screen element read mode.

ROIs Control Options

The middle column consists of ROIs definition control buttons area: Read ROIs, Save ROIs, Add/Delete ROI, List All ROIs, Modify ROI, Zoom Add/Delete, Query ROI, etc..

The ROI control consists of following contol buttons:

Help...     - Pop up the simple on-line help window
Read ROIs...- Call pickfile dialog to load old ROIs into program
Save ROIs...- Save current ROIs through pickfile dialog, default
                filename used 'roi.pick'
Tiff/Pgn/Pict- Save current ROIs to a corresponding output image file 
Color...    - Calls xloadct to change color table,default Ranbow+White
Refresh     - Refresh the TV image area (with no element hashed)
ShowAll ROIs- Redraw the TV ROIs area and generate ROI report and 
               	update scroll report text window (for all ROIs)
ROI# List   - Select ROI # desired and update the report text window
		(for selected ROI #)
Draw PolyROI- Draw polyROI by free hand drawing for newly added ROI #
		LMB : define polygon vertex node 
		MMB : clear last vertex node 
		RMB : close the polygon
Modify ROI  - Modify the selected ROI # 
		LMB : picking/unpicking the element
		RMB : terminate modification mode
Add ROI     - Increase ROI # by one, adds the ROI # to the list box,
                and fall into Modifying ROI mode
Del ROI     - Delete all the elements corresponding to the selected 
                ROI # from the ROI list
Zoom Add    - Use Zoom box to add elements to a ROI #
		LMB : picking new elements to be added
		RMB : terminate modification mode
Zoom Del    - Use Zoom box to delete elements from a ROI #
		LMB : picking old elements to be deleted
		RMB : terminate modification mode
Query Image - Display the image value of the mouse position 
                at the TV top left corner 
		RMB : terminate query image mode

ROIs Report Controls

The right column consists of rows of ROI report controls. The top row contains two fields: statistic offset value and character size used in marking the elements selected in TV drawing area. The scroll text area shows the statistic report area for selected ROIs. The third row contans the scroll text control buttons and a slider bar control the TV background color. The fourth row contans the output image specifications. The last row is 'Done' button.

Offset Val:    - Enter the offset value in statistic calculation
		   (default 0.)
Charsize:      - Enter the character size for ROI # marker of the selected
		   pixel elements (default 1)
Scroll Text    - Scroll text area for displaying ROI statistic report
Save As...     - Save the scroll text area content as an output report
		   file, filename must contain the substring '.rpt' 
Print          - Send the scroll text area content to the PS printer
Clear          - Clear the scroll text area
Slider         - Set background color to different value  
ROIs Tiff      - Droplist Tiff/Png/Pict to select the output image type, 
		   default saved as TIFF file
                   Display the output ROIs image filename, default
Done           - Closes the MULTIROI_PICK program

The output image file is automatically generated from the ROIs definition file. The default file for the ROIs file is ended with 'roi.pick' string. The image file will end with 'roi.pick.tiff' or 'roi.pick.png' or 'roi.pick.pict' respectively according the type set by the droplist.


The multiROI files are stored under the ROI sub-directory. If the ROI sub-directory is not found, it will be automatically created for user on the UNIX system, on W95 a user has to create it manually. The program tries to create the ROI sub-directory under the source data directory first, if the user has no write permission then it will try to create the ROI sub-directory where the program was invoked.

Three types of files can be saved by the multiroi_pick program: ROI definition file, output ROI image file, and ROI report file.

ROI Definition File

The multiROI definition file is created by the routines in the file. It just contains a single element array which contains the same element number as in the 2D image array. The value of each element indicates the ROI # it belongs to. Default is 0 for every element, i.e, no ROI defined yet. Any data element from the 2D image array can only belong to a single ROI # region.

The file name used for multiROI definition file should contain the sub-string 'roi.pick'. It is recommended that the file name should at least include the string of the original scan file name. It is possible to save many different 'roi.pick' files for a given scan file as long as they are uniquely identifiable by the user.

The multiroi_pick program checks whether the read in ROI definition file contains same number of elements as the 2D image array. If the elements of multiROI definition does not agree with the 2D image data array, the ROI # are reset to 0 for whole 2D image array.

ROI Output Image File

Three types of output image file can be saved by the multiroi_pick program: TIFF, PNG, and PICT. The file name is composed of the ROI definition file name and suffixed with '.tiff' or '.png' or '.pict' substring according to the droplist setting.

The TIFF file is target for various general image displaying tools.

The PNG file is the format readable by the W95 Paint Shop Pro raster image editing program.

The PICT file is target for image displaying program used on the MAC system.

ROI Report File

The multiROI report file is generated from the content in the scroll text area. The scroll text can be updated by the selection in ROI # list or by the 'ShowAll ROIs' button. The 'ShowAll ROIs' button generates the report for every ROIs defined for the image data. The ROI # selected from the list only displays the statistic report corresponding to the selected ROI #.

The file name used for multiROI report file should contain the sub-string 'rois.rpt'. It is recommended that the file name should at least include the string of the original scan file name. It is possible to save many different 'rois.rpt' files for a given scan file as long as they are uniquely identifiable by the user.

As long as the multiROI definition file is saved the report file can be easily regenerated.

The typical output for a multiROI report is given below:

Report generated at: Tue May  1 14:48:57 2001

MINIMUM:        0.494017  I=4  J=3
MAXIMUM:        0.890931  I=4  J=4
TOTAL:          7.51586
AVERAGE:        0.626322
VARIANCE:       0.0381918
DEVIATION:      0.195427
OFFSET:         0.00000
NELEM:          12
N           I           J  IM(I,J)-Offset
0           4           3     0.494017
1           5           3     0.494017
2           3           4     0.494017
3           4           4     0.890931
4           5           4     0.890931
5           6           4     0.494017
6           3           5     0.494017
7           4           5     0.890931
8           5           5     0.890931
9           6           5     0.494017
10           4           6     0.494017
11           5           6     0.494017