SCAN2D ROI Program [TOC]

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


SCAN2D_ROI Statistic Program provides the IDL user with a flexible widget application package for defining region of interest for any 2D image.

It supports three types of ROI: rectangle, polygon, and pixel value range filter. Based on user selected type of ROI, it allows the user dynamically define and save the new ROI. It provides flexible ROI statistics calculation and report generations.

Command Syntax

Please refer User's Reference Guide for Scan2D_ROI 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.

Access SCAN2D_ROI Program

To access the SCAN2D_ROI program in IDL just enter the following command at the IDL prompt:
	IDL>SCAN2D_ROI, IM ,X ,Y [,HEADER=header] [,COMMENT=comment]
This commnad will automatically load the program into the IDL session . The variables IM specifies the 2D image array, and X, and Y specifies the corresponding X and Y vectors. The string variable header specifeds the description info about the IM. The string variable comment specifies any additional info about the IM. Before calling the SCAN2D_ROI, referal variables must be defined first.


The 2D statistic ROI dialog consists of two columns. The left column consists of an image drawing area, a scrollable message information area, and a TV cursor value display area. The right column consists of rows of ROI Control areas. The top row contains buttons to control the ROI program options. Followed with three regions of buttons and fields: ROI Type Control Area, ROI Statistics Fields Area, and ROI Report Fields and Buttons Area.

Image Info Areas

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.

Scroll Message Info Area

The scroll message info area gives the hint of the mouse button functions for definition of RectROI or PolyROI mode. Steps of click mouse button depends on the ROI mode. The user should follow the info provided in this area to properly define the corresponding ROI.

Cursor Value Area

This area displays the cursor position values. Click the MMB (middle mouse button) to get the new cursor position, then the new index number I,J and the corresponding value are displayed here. Three mouse buttons is assumed.

ROI Control Options

The program control consists of four options: ROI Mode, MultiROIs..., Help..., Color..., and Done buttons.
ROI Mode:   - Selects the desired type of ROI model and
              updating the message infomation area.
MultiROIs...- Runs the MULTIROI_PICK program.
HELP...     - Pops up the simple on-line help window.
Color...    - Runs the XLOADCT to select/load the desired color table.
Done        - Closes the 2D statistic ROI program.

ROI Type Control Area

ROI Type Control Area contains three rows of ROI control : Rectangle ROI, Filter ROI, and Polygon ROI. Only one row is active at a time depending on the type of ROI Mode been selected. Please refer the message information area for mouse operation in defining ROI. The LMB, MMB, RMB represents left, middle, and right mouse button respectively.

The ROI saved by the 'Filter ROI' mode can directly be loaded into Multiroi_pick program. The filename used by filter mode is ended with '_roi.pickfltr' suffix.

Rectangle ROI:    (Please refer message info area)
	SaveRectROI  -  Save new rectangle ROI in ROIFile 
			(file name with '_roi.xdr' suffix)
                        Re-calculate the ROI statistics
	Refresh      -  Refresh the drawing area and re-calculate the
                        ROI statistics based on the whole image area
	ReadRectROI  -  Read rectanglar ROI from the defenition file
                        Re-calculate the ROI statistics

Filter ROI:       (Please refer message info area)
	SaveFltr     -  Save ROI defined by the range of low and high filters
			(file name with '_roi.pickfltr' suffix)
	ReadFltr     -  Read ROI defined by the range of low and high filters
			from the saved file
	Low:         -  Field indicates the low filter value
                        Re-calculate the ROI statistics
	Slider       -  Sets the low filter value
                        Re-calculate the ROI statistics
	High:        -  Field indicates the high filter value
                        Re-calculate the ROI statistics
	Slider       -  Sets the high filter value
                        Re-calculate the ROI statistics

Polygon ROI:      (Please refer message info area)
	DefPolyROI&Save  - Define polygon vertices by clicking the LMB and 
			   close the ROI by clicking the RMB
                           Save polygon ROI in file end with the 
			   '_roi.xdr.poly' suffix
                           Re-calculate the ROI statistics
	ReadPolyROI      - Read polygon ROI from saved file
                           Re-calculate the ROI statistics

ROI Statistics Fields Area

ROI Statistics Fields Area contains the ROI statistics value fields which reflects the calculated results corresponding to the selected ROI defined.
Data:IM  [n x m], Total= ...   - default image dim and total
ROI:IM[n1:n2,m1:m2], Nelem=...,  total=...  
                               - ROI ranges, Nelem and total
ROI Ave:                       - ROI average value
ROI Dev:                       - ROI standard deviation value
ROI Min:                       - ROI minimum value
    @x                         - X for ROI minimum 
    @y                         - Y for ROI minimum 
  vs Index#/Values             - @ X / Y as Index#/Values
ROI Max:                       - ROI maximum value
    @x                         - X for ROI maximum 
    @y                         - Y for ROI maximum 
Comment:                       - Optional comment field for ROI 

ROI Report Fields and Buttons Area

Default ROIFile for rectangle ROI is tmproi.xdr. Default ROIFile for polygon ROI is tmproi.xdr.poly. Default file name used for report file is tmproi.rpt.

ROI Report Fields and Buttons Area contains the buttons and fields used to specify the filename of ROIFile and ROIRpt used.

ROIFile        -  Select/Enter ROI definition File
ROIRpt         -  Select/Enter ROI report File 
RenameRpt...   -  Rename current ROI report file
AppendRpt...   -  Append ROI statistic report to current ROIRpt file
ViewRpt...     -  View ROI report file by using file selection dialog 


Two types of file can be generated by the 2D statistic ROI program: ROI Definition Files and ROI Report Files. A subdirectory ROI will be created under the current working directory for UNIX system. For PC system the user has to create the directory first before running this program. All the file created by this program will be stored under the ROI subdiretory.

The root file name 'tmp' mentioned in following sections can be replaced by any scanSee filename created by the IOC.

ROI Defenition File

The default ROI defenition file generated will be suffixed with _roi.xdr for rectangle ROI, _roi.pickfltr for filter ROI, and _roi.xdr.poly for polygon ROI. Different scan image may have different ROI or more than one ROI files defined. A user should adopt a naming convention such that ROIFile can be easily identified with the case study with different image number and scan number.
Tmp_roi.xdr contains a single vector.
Rectangular bounding box region is defined by a vector of 6 numbers.
It is defined as below for a rectangle ROI:

	x[0]    - left bound pixel value
	x[1]    - right bound pixel value
	x[2]    - bottom bound pixel value
	x[3]    - top bound pixel value
	x[4]    - 300/width
	x[5]    - 300/height
		width  - X dim of image data
		height - Y dim of image data

tmp_roi.pickfltr contains three objects.
The first array is dimensioned the same as the image array. 
The second number is the lower bound of the filter value.
The third number is the upper bound of the filter value.

	bine[N,M]  - a binary image element array
			0  value falls outside the filter range
			1  value falls inside the filter range
	lower_b    - lower bound of filter range
	upper_b    - upper bound of filter range

Tmp_roi.xdr.poly contains two vectors.
Polygonal region is defined by two vectors: xverts, and yverts. The 
number of elements of the vector depends on the sides of polygon.

	xverts  -  X pixel values of polygon vertices
	yverts  -  Y pixel values of polygon vertices

Vector in ROIFile is stored in XDR format and is created by calling the rountines defined in xdr_open program. TV image is drawn in a 300x300 pixel area.

ROI Report File

Two types of ROI report can be generated: summary report for all detectors or detailed report for the selected detector only. The detailed report includes the list of all elements of the selected detecor ROI.

Many ROI reports can be aggregated in one single file. Each 2D statistic report contains the time stamp, optional header and comment specifications, the variables describing the ROI defenition, and the statistic summary. The time stamp indicates the time and day the report was generated. The header echoes the header keyword specified on the command line about the image. The comment field entered in ROI program overrides the comment keyword specified on the command line.

The default ROI report file used will be tmp_roi.rpt. A user can override the default ROI report file through using the file selection dialog. A typical detailed ROI report content is given below, for the selected detector ROI, it includes the summary statistic report plus the list of elements included in the ROI.

Generated at:  Mon Apr 30 12:44:48 2001
Header:  /home/beams/CHA/data/xxx/cha:_0002.scan
 Image Seq # 5,  2D Scan # 2,  Detector # 5  (D5)
ROI: Rectangle region defined in 
ROI in index: [3:6, 3:6] 
ROI in values: [-1.00000:1.00000, -1.00000:1.00000] 

ave =      0.508727
dev =      0.268809
min =      0.155944
max =      0.890931
total =       8.13964
nelem =           16

            N         I            J    IM(I,J)    IM(I,J)-ave   ROI
           0           3           3     0.155944    -0.352784    RECT
            1           4           3     0.494017   -0.0147103    RECT
            2           5           3     0.494017   -0.0147103    RECT
            3           6           3     0.155944    -0.352784    RECT
            4           3           4     0.494017   -0.0147103    RECT
            5           4           4     0.890931     0.382204    RECT
            6           5           4     0.890931     0.382204    RECT
            7           6           4     0.494017   -0.0147103    RECT
            8           3           5     0.494017   -0.0147103    RECT
            9           4           5     0.890931     0.382204    RECT
           10           5           5     0.890931     0.382204    RECT
           11           6           5     0.494017   -0.0147103    RECT
           12           3           6     0.155944    -0.352784    RECT
           13           4           6     0.494017   -0.0147103    RECT
           14           5           6     0.494017   -0.0147103    RECT
           15           6           6     0.155944    -0.352784    RECT
Generated at:  Mon Apr 30 12:54:35 2001
Header:  /home/beams/CHA/data/xxx/cha:_0002.scan
 Image Seq # 5,  2D Scan # 2,  Detector # 5  (D5)
ROI: Polygon region defined in 
Xverts index:       5       3       5       7
Yverts index:       7       5       3       5
ave =      0.626322
dev =      0.195427
min =      0.494017
max =      0.890931
total =       7.51586
nelem =           12

            N         I            J    IM(I,J)    IM(I,J)-ave   ROI
           0           4           3     0.494017    -0.132305    POLY
            1           5           3     0.494017    -0.132305    POLY
            2           3           4     0.494017    -0.132305    POLY
            3           4           4     0.890931     0.264610    POLY
            4           5           4     0.890931     0.264610    POLY
            5           6           4     0.494017    -0.132305    POLY
            6           3           5     0.494017    -0.132305    POLY
            7           4           5     0.890931     0.264610    POLY
            8           5           5     0.890931     0.264610    POLY
            9           6           5     0.494017    -0.132305    POLY
           10           4           6     0.494017    -0.132305    POLY
           11           5           6     0.494017    -0.132305    POLY