IMAGE2D Program [TOC]

User's Guide For IMAGE2D (image2d.pro)

by Ben-chin Cha (10/10/02)

INTRODUCTION

IMAGE2D is a mouse driven widget application program. It provides the IDL user with a general purpose image viewing program for processing a set of 2D images. It accepts the variable image_array on the IDL command line, where the image_array(Width,Height,Num) is a collection of 2D images with "Width x Height" size and "Num" representing the number of images defined in the variable.

It provides simple and easy methods of viewing and examining the selected 2D image data, obtaining various 2D/1D plots, exporting image in various output format, trying different color tables, etc. It also provides eazy access of few simple analysis tools: fitting, statistics calculation, image calibrations, 2D-ROI (region of interest) analysis.

Multiple copies of image2d program can be run simultaneously. There is no limitation of the image_array size as long as user's computer memory allows it.

Command Syntax

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

SYSTEM SETUP

Setup Requirement for Unix System

For proper operation of these IDL programs, a user first has to make sure that the IDL 5.3 or later is used. For example, use IDL 5.5 release, set the following : 
 
	source /usr/local/rsi/idl_5.5/bin/idl_setup
For EPICS R3.13 releases all the UNIX scripts and IDL programs are installed in the /usr/local/epics/extensions/bin/solaris directory.

Starting from EPICS R3.14 releases all the IDL programs will be installed in the /usr/local/epics/extensions/idllib directory, and only the UNIX scripts will be installed in the /usr/local/epics/extensions/bin/solaris-sparc directory.

For EPICS R3.13.X Releases
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
         setenv IDL_STARTUP $EPICS_EXTENSIONS/bin/$HOST_ARCH/viewer_startup.pro
and make sure the directory /usr/local/epics/extensions/bin/$HOST_ARCH is in his/her search path. Where HOST_ARCH is set to "solaris". The IDL_STARTUP will make sure the directory /usr/local/epics/extensions/bin/solaris is in his/her IDL search path.
For EPICS R3.14.X Releases
In order to access IDL programs installed in the local epics/extensions/idllib, a user has to make sure that the following two environment variables are set before invoking IDL : 

         setenv EPICS_EXTENSIONS /usr/local/epics/extensions
         setenv IDL_STARTUP $EPICS_EXTENSIONS/idllib/viewer_startup.pro
The directory /usr/local/epics/extensions/bin/$HOST_ARCH must be in his/her UNIX search path. Where HOST_ARCH is set to "solaris-sparc". The IDL_STARTUP will make sure the directory /usr/local/epics/extensions/idllib is in his/her IDL search path.

Access IMAGE2D Program

To access the IMAGE2D program from the IDL prompt within the idl session just enter the following command at the IDL prompt: 
	IDL> .run PS_open  
	IDL> .run image2d 
	IDL> image2d,image_array,xarr,yarr [,Group=group,....]  
where 
	image_array(Width,Height,Num) - image array
	Width           -   width of 2D image
	Height          -   height of 2D image
	Num             -   number of 2D images in image_array
	xarr(Width)     -   X position vector
	yarr(Height)    -   Y position vector

USER INTERFACE

The main window consists of the drawing area and various widget controls. They provide flexible control and plot generation in viewing the image data. The user interface is briefly described below:

PullDown Menus

File Menu
The file menu provides methods of exporting the image data for other image processors or generating PS output. 
	Save Image for AIM - save current image data in AIM format 
	Save as TIFF	  - save drawing area as TIFF file 
	Save as R-TIFF	  - save drawing area as reverse TIFF file 
	Save as XDR	  - save current image data as XDR file 
	Printer...	  - dialog to override default printer
	Print 		  - send drawing area content to the PS printer
	Quit		  - exit the image2d program
Color Menu
This menu allows the user to save or load private color table used for display the image data. In order to get the most color contrast effect, the value of image data is linearly scaled with color table used in image2d. The default color table used is the rainbow color with white, where the maximum value is drawn in white color. 
	Save Private Color Table - save current color table as private 
	Load Private Color Table - load private color table into image2d
	Image Color Scheme...    - dialog for user adjustable 
				   color scheme
	Change Color Table...    - dialog for trying various IDL 
				   color tables
The "Change Color Table..." let the user try various IDL color tables. The "Save Private Color Table" can be used to save the preferred color table, the "Load Private Color Table" override the default color table by the preferred one.

To reach user desirable effect, the "Image Color Scheme..." dialog allows the user to access the user scalable Zmin and Zmax or normalized against another image, etc.

Help Menu
	Help...    - gives help info page

Drawing Area Controls

View as Droplist
This "View as" droplist menu let the user set the image display mode. The default is displaying the image data as a scaled TV image. 
	TV               - display 2D data as scaled TV iamge
	Eq.TV.AspRt      - display 2D data with equal X,Y axis aspect ratio
	LIGHT_SHADE_SURF - display 2D data as light shade surface plot
	CONTOUR          - display 2D data as equal contour line plot
	SHOW3            - show data as image, surface, and equal contour plot
	PLOT2D...        - use PLOT2D program to display 2D image data
	SHADE_SURF       - display 2D data as shade surface plot
Pixel Scaling Menu
The "Pixel" scaling droplist menu provides two displaying mode: "By Image" or "By User". The "By Image" will display the raw image data at the lower left corner in the drawing area without any scaling. The "By User" option will scale and resize the image data to occupy a 300x300 drawing area. The coordinate system and data information are also drawn with the image. The default option is set to "By User". 
	By Image - display actual 2D data image without scaling
	By User  - pixel automatically re-sized by user data (default)
Plot vs Menu
The X, Y coordinates can be drawn as real number or index number. The default is plotted as real values. 
	Step #           - step # used in X, Y axis plot
	Values           - real values used in X, Y axis plot (default)
A user can use the "Step #" to verify the X,Y dimensions of the actual image_array.
ASCII Report Control
The "ASCII..." button generates the text file from the 2D image data and display the text file by a scrollable text window. The "Format" field let the user control the number of significant digits used in the column in report. The default format used is G17.7. 
	ASCII...         - pops up termial window display ascii image data
	Format           - text field controls the output ascii data format
Image Selections
The drawing area can only display one image at a time, there are two scroll list widgets allows the user to select the desired image from the input image_array. 
	ReNew            - Refresh TV image as re-selected the same 2D image
	D01...D70        - Detector D01-D70 selection list
	D1...DF  	 - Detector D1-DF selection list
The "ReNew" button re-draw the image with default auto-scaled color scheme. The "D1...DF" scroll list let the user select from the first 15 images from the image_array. The "D01...D70" scroll list let the user select from the remaining image_array.
Mouse Button Events
Three types of mouse event can be handled by image2d. The "Left Mouse Button" event reads the X,Y,Z values at the mouse cursor position and updates the corresponding X,Y,Z display fields. The "Middle Mouse Button" event pops up two XZ, YZ profile 1D plots at the mouse cursor. If line is not displayed initially, try press the "Rvs Bkg" button in the PLOT1D window. 
	Left Mouse Button   - button 1 (LMB) updates cursor X,Y,Z field values
	Middle Mouse Button - button 2 (MMB) pops up profile lines at the cursor position
	Right Mouse Button  - button 3 (RMB) starts/terminates zoomin box mode

	Zoomin Box Mode Operation:
	Click the RMB to start the zoomin box mode, 
	hold down LMB to drag/move the zoomin box, 
	hold down MMB to drag/resize the zoomin box, 
	Click the RMB to terminate the zoomin box,
The end of zoomin box mode will update the drawing area and update XL,XR, YL,YR value fields with the zoomin box coordinates.

The "ReNew" button will redraw the drawing area with default setting and updates XL,XR, YL,YR fields with the initial start and end X,Y value ranges. The query mouse cursor event (LMB) works only when zoomin is not in effect.

Xmin,Xmax,Ymin,Ymax,Zmin,Zmax Fields
The region of image displayed is controlled by the Xmin, Xmax, Ymin, Ymax index fields. The default is the whole image range. 
	Xmin - image starting X index, default 0
	Xmax - image ending X index, default width-1
	Ymin - image starting Y index, default 0
	Ymax - image ending Y index, default height-1
	Zmin - image display minimum Z value 
	Zmax - image display maximum Z value
The Zmin and Zmax gives the corresponding minimum and maximum image value. The pixels below the Zmin will be drawn in black, the pixels above the Zmax will be drawn in white (with the default color table used).

The Zmin and Zman can be changed by the user only when image2d is in the Color->Image Color Scheme...->UserScaled mode.

Image Info Widgets

Min,Max,Cursor X,Y,Z Fields
There are two text label fields to show the minimum and maximum value at the corresponding (I,J) index number for the displayed image data. They are followed with X, Y cursor position text fields and a Z cursor position value. They will reflect the current cursor (mouse click) position and image values. 
	MIN: ... @ (Imin,Jmin)   - minimum value at (I,J)
	MAX: ... @ (Imax,Jmax)   - maximum value at (I,J)
	Cursor @ X 		 - X value at cursor
	Cursor @ Y               - Y value at cursor
	Z:  ....       		 - Z image value at cursor
Please be aware of that the round off error +/-1 may occur in the determination of the cursor index positions.
XL,XR,YL,YR Fields
The start and end position of the X, Y values of image data are initially displayed in XL,XR,YL,YR text fields. This fields can be used to enter the new 2D scan start and end positions as long as the scan1 and scan2 PV name are properly connected. 
	XL - start position of X 
	XR - end position of X 
	YL - start position of Y
	YR - end position of Y
These fields are automatically updated at the end of each zoomin operation. These fields are automatically reset to initial values by the "ReNew" button. These fields also accept any real value entered by the user.
Set New Scan Ranges
The "Set New 2D Scan Ranges" button will accept values in XL,XR,YL,YR text fields and invokes the CA client caput to set the new 2D scan start and end positions for next 2D scan. 
	Set New 2D Scan Ranges -  to set the new 2D scan ranges with XL,XR,YL,YR
The result of the caput will be displayed by the message dialog. The '.P1SP', '.P1EP' for the scan1 and scan2 record will be set by this button.
Info Text Area
At the bottom of main window there is a "Info Text Area". It reveals the following image summary information: 
	Image Filename  - shows where image_array data coming from
	# of Images     - gives the total number of images in image_array
	DETECTOR 	- reflects current image ID name
	(...,...,...)   - gives the plot xtitle,ytitle,title if known
	2D SCAN # 	- gives 2D scan number if known
	1D scan # (.,.) - gives Y index range
	width	        - gives image width dimension
	height	        - gives image height dimension
	x_pv	        - gives scan1 record name if known
	y_pv	        - gives scan2 record name if known

Analysis Tools

PanImages Menu
The "PanImages" menu provides two options: "Calibration..." and "PanImages...". 
	Calibration...   - pops up calibration program
	PanImages...     - pops up PanImage program
The "Calibration..." button allows the user to bring up the calibration program (Ref 1) with the image_array as input. It allows the user to define the calibartion function and calculate the simple mathematical calibration on selecting few interested images out of the image_array. The "PanImages..." button allows the user to access the various options of generating the thumbnail images of the image_array.
Fitting Menu
For a 2D image data the image2d also provides a flexible method of selecting any vertical/horizontal 1D line and performing curve fitting. A user can also load his/her own private fitting function through 'fit_user.pro'. 
	Ez_Fit...        - pops up EZ_FIT program with TV image data
	2D Binary        - saves binary image data in 'fitting.bin'
The "Ez_Fit..." button automatically loads the 2D image data into the ez_fit program (Ref 2). It allows the user flexiblely to select the data line and various curve fitting methods. The "2D Binary" button will save the binary TV image data in "fitting.bin", which can be loaded into ez_fit program through file open menu.
2D-ROI Menu
The "2D-ROI" menu allows the user to calculate the mean and deviation of region of interest of 2D image. The default ROI is the whole image area if no defined ROI file is detected. To explicitly define the ROI the scan2d_ROI (2D-ROI) program (Ref 3) must be used. A multiROI and three simple modes of ROI are supported by 2D-ROI program: RectROI, FilterROI, and PolyROI. 
	Help...          - pops up help info for 2D-ROI program
	ROI...           - pops up 2D-ROI program
	Type subMenu     - sets the type of ROI defined
	    RectROI      - rectangular ROI
	    FilterROI    - filter ROI (lower and upper bound)
	    PolyROI      - polygon ROI
	AppendRpt...     - dialog appends ROI report to old report file (for all images)
	ReplaceRpt...    - dialog replaces an old report file (for all images)
	ViewRpt...       - dialog displays the ROI report file
	RenameRpt...     - dialog renames ROI report
The report generated directly by the "AppendRpt..." or "ReplaceRpt..." button from this menu applies the same ROI on all defined images from the image_array.

Either "Help..." or "ROI..." button pops up the 2D-ROI program, it allows the user to define the ROI based on the ROI mode selected. The report generated by the "AppendRpt..." button in the scan2d_ROI program only applies on the specific image as shown in scan2d_ROI program.